Replaces the file-read-network pattern in dispatch.ts with an OpenClaw
agent:bootstrap hook that injects role instructions at agent init time.
Changes:
- Add lib/bootstrap-hook.ts with hook registration, session key parsing,
and role instruction loading (extracted from dispatch.ts)
- Register agent:bootstrap hook in index.ts
- Remove file I/O from dispatch.ts (no more fs/path imports)
- Remove role instructions from task message body (now injected via
system prompt as WORKER_INSTRUCTIONS.md)
- Add 13 tests for session key parsing and instruction loading
- Remove obsolete docs/poc-bootstrap-hook.ts
The bootstrap hook intercepts DevClaw worker session startup, parses
the session key to extract project name and role, loads the appropriate
instructions from workspace, and injects them as a virtual bootstrap
file that OpenClaw automatically includes in the agent's system prompt.
This eliminates the security audit's potential-exfiltration warning
since dispatch.ts no longer performs any file reads.
Comprehensive investigation of OpenClaw-native alternatives to the
file-read-network pattern in dispatch.ts that triggers security audits.
Key Findings:
- Bootstrap hooks are the recommended solution
- Purpose-built for dynamic workspace file injection
- Plugin-only implementation (no core changes needed)
- Eliminates audit false positive
Deliverables:
- Full research document with pros/cons analysis
- PoC code demonstrating implementation approach
- Migration checklist and testing plan
- Decision matrix comparing alternatives
Recommendation: Implement agent:bootstrap hook to inject role
instructions at system prompt construction time instead of appending
to task message payload.
Addresses issue #181
Addresses issue #179. Adds JSDoc comment to loadRoleInstructions() explaining:
- Purpose: Load role-specific instruction files from workspace
- Intent: Intentionally included in task message context for workers
- Safety: Not data exfiltration, just standard task dispatch context
This clarifies the security audit finding and prevents future false positives.
## Problem
lib/services/queue.ts was not updated during workflow refactor (#147) and still
used hardcoded queue labels: QueueLabel type, QUEUE_PRIORITY constant.
## Solution
- Add getQueueLabelsWithPriority() to derive queue labels from workflow config
- Add getQueuePriority() to get priority for any label
- Update getTaskPriority() and getRoleForLabel() to accept workflow config
- Update fetchProjectQueues() to use workflow-derived labels
- Add getTotalQueuedCount() helper
## Files Changed
- lib/services/queue.ts — use workflow config for all queue operations
- lib/tools/status.ts — handle dynamic queue labels, include queueLabels in response
## Backward Compatibility
- QueueLabel type kept as deprecated alias
- QUEUE_PRIORITY kept as deprecated constant
- All functions accept optional workflow parameter, default to DEFAULT_WORKFLOW
## Summary
Introduces a configurable workflow state machine that replaces all hardcoded
state labels. The default workflow matches current behavior exactly, ensuring
backward compatibility.
## Architecture
### lib/workflow.ts — Core workflow engine
XState-style statechart configuration:
```typescript
type StateConfig = {
type: 'queue' | 'active' | 'hold' | 'terminal';
role?: 'dev' | 'qa';
label: string;
color: string;
priority?: number;
on?: Record<string, TransitionTarget>;
};
```
All behavior is derived from the config:
- Queue states: `type: 'queue'`, grouped by role, ordered by priority
- Active states: `type: 'active'` — worker occupied
- Transitions: defined with optional actions (gitPull, detectPr, closeIssue, reopenIssue)
- Labels and colors: derived from state.label and state.color
### Derivation functions
- `getStateLabels()` — all labels for issue tracker sync
- `getLabelColors()` — label → color mapping
- `getQueueLabels(role)` — queue labels for a role, ordered by priority
- `getActiveLabel(role)` — the active/in-progress label for a role
- `getRevertLabel(role)` — queue label to revert to on failure
- `detectRoleFromLabel()` — detect role from a queue label
- `getCompletionRule(role, result)` — derive transition rule from config
## Files Changed
- **lib/workflow.ts** — NEW: workflow engine and default config
- **lib/providers/provider.ts** — deprecate STATE_LABELS, LABEL_COLORS; derive from workflow
- **lib/providers/github.ts** — use workflow config for label operations
- **lib/providers/gitlab.ts** — use workflow config for label operations
- **lib/services/pipeline.ts** — use getCompletionRule() from workflow
- **lib/services/tick.ts** — use workflow for queue/active labels
- **lib/services/health.ts** — use workflow for active/revert labels
- **lib/tools/work-start.ts** — use workflow for target label
## Backward Compatibility
- DEFAULT_WORKFLOW matches current hardcoded behavior exactly
- Deprecated exports kept for any external consumers
- No breaking changes to tool interfaces or project state
## Future Work
- Load per-project workflow overrides from projects.json
- User-facing config in projects/workflow.json
- Tool schema generation from workflow states
## Problem
`dispatchTask()` shells out to `openclaw gateway call sessions.patch` which
times out when the gateway is busy, causing:
1. Notifications never fire (they're at the end of dispatchTask)
2. Worker state may not be recorded
3. Workers run silently
## Solution (3 changes)
### 1. Make `ensureSession` fire-and-forget
Session key is deterministic, so we don't need to wait for confirmation.
Health check catches orphaned state later.
### 2. Use runtime API for notifications instead of CLI
Pass `runtime` through opts and use direct API calls:
- `runtime.channel.telegram.sendMessageTelegram()`
- `runtime.channel.whatsapp.sendMessageWhatsApp()`
- etc.
### 3. Move notification before session dispatch
Fire workerStart/workerComplete notifications early (after label transition)
before the session calls that can timeout.
## Files Changed
- lib/dispatch.ts — fire-and-forget ensureSession, early notification, accept runtime
- lib/notify.ts — use runtime API for direct channel sends
- lib/services/pipeline.ts — early notification, accept runtime
- lib/services/tick.ts — pass runtime through to dispatchTask
- lib/tool-helpers.ts — accept runtime in tickAndNotify
- lib/tools/work-start.ts — pass api.runtime to dispatchTask
- lib/tools/work-finish.ts — pass api.runtime to executeCompletion/tickAndNotify
## Problem
`dispatchTask()` shells out to `openclaw gateway call sessions.patch` which
times out when the gateway is busy, causing:
1. Notifications never fire (they're at the end of dispatchTask)
2. Worker state may not be recorded
3. Workers run silently
## Solution (3 changes)
### 1. Make `ensureSession` fire-and-forget
Session key is deterministic, so we don't need to wait for confirmation.
Health check catches orphaned state later.
### 2. Use runtime API for notifications instead of CLI
Pass `runtime` through opts and use direct API calls:
- `runtime.channel.telegram.sendMessageTelegram()`
- `runtime.channel.whatsapp.sendMessageWhatsApp()`
- etc.
### 3. Move notification before session dispatch
Fire workerStart/workerComplete notifications early (after label transition)
before the session calls that can timeout.
## Files Changed
- lib/dispatch.ts — fire-and-forget ensureSession, early notification, accept runtime
- lib/notify.ts — use runtime API for direct channel sends
- lib/services/pipeline.ts — early notification, accept runtime
- lib/services/tick.ts — pass runtime through to dispatchTask
- lib/tool-helpers.ts — accept runtime in tickAndNotify
- lib/tools/work-start.ts — pass api.runtime to dispatchTask
- lib/tools/work-finish.ts — pass api.runtime to executeCompletion/tickAndNotify
Change Planning label from #6699cc (blue) to #95a5a6 (grey/slate) to distinguish it from To Do (#428bca).
Note: Only affects newly created labels. Existing repos need manual update.
## Changes
- Remove `activeSessions` parameter from health check (was never populated)
- Add gateway session lookup via `openclaw gateway call status`
- Add issue label lookup via `provider.getIssue(issueId)`
- Implement detection matrix with 6 issue types:
- session_dead: active worker but session missing in gateway
- label_mismatch: active worker but issue not in Doing/Testing
- stale_worker: active for >2h
- stuck_label: inactive but issue has Doing/Testing label
- orphan_issue_id: inactive but issueId set
- issue_gone: active but issue deleted/closed
## Files
- lib/services/health.ts — complete rewrite with three-source triangulation
- lib/tools/health.ts — remove activeSessions param, fetch sessions from gateway
- lib/services/heartbeat.ts — remove empty activeSessions calls, pass sessions map
Changed module resolution from Node16 to Bundler (with ESNext module) to
properly resolve openclaw/plugin-sdk type exports. This fixes build errors
where OpenClawPluginApi and jsonResult types were not being found.
The Node16 module resolution was not following the re-exports in openclaw's
plugin-sdk index.d.ts correctly. Bundler resolution is more compatible with
modern package.json exports.
Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
First stable release of DevClaw, transforming OpenClaw into a
complete dev team management system.
Key features:
- Autonomous multi-project development pipeline
- Intelligent tier-based model selection (Junior/Medior/Senior)
- Token-free scheduling with work_heartbeat
- 60-80% token savings through tier selection and session reuse
- GitHub/GitLab integration with atomic operations
- Comprehensive tooling and documentation
Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
Major changes:
- Add autoconfigure_models tool for intelligent model assignment
- Implement LLM-based model selection using openclaw agent
- Improve onboarding flow with better model access checks
- Update README with clearer installation and onboarding instructions
Technical improvements:
- Add model-fetcher utility to query authenticated models
- Add smart-model-selector for LLM-driven model assignment
- Use session context for LLM calls during onboarding
- Suppress logging from openclaw models list calls
Documentation:
- Add prerequisites section to README
- Add conversational onboarding example
- Improve quick start flow
Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
## Changes
### lib/templates.ts (AGENTS.md template)
- Added 'Critical: You Do NOT Write Code' section to orchestrator instructions
- Listed what orchestrator CAN do (planning, analysis, status checks)
- Listed what MUST go through workers (code, git ops, tests)
- Added 'Never write code yourself' to Safety section
### README.md
- Added 'The orchestrator's role' section explaining the workflow boundary
- Table showing what goes through workers vs orchestrator
- Explained why: audit trail, tier selection, parallelization, QA pipeline
### docs/ARCHITECTURE.md
- Updated scope boundaries diagram to show 'planning only' for orchestrator
- Added key boundary note about planner/dispatcher role
Addresses issue #133
Enhanced the DevClaw onboarding flow to address real-world usability issues
discovered during testing.
Changes:
1. Model Selection Improvements (Step 2):
- Added explicit prompt to check user's available models first
- Changed 'Default Model' table to 'Suggested default' to emphasize flexibility
- Added model selection guidance with class descriptions:
* junior/tester: Fast, cheap (Haiku-class, GPT-4-mini)
* medior/reviewer: Balanced (Sonnet-class, GPT-4)
* senior: Most capable (Opus-class, o1)
- Emphasized guiding users to configure finer-grained mappings
- Added warning that defaults are suggestions, not requirements
2. Telegram Group Setup Guidance (New Step 4):
- Added comprehensive section on project isolation best practices
- Explains the one-group-per-project model clearly
- Provides rationale:
* Clean issue backlogs per project
* Isolated worker state
* Clear audit trails
* Team-specific access control
- Documents mention requirement (@botname command)
- Includes single-project mode option with strong warning
- Provides tip for getting group ID from bot
3. Improved Flow:
- Renumbered steps (Project Registration is now Step 5)
- Added group ID discovery tip
- Maintained conversational tone while being more explicit
Impact:
- Prevents configuration failures from using unavailable models
- Guides users toward sustainable multi-project setup
- Reduces support burden by proactively explaining best practices
- Still allows single-project mode for solo developers
Addresses issue #132
