Stage: intake

Runtime config (canonical): workflow.json → stages.intake

Purpose: Read the project's root docs (README, CLAUDE.md, AGENTS.md, top-level layout) and confirm the user's "unknown" — the research question this run will answer. Output is a compact briefing that downstream stages use as their shared context. Output artifact: write to the absolute path provided in your I/O context Valid results this stage writes: pending (briefing in progress, awaiting user confirmation), ready (user has confirmed the unknown and the briefing is final)

This is an interruptible stage — the stop hook allows natural pauses for Q&A while you confirm the unknown with the user.

By the time you read this file, state.md already exists with status: intake and epoch is set. The bootstrap (topic name, setup-workflow.sh) ran before this stage starts.

Step 1 — Read state and write a pending artifact immediately

Read state.md for the current epoch. Then immediately write the output artifact (at the path shown in your I/O context) with:

This signals to the stop hook that the stage is mid-flight while you Q&A with the user.

Step 2 — Read the project root docs

Use the repo_root run file (path shown in your I/O context) as the search base. Read whichever of these exist:

• README.md / README (top-level)
• CLAUDE.md
• AGENTS.md
• package.json / pyproject.toml / go.mod / Cargo.toml (whatever signals the language + framework)
• The top-level directory listing — names only, one level deep

Skim, don't deep-read — you're building a one-paragraph orientation, not a full audit.

Step 3 — Confirm the unknown with the user

Surface what you understood from the root docs in 2–4 sentences, then ask the user to state (or confirm) the unknown they want researched.

Inline Q&A is allowed — keep it tight:

• One question per message; multiple choice (A/B/C) when reasonable
• Typical exchange: 1–3 turns total
• Goal: a single sentence stating the unknown, plus 1–3 bullets of scope/constraints if the user wants to narrow it

Examples of good unknowns:

• "How does an incoming HTTP request flow from the edge through to the database response?"
• "Where is auth state stored, and how does it propagate across services?"
• "What is the lifecycle of a background job from enqueue to completion?"

Step 4 — Write the final briefing

Once the user has confirmed the unknown, overwrite the artifact:

---
epoch: <epoch>
result: ready
---
# Intake Briefing

## Repo orientation
- Repo root: <absolute path from repo_root run file>
- Stack: <language/framework one-liner>
- Top-level layout: <comma-separated list of notable top-level dirs>
- Root docs read: <comma-separated list of README/CLAUDE/AGENTS files actually present>

## Project summary
<2–4 sentences synthesised from the root docs — what this project is, who uses it, what its main pieces are. Lifted as shared context by downstream stages.>

## The unknown
<One sentence — the research question, in the user's words or as agreed during Q&A.>

## Scope and constraints
- <bullet — e.g. "focus on the web frontend, ignore the mobile app">
- <bullet — e.g. "out of scope: deployment infrastructure">
- <bullet — or "none">

## Suggested entry points
<Optional: 2–5 file paths or symbol names that look like good starting points based on the root-doc skim. Subagents may ignore these and pick their own.>

Rules

• Read each required input from the path shown in your I/O context — never construct or hardcode paths.
• Do NOT call update-status.sh from this stage. The main loop reads result: and advances the state machine.
• Do NOT start research yourself — your job is to confirm the unknown and write the briefing. The actual work happens in decompose/investigate.
• If the user is ambiguous about what they want, keep result: pending and keep asking. Only flip to result: ready once you have a single-sentence unknown the user has confirmed.