@martinffx/atelier 1.2.2 → 1.3.0

package/skills/spec-orchestrator/SKILL.md

@@ -50,8 +50,6 @@ 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
-oracle-architect → DDD patterns, component responsibilities
-oracle-testing   → TDD patterns, boundary testing
 ```
 
 ### "Create a spec for X" / Build / Add Feature
@@ -66,18 +64,6 @@ spec-brainstorm → spec-plan → spec-implement → spec-finish
 spec-brainstorm (research-heavy) → spec-plan (targeted) → spec-implement
 ```
 
-### Write Tests / Testing Questions
-
-```
-oracle-testing
-```
-
-### Architecture / Domain Modeling Questions
-
-```
-oracle-architect
-```
-
 ### Quick Fix / Trivial Change
 
 If genuinely trivial (typo, single-line config, variable rename) — skip the pipeline.
@@ -145,9 +131,12 @@ If you loop 2+ times on the same issue, stop and ask the human:
 **Process skills** (spec-brainstorm, spec-plan, spec-implement, spec-finish): Follow exactly.
 Don't adapt away discipline.
 
-**Knowledge skills** (oracle-architect, oracle-testing): Adapt principles to
+**Knowledge skills** (oracle-grill-me, oracle-domain-modelling): Adapt principles to
 context. These inform decisions within the workflow.
 
+**Discipline skills** (oracle-debug): Strict methodology that must be followed
+exactly — no adaptation that bypasses root-cause investigation.
+
 Process skills come first. Knowledge skills get invoked by process skills when needed.
 
 ## User Instructions

package/skills/spec-plan/SKILL.md

@@ -130,7 +130,7 @@ not HOW to write the code.
 
 ### Task ordering
 
-Follow bottom-up dependency ordering from oracle-architect:
+Follow bottom-up dependency ordering:
 
 ```
 Entity → Repository → Service → Router/Consumer

package/agents/scout.md

@@ -1,40 +0,0 @@
----
-name: scout
-description: Fast codebase reconnaissance and exploration, concise summarization of findings, precise location of relevant context, and efficient workspace preparation through targeted file operations and template application
-model: minimax-m2.7
----
-
-You are the **Scout**, a fast reconnaissance agent. Your job is to explore codebases, summarize what you find, highlight relevant context, and point others to exactly where things live. You move quickly, read minimally, and never break existing work.
-
-## Role
-
-- Explore and map codebase structure, conventions, and key files
-- Summarize findings with clear, concise overviews
-- Highlight relevant context and explain why it matters
-- Point to exact locations (file paths, line numbers, symbol names) so others can dive deeper
-- Retrieve targeted snippets on request—never dump full files unless necessary
-- Create files from templates and set up directory structures when asked
-- Respect existing files—never overwrite without explicit direction
-
-## Skills
-
-Before beginning work, scan your environment for relevant skills and load any that apply to the task at hand. Use them to guide how you explore, summarize, and present your findings.
-
-## Checklist
-
-Before finishing, confirm you have:
-
-- [ ] Retrieved only the specific context requested (no unnecessary full-file reads)
-- [ ] Verified the target file does not already exist before creating
-- [ ] Created parent directories as needed
-- [ ] Applied all relevant variable substitutions when using templates
-- [ ] Confirmed the output matches the request exactly
-- [ ] Reported what was created, retrieved, or modified
-
-## Boundaries
-
-- DO handle file operations and retrieval efficiently
-- DO create files and directories as requested
-- DON'T make design or architectural decisions 
-- DON'T conduct requirements discovery 
-- NEVER overwrite existing files unless explicitly told to

package/skills/code-commit/references/pr-workflow.md

@@ -1,145 +0,0 @@
-# Pull Request Workflow
-
-Creating GitHub pull requests via the `gh` CLI.
-
-## Prerequisites
-
-- `gh` CLI installed and authenticated: `gh auth status`
-- Remote `origin` points to GitHub: `git remote -v`
-- On a feature branch (not main): `git branch --show-current`
-
-## Check for Project Template
-
-Before creating a PR, check if the project has its own PR template:
-
-```bash
-# Check for PR template in .github/
-ls .github/PULL_REQUEST_TEMPLATE.md 2>/dev/null || echo "No project template found"
-```
-
-**If found:** Use it. The `gh pr create` command will automatically pick it up.
-
-**If not found:** Use the minimal template below.
-
----
-
-## Create Pull Request
-
-### Option 1: Auto-fill from commits (recommended)
-
-```bash
-gh pr create --fill
-```
-
-This uses the commit messages as the PR title and body. Best when commits are clean and conventional.
-
-### Option 2: Interactive
-
-```bash
-gh pr create
-```
-
-Opens an editor with the template. Fill in title and body interactively.
-
-### Option 3: Inline (for simple PRs)
-
-```bash
-gh pr create --title "feat(auth): add JWT authentication" --body "Implements token-based auth with refresh support."
-```
-
----
-
-## PR Title Format
-
-Follow conventional commit style for PR titles:
-
-```
-<type>(<scope>): <description>
-```
-
-Examples:
-- `feat(api): add user profile endpoint`
-- `fix(db): resolve connection pool leak`
-- `docs(readme): update installation instructions`
-
----
-
-## PR Body Template (fallback if no project template)
-
-```markdown
-## Description
-<!-- What does this PR do? -->
-
-## Changes
-<!-- What changed? -->
-
-## Testing
-<!-- How was this tested? -->
-
-## Checklist
-- [ ] Tests pass
-- [ ] Commits follow conventional format
-- [ ] Documentation updated (if needed)
-```
-
----
-
-## Linking Issues
-
-Add issue references in the PR body:
-
-```markdown
-Closes #123
-Fixes #456
-Relates to #789
-```
-
-This auto-closes linked issues when the PR merges.
-
----
-
-## Draft PRs
-
-For work-in-progress PRs:
-
-```bash
-gh pr create --draft
-```
-
-Mark as ready later:
-
-```bash
-gh pr ready <pr-number>
-```
-
----
-
-## Review Requests
-
-Request reviewers after creating the PR:
-
-```bash
-gh pr edit <pr-number> --add-reviewer username
-```
-
-Or add via the GitHub web UI.
-
----
-
-## Verify PR Created
-
-```bash
-gh pr view --web  # Open in browser
-gh pr status      # Show PR status
-```
-
----
-
-## Common Mistakes
-
-| Mistake | Fix |
-|---------|-----|
-| PR from main branch | Switch to feature branch first |
-| No remote | `git remote add origin <url>` |
-| Unpushed commits | `git push -u origin <branch>` |
-| PR body is empty | Use `--fill` or write a description |

package/skills/code-debug/SKILL.md

@@ -1,199 +0,0 @@
----
-name: code-debug
-description: >
-  Disciplined diagnosis loop for hard bugs and performance regressions.
-  Reproduce → minimise → hypothesise → instrument → fix → regression-test.
-  Use when user says "diagnose this" / "debug this", reports a bug, says
-  something is broken/throwing/failing, or describes a performance regression.
-user-invocable: true
----
-
-# Code Debug
-
-A discipline for hard bugs. Skip phases only when explicitly justified.
-
-When exploring the codebase, use the project's domain glossary to get a clear
-mental model of the relevant modules, and check ADRs in the area you're touching.
-
----
-
-## Phase 1 — Build a feedback loop
-
-**This is the skill.** Everything else is mechanical. If you have a fast,
-deterministic, agent-runnable pass/fail signal for the bug, you will find the
-cause — bisection, hypothesis-testing, and instrumentation all just consume
-that signal. If you don't have one, no amount of staring at code will save you.
-
-Spend disproportionate effort here. **Be aggressive. Be creative. Refuse to
-give up.**
-
-### Ways to construct one — try them in roughly this order
-
-1. **Failing test** at whatever seam reaches the bug — unit, integration, e2e.
-2. **Curl / HTTP script** against a running dev server.
-3. **CLI invocation** with a fixture input, diffing stdout against a known-good
-   snapshot.
-4. **Headless browser script** (Playwright / Puppeteer) — drives the UI,
-   asserts on DOM/console/network.
-5. **Replay a captured trace.** Save a real network request / payload / event
-   log to disk; replay it through the code path in isolation.
-6. **Throwaway harness.** Spin up a minimal subset of the system (one service,
-   mocked deps) that exercises the bug code path with a single function call.
-7. **Property / fuzz loop.** If the bug is "sometimes wrong output", run 1000
-   random inputs and look for the failure mode.
-8. **Bisection harness.** If the bug appeared between two known states (commit,
-   dataset, version), automate "boot at state X, check, repeat" so you can
-   `git bisect run` it.
-9. **Differential loop.** Run the same input through old-version vs new-version
-   (or two configs) and diff outputs.
-10. **HITL bash script.** Last resort. If a human must click, drive _them_ with
-    a structured script so the loop is still structured. Captured output feeds
-    back to you.
-
-Build the right feedback loop, and the bug is 90% fixed.
-
-### Iterate on the loop itself
-
-Treat the loop as a product. Once you have _a_ loop, ask:
-
-- Can I make it faster? (Cache setup, skip unrelated init, narrow the test scope.)
-- Can I make the signal sharper? (Assert on the specific symptom, not "didn't crash".)
-- Can I make it more deterministic? (Pin time, seed RNG, isolate filesystem, freeze network.)
-
-A 30-second flaky loop is barely better than no loop. A 2-second deterministic
-loop is a debugging superpower.
-
-### Non-deterministic bugs
-
-The goal is not a clean repro but a **higher reproduction rate**. Loop the
-trigger 100×, parallelise, add stress, narrow timing windows, inject sleeps.
-A 50%-flake bug is debuggable; 1% is not — keep raising the rate until it's
-debuggable.
-
-### When you genuinely cannot build a loop
-
-Stop and say so explicitly. List what you tried. Ask the user for:
-(a) access to whatever environment reproduces it,
-(b) a captured artifact (HAR file, log dump, core dump, screen recording with timestamps), or
-(c) permission to add temporary production instrumentation.
-
-Do **not** proceed to hypothesise without a loop.
-
-**Do not proceed to Phase 2 until you have a loop you believe in.**
-
----
-
-## Phase 2 — Reproduce
-
-Run the loop. Watch the bug appear.
-
-Confirm:
-
-- [ ] The loop produces the failure mode the **user** described — not a different failure that happens to be nearby. Wrong bug = wrong fix.
-- [ ] The failure is reproducible across multiple runs (or, for non-deterministic bugs, reproducible at a high enough rate to debug against).
-- [ ] You have captured the exact symptom (error message, wrong output, slow timing) so later phases can verify the fix actually addresses it.
-
-**Do not proceed until you reproduce the bug.**
-
----
-
-## Phase 3 — Hypothesise
-
-Generate **3–5 ranked hypotheses** before testing any of them. Single-hypothesis
-generation anchors on the first plausible idea.
-
-Each hypothesis must be **falsifiable**: state the prediction it makes.
-
-> Format: "If `<X>` is the cause, then `<changing Y>` will make the bug disappear / `<changing Z>` will make it worse."
-
-If you cannot state the prediction, the hypothesis is a vibe — discard or sharpen it.
-
-**Show the ranked list to the user before testing.** They often have domain
-knowledge that re-ranks instantly ("we just deployed a change to #3"), or know
-hypotheses they've already ruled out. Cheap checkpoint, big time saver. Don't
-block on it — proceed with your ranking if the user is AFK.
-
----
-
-## Phase 4 — Instrument
-
-Each probe must map to a specific prediction from Phase 3. **Change one variable
-at a time.**
-
-Tool preference:
-
-1. **Debugger / REPL inspection** if the env supports it. One breakpoint beats ten logs.
-2. **Targeted logs** at the boundaries that distinguish hypotheses.
-3. Never "log everything and grep".
-
-**Tag every debug log** with a unique prefix, e.g. `[DEBUG-a4f2]`. Cleanup at
-the end becomes a single grep. Untagged logs survive; tagged logs die.
-
-**Perf branch.** For performance regressions, logs are usually wrong. Instead:
-establish a baseline measurement (timing harness, `performance.now()`, profiler,
-query plan), then bisect. Measure first, fix second.
-
----
-
-## Phase 5 — Fix + regression test
-
-Write the regression test **before the fix** — but only if there is a
-**correct seam** for it.
-
-A correct seam is one where the test exercises the **real bug pattern** as it
-occurs at the call site. If the only available seam is too shallow (single-caller
-test when the bug needs multiple callers, unit test that can't replicate the
-chain that triggered the bug), a regression test there gives false confidence.
-
-**If no correct seam exists, that itself is the finding.** Note it. The codebase
-architecture is preventing the bug from being locked down. Flag this for the
-next phase.
-
-If a correct seam exists:
-
-1. Turn the minimised repro into a failing test at that seam.
-2. Watch it fail.
-3. Apply the fix.
-4. Watch it pass.
-5. Re-run the Phase 1 feedback loop against the original (un-minimised) scenario.
-
----
-
-## Phase 6 — Cleanup + post-mortem
-
-Required before declaring done:
-
-- [ ] Original repro no longer reproduces (re-run the Phase 1 loop)
-- [ ] Regression test passes (or absence of seam is documented)
-- [ ] All `[DEBUG-...]` instrumentation removed (`grep` the prefix)
-- [ ] Throwaway prototypes deleted (or moved to a clearly-marked debug location)
-- [ ] The hypothesis that turned out correct is stated in the commit / PR message — so the next debugger learns
-
-**Then ask: what would have prevented this bug?**
-
-If the answer involves architectural change (no good test seam, tangled callers,
-hidden coupling) flag this as a codebase health finding for the team.
-
----
-
-## References
-
-- **Language-specific tools** → `references/language-tools.md`
-- **Common bug patterns** → `references/bug-patterns.md`
-- **Logging & techniques** → `references/techniques.md`
-
-## Output Format
-
-After each debugging session, summarise:
-
-```
-## Debug Summary
-
-**Problem:** [One sentence]
-**Root Cause:** [What actually was wrong]
-**Fix:** [How you fixed it]
-**Verification:** [Test results]
-**Prevention:** [Regression test added? Architectural finding?]
-```
-
-This helps future-you understand what happened.

package/skills/code-docs/SKILL.md

@@ -1,171 +0,0 @@
----
-name: code-docs
-description: >
-  Documentation generation for code projects. Use when updating docs, writing README, generating
-  API docs, creating changelog, or when the user mentions documentation, docs, readme, api docs,
-  or any documentation task.
-user-invocable: false
----
-
-# Code Docs
-
-Documentation generation and maintenance for code projects.
-
-## When to Document
-
-**Always update docs when:**
-- Adding new features
-- Changing existing behavior
-- Updating configuration
-- Breaking changes
-
-**Docs should live:**
-- Near the code (docstrings, comments)
-- In the repo (README, docs folder)
-- Generated (API docs, type docs)
-
----
-
-## Doc Types
-
-### README
-
-Project overview, setup, usage. See references/readme-structure.md
-
-**Template:**
-```markdown
-# Project Name
-
-Brief description (one line).
-
-## Quick Start
-
-3-5 commands to get running.
-
-## Installation
-
-Detailed setup steps.
-
-## Usage
-
-Code examples.
-
-## API
-
-Link to full API docs.
-
-## Contributing
-
-How to contribute.
-
-## License
-```
-
-### API Documentation
-
-See references/api-docs.md for:
-- TypeDoc (JavaScript/TypeScript)
-- Sphinx (Python)
-- godoc (Go)
-- JSDoc (JavaScript)
-
-### Changelog
-
-See references/changelog.md for Keep a Changelog format.
-
-**Sections:**
-- Added
-- Changed
-- Deprecated
-- Removed
-- Fixed
-- Security
-
-### Architecture Docs
-
-See references/architecture-docs.md for:
-- ADRs (Architecture Decision Records)
-- Diagrams
-- System overviews
-
----
-
-## Generation Commands
-
-### TypeScript/JavaScript
-
-```bash
-# TypeDoc
-npx typedoc --out docs src/index.ts
-
-# JSDoc
-npx jsdoc src/ -d docs/
-
-# API Extractor (monorepos)
-npx api-extractor run
-```
-
-### Python
-
-```bash
-# Sphinx
-sphinx-build -b html docs docs/_build
-
-# pdoc
-pdoc --output-dir docs src/
-
-# mkdocs
-mkdocs serve
-```
-
-### Go
-
-```bash
-# godoc
-godoc -http=:6060
-
-# swag (OpenAPI from comments)
-swag init -g cmd/server/main.go
-```
-
----
-
-## Workflow
-
-### 1. Identify what needs docs
-
-- New files/features → update relevant doc
-- Breaking change → update CHANGELOG
-- New public API → update API docs
-
-### 2. Generate/Update
-
-- Run doc generators
-- Update manual docs
-- Verify examples work
-
-### 3. Verify
-
-- Links work
-- Examples run
-- Build passes
-
-### 4. Commit
-
-```
-docs: update API documentation
-
-Generated via typedoc.
-Added: new /users endpoint
-Changed: authentication section
-```
-
----
-
-## Best Practices
-
-1. **Write docs in the code** - Docstrings, comments
-2. **Generate where possible** - Don't duplicate
-3. **Keep README minimal** - Link to detailed docs
-4. **Version with code** - Docs in same repo/PR
-5. **Test examples** - Ensure they run