@martinffx/atelier 1.4.0 → 3.0.0

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,12 +108,11 @@ 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)
-for test design patterns when needed.
+Invoke an installed language-specific testing skill when needed.
 
 ```
 1. Read task inputs and description
@@ -118,23 +120,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 +158,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 +235,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 +262,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 +281,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?"
 
@@ -293,5 +293,5 @@ Offer the human their options:
 
 Don't choose for them. Present options and wait.
 
-If validation finds bugs, loop back to implement. See **spec-orchestrator**
+If validation finds bugs, loop back to implement. See **atelier-orchestrator**
 for iteration patterns.

package/skills/spec-plan/SKILL.md

@@ -1,22 +1,64 @@
 ---
 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 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 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
+`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.
+
+## 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.
+
+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 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.
+
+Approval authorizes implementation. Implement the approved conversational plan directly using
+the Inline execution safeguards in `atelier-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 +145,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 +188,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 +220,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 +236,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 +264,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.
 >
@@ -234,15 +278,17 @@ Tell the human:
 Do not start implementing. That's spec-implement's job.
 
 If implementation reveals missing tasks, update plan.json. If design is wrong,
-loop back to research. See **spec-orchestrator** for iteration patterns.
+loop back to research. See **atelier-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 complete Inline Plan from the template, stop |
+| Inline / "I added notes" | Apply the changes, re-present the entire updated Inline Plan, and stop for renewed approval |
+| 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/spec-plan/references/plan_template.md

@@ -0,0 +1,77 @@
+## Context
+
+Describe why the change is needed and summarize the relevant current behavior.
+Include repository facts, constraints, dependencies, and prior work that the
+implementation must preserve. Contrast the current and desired states when useful.
+
+Write enough for an engineer unfamiliar with the immediate problem to understand
+the plan. Do not repeat implementation steps that belong under Changes.
+
+### Decisions
+
+Include this subsection when the plan depends on meaningful implementation choices.
+
+Record the chosen architecture, interfaces, ownership boundaries, data flow,
+execution order, or technology choices. Explain why the selected approach fits
+the existing codebase. Mention rejected alternatives only when doing so prevents
+the implementer from revisiting a settled choice.
+
+Omit this subsection when the implementation is mechanical or the repository
+already dictates the approach.
+
+### Scope
+
+Include this subsection when the boundaries of the work are not obvious or when
+closely related work must be explicitly excluded.
+
+State what is in scope and out of scope. Identify behavior that must remain
+unchanged and any adjacent systems, cleanup, or follow-up work that this plan
+does not address.
+
+Omit this subsection when the Context and Changes already make the boundaries
+unambiguous.
+
+## Changes
+
+Describe the implementation in dependency order. Use a numbered list when there
+is more than one change.
+
+For each change:
+
+- Start with the exact file path and a concise description.
+- Name the affected functions, types, routes, configuration keys, or other symbols.
+- Explain the current behavior when it matters to the change.
+- Describe the required behavior and important implementation constraints.
+- Explain cross-file wiring, data flow, error handling, and execution order where relevant.
+- Identify files to create, modify, rename, or delete.
+- Mention corresponding test changes alongside the behavior they verify.
+- Use a short signature or pseudocode only when it removes material ambiguity.
+
+The plan should provide enough detail for another engineer to implement without
+rediscovering the approach, while avoiding line-by-line coding instructions.
+
+## Known Limitations
+
+Include this section only when the planned implementation intentionally leaves
+limitations, risks, unsupported cases, deferred cleanup, or follow-up work.
+
+Explain the practical impact of each limitation. Do not use this section for
+unresolved decisions that must be settled before implementation.
+
+Omit the entire section when there are no known limitations.
+
+## Verification
+
+List the concrete checks required after implementation.
+
+For each check:
+
+- Provide the exact command or manual action when known.
+- State the expected outcome or invariant being verified.
+- Include focused tests for changed behavior.
+- Include broader build, test, lint, or type-check commands appropriate to the repository.
+- Include repository searches or state checks when confirming removals, migrations,
+  conflict resolution, generated files, or absence of stale references.
+- Note any verification that cannot be performed locally and why.
+
+Prefer the smallest focused check first, followed by broader regression checks.

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]
-```