@martinffx/atelier 1.4.0 → 2.0.0

package/skills/code-subagents/references/implementor-prompt.md

@@ -1,21 +1,21 @@
 # Implementer Prompt Template
 
-Use this template when dispatching an implementer subagent. Paste the full task text from
-plan.json — don't make the subagent read the plan file.
+Use this template when dispatching an implementer subagent. Paste the complete work-item
+requirements. Do not make the subagent recover context.
 
 ## Template
 
 ```
-You are implementing Task {TASK_ID}: {TASK_NAME}
+You are implementing {WORK_ITEM_NAME}
 
-## Task Description
+## Work Item Requirements
 
-{FULL TEXT of task from plan.json — paste it here}
+{WORK_ITEM_REQUIREMENTS}
 
 ## Context
 
-{Scene-setting: where this fits in the feature, what was built before this task,
-relevant architectural decisions from design.md, existing patterns to follow}
+{Scene-setting: where this fits in the work, what was built before it, constraints, and
+existing patterns to follow}
 
 ## Before You Begin
 
@@ -33,9 +33,8 @@ Once you're clear on requirements:
 1. Implement exactly what the task specifies
 2. Write tests following TDD (failing test → verify fail → implement → verify pass)
 3. Verify implementation works
-4. Commit your work
-5. Self-review (see below)
-6. Report back
+4. Self-review (see below)
+5. Report back. Do not commit; the coordinator integrates and commits reviewed work serially.
 
 Work from: {WORKING_DIRECTORY}
 
@@ -47,7 +46,7 @@ It's always OK to pause and clarify. Don't guess or make assumptions.
 Review your work with fresh eyes:
 
 **Completeness:**
-- Did I fully implement everything in the spec?
+- Did I fully implement every requirement?
 - Did I miss any requirements?
 - Are there edge cases I didn't handle?
 

package/skills/spec-brainstorm/SKILL.md

@@ -1,23 +1,27 @@
 ---
 name: spec-brainstorm
 description: >
-  Conversational design workshop for new features. Interviews the human one question
+  Conversational design workshop for substantial work. Interviews the human one question
   at a time, explores 2-3 approaches with trade-offs, and presents the design
   section by section for approval before writing the spec. Combines requirements
   discovery with codebase research and architecture design.
-  Use when the user says "create a spec", "design this feature", "let's brainstorm",
-  "what should we build", or at the start of any feature/refactor/complex-bug workflow.
+  Use when the user explicitly requests a spec or when spec-orchestrator selects a
+  Spec-backed Plan. Ambiguous design or discovery requests route through spec-orchestrator.
 user-invocable: true
 argument-hint: <topic or feature description>
 ---
 
 # Spec Brainstorm
 
-Conversational design workshop that produces a focused, reviewed spec.
+Conversational design workshop for substantial work that produces a focused, reviewed spec.
 
 One question at a time. Multiple approaches explored. Design approved in
 sections. Ruthless scope control. No implementation until design is approved.
 
+Run this skill only after `spec-orchestrator` selects a Spec-backed Plan or the human
+explicitly requests a spec. Bounded work should go directly to `spec-plan` for an Inline
+Plan. Do not reclassify the planning mode here.
+
 ## Artifact
 
 ```
@@ -33,11 +37,11 @@ Requirements are inline — no separate requirements.json needed.
 
 These principles apply to every spec, every time.
 
-### "Too simple for a design" is an anti-pattern
+### Specs must earn their cost
 
-Every project goes through this process. No exceptions. The five-minute conversation
-often reveals assumptions that would cost hours in implementation. If it's truly trivial,
-the spec will be short — but it still gets written.
+Persisted specs are for work whose discovery, architecture, dependencies, or coordination
+needs justify a durable artifact. Do not pull bounded work into this workflow merely because
+it touches multiple files or takes time. That work belongs in an Inline Plan.
 
 ### Design for isolation and clarity
 
@@ -54,8 +58,9 @@ changes.
 ### Decomposition
 
 If the request describes multiple independent subsystems, flag it immediately. Decompose
-into sub-projects before diving into details. Each sub-project gets its own spec and its
-own plan. A spec that tries to cover three subsystems helps no one.
+into sub-projects before diving into details. Each substantial sub-project gets its own spec
+and plan; bounded sub-projects can use Inline Plans. A spec that tries to cover three
+subsystems helps no one.
 
 ### YAGNI ruthlessly
 
@@ -330,16 +335,16 @@ note them at handoff.
 **Tell the human:**
 
 > "Spec written to `docs/specs/<path>`. Every section was approved during our
-> conversation — review it if you'd like, or we can go straight to the
-> implementation plan. Ready for spec-plan?"
+> conversation - review it if you'd like, or we can go straight to the
+> Spec-backed Plan. Ready for spec-plan?"
 
 If the human requests changes — in conversation or by annotating the file —
 address every note, update the spec, and re-run the self-review. If a change
 alters the substance of an approved section, re-present that section for
 approval before continuing.
 
-The next step is **spec-plan**. Do not start planning without the human's
-go-ahead. Do not write code.
+The next step is **spec-plan** in Spec-backed mode. Do not start planning without the
+human's go-ahead. Do not write code.
 
 If planning reveals design flaws, loop back to research. See **spec-orchestrator**
 for iteration patterns.

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