@martinffx/atelier 3.0.1 → 3.1.0

package/skills/spec-implement/SKILL.md

@@ -23,7 +23,8 @@ 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
+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.
 
@@ -39,9 +40,17 @@ Read plan.json critically before writing code. Look for:
 - Missing file paths or incomplete validation criteria
 - Tasks that conflict with each other
 - Dependencies that don't match what you see in the codebase
+- Existing code or platform behavior that already satisfies a planned capability
+- Duplicate IDs, parsers, errors, schemas, lifecycle handling, or test utilities
+- Shared abstractions with fewer than two current consumers
+- Tests whose only purpose is validating a new wrapper
 
-If you find concerns, **raise them with the human before starting**. Don't guess. Don't
-assume. Don't force through blockers.
+If planned machinery fails these checks, stop before implementing it and return to
+`spec-plan` with a smaller revision for human review. Preserve the approved behavior and scope;
+do not force an unsupported structure through implementation.
+
+For other concerns, **raise them with the human before starting**. Don't guess. Don't assume.
+Don't force through blockers.
 
 If no concerns, proceed. Use existing tracker entries when present.
 
@@ -83,36 +92,22 @@ Default to batched if the human hasn't expressed a preference.
 
 ## Step 3: Execute the Plan
 
-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.
-
-**Without a tracker:** Read the next unblocked task directly from plan.json.
+Preserve the approved behavior and scope. Treat the plan's proposed structure as a hypothesis
+that must remain supported by repository evidence.
 
-When a tracker exists, mark it in progress:
+For each task, find the next unblocked task directly from `plan.json`. When tracker entries
+exist, use `docs/agents/issue-tracker.md` to keep their execution state in sync; tracker state
+never overrides the plan's dependency graph.
 
-**With beads:**
-```bash
-bd update <task-id> --status in_progress
-```
-
-**With harness todos:**
-Update the todo status to in_progress.
+When a tracker exists, mark it in progress according to `docs/agents/issue-tracker.md`.
 
 ### For each task
 
 Read the task's **inputs** and **description** first.
 
-Write tests that cover the validation criteria before writing implementation.
-Invoke an installed language-specific testing skill when needed.
+For behavior-changing code tasks, write tests that cover the validation criteria before writing
+implementation. For documentation, configuration, migration, or verification-only tasks, use the
+task's stated validation instead. Invoke an installed language-specific testing skill when needed.
 
 ```
 1. Read task inputs and description
@@ -122,28 +117,22 @@ Invoke an installed language-specific testing skill when needed.
 5. Refactor if needed (tests stay green)
 ```
 
-Do NOT write implementation before tests. Do NOT skip "verify it fails." Do NOT write
-more code than needed to pass the test.
+For behavior-changing code, 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** and acceptance criteria.
 
-### After each batch: Review and commit
+### After each batch: Validate and commit
 
-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**.
+Run the task's focused validation and inspect the local diff for accidental or out-of-scope
+changes. Report deviations and unexpected findings. Use **code-commit** for any commit; plan
+approval does not bypass its approval gate. Comprehensive **code-review** happens in
+**spec-finish**.
 
 ### On completion
 
-When a tracker exists, mark the task done:
-
-**With beads:**
-```bash
-bd close <task-id> --reason "Implemented with tests"
-```
-
-**With harness todos:**
-Mark the task as completed.
+When a tracker exists, mark the task complete according to
+`docs/agents/issue-tracker.md`.
 
 ### Referencing existing code
 
@@ -231,8 +220,11 @@ If the design was wrong:
 ## When to Revisit Earlier Steps
 
 **Return to spec-plan when:**
-- Partner updates the plan based on your feedback
-- Tasks can't be completed as specified
+- A material change affects approved behavior, scope, architecture, public contracts, or major dependencies
+- Tasks cannot be completed without one of those material changes
+
+Minor deviations may be recorded inline and reflected in plan.json when useful. Report them in the
+next progress update.
 
 **Return to spec-brainstorm when:**
 - The fundamental approach needs rethinking
@@ -248,9 +240,8 @@ When all planned work is done, verify and present it.
 
 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 completion** — close every tracker entry when tracking is used
-5. **Diff review** — review the full diff against main/master. Look for:
+3. **Verify completion** — close every tracker entry when tracking is used
+4. **Diff review** — review the full diff against the intended base branch. Look for:
    - Files that changed but shouldn't have
    - Debug code or temporary hacks left behind
    - Inconsistencies between what was planned and what was built
@@ -274,7 +265,7 @@ Present to the human:
 - Test suite: ✓ all passing
 - Type check: ✓ clean
 - Lint: ✓ clean
-- Code review: ✓ complete
+- Comprehensive code review: pending spec-finish
 
 ### Ready for review
 ```

package/skills/spec-plan/SKILL.md

@@ -20,6 +20,23 @@ skill is directly invoked without a selected mode, use Spec-backed Plan. If Inli
 reveals substantial design or coordination needs, ask the human whether to switch to a
 Spec-backed Plan before presenting the plan.
 
+## Planning Rules
+
+- Organize tasks around required behavior, not one task per layer.
+- Record a short list of behavior the change must preserve.
+- For each task, identify existing code to reuse, modify, or delete.
+- Map every new abstraction to a present requirement and its current consumers.
+- Introduce shared infrastructure only when at least two current consumers demonstrate the
+  same need.
+- Group tests by changed contract and active boundary. Do not repeat the CRUD matrix across
+  layers.
+
+### Proportionality Gate
+
+Before presenting any plan, compare its size and concepts with the requested behavior. If a
+bounded migration or refactor introduces shared infrastructure, unrelated behavior, or a plan
+substantially larger than the behavior being changed, stop and simplify it.
+
 ## Outputs
 
 ### Inline Plan (when explicitly selected)
@@ -33,10 +50,11 @@ structure. Omit optional subsections rather than rendering empty headings.
 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.
+ordering constraints where they matter. Apply the Planning Rules and Proportionality Gate
+before presenting it.
 
 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.
+`plan.json`, tracker entries, or harness todos. The conversation is the plan artifact.
 
 **Tell the human:** "Inline Plan ready for review."
 
@@ -76,14 +94,17 @@ structured plan.json when approved.
   "feature": "user-authentication",
   "spec": "docs/specs/2026-03-08-user-auth/design.md",
   "goal": "Add email/password authentication with session management",
+  "preserved_behavior": [
+    "Existing sessions remain valid"
+  ],
   "phases": [
     {
       "id": "P1",
-      "name": "Domain Model",
+      "name": "Authenticate with email and password",
       "tasks": [
         {
           "id": "T1",
-          "name": "Implement UserEntity with validation",
+          "name": "Accept valid credentials and reject invalid credentials",
           "depends_on": [],
           "inputs": [
             "User schema from design.md",
@@ -91,9 +112,18 @@ structured plan.json when approved.
           ],
           "description": "Create UserEntity with email and password fields. Implement validation using a Result type. Password must be hashed, never stored plaintext.",
           "files": {
+            "reuse": ["src/auth/password.ts"],
             "create": ["src/entities/user.ts", "tests/entities/user.test.ts"],
-            "modify": []
+            "modify": [],
+            "delete": []
           },
+          "new_abstractions": [
+            {
+              "name": "UserEntity",
+              "requirement": "Validate email/password credentials",
+              "consumers": ["POST /sessions"]
+            }
+          ],
           "validation": {
             "tests": [
               "rejects empty email",
@@ -121,6 +151,7 @@ structured plan.json when approved.
 | feature | string | Kebab-case feature name |
 | spec | string | Path to the approved design.md |
 | goal | string | One-sentence goal |
+| preserved_behavior | string[] | Short list of existing behavior that must remain unchanged |
 | phases | Phase[] | Implementation phases in dependency order |
 
 #### Phase fields
@@ -140,7 +171,8 @@ structured plan.json when approved.
 | depends_on | string[] | Task IDs that must complete first |
 | inputs | string[] | What you need to know before starting |
 | description | string | What to build, key decisions, constraints |
-| files | {create, modify} | Files to create and modify |
+| files | {reuse, create, modify, delete} | Existing code to reuse, modify, or delete, plus files to create |
+| new_abstractions | {name, requirement, consumers}[] | New abstractions mapped to a present requirement and current consumers |
 | validation | {tests, acceptance} | How to verify the task is done |
 
 ---
@@ -164,19 +196,18 @@ Each task should be self-contained and include:
 
 - **Inputs**: What you need to know or have before starting (from spec, existing code)
 - **Description**: What to build, key design decisions, constraints
-- **Files**: Exact paths to create and modify
-- **Validation**: Tests that must pass and acceptance criteria
+- **Files**: Exact existing code to reuse, modify, or delete, and files to create
+- **New abstractions**: Present requirement and current consumers for each; use an empty list
+  when the task adds none
+- **Validation**: Tests grouped by changed contract and active boundary, plus acceptance criteria
 
 No exact code snippets. No implementation details. The task says WHAT and HOW TO VERIFY,
 not HOW to write the code.
 
 ### Task ordering
 
-Follow bottom-up dependency ordering:
-
-```
-Entity → Repository → Service → Router/Consumer
-```
+Order tasks by required behavior and real dependencies. Keep changes across layers in one task
+when they implement and verify one contract; do not create one task per layer.
 
 ### Task size
 
@@ -227,27 +258,21 @@ into plan.json.
 
 ### 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
-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
-```
-
-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.
+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 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)
+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
 
@@ -257,14 +282,19 @@ After creating plan.json, verify:
 - Every task has an ID and depends_on field
 - Dependencies form a valid DAG (no cycles)
 - Every task has inputs, description, and validation
+- Preserved behavior is short and explicit
+- Every task identifies code to reuse, modify, or delete
+- Every new abstraction names its present requirement and current consumers
+- Shared infrastructure has at least two current consumers with the same demonstrated need
 - File paths are complete and specific
-- Validation criteria are concrete and testable
+- Validation criteria are concrete, testable, and grouped by changed contract and active boundary
+- The plan passes the Proportionality Gate
 
 ---
 
 ## Handoff
 
-When plan.json is created, and any useful tracker entries have been created, the next
+When plan.json is created, and any useful configured tracker entries have been created, the next
 step is **spec-implement** in Spec-backed mode.
 
 Tell the human:
@@ -277,8 +307,10 @@ 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 **atelier-orchestrator** for iteration patterns.
+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.
+Material changes return to spec-plan for renewed approval; design changes return to
+spec-brainstorm. See **atelier-orchestrator** for iteration patterns.
 
 ---
 

package/skills/spec-plan/references/plan_template.md

@@ -7,6 +7,11 @@ implementation must preserve. Contrast the current and desired states when usefu
 Write enough for an engineer unfamiliar with the immediate problem to understand
 the plan. Do not repeat implementation steps that belong under Changes.
 
+### Preserved Behavior
+
+List the existing behavior that must remain unchanged. Keep the list short and tied to
+observable contracts.
+
 ### Decisions
 
 Include this subsection when the plan depends on meaningful implementation choices.
@@ -38,18 +43,26 @@ is more than one change.
 
 For each change:
 
-- Start with the exact file path and a concise description.
+- Start with the required behavior and the exact affected file paths.
 - 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.
+- Identify existing code to reuse, modify, or delete.
+- Map each new abstraction to a present requirement and its current consumers. Shared
+  infrastructure requires at least two current consumers with the same demonstrated need.
 - 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.
+- Group tests by changed contract and active boundary. Do not repeat the CRUD matrix across
+  layers.
 - 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.
 
+Before presenting the plan, compare its size with the requested behavior. If a bounded
+migration or refactor introduces shared infrastructure, unrelated behavior, or a plan
+substantially larger than the behavior being changed, simplify it first.
+
 ## Known Limitations
 
 Include this section only when the planned implementation intentionally leaves

package/skills/oracle-debug/references/language-tools.md

@@ -1,139 +0,0 @@
-# Debugging Tools by Language
-
-## Node.js
-
-### Node Inspector / Chrome DevTools
-
-```bash
-# Start with debugging
-node --inspect server.js
-
-# Break on first line
-node --inspect-brk server.js
-```
-
-Then open chrome://inspect in Chrome.
-
-### VS Code Debugging
-
-Create .vscode/launch.json:
-
-```json
-{
-  "type": "node",
-  "request": "launch",
-  "name": "Debug Server",
-  "program": "${workspaceFolder}/server.js",
-  "console": "integratedTerminal"
-}
-```
-
-### ndb
-
-Better debugging for Node:
-
-```bash
-npm install -g ndb
-ndb server.js
-```
-
-### console.table
-
-```javascript
-const users = [{id: 1, name: 'Alice'}, {id: 2, name: 'Bob'}];
-console.table(users);
-```
-
----
-
-## Python
-
-### pdb
-
-```python
-import pdb
-
-def calculate():
-    x = 10
-    pdb.set_trace()  # Break here
-    y = x * 2
-    return y
-
-# Commands: n (next), s (step), p x (print), l (list), w (where), c (continue)
-```
-
-### ipdb (better pdb)
-
-```bash
-pip install ipdb
-import ipdb; ipdb.set_trace()
-```
-
-### VS Code
-
-Just set breakpoint and press F5.
-
-### PyCharm
-
-Right-click → Debug.
-
----
-
-## Go
-
-### Delve
-
-```bash
-# Install
-go install github.com/go-delve/delve/cmd/dlv@latest
-
-# Run
-dlv debug main.go
-
-# Commands: n (next), s (step), p x (print), bt (backtrace), c (continue)
-```
-
-### VS Code
-
-Just set breakpoint and press F5.
-
----
-
-## Rust
-
-### LLDB with VS Code
-
-```json
-{
-  "type": "lldb",
-  "request": "launch",
-  "program": "${workspaceFolder}/target/debug/myapp",
-  "args": ["--arg1", "value"]
-}
-```
-
-### Rust Analyzer
-
-Hover over variable → "Debug" button.
-
----
-
-## Browser (JavaScript)
-
-### Chrome DevTools
-
-1. F12 → Sources tab
-2. Find file
-3. Set breakpoint
-4. Refresh page
-
-### Firefox DevTools
-
-1. F12 → Debugger tab
-2. Find file
-3. Set breakpoint
-4. Refresh page
-
-### VS Code
-
-Use "Debug JavaScript" or "Debug Edge" configuration.