/plan-prompts

name: plan-prompts
description: 'Use when asked to "create a development plan", "generate execution prompts", "replan a milestone", "update DEVELOPMENT_PLAN.md", "start M5", or "adapt future milestones" after predecessor work changes the current repository design. Not for auditing an existing plan; use plan-review. Not for executing a stack; use stacked-prs.'
metadata:
  version: 1.3.0
  category: development
  tags: [planning, execution-prompts, milestones, adaptive-planning, stacked-prs, release-management, docs]
  difficulty: advanced
  phase: plan
  complements:
    - milestone-runner
    - stacked-prs
    - plan-review
    - task-decomposer

Development Plan and Execution Prompts

Convert source documents into a plan that remains valid as milestones merge:

• `.docs/DEVELOPMENT_PLAN.md` — the committed, authoritative milestone plan.
• `.docs/EXECUTION_PROMPTS.md` — the committed, authoritative `/goal` contract for each milestone.
• `.docs/DEVELOPMENT_PLAN_HISTORY.md` — the single local, append-only design-evidence ledger. It must be gitignored.

This skill plans from documents only. Do not implement product code, create branches, open PRs, or execute the generated prompts.

Inputs

Accept either input shape:

| Input shape | Meaning | | --- | --- | | Folder path | Recursively ingest every supported document in that folder. | | Explicit file list | Ingest listed files only; treat the first file as the primary source of truth. |

Optional context:

| Field | Meaning | Default | | --- | --- | --- | | `REPO_CONTEXT` | Target repo path or description; inspect its current structure, tooling, CI, style, release conventions, and partial implementation. | Greenfield planning if absent. | | `GLOBAL_CONSTRAINTS` | Cross-cutting constraints absent from source docs. | None. | | `STACK_DEPTH_HINT` | Maximum PRs per milestone stack. | 6. |

Workflow

Phase 0 — Ingest and ground the plan

1. Inventory every capability, contract, data model, integration, workflow, and non-functional requirement in the source docs. 2. Preserve source order, but resolve authority by input shape: explicit file-list order wins; otherwise newer or more-specific design docs refine broader overview docs. 3. Build a traceability table from source references to planned capabilities. Use document paths plus section names or line ranges when available. 4. Record `> ASSUMPTION:` for defensible defaults. Record `> GAP:` for missing, ambiguous, or contradictory requirements. A contradiction affecting architecture, data semantics, security posture, or acceptance blocks output until resolved. 5. Map implementation-relevant dependencies. Inspect the target repo when available: CI, package manager, test/type/lint commands, naming conventions, partial implementations, version source, `CHANGELOG.md`, tags, branches, and release commands. 6. Identify source-traceable release targets and group milestones into shared release trains. Every milestone must target a named release, `unversioned`, `none`, or visible `> GAP:`. Never infer a version. 7. For a greenfield repo, make M1 establish the minimum verification surface required by later milestones. 8. If existing plan/prompt artifacts are present, read them before regenerating. Treat them as the current committed contract, not as immutable truth.

Summarize the inventory, dependencies, release trains, assumptions, gaps, and verification surface in chat only.

Phase 1 — Write plan and local history

Create `.docs` when absent. Create `.docs/DEVELOPMENT_PLAN_HISTORY.md` with a header stating that it is local evidence only; `DEVELOPMENT_PLAN.md` and `EXECUTION_PROMPTS.md` are authoritative. Verify the exact history path is ignored with `git check-ignore`. When it is not ignored, add only `.docs/DEVELOPMENT_PLAN_HISTORY.md` to `.gitignore`; create `.gitignore` with that one rule only when it does not exist.

Write `.docs/DEVELOPMENT_PLAN.md` with this structure:

# Development Plan — <System>

## 1. Context & Source Map
<2–4 sentences and a table mapping plan sections and milestone groups to source documents/sections.>

## 2. Assumptions & Gaps
<Visible `> ASSUMPTION:` and `> GAP:` entries, or "None.">

## 3. Dependency Graph
```mermaid
graph TD
  M1 --> M2

4. Release Trains

| Target release | Included milestones | Preparation trigger | Required artifacts | Verification | Publication | | --- | --- | --- | --- | --- | --- | | `<version | unversioned | none>` | `<M1, M2>` | All included milestones are externally merged. | `<version update | CHANGELOG.md | both | none>` | `<exact command or binary manual check>` | `<required command/workflow | not requested>` |

5. Plan Evolution Protocol

• The committed plan and prompt files are authoritative. The ignored history ledger is reconstructible local evidence.
• Before each milestone, inspect its current plan/prompt, source map, current codebase, merged predecessor diffs, predecessor verification/CI evidence, and the local history when available.
• Record exactly one `DESIGN GO — PLAN REVISION: none`, `DESIGN GO — PLAN REVISION: <entry IDs>`, or `DESIGN NO-GO — REASON: <blocking evidence>`.
• A material mismatch updates the current milestone and every directly or transitively affected future milestone in both authoritative files. Recompute the dependency graph, critical path, and release-train membership when affected.
• `DESIGN NO-GO` blocks code, branches, and implementation PRs. A material plan revision requires a docs-only reconciliation PR that is reviewed, green, and externally merged before implementation.

6. Sections & Milestones

Section A — <name>

M1 — <title>

| Field | Value | | --- | --- | | Objective | Observable outcome, 1–2 sentences. | | In / Out of scope | Explicit boundaries. | | Depends on | `none` or milestone IDs. | | Target release | Named release train, `unversioned`, `none`, or `> GAP:`. | | Deliverables | Concrete artifacts or behavior. | | Acceptance | Binary, testabl