Spec

Progress Contract

Register these steps as a native task list at Step 1, before beginning the interview. Report progress as "N steps remaining, size class S/M/L" — never wall-clock ETAs.

Register steps in the native task list named 🐙 <n>/<total> — <step name>; update each to in_progress/completed as you go — the checklist is the user's primary progress view.

Steps: (1) read-context, (2) scope-check, (3) interview, (4) draft-spec, (5) self-review, (6) save-spec, (7) await-approval.

Arguments

• <idea> — the feature, system, or change to design. Free-form; keep it concise. /octo:spec translates it into a full design doc before any planning begins.

Workflow

Step 1 — Read project context

Read the host project's CLAUDE.md. If it is absent or missing a needed section:

• State what is missing explicitly.
• Continue with defaults — do not block on scaffolding.
• Detect what you can from repo artifacts (lockfiles, Makefile, pyproject.toml, CI config, package.json). Label every inferred convention [DETECTED].

Step 2 — Scope check

Assess whether the idea spans multiple independent subsystems (e.g. a new API endpoint, a background worker, and a schema migration that could each be specced and planned separately).

If yes: state the decomposition explicitly and propose the breakdown FIRST — list the sub-specs as distinct items and ask which to tackle first (via AskUserQuestion, options = each sub-spec + "All of them in order (Recommended)"). Do not proceed past this step without a scoping decision.

If no: proceed to Step 3 immediately.

Step 3 — Interview

Conduct a one-question-at-a-time interview to gather enough context to write a complete, unambiguous spec. Cover: purpose, users or consumers, constraints (perf, security, platform), success criteria, and non-goals.

Question discipline:

• Ask exactly ONE question per exchange — never bundle multiple questions.
• Prefer AskUserQuestion wherever choices are enumerable: 2–4 concrete options, recommended first and labeled "(Recommended)", free prose only for genuinely open-ended questions.
• Stop when marginal questions stop changing the design (typically 4–8 questions total).
• If the user's answer resolves two pending questions at once, skip the resolved one.

Step 4 — Draft the spec

Write the spec with these sections, sized to their actual complexity (YAGNI — omit sections that are genuinely N/A rather than padding them):

• Summary — one paragraph; what this is and why it matters.
• Goals & Non-goals — bullet lists; non-goals are as important as goals.
• Architecture — components, boundaries, major dependencies; diagram in prose or ASCII.
• Data flow — how data enters, transforms, and exits the system; happy path + key edge cases.
• Error handling — failure modes, retry strategy, degraded-state behavior.
• Testing approach — unit / integration / e2e breakdown; what a passing test suite proves.
• ## Assumptions — every non-obvious decision, each labeled SAFE or RISKY.
• ## Open Questions — items that need resolution before or during implementation, with who owns the answer.

Step 5 — Self-review pass

Before saving, scan the draft for:

1. Placeholder scan — no TBD, TODO, "to be defined", or blank sections.
2. Internal contradictions — does any section contradict another? Fix inline.
3. Scope creep — does the spec describe more than the agreed idea? Trim.
4. Ambiguity check — would a fresh implementer have to guess at any decision? Clarify.

Fix all issues inline. Do not save a draft that fails any of these checks.

Step 6 — Save spec

1. Derive the slug: lower-case the idea, replace spaces and special characters with -, collapse runs of -. Example: "OAuth token refresh flow" → oauth-token-refresh-flow.

2. Write the spec to .claude/octo/specs/YYYY-MM-DD-<slug>.md using today's date.

3. Register .claude/octo/ in .git/info/exclude: read the file (create if absent), append the line .claude/octo/ only if it is not already present. Never modify the project's .gitignore. State this to the user.

4. Report the saved path.

Step 7 — Await approval ← STOP

Present a brief summary: spec title, section count, key architectural decisions, and any RISKY assumptions that will need resolution before or during planning.

STOP. Use AskUserQuestion: "Spec saved — ready to plan?" with options:

• Run /octo:plan with this spec (Recommended)
• Revise a section first
• Stop here

On approval, offer /octo:plan and tell it to consume the spec at .claude/octo/specs/YYYY-MM-DD-<slug>.md — plan carries the spec's Assumptions forward.

---

Parallel-first law

Where interview questions do not depend on each other's answers, batch them into a single AskUserQuestion multiSelect rather than sequential single-question exchanges. Where spec sections can be drafted independently (e.g. Error handling and Testing approach share no content), draft them in parallel sub-tasks rather than sequentially.

---

Shared Conventions

• Commits: conventional format type(scope): brief description — no AI attribution, no Co-Authored-By lines of any kind.
• Never push directly to protected branches (protected branches — see the octo guard's list).
• Never use --no-verify or force-push.
• Parallel-first: dispatches that do not consume each other's output MUST go in a single message. Dispatching sequentially what could run concurrently is a defect, not a style choice. Cap ≈10 concurrent lanes; more work than lanes → batch waves.
• Reader-first output: lead with the outcome in one sentence; keep the visible reply short and dev-readable — only what changes the reader's next action. Full detail (complete reports, evidence, logs) goes to a file under .claude/octo/reports/YYYY-MM-DD-<skill>-<slug>.md with the path given in chat — never dumped into the conversation.