From cafleet
Validates design documents through structured multi-round Q&A with inline COMMENT(claude) annotations. Supports multi-session splitting via question.md progress tracking.
How this skill is triggered — by the user, by Claude, or both
Slash command
/cafleet:cafleet-design-doc-interviewThis skill is limited to the following tools:
The summary Claude sees in its skill listing — used to decide when to auto-load this skill
Validate an existing design document through structured, fine-grained Q&A across multiple sessions. The Director (main Claude) drives the conversation and writes annotations; an Analyzer member spawned via `cafleet member create` reads the document and returns the question list, then is torn down before the interview rounds begin. Discrepancies surface as inline `COMMENT(claude)` annotations in...
Validate an existing design document through structured, fine-grained Q&A across multiple sessions. The Director (main Claude) drives the conversation and writes annotations; an Analyzer member spawned via cafleet member create reads the document and returns the question list, then is torn down before the interview rounds begin. Discrepancies surface as inline COMMENT(claude) annotations in the design document. Multi-session splitting via question.md prevents context compaction for large interviews.
| Role | Identity | Does | Does NOT | Role definition |
|---|---|---|---|---|
| Director (Interviewer) | Main Claude | Resolve doc path, parse question.md progress, spawn Analyzer, drive AskUserQuestion rounds, write answers + COMMENT annotations + progress marker | Read the document for question generation (delegated to Analyzer); conduct the Q&A rounds outside AskUserQuestion | (inline in this SKILL.md) |
| Analyzer | CAFleet member spawned via cafleet member create | Read the design doc, return a flat numbered question list covering uncovered sections, then idle pending shutdown | Talk to the user; edit any file; persist state across spawns | roles/analyzer.md |
cafleet-design-doc-create skill is the input to this skill; this skill's COMMENT(claude) markers are consumed by the cafleet-design-doc-create skill's resume mode.This skill writes only COMMENT(claude) markers in the design document; the Director-Analyzer cafleet messages are exempt from the verb + pointer schema (the Analyzer's question list is a one-time multi-line payload, and the Director's user relay goes through AskUserQuestion, not cafleet). The COMMENT(role) marker format, the claude role (the Director as user-mediator, carrying user-derived clarifications), and the one-per-issue / actionable rules are canonical in ../cafleet-design-doc/coordination.md § COMMENT(role) Marker.
Interview-specific: place each COMMENT(claude) marker on its own line immediately before the section it refers to (e.g. above ### Retry Strategy); markers persist until the cafleet-design-doc-create skill's resume mode resolves them (reads each marker, applies the fix, removes it).
The Director is the root agent of a CAFleet fleet — bootstrapped automatically by cafleet fleet create (no separate cafleet agent register call) — and spawns one short-lived Analyzer via cafleet member create. The Analyzer is torn down BEFORE the interview rounds begin; the Director then runs the rounds (and writes annotations) on its own. All Analyzer 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, drives Q&A, writes annotations)
+-- Analyzer (member agent -- spawned in tmux pane; returns question list; terminated)
The Director MUST be running inside a tmux session (required by cafleet member create). Verify by running cafleet doctor before spawning the Analyzer — 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).
Two mechanisms prevent context compaction:
question.md in the design document's directory, so subsequent invocations skip already-reviewed sections.Progress is tracked via question.md in the design document's directory (e.g., design-docs/xxx/question.md):
<!-- interview-progress: ["Overview", "Success Criteria", "Specification/Retry Strategy"] -->
<!-- interview-progress: [...] --> HTML comment is at the top of question.md (NOT in the design document).question.md is first written (after the Analyzer returns questions).question.md exists but the marker is absent, the interview is considered complete.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-foo/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, dir_path = ${BASE}, 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 dir_path to the canonicalized absolute task-folder path and doc_path = dir_path / "design-doc.md" (unless $ARGUMENTS already names design-doc.md, in which case use it verbatim and derive dir_path = dirname(doc_path)), and set ${BASE} to the <unset> sentinel so audit-file writes guard-skip per the cafleet-base-dir skill § The <unset> sentinel.
Read the design document at doc_path. If missing or empty, report the error and stop.
Run cafleet doctor. If it reports a problem, surface its message and stop.
{dir_path}/question.md state | Action |
|---|---|
| Does not exist | Fresh start. Proceed to Step 2 to spawn the Analyzer. Set SKIP_ANALYZER=false. |
Exists, no <!-- interview-progress: [...] --> marker | Interview already complete. Report completion and stop. |
| Exists with marker, all sections covered | Report completion. Stop. |
| Exists with marker, unanswered questions remain in the Questions section | Set SKIP_ANALYZER=true. Skip Step 2 and proceed to Step 3 with the unanswered questions parsed from question.md. |
| Exists with marker, all current questions answered but uncovered sections remain | Proceed to Step 2 to generate a new batch of questions for the next uncovered sections. Set SKIP_ANALYZER=false. |
In resume mode where Step 2 IS run, parse the JSON array from the existing interview-progress marker and pass it to the Analyzer as the list of already-reviewed sections.
Skip this step entirely when SKIP_ANALYZER=true (Step 1 found unanswered questions still in question.md from a prior invocation — the Director already has the question list).
cafleet fleet create --label "design-doc-interview-{slug}" --json
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.
BEFORE spawning the Analyzer, load both the cafleet-agent-team-monitoring skill and the cafleet-agent-team-supervision skill (in that order) for their heartbeat, Authorization-Scope Guard, idle semantics, and Stall Response policy. Then spawn the dedicated monitoring member as the first cafleet member create in the fleet, 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 Analyzer spawn (2d) — do not spawn the Analyzer until it 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 audit-file pattern in 2c, 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. The monitoring member is stopped and deleted first in the 2f teardown (first-out).
Resolve the absolute path of <this skill>/roles/analyzer.md. The spawn prompt below references it by absolute path; the spawned Analyzer opens it with Read on its first turn. Do NOT inline the role content — cafleet member create fails with tmux command failed: command too long once the shell-quoted prompt grows past a few KB. See skills/cafleet/reference/director.md § Spawn prompt size limit for the canonical write-up.
Spawn-prompt audit file: the spawn below writes the rendered prompt to
${BASE}/prompts/analyzer-<UTC-compact>.mdBEFORE invokingcafleet member create --prompt-file <abs path>. 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 Analyzer until the monitoring member's ready: monitor live handshake (2b) has arrived.
Render the canonical spawn-prompt skeleton with the Analyzer delta below ({fleet_id} / {agent_id} / {director_agent_id} filled by member create; [INSERT …] markers shell-substituted by the Director first):
| Slot | Analyzer |
|---|---|
| ROLE TITLE / TEAM | the Analyzer / design document interview |
| role-file | roles/analyzer.md |
| EXTRA SKILL LOADS | none (the cafleet skill only) |
| CONTEXT LINES | DESIGN DOCUMENT: [INSERT doc_path] + ALREADY-REVIEWED SECTIONS: [INSERT JSON array from interview-progress, or "none" on fresh start] |
| report-hint | your numbered question list |
| start cue (verbatim) | Read the design document, generate a numbered question list per the role definition, send it to the Director via cafleet message send, then idle pending shutdown. |
Render the prompt to ${BASE}/prompts/analyzer-<UTC-compact>.md per the 2c audit-file pattern (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 "Analyzer" \
--description "Reads the design doc and generates a numbered question list" \
--prompt-file ${BASE}/prompts/analyzer-<UTC-compact>.md
Parse agent_id from the JSON response and substitute it for <analyzer-agent-id> in every subsequent command.
Poll cafleet message poll --fleet-id <fleet-id> --agent-id <director-agent-id> --full until the Analyzer's reply arrives. The --full flag is required: cafleet message poll truncates each message body to 200 codepoints + … by default, which would silently mangle the Analyzer's numbered question list. Acknowledge with cafleet message ack --fleet-id <fleet-id> --agent-id <director-agent-id> --task-id <task-id>.
The reply must be a flat numbered list following the format specified in roles/analyzer.md, terminated by a Total: N questions line. If the Analyzer returns a malformed list, send a single corrective cafleet message send requesting the canonical format and wait again with cafleet message poll --full. After 2 corrective rounds, escalate to the user via AskUserQuestion (options: retry the Analyzer once more / abort the interview / proceed with the partial list).
The Analyzer is stateless and the heavy supervision work is done once its question list arrives — keeping either alive through the Q&A rounds wastes a pane. Run the canonical teardown per the cafleet skill § Shutdown Protocol immediately after the question list is received (first-out): stop the monitoring member's monitor start background task and wait for confirmation; cafleet member delete the monitoring member first, then the Analyzer (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>; cafleet fleet list to confirm.
question.mdFresh start (file does not exist): write {dir_path}/question.md per the § question.md Format below — interview-progress starts as an empty array [], the Questions section is a verbatim copy of the Analyzer's full numbered list, and the Answers section is initially empty.
Resume mode (file already exists, Step 1 sent us here for a new batch): do NOT overwrite the file. Append the new questions to the end of the existing Questions list, continuing the numbering from the last existing question (e.g., if the last question is #20, start the new batch at #21). This preserves prior Answers, progress, and stable question numbers for Step 3.
After persisting the question list (Step 2g) — or directly when SKIP_ANALYZER=true was set in Step 1 — the Director runs a deterministic round-counter loop.
Pre-loop setup:
question.md's Questions section.### Round X (Questions Y-Z) headings carry the question-number range).N.total_rounds = ceil(N / 4)."Starting interview: N questions, total_rounds rounds".Loop: for round = 1 to total_rounds:
AskUserQuestion with the batch, grouped by related topic when possible. Each question carries 2–4 options as supplied by the Analyzer. AskUserQuestion's built-in "Other" free-text option is always available.question.md's Answers section under a ### Round X (Questions Y-Z) heading."Completed round X of total_rounds (Y of N questions asked)".Mandatory completion rule (NON-NEGOTIABLE):
The Director MUST complete all rounds in the current invocation. Stopping before all questions are asked is FORBIDDEN. The only exception is the user explicitly using
AskUserQuestion's built-in "Other" option to request early termination — in that case proceed directly to Step 4 with the answers collected so far.
There is no "End interview" option. The user's escape hatch is the built-in "Other" free-text on any question.
Session termination:
| Condition | Next action |
|---|---|
All rounds completed (round = total_rounds) | Proceed to Step 4 |
| User requests early exit via "Other" | Proceed to Step 4 with answers collected so far |
COMMENT(claude): ... annotation inline in the design document, immediately before the relevant content (per § COMMENT(claude) Marker). Use Edit to insert each annotation.question.md: Append the section headings reviewed in this invocation to the JSON array inside <!-- interview-progress: [...] --> in question.md (NOT in the design document).<!-- interview-progress: [...] --> line from question.md entirely.Grep on the design document to confirm all intended COMMENT annotations were written.Present a summary to the user:
| Field | Content |
|---|---|
| Sections reviewed | List of section headings covered in this invocation |
| Discrepancies found | Count and brief list of each COMMENT added |
| Sections remaining | List of section headings not yet reviewed |
| Next step | See decision table below |
Next-step decision:
| State | Suggested next step |
|---|---|
| Sections remain (with or without COMMENT markers) | Re-invoke the cafleet-design-doc-interview skill with <doc-path> for the next session |
| All sections covered, COMMENT markers present in document | Invoke the cafleet-design-doc-create skill with <doc-path> to fix annotations (resume mode auto-detects markers and routes to the Drafter), then the cafleet-design-doc-execute skill |
| All sections covered, no COMMENT markers in document | Invoke the cafleet-design-doc-execute skill with <doc-path> to implement |
question.md Format<!-- interview-progress: ["Overview", "Specification/Retry Strategy"] -->
## Questions
1. [Section: Specification/Retry Strategy] Should the maximum retries be 3 or 5? | Options: A) 3 (current) B) 5 C) Configurable
2. [Section: Specification/Logging] Should failed requests be logged for debugging? | Options: A) Log all failures B) Log only final failure
...
## Answers
### Round 1 (Questions 1-4)
1. B) 5 — confirmed by user
2. A) Log all failures
...
$ARGUMENTS
npx claudepluginhub himkt/cafleet --plugin cafleetCreates design documents using CAFleet-native orchestration with Director/Drafter/Reviewer team. Invoke when user requests a design doc, specification, or technical spec.
Reviews requirements and plan documents using parallel persona agents to surface role-specific issues, auto-fix quality problems, and pose strategic questions.
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.