@martinffx/atelier 1.4.0 → 2.0.0

package/skills/spec-plan/SKILL.md

@@ -1,22 +1,72 @@
 ---
 name: spec-plan
 description: >
-  Write implementation plans, iterate with human annotations, create structured tasks. Use
-  when there's an approved spec (design.md) and the next step is breaking it into implementable
-  work. Trigger when the user says "write a plan", "plan this out", "break this down",
-  "I added notes" (annotation cycle), or after spec-brainstorm completes. Also trigger for
-  "create tasks" or "add to beads". Do NOT use for research (use spec-brainstorm) or
-  execution (use spec-implement).
+  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 and optional tracked tasks. Trigger after spec-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 plan so clear that any engineer can follow it. Let the human tear it apart
-through annotation cycles until it's right. Then create structured tasks. This skill does
-not write code.
+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.
 
-## Artifacts
+`spec-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.
+
+## Outputs
+
+### Inline Plan (when explicitly selected)
+
+No repository artifact and no task tracker entry. Present the plan in conversation using:
+
+```markdown
+## context
+
+## scope
+
+## changes
+
+## files
+
+## validation
+```
+
+## Inline Plan Workflow
+
+Read enough of the codebase to identify the current behavior, boundaries, affected files,
+and concrete validation. Keep the plan proportional. Populate every section:
+
+- `context`: Current behavior, relevant constraints, and why the change is needed
+- `scope`: Explicit in-scope and out-of-scope boundaries
+- `changes`: Ordered implementation changes at useful engineering granularity
+- `files`: Exact files expected to be created, modified, or deleted
+- `validation`: Concrete tests, checks, or manual verification
+
+Do not manufacture phases, task IDs, dependency graphs, acceptance matrices, `design.md`,
+`plan.json`, Beads issues, 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 changes, revise the plan in conversation and present the complete
+plan again. Do not implement until the human explicitly approves it. A material scope
+change after approval also requires a revised plan and renewed approval.
+
+Approval authorizes implementation. Implement the approved conversational plan directly using
+the Inline execution safeguards in `spec-orchestrator`. Do not invoke `spec-implement`,
+`spec-finish`, `code-subagents`, or task tracking.
+
+Do not create planning artifacts or tracker entries during this handoff.
+
+## Spec-backed Plan Artifacts
 
 ```
 docs/specs/YYYY-MM-DD-<feature-name>/
@@ -103,7 +153,7 @@ structured plan.json when approved.
 
 ---
 
-## Step 1: Write the Plan Draft
+## Spec-backed Step 1: Write the Plan Draft
 
 Read the approved design.md, then write a plan as a markdown section in the same
 document or as a separate draft.
@@ -146,7 +196,7 @@ Each task should take 15-60 minutes. If larger, decompose into smaller tasks.
 
 ---
 
-## Step 2: The Annotation Cycle
+## Spec-backed Step 2: The Annotation Cycle
 
 The human annotates the plan draft directly — adding corrections, rejections, domain
 knowledge, business constraints, or "remove this entirely."
@@ -178,14 +228,15 @@ explicitly approves it.
 
 ---
 
-## Step 3: Create Structured Tasks
+## Spec-backed Step 3: Create Structured Tasks
 
 When the human approves — "looks good", "approved", "create tasks" — convert the plan
 into plan.json.
 
 ### Task Tracking
 
-**Preferred:** Use beads for dependency-aware task tracking:
+Create tracker entries when they add execution value. For multi-task or dependency-ordered
+work, **prefer beads**:
 ```bash
 # Create epic and tasks with dependencies
 bd create "Feature: {name}" --label {feature} --type epic
@@ -193,15 +244,15 @@ bd create "Task: {name}" --label {feature} --type task --epic {epic-id}
 bd dep add --type blocks {task-a} {task-b}  # task-a blocks task-b
 ```
 
-**Fallback:** If beads is not available, use the harness's native todo system.
-The harness provides todo management — use it directly.
+If tracking is useful and beads is unavailable, use the harness's native todo system.
+Do not duplicate a simple plan.json into a tracker merely to satisfy the workflow.
 
 ### What to do
 
 1. Convert the annotated plan draft into structured plan.json
 2. Each task maps to a unit with inputs, description, files, and validation
 3. Dependencies between tasks are captured in `depends_on` fields
-4. Create tasks using beads (preferred) or harness todos:
+4. When execution benefits from task tracking, create tasks using beads or harness todos:
    - Create an epic/feature container
    - Add tasks per phase with clear descriptions
    - Mark dependencies between tasks (beads: `bd dep add`, harness: manual ordering)
@@ -221,11 +272,12 @@ After creating plan.json, verify:
 
 ## Handoff
 
-When plan.json is created and tasks exist, the next step is **spec-implement**.
+When plan.json is created, and any useful tracker entries have been created, the next
+step is **spec-implement** in Spec-backed mode.
 
 Tell the human:
 
-> "Plan is approved and tasks are created. Ready to start implementation?"
+> "Spec-backed Plan is approved. Ready to start implementation?"
 >
 > **Autonomous** — I'll work through all tasks, only stopping if blocked.
 >
@@ -240,9 +292,11 @@ loop back to research. See **spec-orchestrator** for iteration patterns.
 
 ## Quick Reference
 
-| Human says | You do |
-|------------|--------|
-| "write a plan" / "plan this" | Step 1 → write plan draft, stop |
-| "I added notes" | Re-read, address all notes, do NOT implement |
-| "don't implement yet" | Update plan only |
-| "looks good" / "approved" / "create tasks" | Step 3 → create plan.json + task tracking |
+| Selected mode / human says | You do |
+|----------------------------|--------|
+| Inline / "write a plan" | Present the five-section Inline Plan, stop |
+| Inline / "I added notes" | Revise and re-present the complete Inline Plan |
+| Inline / "approved" | Implement the approved conversational plan directly; create no artifacts |
+| Spec-backed / "write a plan" | Write the plan draft from design.md, stop |
+| Spec-backed / "I added notes" | Re-read, address all notes, do NOT implement |
+| Spec-backed / "approved" / "create tasks" | Create plan.json and useful task tracking |

package/skills/code-subagents/references/code-quality-reviewer-prompt.md

@@ -1,48 +0,0 @@
-# Code Quality Reviewer Prompt Template
-
-Dispatch after the spec compliance review passes (✅). Verifies the implementation is
-well-built — clean, tested, maintainable.
-
-**Only dispatch after spec compliance is confirmed.**
-
-## Template
-
-```
-You are reviewing code quality for Task {TASK_ID}: {TASK_NAME}
-
-## What Was Implemented
-
-{From implementer's report — what they built}
-
-## Requirements Reference
-
-Task {TASK_ID} from {PLAN_FILE_PATH}
-
-## Diff Range
-
-Base: {BASE_SHA} (commit before task)
-Head: {HEAD_SHA} (current commit)
-
-## Your Job
-
-Review the implementation for quality:
-
-1. Does the code follow existing patterns and conventions in the codebase?
-2. Are tests meaningful (not just asserting true or testing mocks)?
-3. Is there unnecessary complexity?
-4. Are edge cases handled?
-5. Is the code clean (no dead code, no unnecessary comments, clear naming)?
-6. Are the right things tested at the right boundaries (unit vs integration)?
-
-## Issue Severity
-
-- **Critical** — Blocks merge. Bugs, security issues, broken tests, missing error handling.
-- **Important** — Should fix. Magic numbers, unclear naming, missing edge cases, poor test design.
-- **Minor** — Nice to have. Style preferences, minor refactors, documentation suggestions.
-
-## Report
-
-- **Strengths:** What was done well
-- **Issues:** List with severity (Critical / Important / Minor) and file:line references
-- **Assessment:** Approved, Approved with minor issues, or Changes requested
-```

package/skills/code-subagents/references/spec-reviewer-prompt.md

@@ -1,62 +0,0 @@
-# Spec Compliance Reviewer Prompt Template
-
-Dispatch after the implementer completes a task. Verifies the implementation matches what
-was specified — nothing more, nothing less.
-
-**Dispatch this BEFORE the code quality review.**
-
-## Template
-
-```
-You are reviewing whether an implementation matches its specification.
-
-## What Was Requested
-
-{FULL TEXT of task requirements from plan.json}
-
-## What Implementer Claims They Built
-
-{From implementer's report}
-
-## CRITICAL: Do Not Trust the Report
-
-The implementer's report may be incomplete, inaccurate, or optimistic. You MUST verify
-everything independently.
-
-**DO NOT:**
-- Take their word for what they implemented
-- Trust their claims about completeness
-- Accept their interpretation of requirements
-
-**DO:**
-- Read the actual code they wrote
-- Compare actual implementation to requirements line by line
-- Check for missing pieces they claimed to implement
-- Look for extra features they didn't mention
-
-## Your Job
-
-Read the implementation code and verify:
-
-**Missing requirements:**
-- Did they implement everything that was requested?
-- Are there requirements they skipped or missed?
-- Did they claim something works but didn't actually implement it?
-
-**Extra/unneeded work:**
-- Did they build things that weren't requested?
-- Did they over-engineer or add unnecessary features?
-- Did they add "nice to haves" that weren't in spec?
-
-**Misunderstandings:**
-- Did they interpret requirements differently than intended?
-- Did they solve the wrong problem?
-- Did they implement the right feature but the wrong way?
-
-**Verify by reading code, not by trusting the report.**
-
-## Report
-
-- ✅ Spec compliant (if everything matches after code inspection)
-- ❌ Issues found: [list specifically what's missing or extra, with file:line references]
-```