/spec-plan

name: spec-plan
description: >
  Write approved implementation plans in one of two modes. Explicit Inline mode creates a
  conversational plan for bounded work. Spec-backed Plan converts an approved design.md into
  plan.json. Both modes stop after producing their plan output. Trigger after
  atelier-orchestrator selects a mode, when
  the user asks to plan work, or after spec-brainstorm completes. Direct invocation without a
  selected mode uses Spec-backed Plan. Do NOT use for research or execution.
user-invocable: true

Spec Plan

Write a proportional plan so clear that any engineer can follow it. The selected planning mode determines whether the plan stays in the conversation or becomes a persisted structured artifact. This skill does not write code or start implementation.

`atelier-orchestrator` owns automatic classification and the human may override it. When this skill is directly invoked without a selected mode, use Spec-backed Plan. If Inline planning reveals substantial design or coordination needs, ask the human whether to switch to a Spec-backed Plan before presenting the plan.

Terminal boundary

This skill produces exactly one plan output and then stops:

• Inline mode presents the plan in conversation and changes no repository files.
• Spec-backed mode creates or updates only `plan.json` from an approved `design.md`.

Planning drafts and annotation cycles stay in conversation. Do not modify `design.md`, persist a Markdown plan draft, create tracker entries, invoke another workflow skill, or edit implementation files. These rules still apply when the human asks to plan and implement in one request. Implementation requires a later, explicit request after this skill has finished.

Planning Rules

• Organize tasks around required behavior, not one task per layer.
• Record a short list of behavior the change must preserve.
• For each task, identify existing code to reuse, modify, or delete.
• Map every new abstraction to a present requirement and its current consumers.
• Introduce shared infrastructure only when at least two current consumers demonstrate the

same need.

• Group tests by changed contract and active boundary. Do not repeat the CRUD matrix across

layers.

Proportionality Gate

Before presenting any plan, compare its size and concepts with the requested behavior. If a bounded migration or refactor introduces shared infrastructure, unrelated behavior, or a plan substantially larger than the behavior being changed, stop and simplify it.

Outputs

Inline Plan (when explicitly selected)

No repository artifact and no task tracker entry. Read `references/plan_template.md` and present the plan in conversation using its structure. Omit optional subsections rather than rendering empty headings.

Inline Plan Workflow

Read enough of the codebase to identify the current behavior, boundaries, affected files, and concrete validation. Keep the plan proportional to implementation risk. Fill the template with confirmed, file-and-symbol-level details, including cross-file wiring or ordering constraints where they matter. Apply the Planning Rules and Proportionality Gate before presenting it.

Do not manufacture phases, task IDs, dependency graphs, acceptance matrices, `design.md`, `plan.json`, tracker entries, or harness todos. The conversation is the plan artifact.

**Tell the human:** "Inline Plan ready for review."

**STOP. Wait for human review.**

If the human requests any adjustment, apply it to the working plan and re-present the entire updated plan using `references/plan_template.md`. Include unchanged sections so the human reviews one coherent plan. Never respond with only the changed text, an affected section, a summary, or an acknowledgement. A one-word correction is still a plan revision: incorporate it and present the complete plan again.

Every revision invalidates prior approval. End each revised plan with "Inline Plan ready for review." and stop until the human explicitly approves that complete version. Do not implement until the current plan is approved.

When the human approves the Inline Plan, acknowledge that the plan is approved and stop. Do not implement it in the same invocation. A later explicit implementation request may execute the approved conversational plan directly using the Inline execution safeguards in `atelier-orchestrator`; it does not use `spec-implement`, `spec-finish`, `code-subagents`, or task tracking.

Spec-backed Plan Artifacts

docs/specs/YYYY-MM-DD-<feature-name>/
├── design.md  ← From spec-brainstorm (approved)
└── plan.json  ← This skill's output

The plan starts as a conversational draft for human annotation, then gets converted to structured `plan.json` when approved.

plan.json Schema

{
  "feature": "user-authentication",
  "spec": "docs/specs/2026-03-08-user-auth/design.md",
  "goal": "Add email/password authentication with session management",
  "preserved_behavior": [
    "Existing sessions remain valid"
  ],
  "phases": [
    {
      "id": "P1",
      "name": "Authenticate with email and password",
      "tasks": [
        {
          "id": "T1",
          "name": "Accept valid credentials and reject invalid credentials",
          "depends_on": [],
          "inputs": [
            "User schema from design.md",
            "Validation rules (email format, password strength)"
          ],
          "description": "Create UserEntity with email and password fields. Implement validation using a Result type. Password must be hashed, never stored plaintext.",
          "files": {
            "reuse": ["src/auth/password.ts"],
            "create": ["src/entities/user.ts", "tests/entities/user.test.ts"],
            "modify": [],
            "delete": []
          },
          "new_abstractions": [
            {
              "name": "UserEntity",
              "requirement": "Validate email/password credentials",
              "consumers": ["POST /sessions"]
            }