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 worker observability.

Overview

Developer Agents take Tasks created by PM Agents (via the proposal skill, skill_view("chorus: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, the main agent runs Chorus workers as Hermes delegate_task children, with one Chorus session per worker for observability.

Tools

Task Lifecycle:

Work Reporting:

Acceptance Criteria:

Session (workers check in/out; the Team Lead creates and closes):

Workers: always pass sessionUuid to chorus_update_task and chorus_report_work for attribution. Main agent / Team Lead working a task itself: call these tools without sessionUuid — the main agent uses no session.

Shared tools (checkin, query, comment, search, notifications): see the chorus overview skill (skill_view("chorus:chorus"))

Workflow

Step 1: Check In

chorus_checkin()

Review your persona, current assignments, and pending work counts. In a Hermes session the Chorus Hermes plugin already ran this on the first turn (its pre_llm_call hook injects ## Checkin, ## Spec Mode, and ## Quick Reference); call it again only if you need fresh data.

Step 1.5: Get Your Session (Workers Only)

Skip if you are the main agent or Team Lead.

If you are a worker (a delegate_task child), Chorus sessions are NOT auto-created on Hermes. The Team Lead created one for you and put its UUID in your context (look for a Chorus session UUID: line). Keep it for all task operations. If your context has no session UUID, work without one — do not create a session yourself.

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 (skill_view("chorus:openspec-aware")) and follow §3.8: edit the local .md file first, then mirror it — prefer chorus mcp call … --arg-file content=<file> via terminal (see skill_view("chorus:chorus-cli")); when chorus is not on PATH, call the native MCP tool (mcp__chorus__chorus_pm_update_document) directly with content read from the file via read_file. Halt on any error.

⛔ Do not call chorus_pm_update_document 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 Chorus Hermes plugin appends an archive reminder to the chorus_admin_verify_task result (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_view("chorus: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); when chorus is not on PATH, call mcp__chorus__chorus_pm_update_document directly with content read from the file via read_file. Halt 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 local file step.

Step 5: Start Working

Worker: checkin to the task first:

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

Then mark as in-progress:

# Worker:
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

Workers — 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 Hermes plugin appends a reminder to the tool result telling you to run the chorus-task-reviewer — an independent, read-only reviewer. You MUST run it yourself (it is NOT auto-launched). Workers skip this: the Team Lead reviews after the worker batch returns. The reviewer runs as a delegate_task child under the read-only guard, so it cannot run terminal; build the evidence bundle first, then delegate. delegate_task blocks until the reviewer finishes. The verdict is the comment the reviewer posts on the task, not the call's return value.

Build the evidence bundle (parent, via terminal; <base> is the branch point, e.g. main):

mkdir -p /tmp/chorus-review/<task-uuid>
git diff <base>...HEAD > /tmp/chorus-review/<task-uuid>/diff.patch
git log --oneline <base>..HEAD > /tmp/chorus-review/<task-uuid>/log.txt
<project test/build command> > /tmp/chorus-review/<task-uuid>/tests.txt 2>&1

Run the task reviewer:

delegate_task(
  goal="[chorus-reviewer:task] Review Chorus task <task-uuid> and post one VERDICT comment.",
  context="[chorus-reviewer:task]\nFirst call skill_view(\"chorus:chorus-task-reviewer\") and follow it.\nTask UUID: <task-uuid>\nProject UUID: <project-uuid>\nMax review rounds: 3\nRepo: <abs repo path>\nEvidence: /tmp/chorus-review/<task-uuid>/diff.patch, /tmp/chorus-review/<task-uuid>/log.txt, /tmp/chorus-review/<task-uuid>/tests.txt",
)

The [chorus-reviewer:task] marker MUST be the first line of context (and should also be in goal) — the plugin uses it to put the child in read-only mode. The proposal and code reviewer examples are in the review skill (skill_view("chorus:review"), Review Strategy).

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 Chorus Hermes plugin appends a reminder to the chorus_admin_verify_task result to run chorus-code-reviewer (gated by CHORUS_ENABLE_CODE_REVIEWER, default on). Run it yourself as a delegate_task child with the [chorus-reviewer:code] marker (full example in skill_view("chorus:review")), passing the ideaUuid + round number and an evidence bundle covering the whole feature (aggregate diff, log, and test output across all of the idea's tasks). 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 the quick-dev skill (skill_view("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 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. In an interactive session, ask the human in chat (yes/no). In a gateway (Chorus-woken) session or with no human in chat, post a chorus_add_comment on the Idea that @mentions the owner (@[Name](user:<ownerUuid>) from chorus_checkin) asking whether to write the report, then end the turn and act on the reply when woken. 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 plugin will remind on the next run.

Session (Workers Only)

On Hermes, Chorus sessions for workers are not created automatically. The Team Lead owns the session lifecycle:

1. Before delegating, for each worker: chorus_list_sessions() and reopen a closed session with the same worker name (chorus_reopen_session({ sessionUuid })), or else chorus_create_session({ name: "<worker-name>" }).
2. Pass the sessionUuid in that worker's context.
3. After delegate_task returns, call chorus_close_session({ sessionUuid }) for every worker session in the batch.

Workers only do 3 things with the session:

1. chorus_session_checkin_task({ sessionUuid, taskUuid }) — before starting work
2. chorus_session_checkout_task({ sessionUuid, taskUuid }) — when done, before chorus_submit_for_verify
3. Pass sessionUuid to chorus_update_task and chorus_report_work for attribution

Workers never call chorus_create_session or chorus_close_session.

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

Parallel Workers with delegate_task

Use Hermes delegate_task to run multiple Chorus workers in parallel; Chorus provides full work observability through the per-worker sessions.

Key semantics:

• Batch form. delegate_task(tasks=[{"goal": "...", "context": "..."}, ...]) runs one child per entry in parallel. delegate_task(goal="...", context="...") runs a single child. The batch size is capped by delegation.max_concurrent_children in ~/.hermes/config.yaml; if a wave has more ready tasks than that, split it into several consecutive calls.
• Blocking. The call BLOCKS until every child in the batch finishes, then returns each child's final summary. There is no handle to track and nothing to close on the Hermes side.
• Isolated context. Each child starts with a fresh context and knows nothing of the parent conversation. It inherits the parent's toolsets, including the Chorus MCP server. Put everything the worker needs in context: task UUID(s), project UUID, repo path, Chorus session UUID, the instruction to load this skill first, and any decision from the conversation that is not recorded in Chorus.

Two-Layer Architecture

Team Lead Workflow

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

# 2. One Chorus session per worker (reopen by name if one exists)
chorus_list_sessions()
s1 = chorus_create_session({ name: "worker-auth-api" })   # or chorus_reopen_session
s2 = chorus_create_session({ name: "worker-auth-ui" })

# 3. Delegate the whole wave in ONE batch call (split if above max_concurrent_children)
delegate_task(tasks=[
  { "goal": "Implement Chorus task <task-uuid-1> and submit it for verification.",
    "context": "<worker context, see template below, with task-uuid-1 and s1.uuid>" },
  { "goal": "Implement Chorus task <task-uuid-2> and submit it for verification.",
    "context": "<worker context, see template below, with task-uuid-2 and s2.uuid>" },
])
# Blocks until both workers finish; returns each worker's final summary.

# 4. Close every worker session from this batch
chorus_close_session({ sessionUuid: s1.uuid })
chorus_close_session({ sessionUuid: s2.uuid })

# 5. Review + verify each task (task reviewer, then chorus_admin_verify_task), then next wave

What the worker context needs:

• Task UUID(s) + Project UUID + absolute repo path
• The Chorus session UUID created for this worker
• The instruction to call skill_view("chorus:develop") first
• The worker loop (below) and the rule to stop after chorus_submit_for_verify
• Any conversation decisions the worker cannot fetch from Chorus

Worker Context Template

You are a Chorus worker. Your job is one Chorus task; the Chorus server is the source of truth.

First call skill_view("chorus:develop") and follow its worker steps.

Chorus task UUID: <task-uuid>
Project UUID: <project-uuid>
Repo: <abs repo path>
Chorus session UUID: <session-uuid>

Worker loop (pass sessionUuid to every call that accepts it):
1. chorus_session_checkin_task({ sessionUuid: "<session-uuid>", taskUuid: "<task-uuid>" })
2. chorus_update_task({ taskUuid: "<task-uuid>", status: "in_progress", sessionUuid: "<session-uuid>" })
3. Gather context (task, comments, upstream tasks, proposal documents), then implement, test, commit.
4. chorus_report_work({ taskUuid: "<task-uuid>", report: "<files, commits, tests>", sessionUuid: "<session-uuid>" })
5. chorus_report_criteria_self_check for every acceptance criterion.
6. chorus_session_checkout_task({ sessionUuid: "<session-uuid>", taskUuid: "<task-uuid>" })
7. chorus_submit_for_verify({ taskUuid: "<task-uuid>", summary: "..." })

Rules:
- Do NOT call chorus_create_session or chorus_close_session; the Team Lead owns the session.
- Do NOT run the task reviewer and do NOT verify; the Team Lead does both after you return.
- Notes from the Team Lead: <decisions from the conversation, constraints, files to avoid>.
- Your final message is returned to the Team Lead: list files changed, commits, test results, and AC status.

Worker Workflow

The worker reads Chorus session UUID: from its context and runs the loop:

# 1. Checkin to 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 its delegate_task summary.
# DO NOT call chorus_close_session — the Team Lead closes it after delegate_task returns.

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. Create (or reopen) one Chorus session per ready task, then run the wave as one delegate_task(tasks=[...]) batch (split into several calls above delegation.max_concurrent_children). The call returns when every worker has finished (each task at to_verify).
3. Close each worker session (chorus_close_session).
4. Verify each task — build its evidence bundle, run chorus-task-reviewer (Step 8), act on its VERDICT, then chorus_admin_verify_task → done.
5. chorus_get_unblocked_tasks — find newly unblocked tasks (Wave 2)
6. 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.

Multiple Tasks Per Worker

A single worker can handle several tasks sequentially — one delegate_task child with an ordered list:

delegate_task(
  goal="Implement Chorus tasks <task-schema-uuid> then <task-api-uuid>, in order.",
  context="You are a Chorus worker.\nFirst call skill_view(\"chorus:develop\") and follow its worker steps.\nYour Chorus tasks (work in order):\n1. <task-schema-uuid>\n2. <task-api-uuid> (depends on #1)\nProject UUID: <project-uuid>\nRepo: <abs repo path>\nChorus session UUID: <session-uuid>\n\nFor EACH task: checkin -> in_progress -> work -> report -> checkout -> submit_for_verify",
)

Note that task #2 cannot move to in_progress until task #1 is done, which needs the Team Lead's verification. Only chain dependent tasks in one worker when the Team Lead verifies in between, or split them into separate waves.

MCP Access for Workers

delegate_task children inherit the parent's toolsets, so they get the same chorus MCP server as the parent. If the parent has no Chorus tools, fix the MCP setup first: install the chorus-mcp package (loopback http://localhost:8637/api/mcp, header Authorization: Bearer ${CHORUS_API_KEY}), or for any other deployment run chorus agents add --agents hermes or set mcp_servers.chorus.url / mcp_servers.chorus.headers.Authorization with hermes config set. Credentials come from CHORUS_URL / CHORUS_API_KEY or ~/.hermes/.env. Restart Hermes after configuration.

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 worker 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 the review skill (skill_view("chorus: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 (skill_view("chorus:yolo"), 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 skill_view("chorus:chorus")