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.
Remove TEST.md which was created for testing purposes (issue #105)
and should not be in the repository.
File contained test content about Lauren ten Hoor profile information
and was not part of the core project functionality.
Addresses issue #117
Issue #115 requested changing the default from 'To Do' to 'Planning',
but investigation reveals this is already implemented.
Findings:
- Code has defaulted to 'Planning' since initial commit (8a79755e, Feb 9)
- README documentation correctly states 'defaults to Planning' (line 308)
- Tool description confirms 'defaults to Planning' behavior
Timeline:
- Feb 9, 2026: task_create implemented with Planning default
- Feb 10, 2026: Issue #115 filed (requesting already-implemented feature)
No code changes needed - feature already works as requested.
Added VERIFICATION.md documenting the current implementation and
providing evidence that the requested behavior is already active.
Addresses issue #115
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
Added comprehensive QA workflow documentation explaining:
- Required steps for QA reviews
- Mandatory task_comment before task_complete
- Comment templates for pass/fail scenarios
- Rationale for enforcement (audit trail, knowledge sharing, etc.)
- Best practices for QA documentation
This documentation supports the QA comment enforcement
introduced in role templates.
Related to issue #103
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
- Deleted `helpers.ts`, `projects.test.ts`, and `scenarios.test.ts` as they are no longer needed.
- Updated `package.json` to remove the test script that referenced the deleted files.
