From cafleet
Creates design documents using CAFleet-native orchestration with Director/Drafter/Reviewer team. Invoke when user requests a design doc, specification, or technical spec.
How this skill is triggered — by the user, by Claude, or both
Slash command
/cafleet:cafleet-design-doc-createThis skill is limited to the following tools:
The summary Claude sees in its skill listing — used to decide when to auto-load this skill
Create high-quality design documents using a three-role team orchestrated via the CAFleet message broker: Director (orchestrator), Drafter (writes the document), and Reviewer (critically reviews drafts). Every inter-agent message is persisted in SQLite and visible in the admin WebUI timeline. The team iterates through an internal quality loop before presenting a polished draft to the user.
Create high-quality design documents using a three-role team orchestrated via the CAFleet message broker: Director (orchestrator), Drafter (writes the document), and Reviewer (critically reviews drafts). Every inter-agent message is persisted in SQLite and visible in the admin WebUI timeline. The team iterates through an internal quality loop before presenting a polished draft to the user.
| Role | Identity | Does | Does NOT | Role definition |
|---|---|---|---|---|
| Director | Main Claude | Register with CAFleet fleet, spawn members via cafleet member create, relay user answers, enforce clarification gate, orchestrate internal quality loop, present polished draft to user | Write the document, review it in detail | roles/director.md |
| Drafter | Member agent (claude) | Ask clarifying questions (via Director relay), read target codebase, write and revise the design document | Communicate with user directly (goes through Director), review own work | roles/drafter.md |
| Reviewer | Member agent (claude) | Critically review drafts for rule compliance, readability, completeness, correctness | Write the document, communicate with user | roles/reviewer.md |
COMMENT(role) markers), see: ../cafleet-design-doc/coordination.mdThis skill's Director, Drafter, and Reviewer coordinate via the verb + pointer schema and COMMENT(role) markers defined canonically in ../cafleet-design-doc/coordination.md — the single source of truth for the 6 verbs, the 3 pointer forms, the message format, the COMMENT(role) marker grammar, the issue/status split, Copilot routing, anchorless status, finalize-time cleanup, and Director per-file detail recovery.
Two skill-specific notes layer on top of that canonical protocol:
director, drafter, reviewer, claude, and copilot marker roles — never programmer, tester, or verifier (those belong to the cafleet-design-doc-execute skill). Copilot review in this skill is design-doc-anchored only, routed through COMMENT(director); finalize happens at Status: Approved (Step 6).The Director is the root agent of a CAFleet fleet — bootstrapped automatically by cafleet fleet create (no separate cafleet agent register call) — and spawns both the Drafter and Reviewer via cafleet member create. All coordination goes through the persistent message queue — every message is auditable via the admin WebUI.
User
+-- Director (main Claude -- cafleet fleet create, cafleet member create, orchestrates cycle)
+-- Drafter (member agent -- spawned in tmux pane; writes the design document)
+-- Reviewer (member agent -- spawned in tmux pane; critically reviews the draft)
The Director MUST be running inside a tmux session (required by cafleet member create). Verify by running cafleet doctor before spawning anyone — it reports the tmux session/window/pane identifiers and exits non-zero with a clear message when the environment is not ready. If cafleet doctor reports a problem, abort and surface its message to the user. Do NOT invoke tmux display-message, printenv TMUX, or any other raw tmux/env probe — cafleet doctor is the only supported environment check (see skills/cafleet/SKILL.md § use cafleet primitives only).
Path resolution (before resume detection):
Load the cafleet-base-dir skill for the no-bypass write protocol and <unset> sentinel contract. Then canonicalize $ARGUMENTS and resolve the task-scoped BASE:
Relative input — accept any of: 0000060-foo, 0000060-foo/design-doc.md, design-docs/0000060-foo, design-docs/0000060-foo/design-doc.md. Canonicalize to design-docs/<slug> by: (1) stripping the trailing /design-doc.md if present; (2) stripping the leading design-docs/ if present; (3) prepending design-docs/. The skill's Step 0 does NOT perform this stripping (per the cafleet-base-dir skill § Consumer contract) — canonicalize first, then run the skill's Step 0 (task-scope resolution) with the relpath design-docs/<slug>.
Absolute path (e.g. /abs/path/to/design-docs/0000060-skill-task-scoped-base-dir/design-doc.md): Step 0 accepts only the task-folder path, not a child file. Strip the trailing /design-doc.md if present so the absolute path identifies the task folder, then run Step 0 with that absolute task-folder path. Step 0 accepts the absolute path if it lies strictly under the inferred repo root; otherwise it yields the <unset> sentinel.
Branch on Step 0's outcome: when it resolves, set ${BASE} to the resolved task folder and ${DOC_PATH} = ${BASE}/design-doc.md (the task folder IS the design-doc directory; no further ${BASE}/design-docs/... concatenation). When it yields <unset> (absolute $ARGUMENTS outside the repo root, or equal to the repo root), set ${DOC_PATH} to the canonicalized absolute task-folder path with /design-doc.md appended (unless $ARGUMENTS already names design-doc.md, in which case use it verbatim) so the Drafter receives a writable doc file path rather than a directory, and set ${BASE} to the <unset> sentinel so audit-file writes guard-skip per the cafleet-base-dir skill § The <unset> sentinel.
Pass ${DOC_PATH} to the Drafter as OUTPUT PATH in the spawn prompt. The audit-file path ${BASE}/prompts/<role>-<UTC-compact>.md is naturally task-scoped — it lives under <task-folder>/prompts/, not under the repo root.
Resume detection (using resolved ${DOC_PATH}):
COMMENT(claude) markers:
Use Grep to search for COMMENT(claude) in the file. The grep is tightened to the claude role because user-derived clarifications are the only marker class that warrants resume-mode. Stale COMMENT(reviewer) / COMMENT(director) / COMMENT(programmer) markers from other workflows MUST NOT be misclassified as interview-resume. Note: the cafleet-design-doc-execute skill also writes transient COMMENT(claude): <choice> markers for user arbitration (e.g., test-framework selection in Phase 1), but those are short-lived and removed by the routed member as part of the fix; under normal flow no COMMENT(claude) survives an in-progress execute run. If the user invokes the cafleet-design-doc-create skill against a half-finished execute doc that happens to carry a transient COMMENT(claude), treating it as resume-mode is acceptable — the Drafter will read and resolve the marker the same way it handles interview clarifications.
COMMENT(claude) markers found → This is resume mode. Proceed to Step 1 with the resume-specific Drafter spawn prompt. Set an internal flag SKIP_CLARIFICATION=true so Step 2 (clarification) is skipped.
No COMMENT(claude) markers found → Inform the user: "No COMMENT(claude) markers found in the existing document." Use AskUserQuestion with two options:
SKIP_CLARIFICATION=true and QUALITY_REVIEW_ONLY=true. Skip Step 2 entirely and enter Step 3 by immediately routing the existing ${DOC_PATH} to the Reviewer via cafleet message send (no new draft is produced; the Drafter is only involved later if the Reviewer requests revisions).SKIP_CLARIFICATION and QUALITY_REVIEW_ONLY are unset, then proceed to Step 1 as normal.Load the cafleet skill, the cafleet-agent-team-monitoring skill, and the cafleet-agent-team-supervision skill (in that order — monitoring is the foundation layer, supervision the governance layer that depends on it).
agent_idcafleet fleet create (which must be run inside a tmux session) atomically creates the fleet and registers a root Director bound to the current tmux pane — there is no separate cafleet agent register step for the Director. Use --json so both IDs are machine-parseable:
cafleet fleet create --label "design-doc-create-{slug}" --json
# → { "fleet_id": <int>, "administrator_agent_id": <int>, "director": { "agent_id": <int>, "name": "Director", "placement": {...} } }
Capture fleet_id and director.agent_id from the JSON response. Substitute them for <fleet-id> and <director-agent-id> in every subsequent command. Do not store them in shell variables — permissions.allow matches command strings literally, so every command must carry the literal ids.
If you already have a running fleet (e.g. an outer orchestration), reuse its fleet_id and its root Director's agent_id instead of creating a new fleet. Do not attempt to register a second Director with cafleet agent register --name Director — the root Director from fleet create is the team lead; a second registration would just create an unrelated agent with no placement row.
The first cafleet member create in the fleet is the dedicated monitoring member, spawned with --role monitor --model sonnet. It launches cafleet monitor start --fleet-id <fleet-id> as a background task in its own pane, confirms with cafleet monitor status, and reports ready: monitor live to the Director. Receipt of that handshake gates the Drafter and Reviewer spawns (1d/1e) — do not spawn an ordinary member until ready: monitor live has arrived (first-in). The Director does not run cafleet monitor start itself.
Render the canonical monitoring-member spawn prompt (the conditional idle-nudge routine — re-engage the Director via cafleet member nudge only when un-acked inbox items or stalled members can be named) to a --prompt-file per the two-step audit-file pattern in Step 1c, then spawn:
cafleet --json member create --fleet-id <fleet-id> --agent-id <director-agent-id> \
--name "monitor" \
--description "Monitoring member — runs the heartbeat and re-engages the idle Director" \
--role monitor --model sonnet \
--prompt-file ${BASE}/prompts/monitor-<UTC-compact>.md
See the cafleet-agent-team-monitoring skill § The monitoring member for the canonical spawn prompt and lifecycle, and the cafleet-agent-team-supervision skill for supervision obligations (Authorization-Scope Guard, idle semantics, Stall Response). The heartbeat runs unchanged through the quality loop; its monitor start background task is stopped first in Step 6's teardown (first-out).
The Director references each role definition by absolute path in the spawn prompt — the spawned member opens its role doc with Read at startup. Do NOT inline the role content. Resolve the absolute paths for:
<abs path to this skill>/roles/drafter.md<abs path to this skill>/roles/reviewer.mdSubstitute these absolute paths into the spawn prompts below.
Spawn-prompt audit file (two-step pattern): every spawn in this skill follows the same two steps — (1) render the prompt (substitute the
[INSERT …]markers; leave{fleet_id}/{agent_id}/{director_agent_id}intact for the CLI'sstr.format()pass); (2) write it to${BASE}/prompts/<role>-<UTC-compact>.md(<UTC-compact>=datetime.now(UTC).strftime("%Y%m%dT%H%M%SZ"); create${BASE}/prompts/on first write; same-second collision → append_2,_3, … — never overwrite), then invokecafleet member create --prompt-file <abs path>(see Step 1d / 1e for the per-role spawn templates and commands). The pre-spawn file IS both the CLI input AND the permanent audit artifact — there is no second post-spawn re-render write. See thecafleet-base-dirskill § No-bypass write protocol and thecafleetskill'sreference/director.mdreference file § Member Create — Scratch and audit files for the contract, including the${BASE} == <unset>guarded-skip + inline-fallback branch.
Gate: do not spawn the Drafter until the monitoring member's ready: monitor live handshake (1b) has arrived.
Drafter spawn prompt — render the canonical spawn-prompt skeleton with the per-role delta below. {fleet_id} / {agent_id} / {director_agent_id} are filled by member create's str.format(); the [INSERT …] markers ([INSERT DOC PATH], [INSERT USER'S ORIGINAL REQUEST], [INSERT abs path to roles/drafter.md]) are shell-substituted by the Director first. Per the Template-safety note in cafleet/reference/director.md, double any literal { / }, and keep the prompt under ~2 KB (path-by-reference). Use the normal-mode column by default; the resume-mode column when Step 0 detected resume mode.
| Slot | Drafter (normal mode) | Drafter (resume mode) |
|---|---|---|
| ROLE TITLE / TEAM | the Drafter / design document creation | the Drafter / design document creation, with (CAFleet-native, RESUME MODE) in the identity line |
| role-file + ROLE-DEF suffix | roles/drafter.md | roles/drafter.md; add suffix Follow the Resume Mode section in particular. |
| EXTRA SKILL LOADS | cafleet-design-doc (template + guidelines) | same |
| CONTEXT LINES | OUTPUT PATH: [INSERT DOC PATH] + a blank line + The user's request: [INSERT USER'S ORIGINAL REQUEST] | DESIGN DOCUMENT: [INSERT DOC PATH] |
| IMPORTANT / start cue (verbatim) | IMPORTANT: You MUST ask clarifying questions BEFORE writing any design document file. / Send your questions to the Director who will relay them to the user. / Start by reading the target codebase for context, then send your clarifying questions. / Do NOT create any design document file until you have received answers. | This is a RESUME run. The document contains COMMENT markers from a previous interview. Follow the Resume Mode instructions in your role definition. / Do NOT ask clarifying questions — the COMMENTs contain the needed information. / Start by reading the design document. |
Render the prompt to ${BASE}/prompts/drafter-<UTC-compact>.md per the Step 1c two-step audit-file pattern (both normal and resume modes — leave {fleet_id} / {agent_id} / {director_agent_id} intact for the CLI's str.format() pass), then spawn with --prompt-file:
cafleet --json member create --fleet-id <fleet-id> --agent-id <director-agent-id> \
--name "Drafter" \
--description "Writes and revises the design document" \
--prompt-file ${BASE}/prompts/drafter-<UTC-compact>.md
Parse agent_id from the JSON response and substitute it for <drafter-agent-id> in every subsequent command.
Reviewer spawn prompt — the canonical spawn-prompt skeleton with this delta:
| Slot | Reviewer |
|---|---|
| ROLE TITLE / TEAM | the Reviewer / design document creation |
| role-file | roles/reviewer.md |
| EXTRA SKILL LOADS | cafleet-design-doc (template + guidelines) |
| CONTEXT LINES | DESIGN DOCUMENT: [INSERT DOC PATH] |
| start cue (verbatim) | Wait for the Director to assign a document for review (cafleet body: ready (doc)). When you receive that message, the doc pointer refers to the DESIGN DOCUMENT path above — read that file and provide specific, actionable feedback per the role definition. |
Render the prompt to ${BASE}/prompts/reviewer-<UTC-compact>.md per the Step 1c two-step audit-file pattern, then spawn with --prompt-file:
cafleet --json member create --fleet-id <fleet-id> --agent-id <director-agent-id> \
--name "Reviewer" \
--description "Critically reviews drafts for rule compliance and quality" \
--prompt-file ${BASE}/prompts/reviewer-<UTC-compact>.md
Parse agent_id from the JSON response and substitute it for <reviewer-agent-id> in every subsequent command.
cafleet member list --fleet-id <fleet-id>
Both members must show status: active with a non-null pane_id. If either is missing or pending, retry the spawn before proceeding.
Skip this step entirely when SKIP_CLARIFICATION=true (set by Step 0 in resume mode or quality-review-only mode). Resume mode: the COMMENT markers serve as the clarification and the Drafter already has all the information needed. Quality-review-only mode: the Drafter is not producing a new draft at all — proceed directly to Step 3 by routing the existing ${DOC_PATH} to the Reviewer.
Clarification Exemption: Director-to-Drafter messages during this step are exempt from the verb + pointer schema documented in the Coordination Protocol section above. At clarification time the design doc does not yet exist (the Drafter is forbidden from creating any file before clarifying), so there is no in-doc target for
COMMENT(claude)markers — the user-answer relay rides as a free-form multi-line cafleet body. From Step 3 onward (once the initial draft exists) every message falls back under the schema.
message send, and your own periodic cafleet message poll --fleet-id <fleet-id> --agent-id <director-agent-id>, will surface the Drafter's message once it arrives.cafleet message ack --fleet-id <fleet-id> --agent-id <director-agent-id> --task-id <task-id> each received message after reading it.AskUserQuestion. If the number of questions exceeds the per-call limit of AskUserQuestion, split them into multiple sequential calls to relay all questions without omission.cafleet message send --fleet-id <fleet-id> --agent-id <director-agent-id> \
--to <drafter-agent-id> --text "User answers: ..."
cafleet message send --fleet-id <fleet-id> --agent-id <director-agent-id> \
--to <drafter-agent-id> --text "Stop — you must send clarifying questions before drafting. Discard the draft and send questions first."
A focused confirmation round counts as valid clarification.Enter this step after the Drafter reports complete (doc), or immediately when QUALITY_REVIEW_ONLY=true (the existing ${DOC_PATH} is treated as the "completed draft" — no waiting for a Drafter report):
${DOC_PATH} directly; no path needs to be embedded in the cafleet body.
cafleet message send --fleet-id <fleet-id> --agent-id <director-agent-id> \
--to <reviewer-agent-id> --text "ready (doc)"
cafleet message poll --fleet-id <fleet-id> --agent-id <director-agent-id>. Round-1 fresh review arrives as complete (doc) — N issues; approval arrives as approved (doc). Each finding is recorded as a COMMENT(reviewer): [TAG] <body> marker inline in the design doc — the Director does NOT relay the finding text in cafleet.cafleet message send --fleet-id <fleet-id> --agent-id <director-agent-id> \
--to <drafter-agent-id> --text "ready (doc)"
addressed (doc) reply (revisions resolve the COMMENT(reviewer) markers), then loop back to step 1 (re-route to Reviewer with ready (doc)).approved (doc).COMMENT(reviewer) markers in the doc) and use AskUserQuestion to ask whether to continue iterating or abort. Do not proceed to Step 4 until the Reviewer has approved.Only after the Reviewer explicitly approves, present a summary (including file path) and use AskUserQuestion:
| Option | Label | Description | Behavior |
|---|---|---|---|
| 1 | Approve | Proceed with the current result | Proceed to finalization (Step 6) |
| 2 | Scan for COMMENT markers | Immediately scan the document for COMMENT(name): feedback markers and process them | Scan immediately and process markers (see Step 5) |
| 3 | (Other — built-in) | (Free text input) | Interpret user intent (see Step 5) |
See roles/director.md for user interaction rules (COMMENT handling, intent judgment, abort detection).
Process the user's selection:
"Scan for COMMENT markers":
COMMENT( markers — do NOT wait for the user to confirm they are done editing. The selection itself is the signal to scan now.ready (doc) — no marker content is quoted in the cafleet body:
cafleet message send --fleet-id <fleet-id> --agent-id <director-agent-id> \
--to <drafter-agent-id> --text "ready (doc)"
After the Drafter replies addressed (doc) and removes the markers, verify with Grep that no COMMENT( markers remain. Then re-enter the quality loop (Step 3) and re-present (Step 4).# COMMENT(username): feedback placed directly in the design document file. Show the file path so the user can edit it. Then re-prompt with the same three-option pattern (Approve / Scan for COMMENT markers / built-in Other)."Other" (free text): Use LLM reasoning — not keyword matching — to distinguish between:
No round limit — loop continues until approved or aborted.
Instruct the Drafter to finalize. The Drafter's role definition spells out the finalize checklist (set Status to Approved, refresh Last Updated, bump the Progress header field if present, verify implementation steps are actionable); the cafleet body is just the verb + pointer poke:
cafleet message send --fleet-id <fleet-id> --agent-id <director-agent-id> \
--to <drafter-agent-id> --text "ready (doc)"
Wait for the Drafter's addressed (doc) confirmation.
Run the canonical teardown per the cafleet skill § Shutdown Protocol (first-out): stop the monitoring member's monitor start background task and wait for confirmation; cafleet member delete the monitoring member first, then Drafter and Reviewer (each call blocks 15 s; on exit 2 use member capture + send-input recovery or --force); cafleet member list to verify the roster is empty; cafleet fleet delete <fleet-id> (positional); cafleet fleet list to confirm.
The fleet row is soft-deleted and tasks are preserved so the message trail remains inspectable in the admin WebUI.
npx claudepluginhub himkt/cafleet --plugin cafleetValidates design documents through structured multi-round Q&A with inline COMMENT(claude) annotations. Supports multi-session splitting via question.md progress tracking.
Technical design documents — problem analysis, solution exploration, architectural decisions. Invoke whenever task involves any interaction with design documents — creating, updating, reviewing, comparing options, or capturing architectural decisions.
Generates architecture/design documents from approved SRS docs when no prior design exists, proposing 2-3 approaches with trade-offs and securing section-by-section approval.