@martinffx/atelier 0.1.0

package/skills/spec-implement/SKILL.md

@@ -0,0 +1,296 @@
+---
+name: spec-implement
+description: >
+  Execute implementation tasks from an approved plan.json. Use when spec-plan has produced
+  approved tasks and the human is ready to start coding. Tracks progress via beads
+  (preferred) or harness-native todos, enforces TDD, reports between batches. Trigger when the user says "implement", "go", "start",
+  "do it", or after spec-plan completes task creation. Do NOT use without an approved plan —
+  invoke spec-plan first.
+user-invocable: true
+---
+
+# Spec Implement
+
+Pick up tasks. Execute them. Track progress. Report. Stop 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.
+
+## Prerequisites
+
+Before starting, verify these exist:
+
+1. **Approved spec** — `docs/specs/YYYY-MM-DD-<feature>/design.md`
+2. **Approved plan** — `docs/specs/YYYY-MM-DD-<feature>/plan.json`
+3. **Tasks created** — In beads, harness todo list, or plan.json task list
+4. **Not on main/master** — Never start implementation 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.
+
+---
+
+## Step 1: Load and Review the Plan
+
+Read plan.json critically before writing code. Look for:
+
+- Unclear or ambiguous tasks
+- Missing file paths or incomplete validation criteria
+- Tasks that conflict with each other
+- Dependencies that don't match what you see in the codebase
+
+If you find concerns, **raise them with the human before starting**. Don't guess. Don't
+assume. Don't force through blockers.
+
+If no concerns, create task tracking and proceed.
+
+---
+
+## Step 2: Choose Execution Mode
+
+If the human hasn't specified a mode, ask.
+
+### Autonomous Mode
+
+> "Implement it all. Don't stop until you're done."
+
+- Execute all tasks in dependency order
+- Track progress: beads `bd update <id> --status in_progress` → `bd close <id>`, or harness todo list
+- Run type checking / linting continuously
+- Only stop if blocked
+
+### Batched Mode (default)
+
+> "Do a few tasks at a time."
+
+- Execute 3-5 tasks
+- Stop and report: what was done, test output, anything unexpected
+- Wait for human feedback before continuing
+
+### Subagent Mode
+
+> "Use subagents."
+
+- Invoke **code-subagents** for dispatch patterns and review cycle
+- Fresh subagent per task — no context pollution
+- Two-stage review after each: spec compliance, then code quality
+- Independent tasks dispatch in parallel, dependent tasks run sequentially
+
+Default to batched if the human hasn't expressed a preference.
+
+---
+
+## Step 3: Execute Tasks
+
+For each task, follow the plan exactly. 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).
+
+Mark it in progress:
+
+**With beads:**
+```bash
+bd update <task-id> --status in_progress
+```
+
+**With harness todos:**
+Update the todo status to in_progress.
+
+### For each task
+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.
+
+```
+1. Read task inputs and description
+2. Write failing tests (cover validation criteria)
+3. Run them — verify they fail for the RIGHT reason
+4. Implement minimal code to make tests pass
+5. Refactor if needed (tests stay green)
+6. Commit (use code-conventional-commit for commit message)
+```
+
+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** — run the tests listed in the task and check
+all acceptance criteria are met.
+
+### After each task: Review
+
+Invoke **code-review** to review the implementation before moving to the next task.
+This catches issues early rather than accumulating debt across multiple tasks.
+
+### On completion
+
+Mark the task done:
+
+**With beads:**
+```bash
+bd close <task-id> --reason "Implemented with tests"
+```
+
+**With harness todos:**
+Mark the task as completed.
+
+### Referencing existing code
+
+When the plan or human references existing implementations ("make it look like the
+users table"), read the referenced code before making changes. A reference communicates
+all implicit requirements without spelling them out.
+
+---
+
+## Step 4: Report (Batched Mode)
+
+After each batch:
+
+```
+Completed: Tasks T1-T3
+- T1: UserEntity with validation ✓
+- T2: UserEntity tests (6 passing) ✓
+- T3: UserRepository ✓
+
+Test output: 6 passed, 0 failed
+Type check: clean
+
+Ready for feedback.
+```
+
+Wait. Don't continue until the human responds.
+
+---
+
+## Step 5: Handle Feedback
+
+Expect short, terse corrections:
+
+- "You didn't implement `deduplicateByTitle`."
+- "This should be in the admin app. Move it."
+- "wider" / "still cropped"
+
+Don't ask for elaboration unless genuinely needed.
+
+### Steering patterns
+
+| Pattern | Example | What to do |
+|---------|---------|------------|
+| Cherry-pick | "Use X for the first one. Ignore the fourth." | Item-level as directed |
+| Trim scope | "Skip task T7." | Mark skipped, move on |
+| Protect interfaces | "These signatures must not change." | Adapt callers |
+| Override | "Use the library's built-in method." | Direct override |
+| Revert | "I reverted. Now just do X." | Respect narrowed scope |
+
+### On revert
+
+If the human reverts git changes and re-scopes, respect the narrowed scope completely.
+Don't salvage the previous approach. Don't ask "are you sure?"
+
+---
+
+## When to Stop and Ask
+
+**STOP immediately when:**
+
+- A test fails and you can't fix it within 2 attempts
+- You hit a dependency not covered in the plan
+- An instruction is unclear or ambiguous
+- The plan conflicts with the actual codebase
+- The design needs to change, not just the implementation
+- Verification fails repeatedly
+
+**When you stop:**
+
+1. Explain the blocker clearly
+2. Show what you tried
+3. Ask for direction
+
+Do not guess. Do not work around it. Stop and ask. **Ask for clarification rather than
+guessing.**
+
+If the plan needs to change:
+
+> "This needs a plan revision. Want me to go back to spec-plan?"
+
+If the design was wrong:
+
+> "This changes design assumptions. Want me to go back to spec-brainstorm?"
+
+---
+
+## 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
+
+**Return to spec-brainstorm when:**
+- Fundamental approach needs rethinking
+- Implementation reveals design is wrong
+
+---
+
+## Completion
+
+When all tasks are done, verify and present the work.
+
+### Verification checklist
+
+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 tasks closed** — `bd list --label <feature> --json` (beads) or check harness todo list — all tasks must be done
+5. **Diff review** — review the full diff against main/master. 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
+
+### Summary report
+
+Present to the human:
+
+```
+## Feature Complete: {feature name}
+
+**Tasks:** {completed} / {total}
+**Tests:** {new tests added}, {total passing}
+**Files:** {created}, {modified}
+
+### What was built
+- [concise list of what was implemented]
+
+### Verification
+- Test suite: ✓ all passing
+- Type check: ✓ clean
+- Lint: ✓ clean
+- Code review: ✓ complete
+
+### Ready for review
+```
+
+### Next steps
+
+After all tasks complete and verified, the next step is **spec-finish**.
+
+> "Implementation complete. Ready to validate, review, and prepare for PR?"
+
+Offer the human their options:
+
+> **Finish** — invoke spec-finish to validate, review, stack commits
+> **Keep** — leave the branch for now, come back later
+> **Discard** — delete the branch, start over
+
+Don't choose for them. Present options and wait.
+
+If validation finds bugs, loop back to implement. See **spec-orchestrator**
+for iteration patterns.

package/skills/spec-orchestrator/SKILL.md

@@ -0,0 +1,156 @@
+---
+name: spec-orchestrator
+description: >
+  Skill routing and workflow orchestration. Routes to correct spec skill based on task type.
+  Establishes discipline and manages transitions between workflow phases. Use when starting
+  any conversation or task to determine which spec skill applies.
+user-invocable: false
+---
+
+<EXTREMELY-IMPORTANT>
+If you think there is even a 1% chance a skill might apply to what you are doing, you ABSOLUTELY
+MUST invoke the skill.
+
+IF A SKILL APPLIES TO YOUR TASK, YOU DO NOT HAVE A CHOICE. YOU MUST USE IT.
+
+This is not negotiable. This is not optional. You cannot rationalize your way out of this.
+</EXTREMELY-IMPORTANT>
+
+# Spec Workflow
+
+You have skills. You MUST use them. Not "should." Not "when convenient." MUST.
+
+Invoke relevant skills BEFORE any response or action. Even a 1% chance a skill might apply
+means you invoke it. If an invoked skill turns out to be wrong for the situation, you don't
+need to follow it. But you must check.
+
+## The One Rule
+
+**Never write code until the human has reviewed and approved a written plan.**
+
+Every project goes through this process. A todo list, a single-function utility, a config
+change — all of them. "Simple" projects are where unexamined assumptions cause the most
+wasted work. The spec can be short, the plan can be brief, but you MUST present them
+and get approval.
+
+## Artifacts
+
+Every feature produces two artifacts in `docs/specs/YYYY-MM-DD-<feature>/`:
+
+```
+design.md    ← spec-brainstorm (requirements + research + architecture)
+plan.json    ← spec-plan (tasks, dependencies)
+```
+
+## Skill Routing
+
+```
+spec-brainstorm → Discovery + design + architecture → design.md
+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
+
+```
+spec-brainstorm → spec-plan → spec-implement → spec-finish
+```
+
+### Fix Complex Bug / Refactor
+
+```
+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.
+But be honest. If there's any doubt, plan it.
+
+## Hard Transitions
+
+| After completing... | The ONLY next step is... |
+|---------------------|--------------------------|
+| spec-brainstorm | spec-plan |
+| spec-plan | spec-implement |
+| spec-implement | spec-finish |
+
+Do NOT jump from requirements to code. Do NOT jump from research to implementation.
+
+## Iteration Patterns
+
+The workflow is not purely linear. Expect backflows:
+
+### Research → Research (discovery loop)
+- Brainstorm reveals new requirements → loop back to discovery phase
+- Human adds new scope mid-brainstorm → continue discovery
+
+### Plan → Research (design flaw)
+- Planning reveals design assumptions are wrong → back to brainstorm
+- Tasks can't be decomposed without more context → back to brainstorm
+
+### Implement → Plan (missing tasks)
+- Implementation reveals missing tasks → update plan.json
+- Blocked on dependency not in plan → back to plan
+
+### Implement → Research (fundamental issue)
+- Implementation reveals design is fundamentally wrong → back to brainstorm
+- "This can't work as designed" → back to brainstorm
+
+### Finish → Implement (bugs found)
+- Validation finds bugs → back to implement
+- Tests failing → back to implement
+
+### When to escalate
+If you loop 2+ times on the same issue, stop and ask the human:
+
+> "We've looped on [issue] twice. Should we reconsider the approach?"
+
+## Red Flags — You Are Rationalizing
+
+| What you're thinking | Why it's wrong |
+|----------------------|----------------|
+| "This is too simple for a plan" | Simple tasks have the most unexamined assumptions |
+| "I already know how to do this" | Knowing how ≠ having the human's approval for how |
+| "The human seems impatient" | Wasting time on wrong code is worse than planning |
+| "I'll just do a quick prototype" | Prototypes become production. Plan it. |
+| "I need to explore the code first" | That's the brainstorm phase. Write it in design.md. |
+| "Let me just fix this one thing" | One thing becomes three. Plan it. |
+| "I can plan in my head" | Plans in your head can't be reviewed or annotated |
+| "This is just a refactor" | Refactors touch more code than features. Plan it. |
+| "I'll write the plan after" | Post-hoc plans are fiction. Plan before. |
+| "I need more context first" | Skills tell you HOW to gather context. Check first. |
+| "The skill is overkill" | Simple things become complex. Use it. |
+| "I know what that skill says" | Skills evolve. Read current version. Invoke it. |
+| "This feels productive" | Undisciplined action wastes time. Skills prevent this. |
+
+## Skill Types
+
+**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
+context. These inform decisions within the workflow.
+
+Process skills come first. Knowledge skills get invoked by process skills when needed.
+
+## User Instructions
+
+"Add X" or "Fix Y" doesn't mean skip workflows. Instructions say WHAT, not HOW.
+The skills define HOW.

package/skills/spec-plan/SKILL.md

@@ -0,0 +1,248 @@
+---
+name: spec-plan
+description: >
+  Write implementation plans, iterate with human annotations, create structured tasks. Use
+  when there's an approved spec (design.md) and the next step is breaking it into implementable
+  work. Trigger when the user says "write a plan", "plan this out", "break this down",
+  "I added notes" (annotation cycle), or after spec-brainstorm completes. Also trigger for
+  "create tasks". Do NOT use for research (use spec-brainstorm) or
+  execution (use spec-implement).
+user-invocable: true
+---
+
+# Spec Plan
+
+Write a plan so clear that any engineer can follow it. Let the human tear it apart
+through annotation cycles until it's right. Then create structured tasks. This skill does
+not write code.
+
+## Artifacts
+
+```
+docs/specs/YYYY-MM-DD-<feature-name>/
+├── design.md  ← From spec-brainstorm (approved)
+└── 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.
+
+### plan.json Schema
+
+```json
+{
+  "feature": "user-authentication",
+  "spec": "docs/specs/2026-03-08-user-auth/design.md",
+  "goal": "Add email/password authentication with session management",
+  "phases": [
+    {
+      "id": "P1",
+      "name": "Domain Model",
+      "tasks": [
+        {
+          "id": "T1",
+          "name": "Implement UserEntity with validation",
+          "depends_on": [],
+          "inputs": [
+            "User schema from design.md",
+            "Validation rules (email format, password strength)"
+          ],
+          "description": "Create UserEntity with email and password fields. Implement validation using a Result type. Password must be hashed, never stored plaintext.",
+          "files": {
+            "create": ["src/entities/user.ts", "tests/entities/user.test.ts"],
+            "modify": []
+          },
+          "validation": {
+            "tests": [
+              "rejects empty email",
+              "rejects invalid email format",
+              "rejects weak password",
+              "accepts valid user input"
+            ],
+            "acceptance": [
+              "All validation tests pass",
+              "User.fromRequest returns Result<User>",
+              "No direct throws — all errors via Result"
+            ]
+          }
+        }
+      ]
+    }
+  ]
+}
+```
+
+#### Top-level fields
+
+| Field | Type | Description |
+|-------|------|-------------|
+| feature | string | Kebab-case feature name |
+| spec | string | Path to the approved design.md |
+| goal | string | One-sentence goal |
+| phases | Phase[] | Implementation phases in dependency order |
+
+#### Phase fields
+
+| Field | Type | Description |
+|-------|------|-------------|
+| id | string | Phase identifier (P1, P2...) |
+| name | string | Phase name (e.g. "Domain Model", "Data Access") |
+| tasks | Task[] | Tasks within this phase |
+
+#### Task fields
+
+| Field | Type | Description |
+|-------|------|-------------|
+| id | string | Task identifier (T1, T2...) |
+| name | string | What this task implements |
+| 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 |
+| validation | {tests, acceptance} | How to verify the task is done |
+
+---
+
+## 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.
+
+### Plan quality
+
+Write assuming the implementer:
+- Knows the language and framework
+- Doesn't know this codebase's specific patterns
+- Needs clear boundaries and validation criteria
+- Will take the path of least resistance if the plan is vague
+
+### Task structure
+
+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
+
+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 from oracle-architect:
+
+```
+Entity → Repository → Service → Router/Consumer
+```
+
+### Task size
+
+Each task should take 15-60 minutes. If larger, decompose into smaller tasks.
+
+**Tell the human:** "Plan draft is ready for review."
+
+**STOP. Wait for human review.**
+
+---
+
+## Step 2: The Annotation Cycle
+
+The human annotates the plan draft directly — adding corrections, rejections, domain
+knowledge, business constraints, or "remove this entirely."
+
+```
+You write plan → Human adds inline notes → You address all notes → Repeat 1-6x
+```
+
+When the human says "I added notes":
+
+1. Re-read the entire document
+2. Address every single note
+3. Update the plan
+4. **Do not create tasks. Do not implement.**
+
+The "don't implement yet" guard is sacred. The plan is not ready until the human
+explicitly approves it.
+
+### Steering patterns
+
+| Pattern | Example | What to do |
+|---------|---------|------------|
+| Correct assumptions | "use PATCH not PUT" | Fix it |
+| Reject approaches | "remove caching, we don't need it" | Cut cleanly |
+| Add constraints | "queue consumer already handles retries" | Restructure |
+| Override choices | "use drizzle:generate, not raw SQL" | Direct override |
+| Redirect sections | "visibility on the list, not items" | Rethink section |
+| Trim scope | "remove download, not implementing now" | Remove, no stubs |
+
+---
+
+## Step 3: Create Structured Tasks
+
+When the human approves — "looks good", "approved", "create tasks" — convert the plan
+into plan.json.
+
+### Task Tracking
+
+**Preferred:** Use beads for dependency-aware task tracking:
+```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
+```
+
+**Fallback:** If beads is not available, use the harness's native todo system.
+The harness provides todo management — use it directly.
+
+### 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. Create tasks using beads (preferred) 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)
+5. The plan.json is the source of truth for task details; the task tracker
+tracks execution state
+
+### Verification
+
+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
+- File paths are complete and specific
+- Validation criteria are concrete and testable
+
+---
+
+## Handoff
+
+When plan.json is created and tasks exist, the next step is **spec-implement**.
+
+Tell the human:
+
+> "Plan is approved and tasks are created. 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.
+
+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 **spec-orchestrator** for iteration patterns.
+
+---
+
+## Quick Reference
+
+| Human says | You do |
+|------------|--------|
+| "write a plan" / "plan this" | Step 1 → write plan draft, stop |
+| "I added notes" | Re-read, address all notes, do NOT implement |
+| "don't implement yet" | Update plan only |
+| "looks good" / "approved" / "create tasks" | Step 3 → create plan.json + task tracking |