Develop

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.

Overview

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

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

For multi-agent parallel execution, Chorus integrates with Claude Code Agent Teams (swarm mode) with full session-based observability.

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: Get Your Session (Sub-Agents Only)

Skip if you are the main agent or Team Lead.

If you are a sub-agent, the Chorus Plugin automatically creates your session — look for a "Chorus Session" section in your system reminders containing your sessionUuid. Keep it for all task operations.

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 skill at .claude/skills/openspec-aware/SKILL.md 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 chorus-api.sh wrapper with json_encode_file when chorus is not on PATH — with chorus_check_response halting on error.

⛔ 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 §2 Rule 1).

When the LAST task of an OpenSpec idea is verified, the plugin's PostToolUse hook injects an archive reminder (openspec-aware §3.9) — run openspec archive <slug> --yes, then mirror each emitted openspec/specs/<capability>/spec.md back via §3.8.

In the no-OpenSpec fallback (no slug line, or no openspec CLI), 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 project's prd / tech_design / … Documents are persistent mirrors of the Chorus-typed docs in that dated change folder (prd.md, tech_design.md, …, named by Chorus Document type). Load the spec-lite skill (skills/spec-lite/SKILL.md). Locate the dated folder deterministically from that locator line (not by title/type, which isn't unique). Edit those <type>.md files in place (they are the source of truth for the change) 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 as work completes, 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). No new tool/CLI — same --arg-file transport as OpenSpec. Git history is the audit trail (git log -- .chorus/specs/<slug>/ for the whole capability — the durable spec.md's diffs + each dated folder's change docs; git log --follow -- <file> to trace a single renamed file) — there is no changelog section to maintain.

Single-writer: the folder is shared — in a multi-task wave, only the orchestrator / main agent edits + re-mirrors it; parallel workers report via chorus_report_work only. A non-orchestrator that must update it re-reads immediately before writing to detect conflicts.

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.

Review Agent: After chorus_submit_for_verify, the Chorus plugin's PostToolUse hook injects context instructing you to spawn chorus:task-reviewer — an independent, read-only review agent. You MUST spawn it yourself (it is NOT auto-launched). Wait for it to complete — in Claude Code, that means waiting for the sub-agent's completion notification; the launch result itself is never the verdict. The reviewer posts a VERDICT comment on the task.

After the reviewer completes, read this round's VERDICT:

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

Find the VERDICT: comment posted after you dispatched the reviewer — not an older round's — and act on it. Do not advance the pipeline (verify or reopen) before you have read that comment:

• 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.

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 review the task yourself as a read-only pass using the checklist and POST the VERDICT comment. 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 — the PostToolUse hook injects a reminder to spawn chorus:code-reviewer (gated by enableCodeReviewer, default on). Spawn it yourself and wait for its completion notification, passing the ideaUuid + round number; then read THIS round's VERDICT comment on the idea before deciding. It reviews the Idea's aggregate code change across all its tasks (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 /chorus:quick-dev (chorus_create_tasks with proposalUuid set to the current approved proposal so the fix tasks attach to it — do NOT reopen the verified tasks). Group related small BLOCKERs by default; split only materially large or independently testable fixes. Require AC self-check, independent task review, and admin verification for every fix task. Re-run aggregate review only after every fix is successfully done; a failed or cancelled fix stops the loop and escalates, bounded by maxCodeReviewRounds. Advisory/behavioral, like the other reviewers. Run it before any idea-completion report.