@martinffx/atelier 1.2.1 → 1.3.0

package/skills/spec-brainstorm/SKILL.md

@@ -2,8 +2,9 @@
 name: spec-brainstorm
 description: >
   Conversational design workshop for new features. Interviews the human one question
-  at a time, explores 2-3 approaches with trade-offs, then produces a focused spec.
-  Combines requirements discovery with codebase research and architecture design.
+  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.
 user-invocable: true
@@ -14,13 +15,14 @@ argument-hint: <topic or feature description>
 
 Conversational design workshop that produces a focused, reviewed spec.
 
-One question at a time. Multiple approaches explored. Ruthless scope control.
-No implementation until design is approved.
+One question at a time. Multiple approaches explored. Design approved in
+sections. Ruthless scope control. No implementation until design is approved.
 
 ## Artifact
 
 ```
-docs/specs/YYYY-MM-DD-<topic>-design.md  ← This skill's output
+docs/specs/YYYY-MM-DD-<feature>/
+└── design.md  ← This skill's output
 ```
 
 Requirements are inline — no separate requirements.json needed.
@@ -156,11 +158,14 @@ review before I continue with the design."
 
 ---
 
-## Step 4: Design — Explore Approaches
+## Step 4: Design
 
-Before settling on a design, present **2-3 approaches** with trade-offs.
+Design happens in three phases: explore approaches, present the design in sections,
+then write the spec file.
+
+### 4a. Explore approaches
 
-### Approach exploration
+Before settling on a design, present **2-3 approaches** with trade-offs.
 
 For each approach, address:
 
@@ -169,7 +174,7 @@ For each approach, address:
 3. **Cons** — What's painful, expensive, or risky
 4. **Complexity estimate** — Rough sense of implementation effort
 
-Then make a recommendation and explain why.
+Lead with your recommended option and explain why it wins.
 
 **Example:**
 
@@ -186,23 +191,60 @@ Then make a recommendation and explain why.
 > **Recommendation:** Approach B — the query flexibility matters more here than
 > implementation speed.
 
-### Design approval gate
+Get explicit approval on the chosen approach before presenting the design.
 
-Get explicit approval on the chosen approach before writing the full spec.
-
-**Tell the human:** "Which approach should we go with? Or should I explore a different
-direction?"
+**Tell the human:** "Which approach should we go with? Or should I explore a
+different direction?"
 
 **STOP. Wait for human to choose an approach.**
 
-### Write the spec
+### 4b. Present the design in sections
+
+Present the design in batches. Get approval after each batch before continuing.
+
+Sections already confirmed in earlier steps (Problem, Scope, Constraints, Context)
+are written into the spec from those confirmations — do not re-present them.
+
+**Batch A: User Stories** — the contract you're designing against. Formal stories
+with acceptance criteria and priorities. If rejected: revise. If the rejection
+reveals a scope misunderstanding, loop back to Discovery (Step 2).
+
+**Batch B: Architecture** — component design, domain modeling, and layer
+boundaries. Use `python-architecture` or `typescript-api-design` as relevant to
+your stack. Then present: component structure, domain model, where business
+logic lives, where IO lives. If rejected: revise. If the rejection undermines
+the chosen approach, offer to return to approach exploration (4a). If it
+reveals a fundamental gap, loop back to Research (Step 3). If the detail reveals
+the work is far more complex than estimated, say so and offer to revisit the
+approach.
+
+**Batch C: API Design + Data Model** — contracts derived from the approved
+architecture. Skip sections that don't apply, but say so explicitly ("No API
+changes — moving to Trade-offs"). Never skip silently. If rejected: revise. If
+the rejection implicates the architecture, go back to Batch B.
 
-Once an approach is chosen, write the full spec document.
+**Batch D: Trade-offs + Open Questions** — alternatives considered, why this
+approach wins, known limitations, anything unresolved. Usually revisable inline.
 
-Use the Skill tool to invoke **oracle-architect** for component design, domain modeling,
-and layer boundaries.
+Each batch ends with:
 
-### What the spec should contain
+**Tell the human:** "Does this look right?"
+
+**STOP. Wait for approval before continuing.**
+
+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.
+
+### 4c. Write the spec
+
+Once all batches are approved, write the full spec document.
+
+#### What the spec should contain
 
 ```markdown
 # Feature Name
@@ -256,70 +298,48 @@ and layer boundaries.
 Scale each section to complexity — a few sentences if straightforward, detailed if
 nuanced.
 
-### Reference implementations
-
-If human provides reference code — from open source, from elsewhere in codebase — use it
-as a concrete guide. Working from a reference produces dramatically better designs.
+#### Reference implementations
 
----
-
-## Step 5: Self-Review
-
-Before presenting the spec to the human, run this checklist silently:
-
-### 1. Placeholder scan
-
-Are there any TBD, TODO, FIXME, or incomplete sections? Every section should have real
-content or be removed.
-
-### 2. Internal consistency
-
-Do sections contradict each other? If the Architecture section says "stateless" but the
-Data Model includes session state, resolve the conflict before presenting.
-
-### 3. Scope check
-
-Is this focused enough for a single implementation plan? If the spec covers more than
-one independent subsystem, it should have been decomposed in Step 2. If it's still too
-broad, flag it now.
+If the human provides reference code — from open source, from elsewhere in the
+codebase — use it as a concrete guide. Working from a reference produces
+dramatically better designs.
 
-### 4. Ambiguity check
+#### Self-review
 
-Could any requirement be interpreted two ways? If so, pick one interpretation, state it
-explicitly, and let the human correct you.
+After writing the file, check it with fresh eyes:
 
-Fix any issues found. Then present.
+1. **Placeholder scan** — Any TBD, TODO, FIXME, or incomplete sections? Every
+   section should have real content or be removed.
+2. **Internal consistency** — Do sections contradict each other? If the
+   Architecture section says "stateless" but the Data Model includes session
+   state, resolve the conflict.
+3. **Scope check** — Is this focused enough for a single implementation plan?
+   If the spec covers more than one independent subsystem, it should have been
+   decomposed in Step 2. If it's still too broad, flag it now.
+4. **Ambiguity check** — Could any requirement be interpreted two ways? If so,
+   pick one interpretation, state it explicitly, and let the human correct you.
 
-**Tell the human:** "The spec is complete. Ready for your review."
-
-**STOP. Wait for human review.**
+**Substance rule:** if a fix changes the substance of an approved section,
+re-present that section for approval. Wording and consistency fixes go inline —
+note them at handoff.
 
 ---
 
-## Step 6: Annotation
-
-Human may annotate the spec directly — adding corrections, rejections, domain knowledge,
-or "remove this section entirely."
-
-When they say "I added notes":
+## Step 5: Handoff
 
-1. Re-read the full document
-2. Address every note
-3. Update the spec
-4. Run the self-review checklist again (Step 5)
-5. **Do not move to planning**
+**Tell the human:**
 
-This may repeat 1-6 times. Spec is not approved until human explicitly says so.
+> "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?"
 
----
-
-## Handoff
+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.
 
-When the spec is approved, the next step is **spec-plan**.
-
-> "Spec is approved. Ready to write the implementation plan?"
+The next step is **spec-plan**. 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.
-
-Do not start planning without explicit approval. Do not write code.

package/skills/spec-finish/SKILL.md

@@ -2,8 +2,9 @@
 name: spec-finish
 description: >
   Post-implementation completion workflow. Use after spec-implement completes to validate,
-  review, create stacked commits, and prepare for PR. Triggers when implementation is done,
-  when the user says "finish", "done", "complete", or after implementation tasks are finished.
+  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.
 user-invocable: true
 ---
 
@@ -99,29 +100,26 @@ Use the Skill tool to invoke code-review skill for comprehensive code review.
 
 ## Step 4: Update Documentation
 
-Optional - use code-docs skill if needed.
-
 ### Check for Updates
 - README changes needed?
 - API documentation updated?
 - Changelog updated?
 
 ### If documentation needed
-- Load code-docs
 - Update relevant docs
 - Commit with docs
 
 ---
 
-## Step 5: Prepare for PR
+## 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.**
 
-### Verify
-- All tests passing
-- All reviews complete
-- Documentation updated
-- Commits stacked properly
+### Step 5a: Present Completion Summary
 
-### Summary for Human
+Before creating the PR, present a summary to the human:
 
 ```
 ## Completion Summary
@@ -130,13 +128,21 @@ Optional - use code-docs skill if needed.
 **Tests:** [passed/failed]
 **Type Check:** [passed/failed]
 **Lint:** [passed/failed]
+**Review:** [passed/issues found]
 **Commits:** [N commits in stack]
 **Ready for PR:** [yes/no]
 ```
 
+### Step 5b: Invoke code-pull-request
+
+Only when the summary shows **Ready for PR: yes**, invoke the
+[code-pull-request](../code-pull-request/SKILL.md) skill to create the PR. It
+detects the platform (GitHub/GitLab), checks for an existing PR, finds a
+template, generates the body from commits, and opens the PR via `gh` or `glab`.
+
 ### Handoff
 
-> "Implementation complete. [N] commits stacked. Ready for [submit/open PR]."
+> "Implementation complete. [N] commits stacked. Opening PR now."
 
 ---
 
@@ -145,7 +151,7 @@ Optional - use code-docs skill if needed.
 This skill orchestrates other skills:
 
 - Invokes code-review for quality check
-- Invokes code-docs if documentation needs updates
+- Invokes code-pull-request as the final step to open the PR
 
 ---
 

package/skills/spec-implement/SKILL.md

@@ -108,8 +108,9 @@ Update the todo status to in_progress.
 Read the task's **inputs** first — understand what context you need.
 Then read the **description** — know what to build and the constraints.
 
-Invoke **oracle-testing** for test design. Write tests that cover the validation
-criteria before writing implementation.
+Write tests that cover the validation criteria before writing implementation.
+Invoke `typescript-testing` or `python-testing` (whichever matches the project)
+for test design patterns when needed.
 
 ```
 1. Read task inputs and description

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 |