@martinffx/atelier 3.1.0 → 3.1.2

package/CHANGELOG.md

@@ -4,6 +4,20 @@
 
 - **breaking:** rename the `recon` agent to `sentinel`. Existing Atelier configuration is migrated automatically and legacy generated files are removed during the next command.
 
+## [3.1.2](https://github.com/martinffx/atelier/compare/v3.1.1...v3.1.2) (2026-08-09)
+
+
+### Bug Fixes
+
+* **spec-implement:** persist missing plan artifacts ([8391bb6](https://github.com/martinffx/atelier/commit/8391bb62726ed189e1e745a7af69e385fa74c991))
+
+## [3.1.1](https://github.com/martinffx/atelier/compare/v3.1.0...v3.1.1) (2026-08-09)
+
+
+### Bug Fixes
+
+* **skills:** stop planning skills at artifact boundaries ([2626d8c](https://github.com/martinffx/atelier/commit/2626d8cd8ad2c18a3dc238f7491b9f231da143b7))
+
 ## [3.1.0](https://github.com/martinffx/atelier/compare/v3.0.2...v3.1.0) (2026-08-09)
 
 

package/README.md

@@ -39,8 +39,10 @@ flowchart TD
 
     O -->|Bounded work| IP[spec-plan: Inline Plan]
     IP --> IA{Developer approval}
-    IA -->|Approved| I[Implement directly]
+    IA -->|Approved| IS[Stop]
     IA -.->|Revise| IP
+
+    IS -->|New implementation request| I[Implement directly]
     I --> V[Validate]
     V -.->|Issues found| I
     IP -.->|Needs brainstorming| B
@@ -48,14 +50,16 @@ flowchart TD
 
     O -->|Substantial work| B[spec-brainstorm]
     B --> D[design.md]
-    D --> G[oracle-grill-me]
+    D --> BS[Stop]
+    BS -->|New planning request| G[oracle-grill-me]
     G --> P[spec-plan]
     G -.->|Refine design| D
     P --> SA{Developer approval}
     SA -->|Approved| J[plan.json]
     SA -.->|Revise plan| P
     SA -.->|Revisit design| B
-    J --> SI[spec-implement]
+    J --> PS[Stop]
+    PS -->|New implementation request| SI[spec-implement]
     SI --> CR[code-review]
     CR --> F[spec-finish]
     F --> PR[code-pull-request]
@@ -64,7 +68,7 @@ flowchart TD
     F -.->|Issues found| SI
 ```
 
-The workflow is deliberately harder to rush than an unstructured agent session. It records decisions when they need to survive the conversation, keeps implementation tied to an approved plan, and requires evidence before calling the work complete.
+The workflow is deliberately harder to rush than an unstructured agent session. `spec-brainstorm` writes only `design.md`, and `spec-plan` writes only its selected plan output. Each skill then stops. The developer starts planning and implementation with separate requests. This records decisions when they need to survive the conversation, keeps implementation tied to an approved plan, and requires evidence before calling the work complete.
 
 ## Grill the idea
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@martinffx/atelier",
-  "version": "3.1.0",
+  "version": "3.1.2",
   "description": "Personal development toolkit - spec-driven development, code quality, deep thinking, and ecosystem patterns",
   "type": "module",
   "bin": {

package/skills/atelier-orchestrator/SKILL.md

@@ -52,8 +52,9 @@ returning or persisting that prose, apply **humanizer** in embedded mode.
 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`.
+or tracker entries, and stops for approval. Approval ends the `spec-plan` invocation. A later,
+explicit implementation request may implement the plan directly; do not invoke
+`spec-implement`, `spec-finish`, or `code-subagents` for Inline work.
 
 Direct Inline implementation must:
 
@@ -83,14 +84,17 @@ design.md    ← spec-brainstorm (requirements + research + architecture)
 plan.json    ← spec-plan (tasks, dependencies)
 ```
 
+Each skill produces only its declared output and stops. The human starts the next phase with a
+separate request.
+
 Do not infer substantial work from size alone. If no concrete signal applies, use Inline Plan.
 
 ## Skill Routing
 
 ```
 atelier-orchestrator → Select and announce planning mode
-spec-brainstorm   → Spec-backed discovery + design → design.md
-spec-plan         → Inline Plan or Spec-backed Plan → approval
+spec-brainstorm   → Spec-backed discovery + design → only design.md → stop
+spec-plan         → Inline conversation or only plan.json → stop
 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
@@ -99,13 +103,16 @@ code-subagents    → Parallel dispatch for Spec-backed Plan tasks
 ### Ordinary bounded work
 
 ```
-spec-plan (Inline mode) → approval → implement directly
+spec-plan (Inline mode) → approval → STOP
+new implementation request → implement directly
 ```
 
 ### Substantial work or explicit spec request
 
 ```
-spec-brainstorm → spec-plan (Spec-backed Plan) → approval → spec-implement → spec-finish
+spec-brainstorm → design.md → STOP
+new spec-plan request → plan.json → STOP
+new spec-implement request → implementation → spec-finish
 ```
 
 ### Truly mechanical change
@@ -117,14 +124,17 @@ choice to review. If any choice exists, use an Inline Plan.
 
 | 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-brainstorm | Stop; wait for a separate spec-plan request |
+| approved Inline Plan | Stop; wait for a separate implementation request |
+| approved Spec-backed Plan | Stop; wait for a separate spec-implement request |
 | spec-implement | spec-finish |
 
 Do not begin implementation without an approved written plan. Spec-backed work must not
 jump from research to implementation.
 
+`spec-brainstorm` and `spec-plan` are terminal within their invocation. They must not chain into
+the next workflow skill, even when the original request asks for multiple phases at once.
+
 ## Iteration Patterns
 
 The workflow is not purely linear. Expect backflows:

package/skills/spec-brainstorm/SKILL.md

@@ -3,8 +3,8 @@ name: spec-brainstorm
 description: >
   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.
+  section by section for approval before writing only design.md, then stops. Combines
+  requirements discovery with codebase research and architecture design.
   Use when the user explicitly requests a spec or when atelier-orchestrator selects a
   Spec-backed Plan. Ambiguous design or discovery requests route through atelier-orchestrator.
 user-invocable: true
@@ -31,6 +31,14 @@ docs/specs/YYYY-MM-DD-<feature>/
 
 Requirements are inline — no separate requirements.json needed.
 
+### Exclusive output contract
+
+This skill may create or update only the `design.md` shown above. It may inspect the
+repository and discuss drafts in conversation, but it must not modify any other file, create
+`plan.json`, create tracker entries, invoke another workflow skill, or write implementation
+code. This boundary still applies when the human asks to brainstorm, plan, and implement in
+one request. Finish `design.md`, report it, and stop.
+
 ---
 
 ## Lessons
@@ -265,9 +273,9 @@ If you loop twice on the same batch, stop and ask:
 
 > "We've looped on [batch] twice. Should we reconsider the approach?"
 
-**Terminology discipline:** while drafting batches, challenge terms against
-`CONTEXT.md` and update it inline as terms resolve, using the **oracle-domain-modelling**
-skill. If domain confusion runs deep, suggest pausing for **oracle-grill-me** before continuing.
+**Terminology discipline:** while drafting batches, challenge terms against `CONTEXT.md` and
+record resolved terminology in `design.md`. Do not update `CONTEXT.md` from this skill. If
+domain confusion runs deep, suggest pausing for **oracle-grill-me** before continuing.
 
 ### 4c. Write the spec
 
@@ -360,16 +368,17 @@ note them at handoff.
 
 **Tell the human:**
 
-> "Spec written to `docs/specs/<path>`. Please confirm this assembled document before we move to
-> the Spec-backed Plan."
+> "Brainstorm complete. Design written to `docs/specs/<path>/design.md`. A separate
+> `spec-plan` invocation can create `plan.json` after you approve this document."
 
 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. Resolve questions that affect
 scope, architecture, contracts, data, security, or task ordering before handoff.
 
-The next step is **spec-plan** in Spec-backed mode. Do not start planning without the
-human's go-ahead. Do not write code.
+Stop after reporting the completed `design.md`. Do not invoke `spec-plan`, offer to continue
+automatically, create `plan.json`, or write code. The human must start the next phase with a
+separate request.
 
 If planning reveals design flaws, loop back to research. See **atelier-orchestrator**
 for iteration patterns.

package/skills/spec-implement/SKILL.md

@@ -1,9 +1,9 @@
 ---
 name: spec-implement
 description: >
-  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.
+  Continue an approved Spec-backed workflow when the user says "implement", "go", "start", or
+  "do it". After Codex Plan Mode, persist the next missing design.md or plan.json artifact and
+  stop. When both artifacts exist, execute plan.json with TDD and report between batches.
 user-invocable: true
 ---
 
@@ -14,21 +14,30 @@ when blocked.
 
 **Announce at start:** "I'm using the spec-implement skill to execute this plan."
 
-This skill does not make design decisions or modify the plan. If the plan is wrong, go
-back to spec-plan. If the design is wrong, go back to spec-brainstorm.
+This skill does not make design decisions or change approved content. It may persist approved
+content from the conversation when Plan Mode could not write the required artifact. If the plan
+is wrong, go back to spec-plan. If the design is wrong, go back to spec-brainstorm.
 
 ## Prerequisites
 
-Before starting, verify these exist:
-
-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, along with
-   `docs/agents/issue-tracker.md` when tracking is configured
-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.
+Resolve required artifacts in order before starting product implementation:
+
+1. If `docs/specs/YYYY-MM-DD-<feature>/design.md` is missing, write it from the approved design
+   in the current conversation. Validate the file, report its path, and stop. Do not create
+   `plan.json` or start implementation in the same invocation.
+2. Otherwise, if `docs/specs/YYYY-MM-DD-<feature>/plan.json` is missing, write it from the
+   approved plan in the current conversation. Validate it against the schema in `spec-plan`,
+   report its path, and stop. Do not start implementation in the same invocation.
+3. If the approved content needed for the next missing artifact is not available in the current
+   conversation, stop and tell the human what content is unavailable. Do not ask the human to
+   create the file.
+4. When both artifacts exist, verify that any tracker entries selected during planning are
+   available, along with `docs/agents/issue-tracker.md` when tracking is configured.
+5. Verify that you are not on main/master without explicit user consent. Create a branch or use
+   a git worktree first.
+
+Each invocation creates at most one missing artifact. Only proceed to product implementation
+when both approved artifacts existed at the start of the invocation.
 
 ---
 

package/skills/spec-plan/SKILL.md

@@ -3,7 +3,8 @@ 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 and optional tracked tasks. Trigger after atelier-orchestrator selects a mode, when
+  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
@@ -13,13 +14,25 @@ user-invocable: true
 
 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.
+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.json` from an approved `design.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.
@@ -70,11 +83,11 @@ Every revision invalidates prior approval. End each revised plan with "Inline Pl
 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.
+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
 
@@ -84,8 +97,8 @@ docs/specs/YYYY-MM-DD-<feature-name>/
 └── plan.json  ← This skill's output
 ```
 
-The plan starts as a markdown draft for human annotation, then gets converted to
-structured plan.json when approved.
+The plan starts as a conversational draft for human annotation, then gets converted to
+structured `plan.json` when approved.
 
 ### plan.json Schema
 
@@ -179,8 +192,8 @@ structured plan.json when approved.
 
 ## 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.
+Read the approved `design.md`, then present the plan draft in conversation. Do not write the
+draft into `design.md` or create a separate draft file.
 
 ### Plan quality
 
@@ -256,25 +269,12 @@ explicitly approves it.
 When the human approves — "looks good", "approved", "create tasks" — convert the plan
 into plan.json.
 
-### Task Tracking
-
-Read `docs/agents/issue-tracker.md` when it exists. Create tracker entries only when that
-document configures a tracker, mirroring is enabled, and tracking adds execution value. Do not
-choose or configure a tracker here. 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. When execution benefits from configured task tracking, create entries according to
-   `docs/agents/issue-tracker.md`:
-   - Create any configured feature container
-   - Add tasks with clear descriptions
-   - Mirror dependencies when the configured tracker supports them
-5. The plan.json is the source of truth for task details; the task tracker
-tracks execution state
+4. Do not create tracker entries or modify any file other than `plan.json`
 
 ### Verification
 
@@ -294,18 +294,15 @@ After creating plan.json, verify:
 
 ## Handoff
 
-When plan.json is created, and any useful configured tracker entries have been created, the next
-step is **spec-implement** in Spec-backed mode.
+When `plan.json` is created, report its path and stop.
 
 Tell the human:
 
-> "Spec-backed Plan is approved. Ready to start implementation?"
->
-> **Autonomous** — I'll work through all tasks, only stopping if blocked.
->
-> **Batched** — I'll do 3-5 tasks at a time, then report and wait for feedback.
+> "Planning complete. Plan written to `docs/specs/<path>/plan.json`. A separate
+> `spec-implement` invocation can execute it."
 
-Do not start implementing. That's spec-implement's job.
+Do not invoke `spec-implement`, offer execution modes, or start implementing. The human must
+start implementation with a separate request.
 
 Minor implementation deviations may be recorded inline and reflected in plan.json when they do
 not change approved behavior, scope, architecture, public contracts, or major dependencies.
@@ -320,7 +317,7 @@ spec-brainstorm. See **atelier-orchestrator** for iteration patterns.
 |----------------------------|--------|
 | 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 |
+| Inline / "approved" | Acknowledge approval and stop; create no artifacts and do not implement |
 | 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 |
+| Spec-backed / "approved" / "create tasks" | Create only plan.json, report its path, and stop |