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 Pi subagents (parallel workers) 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 (dispatched via the subagent tool), the Chorus extension automatically creates your session and injects it into your task prompt — look for a --- Chorus session (auto-injected) --- section containing your Session UUID. 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 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-mcp-call.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 extension 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.

Document update flow (spec-lite mode): if the proposal description contains a line Spec-lite: .chorus/specs/<slug>/<YYYY-MM-DD>-<change-slug>/, the project's PRD / tech_design / … Documents are mirrors of the files in that dated folder. To update such a Document, load the spec-lite skill (/skill:spec-lite) and follow its Mirror section: edit the local <type>.md file first, then mirror it via chorus mcp call chorus_pm_update_document "{\"documentUuid\":\"<uuid>\"}" --arg-file content=<file> (recorded documentUuid from the file's frontmatter), falling back to the chorus-mcp-call.sh wrapper when chorus is not on PATH, chorus_check_response halting on error. Same ⛔ do-not-hand-type-content rule as OpenSpec. The durable .chorus/specs/<slug>/spec.md is edited in place too but is never mirrored (git history is its record). No archive flow — spec-lite has no CLI/validate/archive; on delivery just set spec.md status: done.

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

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 extension nudges you to spawn chorus-task-reviewer — an independent, read-only review agent. You MUST spawn it yourself (it is NOT auto-launched). Spawn it with the subagent tool and wait for its VERDICT — wait before proceeding. The verdict is the comment the reviewer posts on the task, not the call's return value.

After the reviewer completes, read its VERDICT:

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 — and act on it:

• 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 extension nudges you to spawn chorus-code-reviewer (gated by CHORUS_ENABLE_CODE_REVIEWER, default on). Spawn it yourself with the subagent tool, passing the ideaUuid + round number; 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 /skill: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 CHORUS_MAX_CODE_REVIEW_ROUNDS (env, default 3; 0 = unlimited). Advisory/behavioral, like the other reviewers. Run it before any idea-completion report.

Step 9: Handle Review Feedback

If the reviewer returns FAIL, or the task is reopened after verification:

All acceptance criteria are reset to pending when a task is reopened.

1. Check feedback:

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

2. Fix every BLOCKER listed in the reviewer's FAIL comment.
3. Checkin again, fix issues, report fixes, resubmit.

Step 10: Task Complete

Once Admin verifies (status: done), move to the next available task (back to Step 2).

Step 11: Idea Completion Report (advisory)

If the task you just self-verified was the LAST one of its Idea (every Task across every approved Proposal is now done/closed) and you have document:write, offer to call chorus_create_report via AskUserQuestion. The call requires title (a short report title) plus content; content's parameter description carries the three-section template (## Summary / ## Decisions / ## Follow-ups). Skip on decline — the extension will remind on the next run.

Session (Sub-Agents Only)

The Chorus extension fully automates session lifecycle — a Chorus session is created (on subagent dispatch, via tool_call task injection) and closed by the extension (when the call returns for a blocking implementation, or when the run settles — subagent:async-complete / process-terminal — under nicobailon pi-subagents). Sub-agents only do 3 things manually:

1. chorus_session_checkin_task({ sessionUuid, taskUuid }) — before starting work
2. chorus_session_checkout_task({ sessionUuid, taskUuid }) — when done (recommended; plugin also auto-checkouts on exit)
3. Pass sessionUuid to chorus_update_task and chorus_report_work for attribution

Main agent / Team Lead: no session needed — call tools without sessionUuid.

Parallel Sub-Agent Integration

Use the subagent tool to run multiple Chorus workers in parallel; Chorus provides full work observability. Both the dispatch shape and the run mode depend on the installed implementation, so pick the shape that matches the active one:

Either way there is no agentId to track and no manual close. The chorus-pi extension automates session lifecycle: when you dispatch a chorus-worker, it creates a Chorus session and injects the session UUID + workflow into that worker's task, then closes the session when the dispatch returns (blocking) or when the run settles (subagent:async-complete / process-terminal).

The three modes — single ({ agent, task }), parallel ({ tasks: [...] }, max 8 per call, concurrency 4), and chain ({ chain: [...] }, sequential with a {previous} placeholder) — are the bundled subagent's schema. Under nicobailon pi-subagents the public tool rejects top-level tasks/chain (Legacy top-level chain and parallel inputs were removed; use workflowScript.), and its workflowScript children are invisible to the extension's session hook — so under nicobailon dispatch one worker per call. Dispatch agent: "chorus-worker" for Chorus task implementation.

Two-Layer Architecture

Team Lead Workflow

# 1. Check in and plan
chorus_checkin()
chorus_list_tasks({ projectUuid: "<project-uuid>" })

# 2. Dispatch a worker per ready task in ONE wave — the call shape follows the
#    installed implementation:
#      bundled subagent    → one composite call, max 8 entries:
subagent({
  tasks: [
    { agent: "chorus-worker",
      task: "Your Chorus task UUID: <task-uuid>\nProject UUID: <project-uuid>\n\nImplement..." },
    // ... one entry per ready task, max 8 (batch into multiple calls if more)
  ]
})
#      nicobailon pi-subagents → one single dispatch per worker (it rejects
#      top-level `tasks`); issue them together for the same wave:
subagent({ agent: "chorus-worker", task: "Your Chorus task UUID: <task-uuid>\n..." })  # task 1
subagent({ agent: "chorus-worker", task: "Your Chorus task UUID: <task-uuid>\n..." })  # task 2
# Pass only task + project UUIDs — the chorus-pi extension auto-injects the
# session UUID + workflow into each worker's task.
# The composite call returns when every worker finishes (bundled subagent); each
# nicobailon call returns a run receipt (async by default) — wait for the wave to
# settle either way.
# For a single task, single mode is all you need:
#   subagent({ agent: "chorus-worker", task: "..." })

What the Team Lead prompt needs:

• Task UUID(s) + Project UUID
• NO session UUID, NO workflow boilerplate — the extension auto-injects everything
• No agentId to track and no close step — the dispatch owns the worker's whole lifecycle

Sub-Agent Workflow

The extension injects the session UUID + workflow into the worker's task automatically (at tool_call time, before the subprocess starts). The worker reads the Session UUID: from its task prompt and follows the injected steps:

# 1. Checkin to task (sessionUuid comes from the auto-injected task)
chorus_session_checkin_task({ sessionUuid: "<my-session-uuid>", taskUuid: "<my-task-uuid>" })

# 2. Move to in_progress
chorus_update_task({ taskUuid: "<my-task-uuid>", status: "in_progress", sessionUuid: "<my-session-uuid>" })

# 3. Do work... code, test, commit...

# 4. Report progress
chorus_report_work({ taskUuid: "<my-task-uuid>", report: "...", sessionUuid: "<my-session-uuid>" })

# 5. Checkout and submit
chorus_session_checkout_task({ sessionUuid: "<my-session-uuid>", taskUuid: "<my-task-uuid>" })
chorus_submit_for_verify({ taskUuid: "<my-task-uuid>", summary: "..." })

# The worker's final message is returned to the Team Lead as the subagent result.
# DO NOT call chorus_close_session — the extension closes the session when the
# dispatch returns (blocking) or when the run settles (async).

Handling Task Dependencies (DAG)

Server-side enforcement: chorus_update_task(status: "in_progress") rejects if any dependsOn task is not done or closed.

Wave-based execution (recommended):

1. chorus_get_unblocked_tasks — find ready tasks
2. Dispatch a chorus-worker per ready task as one wave — one subagent({ tasks: [...] }) call under the bundled subagent (max 8; batch if more), or one subagent({ agent, task }) call per ready task under nicobailon pi-subagents (which rejects top-level tasks). Wait for the whole wave to settle (each worker at to_verify): the bundled call returns when its workers exit; under nicobailon each call returns a run receipt, so wait on the run notifications / bg_wait.
3. Verify each task — spawn chorus-task-reviewer, act on its VERDICT, then chorus_admin_verify_task → done.
4. chorus_get_unblocked_tasks — find newly unblocked tasks (Wave 2)
5. Repeat until all tasks done

Critical: to_verify does NOT resolve dependencies — only done or closed does. The Team Lead must verify tasks between waves. The dispatch already released each worker's slot once the wave settled, so there is nothing to close.

Multiple Tasks Per Sub-Agent

A single worker can handle several tasks sequentially — use single mode with an ordered list:

subagent({
  agent: "chorus-worker",
  task: "Your Chorus tasks (work in order):\n1. task-schema-uuid\n2. task-api-uuid (depends on #1)\n\nFor EACH task: checkin -> in_progress -> work -> report -> checkout -> submit_for_verify"
})

For strictly dependent stages where each step consumes the previous output, use chain mode — bundled subagent only (nicobailon pi-subagents has no top-level chain; run its stages as separate dispatches, or as workflowScript steps, which the session hook cannot reach): subagent({ chain: [{ agent: "chorus-worker", task: "..." }, { agent: "chorus-worker", task: "... {previous} ..." }] }).

MCP Access for Sub-Agents

Sub-agents need MCP configured at project level (.mcp.json) or user level (~/.pi/agent/mcp.json). The chorus-pi extension's session injection works regardless, because it calls chorus over its own MCP-over-HTTP fetch (not the sub-agent's gateway).

Troubleshooting

Work Report Best Practices

Good report (enables session continuity):

Implemented password reset flow:

Files created/modified:
- src/services/auth.service.ts (new)
- src/app/api/auth/reset/route.ts (new)
- tests/auth/reset.test.ts (new)

Git:
- Commit: a1b2c3d "feat: password reset flow"
- PR: https://github.com/org/repo/pull/15

Implementation details:
- POST /api/auth/reset-request: sends email with token
- Token expires after 1 hour, single-use
- Rate limiting: 3 requests/hour/email
- 12 new tests, all passing

Acceptance criteria:
- [x] User can request reset via email
- [x] Reset link expires after 1 hour
- [x] Rate limiting prevents abuse

Bad report: Done.

Tips

• Read task comments first — they contain previous work reports for session continuity
• Check upstream dependencies — read dependsOn tasks and their comments for interfaces/APIs
• Read the originating proposal — understand design rationale and task DAG
• Use commentCount — skip fetching comments on entities with count 0
• Report progress frequently — include file paths, commits, and PRs
• Write detailed submit summaries — Admin needs them to verify
• If blocked, add a comment and consider releasing the task
• One task at a time: finish or release before claiming another
• Use meaningful sub-agent names — they become Chorus session names

When to Release a Task

Release if:

• You can't complete it (missing knowledge, blocked)
• A higher-priority task needs attention
• You won't finish in a reasonable timeframe

chorus_release_task({ taskUuid: "<task-uuid>" })
chorus_add_comment({ targetType: "task", targetUuid: "<task-uuid>", content: "Releasing: reason..." })

Next

• After submitting for verification, an Admin reviews using /review
• Human "Start Development" wake: a start_development wake (the human clicked Start Development on the idea-detail panel) means: claim and execute ALL remaining tasks of the idea's approved proposal in dependency order — loop this workflow until no claimable task remains, leaving to_verify and other-session tasks untouched.
• Human "Yolo" wake: a yolo_requested wake (the human clicked Yolo on the idea-detail panel) means: drive the WHOLE idea to done via the yolo skill (the full-auto AI-DLC pipeline), not just the execute stage — read the idea's current state and resume from whatever phase it is in. Unlike start_development it is stage-adaptive, and it must never merge or push a PR without explicit human approval.
• For platform overview and shared tools, see /chorus