--- name: ss-plan model: opus description: Design an implementation plan from a confirmed spec before writing code. Use after the spec is confirmed, when asked to "plan this feature", "how should we implement X", "break this down into steps", or "lên kế hoạch". Produces an ordered, verifiable step-by-step plan with files to touch, approach, tradeoffs, and per-step success checks. Second stage of the specship pipeline. --- # Plan Goal: turn an understood spec into a concrete, ordered implementation plan — small steps, each independently verifiable — **before** any code is written. ## When to use - The spec is understood (ideally via the `ss-spec` skill) and you're ready to design. - You're asked to break a feature into steps or weigh implementation approaches. - Second stage of the workflow: **spec → plan → coding → review** (+ `debug`). ## Shared task state Part of the task pipeline — see `../WORKFLOW.md` for the full contract. - **Hydrate:** resolve the active `TASK-`, read `tasks/TASK-/task.md` + `spec.md`, plus `docs/onboarding/{source-structure,how-to-code}.md` if present. If `spec.md` is missing or `status: draft` with open blockers, run `ss-spec` first. - **Checkpoint:** write `plan.md`, then update `task.md` — set `stage: plan`, `plan` artifact `draft`→`approved`, bump `updated:`, append a Pipeline Log line carrying your agent label (format: `../WORKFLOW.md` → Agent handoff). - **Blocked?** If planning can't be finalized because of an unresolved **blocker `Q#`** or an external dependency (an API/data/decision the plan hinges on), set `status: blocked`, note it in `Blocked by:`, and log it; flip back to `active` when it clears. `blocked` is involuntary — to set the task aside by choice, use `ss-pause-task`. See `../WORKFLOW.md` → Status values. - **Lessons:** read `tasks/LESSONS.md` at hydrate and apply its rules; if you detect a process mistake, fix it and append an `L#` entry there (see `../WORKFLOW.md` → Lessons). ## Method ### 1. Read the inputs - **Read `tasks/TASK-/spec.md`** (produced by `ss-spec`) — every step must trace to a requirement or acceptance criterion in it, and its **Assumptions** can decide the design, so read them too. If it's missing, run `ss-spec` first. - Know where the code will live and the patterns to follow: reuse `docs/onboarding/source-structure.md` and `how-to-code.md` if present, or run `ss-explore-source` if the project is unfamiliar. - **Open the actual files the plan will touch** — confirm the functions, signatures, and patterns the steps rely on really exist as you believe. A plan referencing imagined code doesn't fail now; it fails at `coding`, where it's more expensive. - **Delegate wide reads to a subagent.** If confirming the plan's assumptions requires broad exploration (an unfamiliar area, many candidate files), spawn the **`ss-explorer`** agent if your platform can spawn it (ships with specship for Claude Code), else the built-in **Explore** agent, for the fan-out and keep only its conclusions in this thread - but still open the specific files the steps touch yourself, and verify any path or symbol an agent reports before the plan relies on it. If your platform can't spawn subagents, do the exploration **inline** in this thread instead (`../WORKFLOW.md` → In-stage subagents: delegation is an optimization, never a precondition). ### 2. Choose an approach - If multiple designs are viable, lay out the options with **tradeoffs** and pick one with a clear reason. Don't silently choose. - Prefer the **simplest** design that satisfies the spec — no speculative abstractions or unrequested flexibility. - Reuse existing patterns/utilities instead of inventing new ones. - **Elegance checkpoint:** before locking the approach in, pause and ask "is there a simpler way to do this?" - a smaller diff, an existing utility, a design that removes a whole step. This is the cheapest moment to change course; at `coding` it costs a rewrite. Skip the ceremony for tiny fixes (a one- or two-step plan) - forcing it there invites over-engineering. ### 3. Break into steps - Order steps so each leaves the code in a working, testable state. - **Size each step like a commit:** one coherent change, independently verifiable. Too big: it mixes refactoring with behavior change, or its `verify:` can only pass once later steps land — split it (prep/refactor steps first, behavior steps after). Too small: it can't be verified on its own — merge it into the step that makes it observable. - **Turn unknowns into spike steps, not guesses.** If an approach hinges on something you can't know without trying (a library's behavior, a perf ceiling, an undocumented API), make the first step a time-boxed spike whose `verify:` is the question answered — and note that its outcome may revise the later steps. - For each step define: **what changes**, **which files** (`path`), and a **verify** check. The `verify:` must be **executable, not a description** — a concrete command or test the coding loop can run and read a pass/fail from (` path::case`, `tsc --noEmit`, `curl … | grep`, an assertion), not prose like "behavior works" or "looks correct". If a step's only honest check is a manual observation, name the **exact action and expected output** so it's still a binary check, not a vibe. A vague `verify:` hands the coding stage a strong loop pointed at a blurry target — it'll report "done" without proof. - **For a step that covers an `AC#`, its `verify:` should run (or extend) that AC's own `verify:` check from `spec.md`** — don't invent a parallel one. This is what carries the spec's acceptance check through to executable code and back up to `review`. - Call out data/schema migrations, API contract changes, and anything irreversible early. - Note risks, unknowns, and where you might need to revisit the spec. ## Output: write the plan to the task folder Write the plan to **`tasks/TASK-/plan.md`** (same `TASK-` as `spec.md`) using the **exact template below** — `ss-coding` and `ss-review` parse it. Then show the user a short summary. Rules for the IDs: steps are `S1, S2, …` and never renumbered (only appended). Each step's `covers:` field references the `R#`/`AC#` IDs from `spec.md` it satisfies — this is how every step traces to a requirement, and how `ss-review` checks nothing was missed. **Coverage runs both ways:** before approval, sweep `spec.md` and confirm every `R#` and `AC#` appears in at least one step's `covers:` — an uncovered ID means a missing step, or a scope question to raise with the user. Don't leave the gap for `ss-review` to find. ```markdown --- task: TASK- title: type: plan status: draft # draft | approved created: updated: --- # Plan: ## Approach <chosen design + key tradeoffs, and why if alternatives existed> ## Files to Touch - `path/to/file` — <one-line role of the change> ## Steps <!-- verify: must be a runnable command/test with a pass/fail, not a description --> - [ ] S1 — <change> (covers: R1, AC1) → verify: <exact command/test to run, e.g. `vitest run auth.test.ts`> - [ ] S2 — <change> (covers: R2) → verify: ... ## Risks / Open Questions - <anything that could change the plan> ## Change History - <YYYY-MM-DD HH:MM +TZ>: Created. ``` Keep it minimal and surgical, and **right-size it**: a small task gets a small plan — two or three steps and `- none` in the empty sections, never steps invented to fill the template. Approval gate: every step lists at least one `covers:` ID **and an executable `verify:`**, and **every `R#`/`AC#` in `spec.md` is covered by at least one step** — a plan failing either check is not ready to approve. For non-trivial plans, present it for approval before coding (use EnterPlanMode when appropriate). Set `status: approved` once the user approves. (Under `ss-ship`, approval is delegated: set `status: approved` directly and log it.) When the plan changes (including after a `spec.md` update), edit it in place: bump `updated:`, append a dated **Change History** line, keep `S#` IDs stable. ## External phase execution If an orchestrator launched you for the **`plan` phase only** (`../WORKFLOW.md` → External phase execution), the rules there override the handoff below. In short: confirm the envelope with `specship check TASK-<ID> --phase plan --actor <codex|claude-code> --expect-revision <n> --json` (exit 0 or stop), work from the named task's `spec.md` alone, write `plan.md`, then checkpoint `task.md` **last** with `revision` +1 and **stop**. Don't ask about coding, don't invoke `ss-coding`, don't call `ss-ship` — skip "Next step" entirely and let the orchestrator decide. ## Next step Once the plan is approved, **ask the user whether they want to start implementing** — e.g. "Bạn có muốn tôi code theo plan này luôn không?". - If the user agrees, **immediately invoke the `ss-coding` skill** (via the Skill tool) and continue into implementation in the same flow — don't make them ask again. - If the user declines or wants to revise the plan first, stop here. - Under `ss-ship` (autopilot), skip the question and invoke `ss-coding` directly.