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
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
- Show plugin-level projectExecution setting in output
- Show project-level roleExecution for each project
- Sequential mode: single global task sequence across projects
- Parallel mode: per-project task tracks
- Proper handling of roleExecution within each project
- Priority ordering (To Improve > To Test > To Do)
- Visual distinction between active and upcoming tasks
Closes#21
When a worker session is successfully dispatched but activateWorker
fails to update projects.json, the error was being logged but not
re-thrown. This caused task_pickup to return success even though
the state wasn't updated, leading to task_complete failures later.
Now we re-throw the error after logging the warning, so the caller
knows the state update failed even though the session is running.
Fixes: #23
- Add issue URL to announcement in dispatch.ts
- Add issueUrl field to workerStart notification event
- Update notification message to include URL
- Both automated notifications and manual announcements now show full ticket URL
Example output:
🔧 Spawning DEV (medior) for #7: Create TODO.md...
🔗https://github.com/laurentenhoor/devclaw/issues/7
Workers shouldn't spawn sub-agents or message other sessions directly.
All coordination should go through DevClaw tools (task_pickup, task_complete, etc.).
Replaces single 'workMode' with two distinct settings:
1. Plugin-level 'projectExecution' (parallel | sequential)
- parallel: each project can have active workers independently
- sequential: only one project can have active workers at a time
2. Project-level 'roleExecution' (parallel | sequential)
- parallel: DEV and QA can run simultaneously on same project
- sequential: only one role (DEV or QA) active at a time per project
Changes:
- index.ts: rename workMode → projectExecution in config schema
- projects.ts: add roleExecution field to Project type
- heartbeat_tick: check both levels before picking up tasks
- task_pickup: enforce roleExecution when picking up manually
- project_register: accept roleExecution param (default: parallel)
- devclaw_setup: accept projectExecution param
All defaults remain 'parallel' for backward compatibility.
Adds notification system for full visibility into the DevClaw pipeline:
Events and targets:
- workerStart: Posted to project group when worker spawns/resumes
- workerComplete: Posted to project group when DEV done/QA pass/fail/refine
- heartbeat: Posted to orchestrator DM with tick summary
Implementation:
- New lib/notify.ts module with buildMessage() and sendMessage()
- Integrated into task_pickup, task_complete, and heartbeat_tick
- Uses OpenClaw gateway to invoke message tool
Configuration (optional):
- orchestratorDm: Chat ID for heartbeat notifications
- notifications.heartbeatDm: Enable/disable heartbeat DM (default: true)
- notifications.workerStart: Enable/disable start notifications (default: true)
- notifications.workerComplete: Enable/disable completion notifications (default: true)
Notifications fail silently (logged but don't break main flow).
Adds heartbeat_tick tool that automates task pickup across all projects:
- Runs session health checks (zombie cleanup) before pickups
- Loops over all registered projects
- Picks up tasks by priority (To Improve > To Test > To Do)
- Supports two work modes:
- parallel: each project can have DEV+QA running independently
- sequential: only 1 DEV + 1 QA globally (can be different projects)
- Respects per-project maxDevWorkers/maxQaWorkers settings
- Supports dryRun mode and maxPickups limit
- Context guard: only works from DM/cron, blocks project groups
Also adds:
- workMode config option (parallel | sequential)
- maxDevWorkers/maxQaWorkers fields to Project type
- projectGroupId: auto-detected from group chat context
- role: inferred from issue label (To Do/To Improve → dev, To Test → qa)
- model: detected from tier labels on issue, then falls back to heuristics
- issueId: if omitted, picks next by priority (To Improve > To Test > To Do)
All parameters are now optional. Tool includes autoDetected object in response
to indicate which values were auto-detected vs explicitly provided.
- Move resolveRepoPath to lib/utils.ts
- Update all tools to use createProvider() from lib/providers/
- Remove direct imports from lib/gitlab.ts
- Mark lib/gitlab.ts as deprecated
- All tools now work with both GitHub (gh CLI) and GitLab (glab CLI)
- Provider auto-detected from git remote URL
- Add context-guard.ts to detect interaction context (via-agent, direct, group) and generate guardrails.
- Introduce onboarding.ts for conversational onboarding context templates and workspace file checks.
- Enhance setup.ts to support new agent creation with channel binding and migration of existing bindings.
- Create analyze-channel-bindings.ts to analyze channel availability and detect binding conflicts.
- Implement context-test.ts for debugging context detection.
- Develop devclaw_onboard.ts for explicit onboarding tool that guides users through setup.
- Update devclaw_setup.ts to include channel binding and migration support in setup process.
- Modify project-register.ts to enforce project registration from group context and auto-populate group ID.
- Enhance queue-status.ts to provide context-aware status checks and recommendations.
- Update task tools (task-complete, task-create, task-pickup) to clarify group ID usage for Telegram/WhatsApp.
- Added TypeScript configuration file (tsconfig.json) with strict settings.
- Introduced devDependencies for TypeScript in package.json.
- Added scripts for type checking and watching for changes.
- Created a new types file (lib/types.ts) defining shared types for the DevClaw plugin.
- Replaced raw model aliases with developer tiers (junior, medior, senior, qa) in dispatch and model selection logic.
- Updated `dispatchTask` to resolve models based on tiers and plugin configuration.
- Modified `selectModel` to return tier names instead of model aliases based on task description.
- Implemented migration logic for transitioning from old model aliases to new tier names in worker state.
- Added setup logic for agent creation and model configuration in `setup.ts`.
- Created shared templates for workspace files and instructions for DEV/QA workers.
- Enhanced project registration to scaffold role files based on developer tiers.
- Updated task management tools to reflect changes in model selection and tier assignment.
- Introduced a new `devclaw_setup` tool for agent-driven setup and configuration.
- Updated plugin configuration schema to support model mapping per developer tier.
- Add GitLabProvider class for handling issue operations, label management, and MR checks.
- Implement methods for ensuring labels, creating issues, listing issues by label, and transitioning labels.
- Introduce a provider factory to auto-detect GitLab or GitHub based on the repository URL.
- Create project registration tool to validate repositories, create state labels, and log project entries.
- Enhance queue status and session health tools to support new session management features.
- Update task completion and task creation tools to support auto-chaining and improved session handling.
- Refactor task pickup tool to streamline model selection and session management.
Multi-project dev/qa pipeline orchestration with 4 agent tools:
- task_pickup: atomic task pickup with model selection and session reuse
- task_complete: DEV done, QA pass/fail/refine with label transitions
- queue_status: task queue and worker status across projects
- session_health: zombie detection and state consistency checks
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
