## 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
Replaced dense inline-linked paragraphs with a short intro sentence
per pillar followed by bullet points. Each bullet is one concept with
one link. Removed the ASCII parallelization diagram.
https://claude.ai/code/session_01R3rGevPY748gP4uK2ggYag
