spec-plan

Files (2)

• SKILL.md
• plan_template.md · references/

SKILL.md (first lines)

# 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.
- Plan tests at each module's interface, not past it (see **oracle-codebase-design**).

### 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.

### Challenge Gate

Before presenting a plan, dispatch two read-only subagents in parallel with the draft plan and
its design context. Select each agent explicitly (see Delegation in `atelier-orchestrator`):

1. **Design review:** check architectural fit, layer and data-model boundaries, API contracts,
   and whether task ordering respects the dependencies.
2. **Critical challenge:** challenge assumptions, look for missing cases, scope creep, and
   unproven requirements, and propose simpler alternatives.

Each returns at most five evidence-backed findings. Fold in the valid ones, drop the rest with a
reason, and present the plan with a short **Challenged** note listing what changed.

Run the gate on every Spec-backed Plan. Run it on an Inline Plan only when the change touches a
data model, an API contract, or more than one module or layer; skip it for small bounded edits.
Run it once per draft; do not re-run it for the human's annotation revisions unless the plan's
structure changes.

## 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, Proportionality Gate, and Challenge 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

```json
{
  "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"
  ],

From martinffx/atelier, MIT.

More from martinffx/atelier