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 Pi subagents (parallel workers) with full session-based observability. --- ## Tools **Task Lifecycle:** | Tool | Purpose | |------|---------| | `chorus_claim_task` | Claim an open task (open -> assigned) | | `chorus_release_task` | Release a claimed task (assigned -> open) | | `chorus_update_task` | Update task status (in_progress / to_verify) | | `chorus_submit_for_verify` | Submit task for admin verification with summary | **Work Reporting:** | Tool | Purpose | |------|---------| | `chorus_report_work` | Report progress or completion (writes comment + records activity, with optional status update) | **Acceptance Criteria:** | Tool | Purpose | |------|---------| | `chorus_report_criteria_self_check` | Report self-check results (passed/failed + optional evidence) on structured acceptance criteria | **Session (sub-agents only — main agent skips these):** | Tool | Purpose | |------|---------| | `chorus_session_checkin_task` | Checkin to a task before starting work | | `chorus_session_checkout_task` | Checkout from a task when work is done | 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 completion without changing the status: ``` 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", sessionUuid: "<session-uuid>" }) ``` > Do **not** pass `status: "to_verify"` here. `chorus_submit_for_verify` (Step 8) is the > `in_progress -> to_verify` transition; reporting `to_verify` first makes that submit fail > with `Can only submit for verification from in_progress status`. > > **Recovering a task that was already moved this way** — do not simply resubmit: > 1. Confirm the task was moved prematurely, not legitimately submitted and awaiting verification. > 2. Have the assignee move it back to `in_progress` with `chorus_update_task`; the usual > dependency checks apply. > 3. **Repeat Step 7.** Leaving `to_verify` clears the developer *and* admin acceptance marks and > their evidence, so restore the self-check evidence and confirm the required criteria pass again. > 4. Submit through Step 8. ### 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)