spec-plan
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.
martinffx · Static checks on file
Installation
Read the source and dependencies before running a command. Copying does not install or execute anything.
npx skills add martinffx/atelier --skill spec-planAbout this skill
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.jsonfrom an approveddesign.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"]
}
Read the complete source ↗