@martinffx/atelier 1.3.0 → 2.0.0

package/skills/spec-finish/SKILL.md

@@ -1,10 +1,10 @@
 ---
 name: spec-finish
 description: >
-  Post-implementation completion workflow. Use after spec-implement completes to validate,
-  review, create stacked commits, and open a PR via code-pull-request. Triggers when
-  implementation is done, when the user says "finish", "done", "complete", or after
-  implementation tasks are finished.
+  Post-implementation completion workflow for Spec-backed Plans. Use after spec-implement
+  completes to validate, review, create stacked commits, and open a PR via code-pull-request.
+  Triggers only with an active Spec-backed Plan after spec-implement completes, including when
+  the user says "finish", "done", or "complete" in that context.
 user-invocable: true
 ---
 
@@ -15,11 +15,11 @@ Post-implementation workflow: validate → review → stack commits → prepare
 ## Prerequisites
 
 Before starting, verify:
-1. All implementation tasks complete
+1. All Spec-backed Plan tasks are complete
 2. Working directory is clean (committed or staged)
 3. Tests pass
 
-If not complete → go back to spec-implement.
+If not complete, go back to `spec-implement`.
 
 ---
 
@@ -61,7 +61,7 @@ npm run build
 go build ./...
 ```
 
-**If any fail:** Return to spec-implement to fix.
+**If any fail:** Return to `spec-implement` to fix.
 
 **If all pass:** Proceed.
 
@@ -78,8 +78,8 @@ Use the Skill tool to invoke code-review skill for comprehensive code review.
 - No debug code left
 
 ### If code-review finds issues
-- Fix or note for follow-up
-- Re-validate
+- Minor fixes may be made here, then re-validated and reviewed.
+- Blocking or scope-changing fixes return to `spec-implement`.
 
 ---
 
@@ -114,8 +114,8 @@ Use the Skill tool to invoke code-review skill for comprehensive code review.
 ## Step 5: Open the PR
 
 Steps 1-4 (validate, review, stack commits, update docs) must all be complete
-before proceeding. **If code-review found blocking issues, stop — return to
-spec-implement to fix them. Do not proceed to Step 5b.**
+before proceeding. **If code-review found blocking or scope-changing issues, stop and return
+to spec-implement to fix them. Do not proceed to Step 5b.**
 
 ### Step 5a: Present Completion Summary
 
@@ -157,6 +157,6 @@ This skill orchestrates other skills:
 
 ## When NOT to Use
 
-- If implementation still in progress → use spec-implement
-- If tests failing → go back to spec-implement
-- If review found blocking issues → go back to spec-implement
+- If implementation is still in progress, use spec-implement
+- If tests are failing, go back to spec-implement
+- If review found blocking or scope-changing issues, go back to spec-implement

package/skills/spec-implement/SKILL.md

@@ -1,17 +1,16 @@
 ---
 name: spec-implement
 description: >
-  Execute implementation tasks from an approved plan.json. Use when spec-plan has produced
-  approved tasks and the human is ready to start coding. Tracks progress via beads
-  (preferred) or harness-native todos, enforces TDD, reports between batches. Trigger when the user says "implement", "go", "start",
-  "do it", or after spec-plan completes task creation. Do NOT use without an approved plan —
-  invoke spec-plan first.
+  Execute an approved Spec-backed Plan from plan.json. Uses task tracking when useful, enforces
+  TDD, and reports between batches. Trigger when the user says "implement", "go", "start", or
+  "do it" after approving a persisted plan. Do NOT use without an approved Spec-backed Plan.
 user-invocable: true
 ---
 
 # Spec Implement
 
-Pick up tasks. Execute them. Track progress. Report. Stop when blocked.
+Execute the approved Spec-backed Plan. Track progress when it uses tracked tasks. Report. Stop
+when blocked.
 
 **Announce at start:** "I'm using the spec-implement skill to execute this plan."
 
@@ -22,11 +21,11 @@ back to spec-plan. If the design is wrong, go back to spec-brainstorm.
 
 Before starting, verify these exist:
 
-1. **Approved spec** — `docs/specs/YYYY-MM-DD-<feature>/design.md`
-2. **Approved plan** — `docs/specs/YYYY-MM-DD-<feature>/plan.json`
-3. **Tasks created** — In beads, harness todo list, or plan.json task list
-4. **Not on main/master** — Never start implementation on main/master without explicit
-   user consent. Create a branch or use a git worktree first.
+1. Approved `docs/specs/YYYY-MM-DD-<feature>/design.md`
+2. Approved `docs/specs/YYYY-MM-DD-<feature>/plan.json`
+3. Any tracker entries selected during planning are available
+4. You are not on main/master without explicit user consent. Create a branch or use a git
+   worktree first.
 
 If anything is missing, do not proceed. Tell the human what's needed.
 
@@ -44,20 +43,20 @@ Read plan.json critically before writing code. Look for:
 If you find concerns, **raise them with the human before starting**. Don't guess. Don't
 assume. Don't force through blockers.
 
-If no concerns, create task tracking and proceed.
+If no concerns, proceed. Use existing tracker entries when present.
 
 ---
 
-## Step 2: Choose Execution Mode
+## Step 2: Choose Execution Style
 
-If the human hasn't specified a mode, ask.
+If the human has not specified an execution style, ask.
 
 ### Autonomous Mode
 
 > "Implement it all. Don't stop until you're done."
 
 - Execute all tasks in dependency order
-- Track progress: beads `bd update <id> --status in_progress` → `bd close <id>`, or harness todo list
+- Track progress when the Spec-backed Plan has tracker entries
 - Run type checking / linting continuously
 - Only stop if blocked
 
@@ -75,26 +74,30 @@ If the human hasn't specified a mode, ask.
 
 - Invoke **code-subagents** for dispatch patterns and review cycle
 - Fresh subagent per task — no context pollution
-- Two-stage review after each: spec compliance, then code quality
+- One combined plan and code-quality review per completed batch
 - Independent tasks dispatch in parallel, dependent tasks run sequentially
 
 Default to batched if the human hasn't expressed a preference.
 
 ---
 
-## Step 3: Execute Tasks
+## Step 3: Execute the Plan
 
-For each task, follow the plan exactly. Find the next ready task:
+Follow the approved plan exactly.
+
+For each task, find the next ready task:
 
 **With beads (preferred):**
 ```bash
 bd ready --label <feature> --json
 ```
 
-**With harness todos:**
-Check the todo list for the next unblocked task (respecting `depends_on` from plan.json).
+**With harness todos:** Check the todo list for the next unblocked task, respecting
+`depends_on` from plan.json.
 
-Mark it in progress:
+**Without a tracker:** Read the next unblocked task directly from plan.json.
+
+When a tracker exists, mark it in progress:
 
 **With beads:**
 ```bash
@@ -105,8 +108,8 @@ bd update <task-id> --status in_progress
 Update the todo status to in_progress.
 
 ### For each task
-Read the task's **inputs** first — understand what context you need.
-Then read the **description** — know what to build and the constraints.
+
+Read the task's **inputs** and **description** first.
 
 Write tests that cover the validation criteria before writing implementation.
 Invoke `typescript-testing` or `python-testing` (whichever matches the project)
@@ -118,23 +121,22 @@ for test design patterns when needed.
 3. Run them — verify they fail for the RIGHT reason
 4. Implement minimal code to make tests pass
 5. Refactor if needed (tests stay green)
-6. Commit (use code-commit for commit message)
 ```
 
 Do NOT write implementation before tests. Do NOT skip "verify it fails." Do NOT write
 more code than needed to pass the test.
 
-Verify the task against its **validation** — run the tests listed in the task and check
-all acceptance criteria are met.
+Verify the task against its **validation** and acceptance criteria.
 
-### After each task: Review
+### After each batch: Review and commit
 
-Invoke **code-review** to review the implementation before moving to the next task.
-This catches issues early rather than accumulating debt across multiple tasks.
+In Subagent Mode, use **code-subagents** for one combined batch review. In other modes,
+invoke **code-review** once for the batch. Resolve blocking findings and revalidate, then the
+coordinator commits the reviewed batch serially using **code-commit**.
 
 ### On completion
 
-Mark the task done:
+When a tracker exists, mark the task done:
 
 **With beads:**
 ```bash
@@ -157,10 +159,8 @@ all implicit requirements without spelling them out.
 After each batch:
 
 ```
-Completed: Tasks T1-T3
-- T1: UserEntity with validation ✓
-- T2: UserEntity tests (6 passing) ✓
-- T3: UserRepository ✓
+Completed: [tasks]
+- [completed work]
 
 Test output: 6 passed, 0 failed
 Type check: clean
@@ -236,21 +236,21 @@ If the design was wrong:
 - Tasks can't be completed as specified
 
 **Return to spec-brainstorm when:**
-- Fundamental approach needs rethinking
-- Implementation reveals design is wrong
+- The fundamental approach needs rethinking
+- Implementation reveals the design is wrong
 
 ---
 
 ## Completion
 
-When all tasks are done, verify and present the work.
+When all planned work is done, verify and present it.
 
 ### Verification checklist
 
 1. **Run full test suite** — all tests must pass, not just the new ones
 2. **Run type check / lint** — clean output, no new warnings
 3. **Invoke code-review** — full review of all changes
-4. **Verify tasks closed** — `bd list --label <feature> --json` (beads) or check harness todo list — all tasks must be done
+4. **Verify completion** — close every tracker entry when tracking is used
 5. **Diff review** — review the full diff against main/master. Look for:
    - Files that changed but shouldn't have
    - Debug code or temporary hacks left behind
@@ -263,6 +263,7 @@ Present to the human:
 ```
 ## Feature Complete: {feature name}
 
+**Plan:** Spec-backed Plan
 **Tasks:** {completed} / {total}
 **Tests:** {new tests added}, {total passing}
 **Files:** {created}, {modified}
@@ -281,7 +282,7 @@ Present to the human:
 
 ### Next steps
 
-After all tasks complete and verified, the next step is **spec-finish**.
+After all planned work is complete and verified, the next step is **spec-finish**.
 
 > "Implementation complete. Ready to validate, review, and prepare for PR?"
 

package/skills/spec-orchestrator/SKILL.md

@@ -1,9 +1,9 @@
 ---
 name: spec-orchestrator
 description: >
-  Skill routing and workflow orchestration. Routes to correct spec skill based on task type.
-  Establishes discipline and manages transitions between workflow phases. Use when starting
-  any conversation or task to determine which spec skill applies.
+  Skill routing and workflow orchestration. Selects Inline Plan or Spec-backed Plan, routes
+  to the correct workflow skill, and manages transitions between phases. Use when starting
+  any conversation or task to determine which planning mode and skill apply.
 user-invocable: false
 ---
 
@@ -16,7 +16,7 @@ IF A SKILL APPLIES TO YOUR TASK, YOU DO NOT HAVE A CHOICE. YOU MUST USE IT.
 This is not negotiable. This is not optional. You cannot rationalize your way out of this.
 </EXTREMELY-IMPORTANT>
 
-# Spec Workflow
+# Planning Workflow
 
 You have skills. You MUST use them. Not "should." Not "when convenient." MUST.
 
@@ -26,58 +26,92 @@ need to follow it. But you must check.
 
 ## The One Rule
 
-**Never write code until the human has reviewed and approved a written plan.**
+**When an implementation choice exists, never write code until the human has reviewed and
+approved a written plan.** Exact mechanical changes may use the exception below.
 
-Every project goes through this process. A todo list, a single-function utility, a config
-change — all of them. "Simple" projects are where unexamined assumptions cause the most
-wasted work. The spec can be short, the plan can be brief, but you MUST present them
-and get approval.
+The plan may be inline in the conversation or backed by persisted spec artifacts. Select
+the mode before invoking an artifact-producing skill, state the choice with one brief
+reason, and let the human override it.
 
-## Artifacts
+## Planning Modes
 
-Every feature produces two artifacts in `docs/specs/YYYY-MM-DD-<feature>/`:
+### Inline Plan (default)
+
+Use for bounded, well-understood work, including ordinary features, bug fixes, refactors,
+configuration changes, and multi-file changes. Route to **spec-plan** with Inline mode
+explicitly selected. It presents a concise plan in conversation, creates no planning artifacts
+or tracker entries, and stops for approval. After approval, implement the plan directly; do
+not invoke `spec-implement`, `spec-finish`, or `code-subagents`.
+
+Direct Inline implementation must:
+
+- Avoid main/master unless the human explicitly permits it
+- Stay within the approved scope and files
+- Run every validation item in the approved plan
+- Review the final diff for unintended changes
+- Do not commit, push, or open a PR without explicit human instruction
+
+When in doubt, choose Inline Plan. File count and estimated duration alone do not make work
+spec-worthy.
+
+### Spec-backed Plan
+
+Use when at least one concrete signal exists:
+
+- The human explicitly requests a spec or durable planning artifacts
+- Requirements or boundaries need discovery before planning
+- The work materially changes architecture, public contracts, data models, or cross-system behavior
+- Multiple dependent subsystems need decomposition and dependency tracking
+- The plan must survive the conversation for handoff, audit, or multi-person coordination
+
+Route through **spec-brainstorm**. This mode produces:
 
 ```
 design.md    ← spec-brainstorm (requirements + research + architecture)
 plan.json    ← spec-plan (tasks, dependencies)
 ```
 
+Do not infer substantial work from size alone. If no concrete signal applies, use Inline Plan.
+
 ## Skill Routing
 
 ```
-spec-brainstorm → Discovery + design + architecture → design.md
-spec-plan        → Implementation plan + tasks → plan.json
-spec-implement   → Execute tasks, track progress, report
-spec-finish      → Post-implementation validation
-code-subagents   → Parallel dispatch, two-stage review
+spec-orchestrator → Select and announce planning mode
+spec-brainstorm   → Spec-backed discovery + design → design.md
+spec-plan         → Inline Plan or Spec-backed Plan → approval
+spec-implement    → Execute approved Spec-backed Plans; track tasks
+spec-finish       → Post-implementation validation for Spec-backed Plans
+code-subagents    → Parallel dispatch for Spec-backed Plan tasks
 ```
 
-### "Create a spec for X" / Build / Add Feature
+### Ordinary bounded work
 
 ```
-spec-brainstorm → spec-plan → spec-implement → spec-finish
+spec-plan (Inline mode) → approval → implement directly
 ```
 
-### Fix Complex Bug / Refactor
+### Substantial work or explicit spec request
 
 ```
-spec-brainstorm (research-heavy) → spec-plan (targeted) → spec-implement
+spec-brainstorm → spec-plan (Spec-backed Plan) → approval → spec-implement → spec-finish
 ```
 
-### Quick Fix / Trivial Change
+### Truly mechanical change
 
-If genuinely trivial (typo, single-line config, variable rename) — skip the pipeline.
-But be honest. If there's any doubt, plan it.
+A typo or exact single-line replacement may skip planning when there is no implementation
+choice to review. If any choice exists, use an Inline Plan.
 
 ## Hard Transitions
 
-| After completing... | The ONLY next step is... |
-|---------------------|--------------------------|
-| spec-brainstorm | spec-plan |
-| spec-plan | spec-implement |
+| After completing... | Next step |
+|---------------------|-----------|
+| spec-brainstorm | spec-plan in Spec-backed mode |
+| approved Inline Plan | implement the approved plan directly |
+| approved Spec-backed Plan | spec-implement in Spec-backed mode |
 | spec-implement | spec-finish |
 
-Do NOT jump from requirements to code. Do NOT jump from research to implementation.
+Do not begin implementation without an approved written plan. Spec-backed work must not
+jump from research to implementation.
 
 ## Iteration Patterns
 
@@ -92,12 +126,13 @@ The workflow is not purely linear. Expect backflows:
 - Tasks can't be decomposed without more context → back to brainstorm
 
 ### Implement → Plan (missing tasks)
-- Implementation reveals missing tasks → update plan.json
-- Blocked on dependency not in plan → back to plan
+- Implementation reveals missing work → revise the active plan and get approval
+- Spec-backed work is blocked on an unplanned dependency → update plan.json
 
 ### Implement → Research (fundamental issue)
-- Implementation reveals design is fundamentally wrong → back to brainstorm
-- "This can't work as designed" → back to brainstorm
+- Inline planning or implementation develops substantial needs → ask the human whether to
+  switch to a Spec-backed Plan
+- Implementation reveals spec-backed design is fundamentally wrong → back to brainstorm
 
 ### Finish → Implement (bugs found)
 - Validation finds bugs → back to implement
@@ -112,17 +147,17 @@ If you loop 2+ times on the same issue, stop and ask the human:
 
 | What you're thinking | Why it's wrong |
 |----------------------|----------------|
-| "This is too simple for a plan" | Simple tasks have the most unexamined assumptions |
+| "This is too simple for a persisted spec" | Use an Inline Plan instead |
 | "I already know how to do this" | Knowing how ≠ having the human's approval for how |
 | "The human seems impatient" | Wasting time on wrong code is worse than planning |
 | "I'll just do a quick prototype" | Prototypes become production. Plan it. |
-| "I need to explore the code first" | That's the brainstorm phase. Write it in design.md. |
+| "I need to explore the code first" | Gather enough context for an Inline Plan; use brainstorm only when discovery is substantial |
 | "Let me just fix this one thing" | One thing becomes three. Plan it. |
 | "I can plan in my head" | Plans in your head can't be reviewed or annotated |
-| "This is just a refactor" | Refactors touch more code than features. Plan it. |
+| "This is just a refactor" | Refactors still need at least an Inline Plan |
 | "I'll write the plan after" | Post-hoc plans are fiction. Plan before. |
 | "I need more context first" | Skills tell you HOW to gather context. Check first. |
-| "The skill is overkill" | Simple things become complex. Use it. |
+| "The spec workflow is overkill" | It may be. Default to an Inline Plan unless substantial-work signals exist. |
 | "I know what that skill says" | Skills evolve. Read current version. Invoke it. |
 | "This feels productive" | Undisciplined action wastes time. Skills prevent this. |
 

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 |