Develop Chorus

Develop Skill

This skill covers the Development stage of the AI-DLC workflow: claiming Tasks, writing code, reporting progress, submitting for verification, and managing sessions for sub-agent observability.

Tool namespace: Chorus tools are exposed by the connected MCP server under a mcp__chorus__ prefix on dsh (e.g. mcp__chorus__chorus_claim_task). Bare names are used below for readability — prepend mcp__chorus__ when invoking. See chorus for the full rule.

Overview

Developer Agents take Tasks created by PM Agents (via proposal-chorus) and turn them into working code. Each task follows:

claim --> in_progress --> report work --> self-check AC --> submit for verify --> reviewer --> Admin /review

For multi-task execution, dispatch one subagent per unblocked task (whole wave in one message), falling back to sequential waves (the main agent works tasks in dependency order) when subagent is unavailable or workers fail repeatedly — see Wave-Based Execution below.

Tools

Task Lifecycle:

Work Reporting:

Acceptance Criteria:

Session (sub-agents only — main agent skips these):

Sub-agents: always pass sessionUuid to chorus_update_task and chorus_report_work for attribution. Main agent / Team Lead: call these tools without sessionUuid — no session needed.

Shared tools (checkin, query, comment, search, notifications): see chorus

Workflow

Step 1: Check In

chorus_checkin()

Review your persona, current assignments, and pending work counts.

Step 1.5: Manage Your Session (Sub-Agents Only)

Skip if you are the main agent.

dsh difference: the Claude Code plugin auto-creates and auto-injects a sub-agent's session via a SubagentStart hook. dsh does not run that hook. Session handling is manual: if you are a sub-agent and the host did not hand you a sessionUuid, create one yourself once at the start, keep it for all task operations, and close it when you finish.

# Create your own session (only if no sessionUuid was provided to you)
chorus_create_session({ name: "<descriptive-worker-name>" })
# -> keep the returned sessionUuid for every task call below

If the dsh host did inject a sessionUuid into your prompt (some hosts forward parent context), reuse it instead of creating a new one. When in doubt, create one — duplicate idle sessions are harmless and auto-go-inactive after 1h.

Step 2: Find Work

chorus_get_available_tasks({ projectUuid: "<project-uuid>" })

Or check existing assignments:

chorus_get_my_assignments()

Step 3: Claim a Task

chorus_get_task({ taskUuid: "<task-uuid>" })  # Review first
chorus_claim_task({ taskUuid: "<task-uuid>" })

Check: description, acceptance criteria, priority, story points, related proposal/documents.

Step 4: Gather Context

Each task and proposal includes a commentCount field — use it to decide which entities have discussions worth reading.

1. Read the task and identify dependencies:

   chorus_get_task({ taskUuid: "<task-uuid>" })

   Pay attention to dependsOn (upstream tasks) and commentCount.

2. Read task comments (contains previous work reports, progress, feedback):

   chorus_get_comments({ targetType: "task", targetUuid: "<task-uuid>" })

3. Review upstream dependency tasks — your work likely builds on theirs:

   chorus_get_task({ taskUuid: "<dependency-task-uuid>" })
   chorus_get_comments({ targetType: "task", targetUuid: "<dependency-task-uuid>" })

   Look for: files created, API contracts, interfaces, trade-offs.

4. Read the originating proposal for design intent:

   chorus_get_proposal({ proposalUuid: "<proposal-uuid>", section: "documents" })

   (chorus_get_proposal defaults to section: "basic" — just metadata + a draft index. Pass section: "documents" for the design docs, or section: "full" for docs + task drafts.)

5. Read project documents (PRD, tech design, ADR):

   chorus_get_documents({ projectUuid: "<project-uuid>" })

Document update flow (OpenSpec mode): if the originating proposal description contains a line OpenSpec change slug: <slug>, the project's PRD / tech_design / spec Documents are mirrors of files under openspec/changes/<slug>/. To update such a Document (e.g. clarify an AC, fix a spec scenario before resubmitting), load the openspec-aware-chorus skill and follow §3.8: edit the local .md file first, then mirror it — prefer chorus mcp call … --arg-file content=<file>, falling back to the package-local CHORUS_MCP_CALL wrapper with json_encode_file when chorus is not on PATH — with chorus_check_response halting on error. (dsh has no SessionStart hook; the chorus-dsh bundle precomputes CHORUS_OPENSPEC_ACTIVE at load and the skill reads it, recomputing the three checks inline only as a fallback — see openspec-aware-chorus §1.)

⛔ Do not call chorus_pm_update_document directly from the MCP harness with a hand-typed content field in OpenSpec mode. The local file is the source of truth; agent-typed content drifts and burns tokens (openspec-aware-chorus §2 Rule 1).

When the LAST task of an OpenSpec idea is verified, run the archive flow yourself (openspec-aware-chorus §3.9): run openspec archive <slug> --yes, then mirror each emitted openspec/specs/<capability>/spec.md back via §3.8. dsh has no PostToolUse hook to remind you — check after each verify whether the just-verified task was the last of its idea, and if so trigger the archive flow yourself.

In the no-OpenSpec, no-spec-lite fallback (no OpenSpec change slug: line, no Spec-lite: line, or free-form mode), edit the Document content directly via the existing MCP tool with no wrapper, no local file step.

Document update flow (spec-lite mode): if the originating proposal description contains a locator line Spec-lite: .chorus/specs/<slug>/<YYYY-MM-DD>-<change-slug>/, the prd / tech_design / … Documents are persistent mirrors of the Chorus-typed docs in that dated change folder. Load the spec-lite-chorus skill (via the skill tool). Locate the dated folder from the locator line (not by title/type). Edit those <type>.md files in place and update the capability's durable .chorus/specs/<slug>/spec.md in place too — but spec.md is never mirrored (local only, no ids). Tick - [ ] acceptance points, then re-mirror each edited dated-folder file via chorus mcp call chorus_pm_update_document … --arg-file content=.chorus/specs/<slug>/<YYYY-MM-DD>-<change-slug>/<type>.md against its documentUuid (each update auto-increments the Document version = its modification history; package-local CHORUS_MCP_CALL wrapper fallback when chorus not on PATH). There is no archive flow (that is OpenSpec-only). Git history is the audit trail (git log -- .chorus/specs/<slug>/; git log --follow -- <file> for a single renamed file) — no changelog section.

Step 5: Start Working

Sub-agent: checkin to the task first:

chorus_session_checkin_task({ sessionUuid: "<session-uuid>", taskUuid: "<task-uuid>" })

Then mark as in-progress:

# Sub-agent:
chorus_update_task({ taskUuid: "<task-uuid>", status: "in_progress", sessionUuid: "<session-uuid>" })

# Main agent:
chorus_update_task({ taskUuid: "<task-uuid>", status: "in_progress" })

Dependency enforcement: If this task has unresolved dependencies (dependsOn tasks not in done or closed), the call will be rejected with detailed blocker info. Use chorus_get_unblocked_tasks to find tasks you can start now.

Step 6: Report Progress

Report periodically with chorus_report_work. Include:

• What was completed
• Files created or modified
• Git commits and PRs
• Current status / remaining work
• Blockers or questions

chorus_report_work({
  taskUuid: "<task-uuid>",
  report: "Progress:\n- Created src/services/auth.service.ts\n- Commit: abc1234\n- Remaining: unit tests",
  sessionUuid: "<session-uuid>"
})

Report with status update when complete:

chorus_report_work({
  taskUuid: "<task-uuid>",
  report: "All implementation complete:\n- Files: ...\n- PR: https://github.com/org/repo/pull/42\n- All tests passing",
  status: "to_verify",
  sessionUuid: "<session-uuid>"
})

Step 7: Self-Check Acceptance Criteria

Before submitting, check structured acceptance criteria:

task = chorus_get_task({ taskUuid: "<task-uuid>" })

# If task.acceptanceCriteriaItems is non-empty:
chorus_report_criteria_self_check({
  taskUuid: "<task-uuid>",
  criteria: [
    { uuid: "<criterion-uuid>", devStatus: "passed", devEvidence: "Unit tests cover this" },
    { uuid: "<criterion-uuid>", devStatus: "passed", devEvidence: "Verified manually" }
  ]
})

For required criteria, keep working until you can self-check as passed. Only use failed for optional criteria that are out of scope.

Step 8: Submit for Verification

Sub-agents — checkout first:

chorus_session_checkout_task({ sessionUuid: "<session-uuid>", taskUuid: "<task-uuid>" })

Then submit:

chorus_submit_for_verify({
  taskUuid: "<task-uuid>",
  summary: "Implemented auth feature:\n- Added login/logout endpoints\n- JWT middleware\n- 95% test coverage\n- All AC self-checked (3/3 passed)"
})

to_verify does NOT unblock downstream tasks — only done (after admin verification) does.

Step 8.5: Run the Task Reviewer (inline — no hook on dsh)

dsh difference: the Claude Code plugin relies on a PostToolUse hook to inject a "spawn the reviewer" reminder after chorus_submit_for_verify. dsh has no such hook. Run the reviewer step inline, right here, immediately after submitting. Do not wait for an injected reminder.

Obtain an independent VERDICT before the task is verified:

1. Preferred — spawn a reviewer sub-agent (foreground). Use the dsh subagent tool to spawn a sub-agent with run_in_background: false (foreground — the call waits for the reviewer to finish, and the verdict is the VERDICT: comment it posts rather than the call's return value; the verify/reopen decision depends on the verdict) whose task tells it to call the skill tool with task-reviewer-chorus, then review the task. The authoritative result is this round's VERDICT: comment on the task. Set run_in_background: true (a continuable/background sub-agent whose settlement notice you collect later) only when you deliberately want to fan out and don't need the verdict before your next step.

   Load and run the task-reviewer-chorus skill to verify taskUuid <uuid>. Read the task, its AC, the proposal documents, and the code; run the project's tests; verify each AC independently; post your VERDICT comment on the task when done.

2. Fallback — review it yourself. If subagent is unavailable on your host (spawning disabled by policy), perform the review yourself as a focused, read-only pass following the task-reviewer-chorus skill's procedure: read chorus_get_task, chorus_get_comments, the originating proposal and its documents; read the code that implements each AC (do not trust the developer summary); run the project's test/build commands; verify each acceptance criterion independently. Then record the result yourself via chorus_add_comment ending with a VERDICT: line (PASS / PASS WITH NOTES / FAIL). Do NOT modify project files during this pass — it is review-only (read-only bash for tests/build is fine). Use the same BLOCKER vs NOTE classification the task-reviewer-chorus skill defines.

3. Read the VERDICT and act:

   chorus_get_comments({ targetType: "task", targetUuid: "<task-uuid>" })

   Find THIS round's VERDICT: comment — the one posted after your dispatch, not an older round's:

   • VERDICT: PASS — All AC verified, no issues. Proceed to admin verification.
   • VERDICT: PASS WITH NOTES — All AC verified, minor notes. Proceed to admin verification (notes are non-blocking).
   • VERDICT: FAIL — BLOCKERs found. Do NOT verify. Fix the BLOCKERs listed in the reviewer's comment, then resubmit (Step 9).

If no new VERDICT: comment appears after the reviewer returns, check what it did post. A comment reporting that the round limit was reached, or any other explicit refusal to review, is a deliberate escalation to a human: STOP — do not respawn, do not self-review, do not post a VERDICT of your own. If it posted nothing at all, respawn it ONCE, telling it to stay within its turn budget and reserve its last turns for the VERDICT, then apply this same check again to what the retry posts. An explicit refusal from the retry still means STOP; only a second true silence lets you fall back to reviewing manually (Step 8.5 fallback) and post the VERDICT yourself. Absence is never a PASS.

Final code-review gateway (after the Idea's LAST task is verified): when the task you just verified is the last task of its idea-rooted proposal, the feature is about to ship — run the ship-time code-review gateway before declaring the Idea done. Inline (no hook on dsh), same mechanism as Step 8.5: spawn a sub-agent via subagent with run_in_background: false (foreground — the call waits for the reviewer to finish, and the verdict is the VERDICT: comment it posts rather than the call's return value; the ship decision depends on it; set run_in_background: true only to deliberately fan out) whose task tells it to call the skill tool with code-reviewer-chorus and follow it against the idea (pass the ideaUuid + round number); fallback is a read-only self-review following the code-reviewer-chorus procedure. It reviews the Idea's aggregate code change (cross-task integration, architecture, security, regression, feature-level coverage) and posts one VERDICT: comment on the idea. PASS / PASS WITH NOTES → ship; FAIL → fix via the quick-dev workflow (quick-dev-chorus): chorus_create_tasks with proposalUuid set to the current approved proposal so the fix tasks attach to it (do not reopen old tasks). Group related small BLOCKERs into one cohesive task by default; split only materially large or independently testable fixes. Each fix task must self-check its acceptance criteria and pass independent task review plus admin verification. Re-run the gateway only after every fix task is successfully done; if there is a failed or cancelled fix task, stop and escalate instead. Advisory/behavioral. Run it before any idea-completion report.