Plan Init

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 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 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
• What are the natural step boundaries? (Size each step as one vertical slice — see ../../references/step-authoring.md §1; don't over-split a coherent slice.)
• **Are there any manual checks, observation periods, or operator-driven

verifications that must happen AFTER the automated build steps complete?** (E.g., visual UI spot-checks against a real client; a soak test the operator runs unattended; integration testing against a live external service.) Surfacing these up-front lets the produced plan split its Build Steps into labeled Automated Steps + Manual Steps subsections from the first draft, with named M1/M2/M3 handoff entries — rather than mixing operator/wait steps into the automated numbering and forcing a re-shape later. All-automated plans skip the split. See output spec section 11 below for the template.

• For any step identified as Type: conditional (i.e. only runs if a predicate

from a prior step is true), ask the operator: "What shell command can the orchestrator run to decide whether this step should execute? (Exit 0 → run; non-zero → skip. Use bash syntax — predicates are evaluated via bash -c \"\".) If you don't know yet, I'll write a placeholder you can fill in later." The answer becomes the step's **Condition:** value. If the operator does not yet know, write the placeholder described in the plan-format section below rather than omitting the field.

---

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:

• Problem:
• Type: code | operator | wait | conditional (default "code", omit if code)
• Condition: (required when Type: conditional — see below)
• Issue: # (leave blank — created later by /repo-init or /repo-sync)
• Flags:
• Produces:
• Done when:
• Depends on:

`` 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.

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

• .py, .ts, .tsx, .js, .sh, .rs, .go source files
• .json, .yaml, .toml configs shipped in src/ or scripts/ or any

package directory the project's build tooling reads

• .md ops docs that depend on code-state (under documentation/operator/

or similar)

If a step would naturally produce both an operator action AND a code artifact, SPLIT into two adjacent steps: N-prep (Type: code) authors the artifact via the standard /build-step flow, and N (Type: operator) runs the manual checks. Symmetric inverse: if a step is declared Type: code but its Done when: field requires an operator visual review or manual confirmation (e.g., "operator visually reviews", "operator runs and confirms", "operator inspects output"), apply the same split in reverse — N-prep (Type: code) covers the automatable portion and N (Type: operator) covers the manual verification. Otherwise /build-phase halts mid-run asking the operator to do code/operator work the plan didn't budget for.

Split pattern:

```markdown ### Step N-prep:

• Problem:
• Type: code
• Produces:
• Done when:

### Step N:

• Problem:
• Type: operator
• Produces:
• Done when:

```

Step field reference — **Condition:**:

• Condition: ` — required when Type: conditional`.

Build-phase evaluates this predicate via bash -c "" at step-dispatch time. Exit 0 → run the step; non-zero → skip with Status: SKIPPED (condition false). Steps with Type: conditional lacking this field are pre-flight Blockers caught by /plan-review §23 and /plan-wrap §12.

Worked example of a conditional step:

```markdown ### Step 5: Fix blockers and re-soak

• Problem: Address blockers found in Step 4 triage
• Type: conditional
• Condition: test -s documentation/findings/step-4-blockers.md
• Issue: #65

```

If the operator does not yet know the predicate during the planning conversation, emit **Condition:** as a placeholder. The operator (or /plan-review --autofix once Step 7 of the BPA plan lands) fills in the real predicate later. The placeholder is NOT considered "empty" by the upstream §23/§12 checks — it is a valid intermediate state.

Mixed-type plans split Build Steps into Automated + Manual subsections. If the plan has any Type: operator or Type: wait steps mixed with Type: code steps, render Build Steps as two labeled subsections — ### Automated Steps (all Type: code / Type: conditional / Type: wait steps that /build-phase walks unattended, numbered 1..N) and ### Manual Steps (operator-driven verifications that run AFTER /build-phase completes, named M1/M2/M3...). Each manual entry carries a **Commands:** code-fence block (copy-paste-ready) and a **What to look for:** table with Check | Expected outcome columns — keeping the commands separate from the checks so the operator can paste without scanning past prose. Close the section with an explicit handoff cue (e.g., the closing line of /plan-init and the orchestrator's end-of-phase report both surface "Please run M1 next." rather than dropping the command in passing prose).

All-automated plans (no Type: operator / Type: wait steps) skip the split — render Build Steps as a flat numbered list, no subsection headers required.

Sub-template:

````markdown ## Build Steps

### Automated Steps (These run unattended via /build-phase.)

### Step 1:

• Problem: ...
• Type: code
• Issue: #...
• Flags: --reviewers code
• Produces: ...
• Done when: ...
• Depends on: ...

### Step 2: ... (all code/wait/conditional steps numbered 1..N)

### M

…

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: aberson
• Source: aberson/claude-skills
• License: MIT

Install and usage instructions live in the source repository linked above.