Plan

---
name: plan
description: Produce the implementation plan (Stage 3, Build) from an approved spec - plan.md (files that change, order of work, risks, proof, rollback) and tasks.md - for engineer approval before any code is written. Use after the spec gate is approved or when the user asks for an implementation plan.
argument-hint: "[change-id]"
license: "PolyForm-Noncommercial-1.0.0 with sdlc Additional Permissions, or sdlc Commercial License (https://github.com/marin-ai-tech/sdlc)"
compatibility: Requires the sdlc CLI (sdlc) from the sdlc package.
allowed-tools: Bash(sdlc *)
metadata:
  author: marin-ai technologies
  version: "1"
  generatedBy: "sdlc 0.23.7"
---

Produce the implementation plan - Stage 3 (Build). Nothing is implemented without an accepted plan: the plan is reviewed while changing course is still a matter of editing a document.

**Harness contract** (applies to every SDLC workflow)
- `sdlc` is the source of truth for lifecycle state. Read it (`sdlc status --change <id> --json`) instead of inferring the stage from the conversation, and re-read artifacts from disk before using them.
- Gates are human decisions. Never run `sdlc approve`, `sdlc reject`, `sdlc waive` or `sdlc tests unlock`, and never edit `.sdlc.yaml`. When a gate needs a person, stop, name the people from the hint (`next.people` in `sdlc next --json`) rather than the role, and give them the exact command to run in their own terminal.
- An answer in chat is never an approval: gate approvals, `track set`, `backlog move`/`drop` and other human decisions happen only as a command the person runs in their own terminal. Offer the choice, explain the consequences, and give the exact command.
- OpenSpec is the specification subsystem: `sdlc openspec <args>` runs the bundled OpenSpec CLI (`list --specs`, `show`, `validate`, `instructions`). Change folders live in `openspec/changes/<id>/`.
- **Change selection**: use the change named in the input. Otherwise run `sdlc status --json`; with exactly one active change use it, with several ask which one. Announce "Using change: <id>".
- **Language**: talk to the person, and write notes and artifacts, in the person's language; when `locale:` is set in `openspec/sdlc.yaml`, use that language. Keep command names, file names, ids and the template headings as they are (sdlc and OpenSpec parse those headings).
- End every workflow with the next step from `sdlc next --json` (the exact command when a person must act).

**Input**: the user's request (a change id, or a description of the work)

**Steps**

1. **Check the gate.** `sdlc status --change <id> --json`: the `spec` gate must be `approved`, `waived` or `n/a` (a `lite` change skips intent and spec). Otherwise stop and report.
2. **Stay read-only while planning.** If the session is in plan mode, explore read-only and present the plan for acceptance first; write plan.md and tasks.md once it is accepted. Otherwise edit only those two files. Read intent.md, proposal.md, specs/ and design.md from disk; explore the codebase (use the `sdlc-researcher` subagent for broad searches).
3. **Draft `plan.md`**: `sdlc instructions plan --change <id> --json`, then fill every section - files that change,
   order of work (mark independent steps `[parallel]`), risks, alternatives considered, proof (tests per spec scenario,
   the `sdlc verify` checks, visual evidence), rollback. Under "Files that change", write paths in backticks, one per
   list item. Write the artifact to `resolvedOutputPath` from that JSON response.
4. **Interrogate the plan with the engineer.** Ask: what could this change break? Which step is riskiest? Which options were rejected and why? Iterate until an engineer who never saw this conversation could implement the change from plan.md alone.
5. **Write `tasks.md`**: `sdlc instructions tasks --change <id> --json`. For a bug fix, name the reproducing
   test in the plan; the first build task writes and runs it after a person approves the plan. Write tasks to that
   response's `resolvedOutputPath`.
6. **Stop at the gate.** Present the plan and give the engineer the approval command: `sdlc approve plan --change <id>` (`risk: high` also needs `--as tech-lead`). Implementation starts with `/sdlc:build` only after approval.

**Guardrails**
- Do not edit project code in this workflow.
- Plans name concrete files and concrete tests; "explore the codebase" or "figure out X" is not a task - do that discovery now.
- If the plan reveals the spec is wrong, stop and propose a spec revision (the spec gate will need re-approval) rather than planning around it.

<!--
Generated by sdlc 0.23.7 (https://github.com/marin-ai-tech/sdlc).
Required Notice: Copyright (c) 2026 marin-ai technologies (https://github.com/marin-ai-tech/sdlc)
License: PolyForm Noncommercial 1.0.0 (https://polyformproject.org/licenses/noncommercial/1.0.0) with the sdlc Additional Permissions, or a commercial license; see https://github.com/marin-ai-tech/sdlc
-->