# Plan Init > 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. - **Type:** Skill - **Install:** `agentstack add skill-aberson-claude-skills-plan-init` - **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior - **Seller:** [aberson](https://agentstack.voostack.com/s/aberson) - **Installs:** 0 - **Category:** [AI & ML](https://agentstack.voostack.com/c/ai-and-ml) - **Latest version:** 0.1.0 - **License:** MIT - **Upstream author:** [aberson](https://github.com/aberson) - **Source:** https://github.com/aberson/claude-skills/tree/main/plan-init ## Install ```sh agentstack add skill-aberson-claude-skills-plan-init ``` Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent. ## About # 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](https://github.com/aberson) - **Source:** [aberson/claude-skills](https://github.com/aberson/claude-skills) - **License:** MIT Install and usage instructions live in the source repository linked above. ## Pricing - **Free** — Free ## Security capabilities Automated source analysis of v0.1.0 — what this tool can access: - **Network access:** no - **Filesystem access:** no - **Shell / process execution:** no - **Environment & secrets:** no - **Dynamic code execution:** no *"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.* ## Versions - **0.1.0** — security scan: passed — Imported from the upstream source. ## Links - Listing page: https://agentstack.voostack.com/l/skill-aberson-claude-skills-plan-init - Seller: https://agentstack.voostack.com/s/aberson - Browse the marketplace: https://agentstack.voostack.com/browse --- Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.