Plan

Progress Contract

Register these steps as a native task list at Step 2, before beginning exploration. 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-project-context, (2) register-progress, (3) explore, (4) author-plan, (5) plan-self-review, (6) assumption-gate, (7) save-and-register.

Arguments

• <task description> — what to plan. If .claude/octo/specs/ contains a spec for this work (or the user names one explicitly), the plan MUST consume it: load the spec before exploration, carry every ## Assumptions item forward into the plan's own Assumptions section, and ensure every spec requirement maps to at least one Implementation Step.

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.
• Offer to scaffold a minimal CLAUDE.md and wait for the user's answer before proceeding.
• Detect what you can from repo artifacts (lockfiles, Makefile, pyproject.toml, CI config, package.json). Label every inferred convention [DETECTED].

Step 2 — Register progress

Create the native task list for this session (all seven steps). This is the single source of truth for human-visible progress — do not maintain a separate running log.

Step 3 — Explore

Division of labor: this skill owns orchestration, gates, and file I/O. The architect agent owns thinking and plan text. Do not duplicate architect reasoning here.

Partition the codebase into disjoint domains. Dispatch up to 10 parallel Explore or architect subagents in a single message (one tool-use block per agent) — this MUST be a single message; serial exploration when parallel dispatch is possible is a defect, not a style choice.

Retry rule: if a subagent returns empty or contradictory findings, retry it once with a narrower scope. After one retry, report the gap in ## Open Questions rather than blocking.

If two subagents return contradictory findings about the same area, surface the conflict in Open Questions — never resolve it silently.

Step 4 — Author the plan

Dispatch the architect agent with the task description, all exploration findings, any relevant spec from .claude/octo/specs/, and any lessons from .claude/octo/lessons/*.md. The architect produces:

1. Context — what was read and explored; which lessons were relevant; which spec (if any) was consumed.
2. Design — approach, architecture decisions, trade-offs.
3. Implementation Steps — numbered, atomic; each step MUST include:
   • Exact file paths for every file to be created or modified.
   • TDD steps in order: write failing test → run to confirm it fails → implement minimally → run to confirm it passes → commit with a conventional message.
   • Interfaces: block — consumes and produces, with exact names and signatures so the task can be executed by a fresh agent without reading sibling tasks.
   • Verification command with expected output — a command that, when run after the task, confirms it is complete.
   • No-placeholders rule: TBD, "add error handling", "similar to task N", or steps without concrete content are plan defects. Every step must have complete, actionable content.
4. API/Schema Checklist (when applicable).
5. ## Assumptions — every non-obvious decision marked SAFE or RISKY; if a spec was consumed, all spec Assumptions are carried here verbatim.
6. ## Open Questions — specific questions with who owns the answer and what the plan does in each case.

Do not restate the architect's output — use it verbatim as the plan body.

Step 5 — Plan self-review

Before presenting the assumption gate, scan the plan for defects:

1. Spec coverage (if a spec was consumed) — every spec requirement maps to at least one numbered Implementation Step; flag any requirement without a matching step.
2. Placeholder scan — no TBD, TODO, "add error handling", "similar to task N", or blank acceptance criteria anywhere in the Implementation Steps.
3. Interface consistency — the Interfaces: block of each step lists outputs that are consumed by later steps; verify names and signatures are consistent across the chain.

Fix all defects inline before proceeding. Do not present the assumption gate over a plan that fails any of these checks.

Step 6 — Assumption gate ← STOP

Scan the ## Assumptions section for any item marked RISKY where the consequence is also hard to reverse (e.g. schema migrations, public API removals, irreversible data transforms).

If any such item exists: STOP. Do not save the plan. Present RISKY assumptions via AskUserQuestion: one question per assumption, the options being the concrete alternatives (recommended option first, labeled '(Recommended)'); never a prose wall. Wait for answers. Update the plan's Assumptions and Open Questions accordingly, then continue to Step 7.

If no RISKY + hard-to-reverse items exist, proceed immediately.

Step 7 — Save and register

1. Derive the slug: lower-case the task title, replace spaces and special characters with -, collapse runs of -. Example: "Add OAuth flow" → add-oauth-flow.

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

3. Register .claude/plans/ and .claude/octo/ in .git/info/exclude: read the file (create the file if it does not exist), append each line only if it is not already present. Never modify the project's .gitignore.

4. Report the saved path and the total step count to the user.

---

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.