Cafleet Design Doc Create

Additional resources

• For the document template, see: ../cafleet-design-doc/template.md
• For section guidelines and quality standards, see: ../cafleet-design-doc/guidelines.md

Architecture

The Director registers with a CAFleet session 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 register, 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)

• Director ↔ User: AskUserQuestion (clarification relay, draft presentation, feedback collection)
• Director ↔ Drafter: cafleet send (questions relay, user answers, reviewer feedback, drafting instructions)
• Director ↔ Reviewer: cafleet send (draft review requests, review feedback)
• Members receive messages via a push notification: the broker injects cafleet --session-id <session-id> poll --agent-id <recipient-agent-id> into the member's pane via tmux send-keys whenever a cafleet send is persisted. The literal <session-id> and <recipient-agent-id> UUIDs are the session and target member UUIDs the broker has in scope, baked into the injected command string. --session-id is global (before the subcommand); --agent-id is per-subcommand (after the subcommand name).

Prerequisites

The Director MUST be running inside a tmux session (required by cafleet member create). If TMUX is not set, abort with an explanatory message to the user before spawning anyone.

Primitive Mapping

Process

Step 0: Path Resolution & Resume Detection (Director)

Path resolution (before resume detection):

Load Skill(base-dir) and follow its procedure with $ARGUMENTS as the argument.

• If skipped (absolute path): set ${DOC_PATH} = $ARGUMENTS.
• If base resolved: set ${DOC_PATH} = ${BASE}/design-docs/$ARGUMENTS. Resolve to absolute path.

Pass ${DOC_PATH} to the Drafter as OUTPUT PATH in the spawn prompt.

Resume detection (using resolved ${DOC_PATH}):

1. File does not exist → Fresh creation (proceed to Step 1 as normal).
2. File exists → Check for COMMENT markers:
   • Use Grep to search for COMMENT( in the file.
   • COMMENT 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 markers found → Inform the user: "No COMMENT markers found in the existing document." Use AskUserQuestion with two options:
     • "Run quality review": Set internal flags 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 send (no new draft is produced; the Drafter is only involved later if the Reviewer requests revisions).
     • "Start fresh": Treat as new creation, ignoring the existing file. Ensure SKIP_CLARIFICATION and QUALITY_REVIEW_ONLY are unset, then proceed to Step 1 as normal.

Step 1: Register & Spawn Members (Director)

Load Skill(cafleet) and Skill(cafleet-monitoring).

1a. Establish a CAFleet session and capture the root Director's agent_id

cafleet session create (which must be run inside a tmux session) atomically creates the session and registers a root Director bound to the current tmux pane — there is no separate cafleet register step for the Director. Use --json so both IDs are machine-parseable:

cafleet session create --label "design-doc-create-{slug}" --json
# → {
#     "session_id": "550e8400-e29b-41d4-a716-446655440000",
#     "label": "design-doc-create-{slug}",
#     "created_at": "…",
#     "administrator_agent_id": "…",
#     "director": {
#       "agent_id": "7ba91234-…",
#       "name": "director",
#       "description": "Root Director for this session",
#       "registered_at": "…",
#       "placement": { "director_agent_id": null, "tmux_session": "…", "tmux_window_id": "…", "tmux_pane_id": "…", "coding_agent": "unknown", "created_at": "…" }
#     }
#   }

Capture session_id and director.agent_id from the JSON response. Substitute them for <session-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 UUIDs.

If you already have a running session (e.g. an outer orchestration), reuse its session_id and its root Director's agent_id instead of creating a new session. Do not attempt to register a second Director with cafleet register --name Director — the root Director from session create is the team lead; a second registration would just create an unrelated agent with no placement row.

1c. Start the monitoring /loop

BEFORE spawning any member, follow Skill(cafleet-monitoring)'s Monitoring Mandate and start a /loop monitor at the 1-minute interval using the literal <session-id> and <director-agent-id> UUIDs. The loop must stay active from the first member create until Step 6's shutdown cleanup.

1d. Read role definitions

Read the role files that will be embedded verbatim in spawn prompts:

• .claude/skills/cafleet-design-doc-create/roles/drafter.md
• .claude/skills/cafleet-design-doc-create/roles/reviewer.md

1e. Spawn the Drafter

Drafter spawn prompt (normal mode):

When constructing the prompt, substitute the literal <session-id> and <director-agent-id> UUIDs for the placeholders below. The new member's own <my-agent-id> will be allocated by member create and baked into the spawn prompt automatically by the coding_agent.py template — _resolve_prompt now runs str.format() on BOTH the default template AND any user-supplied custom prompt, so {session_id} / {agent_id} / {director_name} / {director_agent_id} placeholders are substituted either way. See the Template safety note under Member Create in .claude/skills/cafleet/SKILL.md — any literal { / } in a custom prompt must be doubled ({{ / }}), because the prompt is passed through .format() even when it contains no placeholders. Pre-substituting the dynamic placeholder values in shell is separate and does NOT remove the need to escape literal braces.

You are the Drafter in a design document creation team (CAFleet-native).

<ROLE DEFINITION>
[Content of roles/drafter.md injected here verbatim]
</ROLE DEFINITION>

Load these skills at startup:
- Skill(cafleet) — for communication with the Director
- Skill(cafleet-design-doc) — for template and guidelines

SESSION ID: <session-id>
DIRECTOR AGENT ID: <director-agent-id>
YOUR AGENT ID: <my-agent-id>     (will be filled in literally by member create)
OUTPUT PATH: [INSERT ${DOC_PATH}]

The user's request: [INSERT USER'S ORIGINAL REQUEST]

COMMUNICATION PROTOCOL:
- Report to Director: cafleet --session-id <session-id> send --agent-id <my-agent-id> --to <director-agent-id> --text "your report"
- When you see cafleet poll output with a message from the Director, act on those instructions.

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.

Drafter spawn prompt (resume mode):

Use this instead when Step 0 detected resume mode:

You are the Drafter in a design document creation team (CAFleet-native, RESUME MODE).

<ROLE DEFINITION>
[Content of roles/drafter.md injected here verbatim]
</ROLE DEFINITION>

Load these skills at startup:
- Skill(cafleet) — for communication with the Director
- Skill(cafleet-design-doc) — for template and guidelines

SESSION ID: <session-id>
DIRECTOR AGENT ID: <director-agent-id>
YOUR AGENT ID: <my-agent-id>
DESIGN DOCUMENT: [INSERT ${DOC_PATH}]

COMMUNICATION PROTOCOL:
- Report to Director: cafleet --session-id <session-id> send --agent-id <my-agent-id> --to <director-agent-id> --text "your report"
- When you see cafleet poll output with a message from the Director, act on those instructions.

This is a RESUME session. 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.

Spawn with:

cafleet --session-id <session-id> --json member create --agent-id <director-agent-id> \
  --name "Drafter" \
  --description "Writes and revises the design document" \
  -- "<Drafter spawn prompt (embedded role content)>"

Parse agent_id from the JSON response and substitute it for <drafter-agent-id> in every subsequent command.

1f. Spawn the Reviewer

Reviewer spawn prompt:

You are the Reviewer in a design document creation team (CAFleet-native).

<ROLE DEFINITION>
[Content of roles/reviewer.md injected here verbatim]
</ROLE DEFINITION>

Load these skills at startup:
- Skill(cafleet) — for communication with the Director
- Skill(cafleet-design-doc) — for template and guidelines

SESSION ID: <session-id>
DIRECTOR AGENT ID: <director-agent-id>
YOUR AGENT ID: <my-agent-id>

COMMUNICATION PROTOCOL:
- Report to Director: cafleet --session-id <session-id> send --agent-id <my-agent-id> --to <director-agent-id> --text "your report"
- When you see cafleet poll output with a message from the Director, act on those instructions.

Wait for the Director to assign a document for review. Read the document file and
provide specific, actionable feedback. If the draft meets all quality standards,