@martinffx/atelier 1.3.0 → 2.0.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@martinffx/atelier",
-  "version": "1.3.0",
+  "version": "2.0.0",
   "description": "Personal development toolkit - spec-driven development, code quality, deep thinking, and ecosystem patterns",
   "type": "module",
   "bin": {
@@ -11,6 +11,8 @@
     "cli",
     "claude-code",
     "opencode",
+    "codex",
+    "cursor",
     "ai-agents",
     "spec-driven-development"
   ],
@@ -19,6 +21,7 @@
     "dist/",
     "skills/",
     "agents/",
+    ".codex-plugin/",
     "README.md",
     "LICENSE",
     "CHANGELOG.md"
@@ -28,6 +31,8 @@
   },
   "scripts": {
     "build": "bun build ./src/atelier.ts --outdir ./dist --target bun",
+    "clean": "rm -rf dist .agents .claude .codex .opencode hooks && rm -f *.log .DS_Store",
+    "cli": "bun src/atelier.ts",
     "typecheck": "tsgo --noEmit",
     "test": "bun test",
     "prepare": "simple-git-hooks"
@@ -39,6 +44,7 @@
     "commander": "^13.1.0",
     "gray-matter": "^4.0.3",
     "inquirer": "^12.5.2",
+    "smol-toml": "^1.7.0",
     "zod": "^3.25.0"
   },
   "devDependencies": {

package/skills/code-commit/SKILL.md

@@ -6,75 +6,95 @@ user-invocable: true
 
 # Conventional Commit Skill
 
-Generate and validate commit messages following the [Conventional Commits](https://www.conventionalcommits.org/) specification.
+Create coherent, reviewable commits that follow the
+[Conventional Commits](https://www.conventionalcommits.org/) specification.
+Message syntax matters, but the selected changes must tell one clear story too.
 
-## Conventional Commit Format
+## Message Format
 
-```
-<type>(<scope>): <subject>
+Every generated commit has a title and body:
 
-[optional body]
+```
+<type>(<scope>): <imperative title>
 
-[optional footer(s)]
+<1-5 lines describing the change and, when useful, its reason or effect>
 ```
 
-### Types
+Use a lowercase scope that identifies the affected component. The title is concise,
+imperative, lowercase, and has no trailing period. The body is concrete: explain the
+behavior, motivation, or important implementation decision rather than restating the title.
 
-| Type | Description |
-|------|-------------|
-| `feat` | New feature |
-| `fix` | Bug fix |
+| Type | Use for |
+|------|---------|
+| `feat` | New user-facing capability |
+| `fix` | Corrected behavior |
 | `docs` | Documentation only |
-| `style` | Code style (formatting, semicolons, etc.) |
-| `refactor` | Code change that neither fixes nor adds |
-| `test` | Adding or updating tests |
-| `chore` | Build, tooling, dependencies |
+| `style` | Formatting only |
+| `refactor` | Restructuring without behavior change |
+| `test` | Tests only |
+| `chore` | Maintenance or tooling |
 | `perf` | Performance improvement |
-| `ci` | CI configuration changes |
+| `ci` | Continuous integration configuration |
 | `build` | Build system or dependencies |
-| `revert` | Reverting a previous commit |
+| `revert` | Reverting a prior commit |
 
-### Rules
+For breaking changes, add `!` after the scope and include a `BREAKING CHANGE:` footer.
+Include issue footers such as `Closes #123` only when the issue is known.
 
-- **Subject**: Short description, imperative mood, lowercase, no period at end
-- **Scope**: Optional, lowercase, describes what was changed (e.g., `auth`, `api`, `ui`)
-- **Breaking changes**: Add `!` after type/scope: `feat(auth)!: change API`
-- **Footer**: For breaking changes (`BREAKING CHANGE:`) or issue references (`Closes #123`)
+## Create a Commit
 
-## Operations
+When the user asks to commit, first inspect the complete worktree:
 
-### 1. Generate Commit from Diff
+1. Run `git status --short`.
+2. Read both `git diff --cached` and `git diff` so pre-staged work is not mistaken for the entire change.
+3. List untracked files with `git ls-files --others --exclude-standard` and inspect relevant ones.
+4. Read recent subjects with `git log --oneline -10` to match established scopes and wording.
+5. Flag likely secrets, credentials, local configuration, or generated output. Do not stage them without explicit direction.
 
-When user wants to commit changes:
+### Decide Whether to Split
 
-1. Run `git status` to see changed files
-2. Run `git diff --staged` for staged changes
-3. Analyze what changed to determine:
-   - **Type**: Which type best describes the changes?
-   - **Scope**: What area was affected? (optional)
-   - **Subject**: What was done? (imperative: "add" not "added")
-4. Create a conventional commit message
-5. Run `git commit -m "<message>"`
+Default to one commit containing all intended, related changes. Look for an obvious
+file-level split only when changes are independent and each group can stand alone.
 
-**Example:**
-```
-feat(auth): add JWT token refresh
+Keep these together:
 
-Implements token refresh endpoint to extend sessions
-without requiring re-authentication.
+- Implementation and its tests.
+- Documentation that describes the same change.
+- Dependency manifests and their lockfiles.
 
-Closes #142
-```
+Do not invent a split for adjacent work, use hunk-level staging, or force the user
+to reorganize a coherent change. If an obvious split exists, propose each commit with
+its files and full message, then ask once for approval. If not, propose one commit.
+
+### Approve, Stage, Commit
+
+Before making any write, show:
+
+- The files in each proposed commit.
+- The full title and 1-5 line body for each commit.
+- Any excluded files and why they are excluded.
 
-### 2. Validate Commit Message
+Ask for approval unless the user explicitly authorizes committing immediately. After
+approval, stage only the files for the approved commit with `git add -- <paths>` and
+commit with the proposed title and body. Do not amend, rebase, push, or include
+unapproved files.
 
-When user asks to validate or check a commit message:
+Repository commit hooks are the final message validation when configured. Never bypass
+a failing hook. Report the commit hash on success; report the error and leave changes
+intact on failure.
 
-1. Parse the commit message
-2. Check format: `<type>(<scope>): <subject>`
-3. Validate type is from the allowed list
-4. Check subject follows rules (lowercase, imperative, no period)
-5. Flag any issues found
+## Validate a Commit Message
+
+When the user asks to validate a message, check:
+
+1. It follows `type(scope): imperative title`.
+2. The type is listed above and the scope is lowercase.
+3. The title is lowercase, imperative, concise, and has no trailing period.
+4. A body follows after a blank line and contains 1-5 meaningful lines.
+5. Breaking changes use both `!` and a `BREAKING CHANGE:` footer.
+
+Return specific corrections and a revised message. When the repository configures
+commitlint, use it as the authoritative validation rule.
 
 ### Delegated: Pull Request Creation
 
@@ -87,24 +107,15 @@ or `glab`.
 
 | Input | Action |
 |-------|--------|
-| User says "commit" or "git commit" | Generate from git diff, then commit |
+| User says "commit" or "git commit" | Inspect the worktree, propose coherent commit(s), then commit after approval |
 | User says "validate commit" | Check the commit message format |
 | User pastes commit message | Validate the provided message |
 
-## Auto-Commit Workflow
-
-When generating a commit:
-
-1. Show the user the commit message first
-2. Ask for confirmation before committing (unless user explicitly says "just do it")
-3. Execute `git commit -m "<message>"` after confirmation
-4. Show the result of the commit
-
 ## Error Handling
 
-- If no staged changes: `git status` shows nothing → warn user nothing to commit
-- If git not initialized: Initialize repo or warn user
-- If commit fails: Show error and offer to retry
+- If there are no changes: report that there is nothing to commit.
+- If Git is not initialized: report it; do not initialize a repository unless asked.
+- If a commit fails: show the error, preserve the worktree, and do not bypass hooks.
 
 ## Examples
 
@@ -113,8 +124,7 @@ When generating a commit:
 ```
 fix(auth): resolve login timeout issue
 
-Users were logged out after 5 minutes due to
-incorrect token expiry calculation.
+Correct token expiry calculation so active users are not logged out after five minutes.
 ```
 
 **Input:** "I added a new API endpoint for users"
@@ -122,8 +132,7 @@ incorrect token expiry calculation.
 ```
 feat(api): add user profile endpoint
 
-GET /users/:id returns user profile data including
-name, email, and avatar URL.
+Expose name, email, and avatar URL from `GET /users/:id`.
 
 Closes #89
 ```
@@ -133,8 +142,7 @@ Closes #89
 ```
 feat(auth)!: change token validation endpoint
 
-The /auth/verify endpoint now requires Bearer token
-instead of query parameter.
+Require a Bearer token on `/auth/verify` instead of a query parameter.
 
 BREAKING CHANGE: Clients must update to send
 Authorization header with Bearer token.

package/skills/code-handoff/SKILL.md

@@ -5,7 +5,7 @@ argument-hint: "What will the next session be used for?"
 user-invocable: true
 ---
 
-Write a handoff document summarising the current conversation so a fresh agent can continue the work. Save to the temporary directory of the user's OS - not the current workspace.
+Write a handoff document summarising the current conversation so a fresh agent can continue the work. Create `<project-root>/.handoff/` if needed and save the document there with a descriptive `.md` filename.
 
 Include a "suggested skills" section in the document, which suggests skills that the agent should invoke.
 

package/skills/code-review/SKILL.md

@@ -34,7 +34,7 @@ Use these concrete harness subagent types. If an exact match is unavailable, use
 
 | `subagent_type` | Purpose |
 |-----------------|---------|
-| `recon` | Triage only: changed-file analysis, context retrieval, reviewer selection |
+| `sentinel` | Triage only: changed-file analysis, context retrieval, reviewer selection |
 | `oracle` | Parallel reviewer personas, evidence-based critique, failure-mode analysis, challenge validation |
 | `architect` | Architecture, design-boundary, data-model, and API-contract review |
 
@@ -67,7 +67,7 @@ Follows [code-subagents](../code-subagents/SKILL.md) patterns:
 
 | Agent | Used In Step |
 |-------|--------------|
-| `recon` | Triage only (context retrieval, file analysis) |
+| `sentinel` | Triage only (context retrieval, file analysis) |
 | `oracle` | Reviewers and challenge validation |
 | `architect` | Architect (architecture review) |
 

package/skills/code-review/references/rq.md

@@ -34,12 +34,12 @@ Capture the list of changed files and the full diff.
 
 **Purpose:** Analyze diff to determine context, select reviewers, identify relevant skills to look for.
 
-**Uses:** `recon` agent.
+**Uses:** `sentinel` agent.
 
 ### Subagent Invocation
 
 ```yaml
-subagent_type: recon
+subagent_type: sentinel
 description: "Triage diff for code review"
 prompt: |
   Analyze this code diff to determine review needs.
@@ -364,7 +364,7 @@ Display findings in terminal per [output.md](./output.md).
 | Step | Subagent | Uses | Parallel? | Purpose |
 |------|----------|------|----------|---------|
 | 1 | Get Diff | inline | — | `git diff <branch>` |
-| 2 | Triage | `recon` agent | No | Detect context, select reviewers, identify relevant skills to look for |
+| 2 | Triage | `sentinel` agent | No | Detect context, select reviewers, identify relevant skills to look for |
 | 3 | Reviewers | `oracle` agent | Yes (per reviewer) | Specialty analysis |
 | 4 | Synthesis | inline | No | Deduplicate and group |
 | 5 | Architect | `architect` agent | No | Architecture review |

package/skills/code-subagents/SKILL.md

@@ -1,25 +1,23 @@
 ---
 name: code-subagents
 description: >
-  Subagent dispatch patterns for implementation tasks. Use when spec-implement has multiple
-  tasks to execute and subagents are available. Covers parallel dispatch for independent work,
-  the two-stage review cycle (spec compliance then code quality), focused prompt construction,
-  and integration of results. Trigger when executing plan tasks with subagent support, when
-  facing 2+ independent problems, or when the user asks to use subagents for implementation.
+  Implementation subagent dispatch patterns. Use when independent implementation work is
+  available and subagents can execute it. Covers parallel dispatch, shared-tree patch
+  snapshots, one combined review per completed batch, and serial integration.
 user-invocable: false
 ---
 
-# Spec Subagents
+# Implementation Subagents
 
-Fresh subagent per task. Two-stage review after each. Parallel when independent, sequential
-when dependent.
+Fresh subagent per task. One combined review per completed batch. Parallel when independent,
+sequential when dependent.
 
 ## When to Use Subagents
 
 **Use when:**
-- Executing tasks from plan.json with subagent support available
-- 2+ independent tasks that don't share state or files
-- Each problem can be understood without context from others
+- 2+ independent work items do not share state or files
+- Each work item has explicit requirements, constraints, files, and validation
+- Each problem can be understood without context from the other work items
 
 **Don't use when:**
 - Tasks are tightly coupled (editing the same files)
@@ -53,6 +51,13 @@ Task C (notification tests) ──→ review → complete
 **Independence check:** Would fixing Task A affect Task B? Would they edit the same files?
 If no to both, dispatch in parallel.
 
+For shared-tree parallel work:
+
+1. Assign each task an exclusive file list before dispatch
+2. Do not let implementers stage or commit changes
+3. Capture a path-scoped `git diff` for each task when it reports completion
+4. Run tasks sequentially if their file ownership overlaps or cannot be isolated
+
 ---
 
 ## Prompt Templates
@@ -60,15 +65,14 @@ If no to both, dispatch in parallel.
 Use these templates when dispatching subagents. Each template is battle-tested — don't
 improvise, use them as-is and fill in the variables.
 
-- **[references/implementer-prompt.md](references/implementer-prompt.md)** — Dispatch an implementer. Includes self-review checklist.
-- **[references/spec-reviewer-prompt.md](references/spec-reviewer-prompt.md)** — Spec compliance review. "Do not trust the report."
-- **[references/code-quality-reviewer-prompt.md](references/code-quality-reviewer-prompt.md)** — Code quality review. Critical/Important/Minor severity.
+- **[references/implementor-prompt.md](references/implementor-prompt.md)** — Dispatch an implementer. Includes self-review checklist.
+- **[references/batch-reviewer-prompt.md](references/batch-reviewer-prompt.md)** — Combined plan and code-quality review for one completed batch.
 
 ### Prompt quality rules
 
 - **Focused** — one task, one problem domain
-- **Self-contained** — all context needed is in the prompt. Don't make the subagent
-  read the plan file; provide the full task text
+- **Self-contained** — all context needed is in the prompt. Provide the complete work-item
+  requirements; do not make the subagent recover context
 - **Specific about files** — exact paths, not "the relevant files"
 - **Specific about output** — what should the subagent return?
 - **Constrained** — what should they NOT touch?
@@ -84,63 +88,30 @@ improvise, use them as-is and fill in the variables.
 
 ---
 
-## Two-Stage Review
-
-Every completed task gets two reviews in order. Do not skip either. Do not reverse the order.
-
-### Stage 1: Spec Compliance
-
-Does the implementation match what was specified?
+## Batch Review
 
-```markdown
-## Spec Review
+Run one combined review after every completed batch, not separate reviews for each task.
 
-Review the implementation against the task specification:
-
-**Task spec:** [paste task from plan.json]
-
-**Files changed:** [list from subagent output]
-
-Check:
-1. Are all requirements from the task spec implemented?
-2. Is anything implemented that wasn't specified? (over-building)
-3. Do tests cover the specified acceptance criteria?
-4. Does the implementation match the design in design.md?
-
-Report: List any gaps or extras. Mark ✅ if compliant, ❌ if not.
-```
+Give one fresh reviewer:
 
-If the spec reviewer finds issues → the implementer subagent fixes them → spec reviewer
-reviews again. Repeat until ✅.
+- The complete requirements for work items in the batch
+- The relevant constraints
+- The path-scoped patch captured for each task
+- The implementers' reports and validation results
 
-### Stage 2: Code Quality
+The reviewer checks both requirements compliance and code quality:
 
-Is the implementation well-built?
+1. Every requirement and acceptance criterion is implemented
+2. The batch follows the supplied constraints
+3. No unrequested work or out-of-scope files are included
+4. Tests are meaningful and cover the right boundaries
+5. The code follows existing patterns without unnecessary complexity
 
-```markdown
-## Code Quality Review
+Use [references/batch-reviewer-prompt.md](references/batch-reviewer-prompt.md) as written.
 
-Review the implementation for code quality:
-
-**Files changed:** [list]
-
-Check:
-1. Does the code follow existing patterns and conventions?
-2. Are tests meaningful (not just asserting true)?
-3. Is there unnecessary complexity?
-4. Are edge cases handled?
-5. Is the code clean (no dead code, no unnecessary comments)?
-
-Rate issues as Critical (blocks merge), Important (should fix), or Minor (nice to have).
-```
-
-If the quality reviewer finds Critical or Important issues → implementer fixes → reviewer
-reviews again. Minor issues can be noted and moved past.
-
-### Why this order matters
-
-Spec compliance first because there's no point polishing code that doesn't meet the spec.
-Quality second because compliant code still needs to be well-built.
+If the reviewer finds Critical or Important issues, send each issue back to the relevant
+implementer, refresh its path-scoped patch, and review the batch again. Minor issues may be
+noted and moved past.
 
 ---
 
@@ -161,9 +132,11 @@ they're thinking rather than guessing.
 After subagents complete (especially parallel dispatch):
 
 1. **Read each summary** — understand what changed
-2. **Check for conflicts** — did any agents edit the same code?
-3. **Run full test suite** — verify all changes work together
-4. **Update task tracking** — mark tasks complete: beads `bd close <id>`, or harness todo list
+2. **Capture task patches** — use each task's exclusive file list
+3. **Review the batch** — one combined requirements and quality review
+4. **Run full test suite** — verify all changes work together
+5. **Commit** — the coordinator commits the reviewed batch serially
+6. **Update progress tracking** — when the caller uses it
 
 If there are conflicts between parallel results, resolve them manually. Don't dispatch
 another subagent to merge — that requires too much context.
@@ -176,9 +149,5 @@ If a subagent fails a task:
 
 - **Don't fix it manually** — that pollutes your context
 - **Dispatch a fix subagent** with specific instructions about what went wrong
-- **If it fails twice**, stop and escalate to the human. The plan may need revision.
-
-If failure reveals a design problem:
-
-> "This task is failing because [reason]. The design in design.md may need to change.
-> Want me to go back to spec-brainstorm?"
+- **If it fails twice**, stop and escalate to the human. The requirements or constraints may
+  need revision.

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

@@ -0,0 +1,44 @@
+# Batch Reviewer Prompt Template
+
+Use this template after all tasks in an implementation batch report completion. Review the
+captured task patches, not a commit range.
+
+## Template
+
+```
+You are reviewing one completed implementation batch for requirements compliance and code quality.
+
+## Batch Requirements
+
+{BATCH_REQUIREMENTS}
+
+## Constraints
+
+{CONSTRAINTS}
+
+## Task Patches
+
+{BATCH_PATCHES}
+
+## Implementer Reports and Validation
+
+{IMPLEMENTER_REPORTS}
+
+## CRITICAL: Verify the Patches
+
+Do not trust the implementer reports. Review the captured patches and relevant code directly.
+
+Check:
+1. Every requirement and acceptance criterion is implemented
+2. The implementation follows the supplied constraints
+3. No unrequested work or out-of-scope files are included
+4. Tests are meaningful and cover the right boundaries
+5. The code follows existing patterns without unnecessary complexity
+6. Error cases and edge conditions are handled
+
+## Report
+
+- **Strengths:** What was done well
+- **Issues:** Critical, Important, or Minor findings with file:line references and fixes
+- **Assessment:** Approved, Approved with minor issues, or Changes requested
+```

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.