## 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
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
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
Auto-chaining was removed from the codebase. All docs now describe the
scheduling model: work_finish transitions labels, the heartbeat's tick
pass (which also fires immediately after every work_finish) detects
available work and fills free slots. Removed autoChain config references.
Files updated: README.md, README2.md, docs/TOOLS.md, ARCHITECTURE.md,
ROADMAP.md, MANAGEMENT.md, ONBOARDING.md, lib/templates.ts
https://claude.ai/code/session_01R3rGevPY748gP4uK2ggYag
Problem:
The work_start tool was automatically running a 'tick' after picking up
an issue, which filled parallel worker slots by dispatching additional
workers for other issues without explicit instruction.
Example: Picking up #123 also auto-dispatched QA for #121 via tickPickups.
Root Cause:
work_start called tickAndNotify() which ran projectTick() to fill free
worker slots in parallel execution mode. This behavior was automatic and
not controllable.
Solution:
- Disabled the auto-tick functionality in work_start
- Commented out the tickAndNotify call
- Removed tickPickups from the response
- Updated documentation to reflect the change
Impact:
- work_start now picks up ONLY the explicitly requested issue
- No automatic worker dispatch for parallel slots
- For filling worker slots, use work_heartbeat instead
- Gives more control over worker assignments
Changes:
- lib/tools/work-start.ts:
* Commented out tickAndNotify call
* Removed tickPickups from output
* Updated file header comment
* Updated tool description
Addresses issue #125
- Updated WorkerState type to use 'level' instead of 'tier'.
- Modified functions related to worker state management, including parseWorkerState, emptyWorkerState, getSessionForLevel, activateWorker, and deactivateWorker to reflect the new terminology.
- Adjusted health check logic to utilize 'level' instead of 'tier'.
- Refactored tick and setup tools to accommodate the change from 'tier' to 'level', including model configuration and workspace scaffolding.
- Updated tests to ensure consistency with the new 'level' terminology.
- Revised documentation and comments to reflect the changes in terminology from 'tier' to 'level'.
- Introduced a new heartbeat service that runs at defined intervals to perform health checks on workers and fill available task slots based on priority.
- Added a health tool to scan worker health across projects with optional auto-fix capabilities.
- Updated the status tool to provide a lightweight overview of worker states and queue counts without health checks.
- Enhanced task creation tool descriptions to clarify task state handling.
- Implemented tests for the work heartbeat logic, ensuring proper project resolution, worker state management, and task prioritization.
Problem:
When workers were deactivated (task completed or fixed by health checks),
the startTime field was not being cleared. This caused:
- Inactive workers to retain stale timestamps
- Misleading duration data in projects.json
- Potential confusion in health checks and status displays
Example from projects.json:
{
"qa": {
"active": false,
"issueId": null,
"startTime": "2026-02-10T08:51:50.725Z", // Stale!
"tier": "qa"
}
}
Root Cause:
The deactivateWorker() function only set active: false and issueId: null,
but did not clear startTime. Similarly, health check auto-fixes that
deactivated workers also failed to clear startTime.
Solution:
Always set startTime: null when deactivating a worker to ensure clean state.
Changes:
1. lib/projects.ts:
- deactivateWorker() now sets startTime: null
- Updated function comment to document this behavior
2. lib/services/health.ts:
- All three auto-fix paths that deactivate workers now clear startTime:
* active_no_session fix (line 77)
* zombie_session fix (line 98)
* stale_worker fix (line 138)
Impact:
- Inactive workers now have clean state (startTime: null)
- Duration calculations only apply to active workers
- Health checks work with accurate data
- No stale timestamps persisting across task completions
- Complements fix from #108 (which ensures startTime is set on activation)
Together with #108:
- #108: Always SET startTime when activating worker
- #113: Always CLEAR startTime when deactivating worker
- Result: startTime accurately reflects current task duration
Addresses issue #113
Problem:
Stale worker detection was reporting incorrect durations when sessions
were reused. Workers showed total session lifetime rather than time
since current task assignment.
Example:
- Session created 13 hours ago for issue #71
- Session reused 4 minutes ago for issue #106
- Status incorrectly showed: "DEV active on #106 (3.3h)"
- Should show: "DEV active on #106 (4m)"
Root Cause:
In recordWorkerState(), startTime was only set when spawning a new
session (sessionAction === 'spawn'). When reusing an existing session
(sessionAction === 'send'), the old startTime persisted, causing
stale worker detection to use total session age instead of task age.
Solution:
Always set startTime to current time when activating a worker,
regardless of whether we're spawning a new session or reusing one.
The startTime field now consistently represents "when did this worker
start THIS specific task" rather than "when was the session created".
Changes:
- lib/dispatch.ts: Move startTime assignment outside spawn-only block
- startTime now set unconditionally for both spawn and send actions
- Maintains backward compatibility with existing health checks
Impact:
- Stale worker detection now accurately reflects task duration
- Session reuse no longer causes false positive stale alerts
- Duration shown in status matches actual time on current task
Addresses issue #108
- Moved setup logic into dedicated files: agent.ts, config.ts, index.ts, workspace.ts.
- Introduced tool-helpers.ts for shared functions across tools, reducing boilerplate.
- Updated tools (status, task-comment, task-create, task-update, work-finish, work-start) to utilize new helper functions for workspace resolution and provider creation.
- Enhanced error handling and context detection in tools.
- Improved project resolution logic to streamline tool execution.
- Added new functionality for agent creation and configuration management in setup.
Remove hard-coded auto-chain dispatch (DEV done→QA, QA fail→DEV) and
replace with a general-purpose projectTick service that scans the queue
and fills free worker slots after every state transition.
- Create lib/services/tick.ts: consolidates shared helpers and core
projectTick() function from duplicated code in work-start/auto-pickup
- work_finish: replaces auto-chain block with projectTick call
- work_start: adds projectTick after dispatch to fill parallel slots
- auto_pickup: delegates per-project loop to projectTick
- Remove autoChain from Project type, migration code, and project-register
- Remove scheduling config dependency from work_finish
- Net -112 lines: simpler, self-healing pipeline
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
- Updated import paths for task management providers in task-comment, task-create, and task-update tools.
- Removed deprecated task-complete and task-pickup tools, replacing them with work-finish and work-start tools for improved task handling.
- Enhanced work-finish and work-start tools to streamline task completion and pickup processes, including context-aware detection and auto-scheduling features.
- Updated package.json to include build scripts and main entry point.
- Modified tsconfig.json to enable output directory, declaration files, and source maps for better TypeScript support.
Automatically includes the issue URL in the announcement when
task_create is called, eliminating the need for users to ask
'What's the URL?' after creating a task.
Changes:
- Enhanced announcement formatting with line breaks
- Always includes issue URL with 🔗 prefix
- Improved readability with structured format
Example output:
📋 Created #109: "Fix bug" (To Do)
🔗https://github.com/user/repo/issues/109
Ready for pickup when needed.
Example with description:
📋 Created #110: "Add feature" (Planning)
With detailed description.
🔗https://github.com/user/repo/issues/110
Picking up for DEV...
Addresses issue #109
Improvements to notification system for better traceability:
1. DEV Completion Notifications:
- Always include issue URL (📋 Issue: ...)
- Include PR/MR URL when available (🔗 PR: ...)
- Issue URL serves as fallback when PR/MR not found
- Both URLs shown when PR/MR exists for maximum traceability
2. QA Pass Notifications:
- Now include issue URL (📋 Issue: ...)
- Provides direct link to resolved issue
3. Tool Aliases:
- Added 'work_finish' as alias for 'task_complete'
- Added 'work_start' as alias for 'task_pickup'
- Added 'status' as alias for 'queue_status'
- Matches naming used in AGENTS.md documentation
Example DEV notification:
✅ DEV done #106 — Enhanced notification URLs
📋 Issue: https://github.com/user/repo/issues/106🔗 PR: https://github.com/user/repo/pull/107
Moved to QA queue.
Example QA notification:
🎉 QA PASS #106 — All tests passed
📋 Issue: https://github.com/user/repo/issues/106
Issue closed.
Addresses issue #106
Adds automatic PR/MR URL detection and inclusion in DEV completion
announcements to provide better visibility into completed work.
Changes:
1. TaskManager interface:
- Added getMergedMRUrl() method to fetch PR/MR URL for an issue
2. GitHub/GitLab providers:
- Implemented getMergedMRUrl() to find most recent merged PR/MR
- Returns URL of PR/MR that references the issue number
3. task_complete tool:
- Added optional prUrl parameter
- Auto-detects PR/MR URL if not provided
- Includes PR URL in announcement with 🔗 prefix
- Format: 'PR: https://github.com/...'
4. Role templates (dev.md):
- Updated to instruct workers to include prUrl in task_complete
- Documents that prUrl is optional (auto-detected as fallback)
Example announcement:
✅ DEV done #101 — Added PR/MR URL to notifications
🔗 PR: https://github.com/user/repo/pull/102
. Moved to QA queue.
Addresses issue #101
Problem:
GitHub was showing confusing label transitions like:
- 'added To Do Doing and removed To Do'
- 'added To Test Testing Done and removed Doing To Test Testing'
This occurred when issues had multiple state labels simultaneously
(due to bugs, manual edits, or failed transitions).
Root Cause:
The old transitionLabel() only removed the 'from' label and added
the 'to' label. If other state labels existed on the issue, they
would remain, causing messy multi-label states.
Solution:
1. Fetch the current issue to inspect all labels
2. Find ALL state labels on the issue (not just 'from')
3. Remove ALL state labels in a single operation
4. Add only the new 'to' label
This ensures atomic, clean transitions that display on GitHub as
a single 'removed X, added Y' operation, even if the issue
previously had multiple state labels.
Changes:
- GitHubProvider.transitionLabel(): Remove all state labels before adding new one
- GitLabProvider.transitionLabel(): Same fix for GitLab consistency
Addresses issue #97
Adds test file with validation scenarios:
- Schema validation for required/optional params
- All 8 state labels are supported
- Same-state transitions handled gracefully
- Audit logging verification
Includes manual test scenarios for integration verification.
Addresses issue #71 acceptance criteria:
✅ Can transition any issue to any valid state
✅ Logs reason to audit trail
✅ Updates GitHub label (projects.json managed by session_health)
✅ Documented as orchestrator-only in AGENTS.md
- Add defensive verification in deactivateWorker to catch any accidental
session clearing bugs
- Enhance documentation in activateWorker, deactivateWorker, and
updateWorker to clearly explain session preservation behavior
- Add comprehensive example flow in activateWorker docs showing session
reuse across multiple tasks and tiers
- Add test suite for session persistence (projects.test.ts) to prevent
regression
- Add npm test script to run test suite
This ensures sessions persist per tier after task completion, enabling
session reuse across multiple tasks of the same tier for massive token
savings (~50K per reuse) and context preservation.
Fixes: Bug where sessions could theoretically be accidentally cleared
during worker state updates, though current code was already correct.
This adds defense-in-depth to make the invariant bulletproof.
- Expanded DEFAULT_DEV_INSTRUCTIONS with more detailed context and explicit
warning about not using 'Closes #X', 'Fixes #X', 'Resolves #X'
- Added 'Fixes issue #X' to the list of prohibited closing keywords
- Added new 'Worker Task Templates' section to AGENTS_MD_TEMPLATE with
explicit CRITICAL warning about closing keywords in PR/MR descriptions
- Updated workflow steps to reinforce proper issue referencing:
Use 'As described in issue #X' or 'Addresses issue #X' instead
This prevents GitHub from auto-closing issues when PRs merge, ensuring
DevClaw's task_complete validation and QA workflow are not bypassed.
As described in issue: #24
Closes#26
This PR adds two new DevClaw tools for better task lifecycle management:
- task_update: Change issue state programmatically without full pickup/complete flow
- task_comment: Add review comments or notes to issues with optional role attribution
- Added explicit warning to DEFAULT_DEV_INSTRUCTIONS
- Added warning to AGENTS_MD_TEMPLATE conventions section
- Workers instructed to use 'As described in issue #X' instead of 'Closes #X'
- Prevents GitHub/GitLab from auto-closing issues before QA validation
Adds defense-in-depth by explicitly calling activateWorker() in task_pickup.ts
after dispatchTask() returns. This ensures the worker state (active, issueId,
model, sessionKey, startTime) is properly set in projects.json even if
dispatchTask's internal state update encounters issues.
The redundant update:
- Sets active=true, issueId, and model for both spawn and reuse cases
- Sets sessionKey and startTime only on new spawns (not on session reuse)
- Provides fallback if race conditions or I/O errors affect dispatch.ts
Fixes#23
