plan-init

name	plan-init
description	Guide the creation of a new project plan.md through a structured conversation. Asks the right questions up front — stack, auth, data storage, async patterns, build tooling, UI — before writing anything. Use at the start of any new project to avoid mid-plan discovery of architectural gaps.
user-invocable	true

Plan Init

Run a structured planning conversation and produce a complete plan.md for a new project. The goal is to surface all architectural decisions before writing the plan, so the document is correct on the first pass rather than requiring a review cycle to patch gaps.

Greenfield check

Before walking through the 7 conversation phases, confirm this is a greenfield project. Run git log --oneline | head -1 in the project directory — if it returns any commit, STOP and recommend /plan-feature instead. /plan-feature reads the existing codebase before drafting; /plan-init does not, and using it on a project with committed code risks proposing data models that conflict with the live schema (Phase 2 entities, Phase 4 stack choices get answered from imagination rather than from the existing producing files — see plan-init deep-dive investigation #17). /plan-init is for wholly new projects with no committed code, no schema, and no existing module structure. If uncertain (e.g., the directory has stray files but no real codebase), ask the operator to confirm "greenfield" before proceeding.

Pipeline position

/plan-init is Step 1 of the plan pipeline: plan-init or plan-feature → plan-review → plan-wrap → repo-sync → build-phase. Always run /plan-review and /plan-wrap on the produced plan BEFORE /repo-sync mints GitHub issues — a gap caught after sync is an N+1-edit problem (1 plan-doc fix + N issue-body edits in GitHub to keep the sync intact), whereas the same gap caught pre-sync is a single plan edit. /plan-expedite is the autonomous pre-flight meta-skill that chains plan-review-autofix → plan-wrap-autofix → repo-sync → session-wrap so /build-phase gets a clean, sync'd plan to walk; operators in autonomous mode should invoke /plan-expedite --plan <path> immediately after /plan-init finishes. Close every /plan-init session by surfacing the next step explicitly to the operator — e.g., "Plan written to . Next: run /plan-expedite --plan <path> to auto-prep, or /plan-review if you want manual review first."

Conversation phases

Work through these phases in order. Ask the questions as a conversation — not all at once. Group related questions together. Listen for implied answers (e.g. "it's a local tool" implies no cloud deployment, no multi-user auth). Do not ask questions the user has already answered.

If the user front-loads many answers in their first message, still walk through every phase explicitly: summarize what you understood for that phase, confirm it, and ask about any gaps. This ensures all 7 phases are covered even when the user provides a dense initial description.

---

Phase 1 — Purpose and scope

• What does this project do in one sentence?
• Who uses it (just you, a small team, public users)?
• Is this a local tool, a hosted service, or a CLI?
• What is explicitly out of scope for the first version?

---

Phase 2 — Data

• What entities does the system create or track? (jobs, users, documents, events…)
• How is each entity identified? (UUID, hash, slug, file path, composite key…) Pin down a concrete format — never leave IDs as generic placeholders.
• Where does that data live? (flat files, SQLite, Postgres, in-memory, external API…)
• Does any data come from an external source? If so, what and how (API, scrape, upload)?
• How should the system handle duplicate or re-processed data?
• Are there any files the user provides as input (JSON, CSV, audio, video)?

---

Phase 3 — AI and external services

• Does this project call any AI models? Which ones?
• How is auth handled for those services? (API key, OAuth token, subscription CLI…)
• Are there any other third-party APIs or services involved?
• What happens if an external service is unavailable or returns an error?

---

Phase 4 — Stack and build

• What language(s) and runtime(s)?
• Frontend: web UI, CLI, none? If web — framework preference?
• Backend: needed? If so — framework preference?
• How should the project be tested? (unit, integration, e2e — which matter most?)
• Any existing tooling or patterns from other projects to reuse?
• Read producing files first for any external artifact the plan will reference (library API, third-party CLI flag, sibling skill's SKILL.md, cross-project schema) — quote real values verbatim into the plan, don't trust docs or memory.

---

Phase 5 — Async and concurrency

• Are there any long-running operations (crawls, AI calls, file processing, uploads)?
• Should those run in the background while the user does other things?
• If yes — how does the user know when they're done? (polling, notification, progress bar…)
• Does this system run autonomously, on a schedule, or in any "always-on" mode? If yes, ask the end-to-end validation follow-ups:
  • How will you know the autonomous loop works end-to-end, not just that each component passes unit tests? (Unit tests prove components work in isolation, not together over time.)
  • Will there be a deliberate observation phase where the full system runs with realistic inputs for long enough to expose time-dependent behavior (memory leaks, cumulative drift, alert thresholds, race conditions, scheduled-task triggers firing wrong — invisible to short test runs)?
  • If the answer is "we'll just run it after we're done and see," surface that as an explicit build step (e.g. "Step N: Soak test — run for 4 hours, observe, document findings") so it cannot be skipped.
  • This applies to any cron job, watcher, polling loop, or scheduled task — not just AI projects.

---

Phase 6 — Auth and secrets

• Does the app have any concept of user login or sessions?
• What secrets does it need (API keys, tokens, passwords)?
• How should secrets be stored and loaded?

---

Phase 7 — Development process

• Should this use /build-phase (multi-step orchestrator) for building?
• For each step, what /build-step flags make sense?

  • --isolation: worktree (default, fast) or docker (clean-room isolation)

  • --reviewers: Default: --reviewers code for build steps. --reviewers code runs the 4-agent code-review gauntlet (correctness, bugs, test quality, style) plus automated typecheck / lint / test gates — safe and fast for backend, library, and pure-docs / JSON changes. Escalate only when the step has a real runtime/UI surface to validate. Values:

    • code (default) — 4-agent diff review + gates. Use for backend logic, libraries, docs, scripts, JSON / YAML config edits, and unit-test-only changes.
    • runtime — 3 evidence-based agents (UI / backend / frontend). Requires --start-cmd + --url. Use when the step changes visible UI behavior with no backend logic.
    • full — all 7 agents (4 code + 3 runtime). Requires --start-cmd
      • --url. Use for full-stack steps spanning backend logic AND visible UI in the same change.
    • auto — gates only (no agent reviewers). Use for fast scaffolds or mechanical wiring where the test suite is the entire reviewer.
    • Auth-gate downgrade: if a step's --url points behind a PIN, login screen, session-bound token, or any auth flow a fresh Playwright session cannot satisfy, DOWNGRADE from runtime / full to code — the runtime reviewers cannot reach the URL, every screenshot shows the gate not the feature, and the step enters silent false-pass mode (Toybox K17 wasted ~50 minutes before the PIN gate was identified). Pair with --exercise-cmd that injects auth state (e.g., a Playwright snippet that does localStorage.setItem('PIN', '1234') before evidence capture) ONLY if such a script exists; otherwise downgrade.

    Rationale: .claude/rules/plan-and-issue-flow.md § Reviewer flag must match step shape (anchors: feedback_plan_reviewer_flags.md, feedback_runtime_reviewers_skip_on_auth_gated_substrate.md).

  • --ui: add if the step needs Playwright screenshots/evidence

---

After the conversation

Once phases 1–7 are complete, produce plan.md with these sections. Every numbered section below is required — adapt the depth, not the presence. For example, a CLI tool with no database still gets a Data Store section describing how it reads and writes data (filesystem layout, file formats). Only section 4 (domain-specific) and section 6 (API Route Contract) may be omitted when genuinely not applicable.

1. What This Is — one-paragraph description

2. Stack — table of layer / tool / why

3. Data Store — schema, file layout, deduplication, corruption protection

4. [Domain-specific sections] — e.g. Candidate Profile, Core Loop, etc.

5. Modules — one subsection per src/ directory with file-level descriptions

6. API Route Contract — full table if there is a backend API

7. Project Structure — annotated directory tree

8. Key Design Decisions — one paragraph per major decision with rationale

9. Open Questions / Risks — table with item / risk / mitigation

10. How to Run — step-by-step quickstart from clone to working app

11. Development Process — describe the build approach (e.g. /build-phase

    • /build-step flags, reviewer gates, isolation choices), then list the ordered build steps in /build-phase-compatible format:

    ### Step N: <name>
    - **Problem:** <what to build or fix — becomes the --problem arg>
    - **Type:** code | operator | wait | conditional   (default "code", omit if code)
    - **Condition:** <shell-expression>   (required when Type: conditional — see below)
    - **Issue:** #<N> (leave blank — created later by /repo-init or /repo-sync)
    - **Flags:** <build-step flags, e.g. --reviewers code --isolation worktree>
    - **Produces:** <files, behavior>
    - **Done when:** <specific test or verification>
    - **Depends on:** <step numbers, or "none">
    

    If no flags are needed, omit the Flags line (build-step defaults apply). Size each step as one vertical slice (../../references/step-authoring.md §1). Phrase Done when: however makes it falsifiable — EARS (WHEN … SHALL …) and Given/When/Then are OPTIONAL examples (../../references/step-authoring.md §2), never required grammar. Use Type: operator for manual smoke tests / observation work that won't produce a code diff. Use Type: wait for long-wall-clock observation steps (soak tests, benchmarks). Use Type: conditional for steps that only run if a predicate from a prior step is true.

    steps must not produce code artifacts. If a step is declared , its field must NOT include code-shaped artifacts:

Quality bar before saving

Before writing the file, verify:

• Every "X or Y" choice from the conversation is resolved to a single answer with rationale.
• Every entity has a defined ID format (UUID, hash, slug — not just <id>).
• Every external file or schema referenced in the plan is summarized inline.
• Every reference to an external artifact — a library API, third-party tool CLI, sibling skill's SKILL.md, or shared schema from another workspace project — was sourced by reading the producing file verbatim, not from docs or memory. Quote the actual value (the real CLI flag, the real schema field name, the real package.json script) into the plan with a file-path citation, or mark it as TBD if unknown. Even on greenfield projects, plans typically reference at least a few existing artifacts the project will reuse — those references must come from the producing file. Rationale: .claude/rules/plan-and-issue-flow.md § Read producers before drafting plan content + feedback_plan_read_producer_first.md.
• A fresh model with no conversation history could read the plan and start building.
• If the project has any autonomous, scheduled, background, or "always-on" behavior, the Build Steps section includes at least one explicit step dedicated to end-to-end observation (run the system for a target duration, capture findings, triage). Unit tests on each component are not enough for systems whose value depends on running unattended. If Phase 5 surfaced autonomous behavior but the build steps are all component-implementation steps with no observation phase, add one before saving. This rule has NO per-request escape hatch. If Phase 5 surfaced any background work — even per-request task offload (FastAPI BackgroundTasks, Celery .delay(), RQ enqueue, asyncio.create_task fire-and-forget, thread-pool submit) — the plan STILL needs a dedicated end-to-end observation step. For always-on / scheduled work, name it e.g. "Step N: Soak test — run for 4 hours, capture findings". For per-request background work, name it e.g. "Step N: Observation run — exercise the background task happy path AND error path end-to-end (10 real invocations), capture timing + failure findings" with a target duration (e.g. 15 minutes) and a capture findings deliverable. The step must be DISTINCT from any component-implementation step — not folded into a "build the worker" step's Done when:. Rationale: per-request background tasks still hide time-dependent failures (queue backpressure, task cancellation on shutdown, silent exception-swallowing inside the executor) that unit tests on the producer endpoint miss.
• If the project has a data pipeline (producer → consumer chains, schema-bound storage, env→model→storage flows, or any "the dimensions/shape/columns must agree across modules" coupling), the Build Steps section includes at least one explicit smoke-gate step BEFORE any long-running observation step. A smoke gate is a 60-second end-to-end run with REAL components wired together (no mocks), exercised just enough to surface producer/consumer drift. It is NOT the same as the observation phase — observation phases are hours long and document behavior; smoke gates are seconds long and surface schema/shape/wiring bugs that unit tests with mocks miss because each test mocks the boundary it would have asserted on. Example: "start the service, send 1 real request, assert no exception." Mark with if it requires manual setup, otherwise with a shell-script test. The smoke gate's deliverable is "the pipeline can complete one real cycle without crashing" — pass/fail of any business logic is out of scope.

Run /plan-wrap on the draft before saving if any of the above is uncertain.

---

After plan.md exists — bootstrap CLAUDE.md

A fresh project also needs a CLAUDE.md so any future session opens with the right context without having to re-derive stack, layout, and commands from scratch. Write one immediately after saving plan.md (skip if a CLAUDE.md already exists — the user already owns the file).

Include all seven sections. Pull values directly from the plan conversation — every field below has an answer from phases 1–7.

1. Project overview — one or two sentences from Phase 1 (purpose + scope).
2. Stack summary — table from the plan's "Stack" section (Phase 4).
3. Key commands — install / run / test / lint / typecheck. Use the actual commands for the chosen tooling (e.g., uv sync, uv run pytest, ruff check, mypy). Don't write placeholders.
4. Directory layout — annotated tree matching the plan's "Project Structure" section.
5. Architecture summary — layers, key modules, patterns. One paragraph per layer, max.
6. Current state — at bootstrap this is "Plan written, no code yet." Update at the end of each phase via /repo-update.
7. Environment requirements — OS, runtimes, external services (SC2, Docker, specific Python/Node versions, API keys). Anything that would block a fresh clone from running the project.

Save to CLAUDE.md at the project root.

Report at the end of plan-init: "plan.md written (N sections) · CLAUDE.md bootstrapped (7 sections)".

---

dev-observatory hook (additive; see .claude/rules/descriptor-contract.md)

On creating a new owned project, register it with the control plane so its ownership + tier become real (until registered, dev-observatory treats a tree as owned=false/write-blocked):

uv run --project dev-observatory observatory register <slug> --owned --path <rel-path>

Keep the new CLAUDE.md's ## Commands/## Stack/port mentions scrapable and the plan's objective clearly labeled (a ## 1. What This Is section) so dev-observatory's verb + goal-vs-reality scrape works.