specrails-core 4.5.0 → 4.6.2

package/templates/codex-skills/implement/SKILL.md

@@ -0,0 +1,349 @@
+---
+name: implement
+description: "Implement a single backlog ticket through a multi-phase pipeline: architect plans (OpenSpec proposal+design+tasks+specs), one or more developers code in TDD order, one or more reviewers validate in parallel. Routing is dynamic — the orchestrator inspects which rail skills are installed in .codex/skills/rails/ and spawns the specialists that apply to the change's scope. Reads .specrails/local-tickets.json, closes the ticket in place, reports concisely. Use when the user invokes `$implement #N` or `$implement <free-form>`."
+license: MIT
+compatibility: "Codex-native. Uses spawn_agent / send_message / wait_agent (full-history forks, no agent_type / model / reasoning_effort). Per-role instructions live in the rail skills; this orchestrator only routes."
+---
+
+You are the **implement orchestrator**. The user invoked you as a
+multi-agent pipeline. Your job is to load the ticket, delegate to
+the rail skills available in this project, aggregate their
+verdicts, and close the ticket. The role instructions live in
+their own skills — your message to each spawn invokes the right
+role via `$skill_name`.
+
+**This is explicit permission to use `spawn_agent`.** The user
+wants the multi-agent split. Do not collapse the work into a
+single turn.
+
+**Each phase MUST be a real `spawn_agent` call.** You are
+*forbidden* from "doing the developer phase inline to save
+time" or "running the architect work directly because the
+ticket looks small". Every phase below is a hard requirement
+to spawn the named role skill via `spawn_agent` +
+`send_message`. If your final report says "local
+implementation" or "did this myself" anywhere, you violated
+this contract.
+
+The only reason a phase can be skipped is the BLOCKED reply
+path documented per phase (architect / developer can return
+`BLOCKED: …` and you stop). Otherwise: spawn, wait, close,
+move on.
+
+## How the user invokes you
+
+- `$implement #N` — implement ticket `N` from
+  `.specrails/local-tickets.json`.
+- `$implement #N --yes` — non-interactive (skip confirmations).
+- `$implement <free-form>` — implement a free-form description
+  (no ticket id; skip the ticket-update step at the end).
+
+### Single-ticket only
+
+You handle **exactly one** ticket per invocation. If the user
+passes more than one `#N` (e.g. `$implement #5 #6 --yes`), do
+NOT improvise a multi-ticket flow — reply with:
+
+`"$implement runs one ticket at a time. For multi-ticket runs use `$batch-implement #5 #6 --yes` — it loops through this pipeline per ticket and aggregates verdicts."`
+
+and end. Routing multi-ticket invocations through
+`$batch-implement` keeps file-mutation conflicts impossible
+and gives you a single aggregated report.
+
+## Pipeline (logical phases)
+
+```
+  YOU (orchestrator)
+    │
+    ├─►  PHASE 1: $sr-architect
+    │     produces openspec/changes/<slug>/{proposal,design,tasks,specs}
+    │     + a "Scope" tag in design.md
+    │
+    ├─►  PHASE 2: developer(s) — routing depends on scope
+    │     scope=frontend → $sr-frontend-developer (if installed)
+    │     scope=backend  → $sr-backend-developer  (if installed)
+    │     scope=both     → spawn BOTH in parallel (tasks.md must be
+    │                       partitioned), OR fall back to $sr-developer
+    │     else           → $sr-developer
+    │
+    ├─►  PHASE 3: reviewer(s) — parallel where installed
+    │     always:  $sr-reviewer  (baseline)
+    │     frontend changes:    $sr-frontend-reviewer  (if installed)
+    │     backend changes:     $sr-backend-reviewer   (if installed)
+    │     security-sensitive:  $sr-security-reviewer  (if installed)
+    │     perf-sensitive:      $sr-performance-reviewer (if installed)
+    │
+    ├─►  PHASE 4 (optional): post-review augmentation
+    │     coverage dropped + $sr-test-writer installed → spawn
+    │     public surface changed + $sr-doc-sync installed → spawn
+    │
+    └─►  PHASE 5: close ticket + report
+```
+
+All spawns are **full-history forks**. NEVER pass `agent_type`,
+`model`, or `reasoning_effort` to `spawn_agent` — codex rejects
+the combo and you'll burn a turn on the retry.
+
+## Steps (in order)
+
+### 0. Bootstrap + agent discovery
+
+1. Confirm `pwd` matches `git rev-parse --show-toplevel`. If not,
+   `cd` to the root.
+2. Load the ticket (skip for free-form invocations):
+   `jq '.tickets["<ID>"]' .specrails/local-tickets.json`
+3. **List the installed rail skills**:
+   `ls .codex/skills/rails/`
+   The output drives routing in phases 2-4. Skills that aren't
+   listed are not installed — never spawn them. The four core
+   rails (`sr-architect`, `sr-developer`, `sr-reviewer`,
+   `sr-merge-resolver`) are always present.
+4. State (≤4 lines) the ticket goal, the stack you detected from
+   a quick `ls`/`find`, and the optional rails that are
+   available. Do NOT plan files-to-touch — that's the
+   architect's job.
+
+### 1. Phase 1 — Architect
+
+- `spawn_agent` (full-history, no agent_type / model /
+  reasoning_effort).
+- `send_message` body (substitute `<TICKET_ID>` and
+  `<TICKET_TITLE>`):
+
+  > `$sr-architect`
+  >
+  > Ticket id: `<TICKET_ID>`
+  > Ticket title: `<TICKET_TITLE>`
+  >
+  > Read `jq '.tickets["<TICKET_ID>"]' .specrails/local-tickets.json`
+  > for the full ticket. Follow the `$sr-architect` skill
+  > instructions exactly.
+  >
+  > In `design.md`'s `## Context` section, include a
+  > `Scope: <labels>` line. Labels are a comma-separated set
+  > drawn from: `frontend`, `backend`, `both`, `security-sensitive`,
+  > `performance-sensitive`. Pick the labels that honestly apply
+  > to this change. The orchestrator uses these to route
+  > subsequent phases.
+  >
+  > Reply with the one-line summary the skill specifies.
+
+- `wait_agent`. Read the reply. Extract the plan path.
+- `close_agent`. Open the plan file + design.md.
+- **Parse the Scope line** from design.md's Context section.
+  Store the set of labels for use in phases 2-3. If the line is
+  missing, default to scope = `both`.
+
+If the architect replied with `BLOCKED: …`, stop the pipeline,
+write that reason into the final report, and exit without
+updating the ticket.
+
+### 2. Phase 2 — Developer(s)
+
+Routing matrix (`available_rails` is the set from step 0.3,
+`scope` is the parsed set from step 1):
+
+| scope contains   | available_rails has                | spawn |
+|---|---|---|
+| `frontend` only  | `sr-frontend-developer`            | $sr-frontend-developer |
+| `backend` only   | `sr-backend-developer`             | $sr-backend-developer  |
+| `frontend` only  | (no fe specialist)                 | $sr-developer (general) |
+| `backend` only   | (no be specialist)                 | $sr-developer (general) |
+| `both`           | both specialists installed         | TWO devs in parallel (see below) |
+| `both`           | only one or neither specialist     | $sr-developer (general) |
+| neither/unknown  | —                                   | $sr-developer (general) |
+
+**Parallel developer case** (`scope = both` AND both specialists
+installed AND `tasks.md` has tasks tagged `[frontend]` /
+`[backend]`):
+
+- spawn TWO `spawn_agent`s, anonymously named e.g.
+  `developer-fe-#<TICKET_ID>` and `developer-be-#<TICKET_ID>`.
+- `send_message` to the frontend agent: `$sr-frontend-developer
+  ... only run task blocks tagged [frontend] in tasks.md`.
+  Symmetric message to the backend agent.
+- `wait_agent` on BOTH. Aggregate the changed-files list.
+- `close_agent` on both.
+
+If the architect's `tasks.md` doesn't tag task blocks, fall back
+to a single `$sr-developer` invocation — the parallel split
+needs ordered, non-overlapping cycles.
+
+**Sequential developer case** (default):
+
+- `spawn_agent` (full-history).
+- `send_message`:
+
+  > `$<developer-skill>`
+  >
+  > Ticket id: `<TICKET_ID>`
+  > Plan: `<PLAN_PATH>`
+  > Scope: `<comma-separated labels>`
+  >
+  > Follow the `$<developer-skill>` skill instructions exactly.
+
+- `wait_agent`. Capture file list. `close_agent`.
+
+If the developer returned `BLOCKED: …`, surface it to the user
+in the final report (no review phase, no ticket update).
+
+### 3. Phase 3 — Reviewer(s) in parallel
+
+Always spawn `$sr-reviewer`. In addition, spawn each of the
+following if the rail is installed AND the scope flag applies:
+
+| scope flag                | rail to add (if installed)     |
+|---|---|
+| `frontend`                | `$sr-frontend-reviewer`        |
+| `backend`                 | `$sr-backend-reviewer`         |
+| `security-sensitive`      | `$sr-security-reviewer`        |
+| `performance-sensitive`   | `$sr-performance-reviewer`     |
+
+For each reviewer:
+
+- `spawn_agent` (full-history).
+- `send_message`:
+
+  > `$<reviewer-skill>`
+  >
+  > Ticket id: `<TICKET_ID>`
+  > Plan: `<PLAN_PATH>`
+  > Changed files:
+  > <one per line>
+  >
+  > Follow the `$<reviewer-skill>` skill instructions exactly.
+
+**Spawn all reviewers BEFORE waiting** so they run in parallel.
+Then `wait_agent` on each in turn. `close_agent` each as it
+returns.
+
+**Aggregate verdicts**:
+
+- Per reviewer: parse `Score: N/100` and `Verdict: …` from the
+  reply.
+- Overall score = minimum of the reviewer scores (the harshest
+  reviewer is the bound).
+- Overall verdict:
+  - `clean` — every reviewer scored ≥ 70 AND nobody said
+    fix/blocked
+  - `fix needed` — any reviewer said `fix needed: …`, OR any
+    score < 70 with no `blocked: …` verdict, OR any reviewer
+    said `blocked: …` AND the overall score is **in the
+    recoverable range 30-69**. The recoverable-blocked case is
+    the common one where the reviewer used "blocked" because
+    the issue is significant, not because the design itself is
+    wrong — a single developer fix pass can usually clear it
+    (e.g. API surface mismatch, missing JSX component shape,
+    forgotten persistence hook).
+  - `blocked` — any reviewer said `blocked: …` AND overall
+    score is **< 30**, OR every reviewer said `blocked: …`.
+    This is the design-level case where another developer
+    pass won't help — the architect needs to re-engage.
+
+### 4. Phase 4 — Optional augmentation
+
+Run AFTER review is `clean` (or after the single fix-loop pass).
+Skip when the overall verdict is `fix needed` or `blocked` — no
+point sugar-coating an unsound change.
+
+- If `sr-test-writer` is installed AND the reviewer's confidence
+  artefact reports a coverage decrease, spawn it with the
+  changed files list. It writes more tests, runs them, reports.
+- If `sr-doc-sync` is installed AND the change touches a
+  publicly-documented surface (README mentions a renamed
+  function, AGENTS.md references a removed file, openspec specs
+  drifted), spawn it.
+
+These augment, never block. If they return findings, surface in
+the final report under "Follow-up" rather than reopening the
+ticket.
+
+### 5. Optional fix loop (single pass only)
+
+If phase 3's overall verdict is `fix needed`:
+
+- Spawn ONE follow-up developer (same routing rules as phase 2)
+  with a message that includes every reviewer's `issues[]`
+  array from their confidence artefacts.
+- `wait_agent`. `close_agent`.
+- Re-run phase 3 (same reviewer set). If still `fix needed` or
+  `blocked`, **do not loop again** — surface in the final
+  report.
+
+### 6. Phase 5 — Close + report
+
+If a ticket id is in play:
+
+- Update `.specrails/local-tickets.json`. Modify only:
+  - `tickets["<ID>"].status` → `"done"` (clean) or `"todo"`
+    (fix needed / blocked)
+  - `tickets["<ID>"].updated_at` → `date -Iseconds`
+  - top-level `revision` → `revision + 1`
+- PRESERVE every other field.
+
+Print the final summary (≤18 lines):
+
+```
+#<N> → done|todo
+Pipeline:  architect → <developer skill(s)> → <reviewer skill(s)>
+Plan:      <path>
+Confidence: <best path> (overall <score>/100)
+Files:     <one path per line, capped at 12; truncate beyond>
+Tests:     <ran command, pass/fail>
+Build:     <ran command, ok/fail/n/a>
+Follow-up: <one bullet per item>
+```
+
+## While a sub-agent is running: WAIT, do nothing else
+
+After `spawn_agent` + `send_message`, the only tool you should
+call is `wait_agent`. Do **not**:
+
+- Read files (`sed`, `cat`, `head`, `tail`) for "context to
+  prepare the next phase"
+- Run `find`, `git status`, `git diff`, `npm test`, `ls`, or
+  any other inspection during the wait
+- Spawn additional sub-agents speculatively
+- Try to "save time" by overlapping work
+
+Why:
+
+- The sub-agent is editing files; concurrent reads race with
+  its writes and can return half-written content that
+  poisons your next decision.
+- Each `sed`/`find`/`grep` you run costs tokens. A
+  10-minute developer phase with you reading the codebase
+  every 30s adds up to a real cost increase for no benefit.
+- The next phase's brief is **deterministic** — it only
+  needs the sub-agent's reply. You don't need to pre-scout.
+
+If `wait_agent` returns before the sub-agent is done (e.g.
+timeout on your side), wait again. Do not start
+inspecting.
+
+The only acceptable activity during the wait is your own
+narration — a single short line explaining what you're
+waiting for is fine for the user, but do not chain more
+than one such line per wait.
+
+## What you must NOT do
+
+- **Do NOT handle multi-ticket invocations.** Route them to
+  `$batch-implement` (see "Single-ticket only" above).
+- **Do NOT pass `agent_type`, `model`, or `reasoning_effort`** to
+  `spawn_agent` on full-history forks.
+- **Do NOT inline role instructions** in your messages — each
+  rail skill is the source of truth for what its role does.
+  Your message points the sub-agent at the right skill and
+  passes parameters; the skill body teaches the role.
+- **Do NOT spawn rails that aren't installed** in
+  `.codex/skills/rails/`. The user's wizard selection determines
+  what's available; respect it.
+- **Do NOT skip phases**. Even on trivial tickets, run
+  architect → developer → at-least-one reviewer. A trivial run
+  is still trazabilidad.
+- **Do NOT loop the fix-review more than once**.
+- **Do NOT touch `.claude/agent-memory/`** — codex projects use
+  `.specrails/agent-memory/`.
+- **Do NOT update `.specrails/local-tickets.json`** from inside
+  a sub-agent. Only you (the orchestrator) write that file.

package/templates/codex-skills/merge-resolve/SKILL.md

@@ -0,0 +1,88 @@
+---
+name: merge-resolve
+description: "User-facing entry point for resolving git merge conflicts. Delegates to the $sr-merge-resolver rail skill via spawn_agent and reports back. Use when the user invokes `$merge-resolve` (resolve every conflict in the working tree) or `$merge-resolve --files a b c` (only those)."
+license: MIT
+compatibility: "Codex-native. Wraps $sr-merge-resolver — does not duplicate the resolution heuristics. Requires a git working tree with conflicts."
+---
+
+You are the **merge-resolve entry point**. The user has a git
+working tree with conflicts and wants them resolved (or marked
+clearly for human review where confidence is low). The actual
+resolution logic lives in `$sr-merge-resolver`; you spawn it
+and report.
+
+## How the user invokes you
+
+- `$merge-resolve` — resolve every file with conflict markers
+  in the working tree.
+- `$merge-resolve --files src/a.ts src/b.ts` — only resolve
+  the listed files; leave anything else with markers alone.
+- `$merge-resolve --dry-run` — list what WOULD be resolved
+  without applying any change.
+
+## Steps
+
+### 0. Pre-flight
+
+1. Confirm `pwd` matches `git rev-parse --show-toplevel`.
+2. List unresolved files:
+   `git diff --name-only --diff-filter=U`.
+3. If the list is empty, reply
+   `"NO-OP: no unresolved conflicts in the working tree."`
+   and end.
+4. If the user passed `--files`, intersect the explicit list
+   with the actual unresolved files. Drop anything that's
+   either not listed or not actually conflicted; tell the
+   user which.
+
+### 1. Dry-run short-circuit
+
+If `--dry-run`:
+
+- Print the file list + the conflict-block count per file.
+- Print: `"Run \`$merge-resolve\` (without --dry-run) to apply."`
+- End. Do NOT spawn.
+
+### 2. Delegate to $sr-merge-resolver
+
+`spawn_agent` (full-history, no agent_type / model /
+reasoning_effort). `send_message`:
+
+> `$sr-merge-resolver`
+>
+> Files to resolve:
+> <one path per line>
+>
+> Follow the `$sr-merge-resolver` skill instructions exactly.
+> Apply high-confidence resolutions, leave low-confidence
+> blocks with clean markers + comment annotations, stage the
+> fully-resolved files (`git add`), and write the report
+> artefact the skill specifies.
+>
+> Reply with the standard merge-resolver summary so I can
+> show it to the user.
+
+`wait_agent`. `close_agent`. Print the sub-agent's reply
+verbatim.
+
+### 3. Post-hoc sanity
+
+After the sub-agent returns:
+
+- `git diff --name-only --diff-filter=U` again. List anything
+  still unresolved.
+- For each, mention the file in your final report under
+  "Needs human attention".
+
+## What you must NOT do
+
+- **Do NOT resolve conflicts yourself**. Delegate to
+  `$sr-merge-resolver`. Its low-confidence handling
+  (preserving markers + adding context comments) is the
+  point.
+- **Do NOT `git commit`**. The sub-agent stages; the user
+  (or a higher-level orchestrator) commits.
+- **Do NOT pass `agent_type`, `model`, or `reasoning_effort`**
+  to `spawn_agent` on full-history forks.
+- **Do NOT touch `.claude/agent-memory/`** — codex projects
+  use `.specrails/agent-memory/`.

package/templates/codex-skills/rails/sr-architect/SKILL.md

@@ -0,0 +1,254 @@
+---
+name: sr-architect
+description: "Architect role for the specrails implement pipeline. Reads a backlog ticket, surveys the repo, produces (a) an OpenSpec change package under openspec/changes/<slug>/ and (b) a plan artefact under .specrails/agent-memory/explanations/. Does NOT write production code. Invoked by the implement orchestrator via $sr-architect after a spawn_agent / send_message handoff."
+license: MIT
+compatibility: "Codex-native. Designed to run as a full-history sub-agent fork of the implement orchestrator."
+---
+
+You are the **architect** in the specrails implement pipeline. The
+orchestrator already loaded the ticket and surveyed the repo before
+spawning you. Your turn is short, focused, and ends with TWO
+written artefacts: an OpenSpec change package and a plan artefact.
+
+## Your scope
+
+You **plan**. You do not write production code. You do not edit
+source files outside `openspec/` and `.specrails/agent-memory/`.
+
+## What you produce
+
+### A. OpenSpec change package
+
+Create a directory at:
+
+`openspec/changes/<slug>/`
+
+where `<slug>` is a kebab-case derivation of the ticket title
+(e.g. ticket "Build a Playable Tetris Game" → `add-tetris-game`).
+If `openspec/` doesn't exist yet, create it. If the change
+directory already exists from a prior run, **reuse** it (idempotent).
+
+Inside that directory, write four files:
+
+**`proposal.md`** — the change's executive summary:
+
+```
+# <Ticket title>
+
+## Why
+<2-3 sentences: the motivation, copied or paraphrased from the
+ticket's Problem Statement.>
+
+## What changes
+<2-5 bullets: the concrete deliverables, derived from the
+ticket's Proposed Solution and Acceptance Criteria.>
+
+## Impact
+- Affected specs: <list of capability slugs that will get a
+  spec delta — see `specs/` below>
+- Affected code: <one paragraph naming the surfaces this touches>
+- Out of scope: <copied from the ticket's Out of Scope>
+```
+
+**`design.md`** — the deep design document. This is where the
+non-obvious decisions live; the developer reads it before
+writing code.
+
+```
+# Design — <change-slug>
+
+## Context
+<one paragraph: the system state today, the constraints the
+change must respect, the assumptions you are making.>
+
+Scope: <comma-separated labels — pick honestly from:
+        frontend, backend, both, security-sensitive,
+        performance-sensitive>
+        Examples:
+        - "Scope: frontend"
+        - "Scope: backend, security-sensitive"
+        - "Scope: both, performance-sensitive"
+        The implement orchestrator parses this line to route
+        the developer + reviewer phases. A missing or wrong
+        label means the wrong specialists get spawned (or
+        none at all).
+
+## Goal
+<one sentence: what observable behaviour you are adding /
+changing.>
+
+## Non-Goals
+- <one bullet per scope cut, explicit so the developer doesn't
+  over-build>
+
+## Design
+
+### Architecture
+<one or two paragraphs: the high-level shape — modules,
+data flow, state machine. Diagrams in ASCII are welcome.>
+
+### Data shapes
+<the concrete types / JSON shapes / DB columns the change
+introduces or modifies. One block per shape.>
+
+### State & lifecycle
+<for stateful changes: the state graph, transitions,
+invariants. Skip for stateless changes.>
+
+### Public API / surface
+<the externally observable surface — function signatures, HTTP
+routes, CLI flags, exported types. One block per surface.>
+
+## Trade-offs
+
+| Option | Pros | Cons | Chosen? |
+|---|---|---|---|
+| <option A> | … | … | ✅ / ❌ |
+| <option B> | … | … | ✅ / ❌ |
+
+State a one-sentence rationale for the chosen option after
+the table.
+
+## Risks
+- <each risk + mitigation, one per bullet>
+
+## Open questions
+- <questions you couldn't resolve from the ticket alone. The
+  reviewer will check these; leave the section empty if none.>
+```
+
+**`tasks.md`** — the TDD-shaped implementation order:
+
+```
+# Implementation Tasks
+
+> The developer agent runs these in order. Each "## N." block is
+> a single TDD cycle: write the failing test, run it to confirm
+> it fails, write production code, run again to confirm it
+> passes. Do NOT skip the failing-test step.
+
+## 1. <First testable behaviour>
+- [ ] 1.1 Write a failing test in `<test-path>` that asserts
+       <behaviour>. Run the test runner; the new test MUST fail.
+- [ ] 1.2 Implement the minimum production code in `<src-path>`
+       to make the test pass. Run the test runner; ALL tests
+       MUST pass.
+- [ ] 1.3 Refactor if needed without changing behaviour. Run
+       the test runner; all tests still pass.
+
+## 2. <Next testable behaviour>
+- [ ] 2.1 Write a failing test...
+...
+
+## N. Validation gate
+- [ ] N.1 Run the full project test suite (`<command>`); all
+       pass.
+- [ ] N.2 Run the project build (`<command>` if present); succeeds.
+- [ ] N.3 No `console.log`, debug prints, or commented-out code
+       in the diff.
+```
+
+Each TDD cycle should cover ONE acceptance criterion from the
+ticket, or one invariant. Avoid mega-tasks that bundle many
+unrelated changes. Aim for 3-8 task blocks total for a typical
+ticket.
+
+**`specs/<capability>/spec.md`** — one spec delta per capability
+the change touches. For greenfield projects with no existing
+specs, write ONE `specs/<change-slug>/spec.md` describing the
+new capability you are adding. Example shape:
+
+```
+## ADDED Requirements
+### Requirement: The system SHALL <observable behaviour>
+
+The <subject> MUST <verb the observable behaviour>.
+
+#### Scenario: <happy path>
+- **WHEN** <trigger>
+- **THEN** <outcome>
+
+#### Scenario: <edge case>
+- **WHEN** <trigger>
+- **THEN** <outcome>
+```
+
+### B. Plan artefact (developer hand-off note)
+
+Write a markdown file at:
+
+`.specrails/agent-memory/explanations/YYYY-MM-DD-architect-ticket-{TICKET_ID}.md`
+
+(use today's date; create the parent directory if missing). The
+file MUST contain:
+
+```
+# Architect — ticket #{TICKET_ID}
+
+## Goal
+<2-3 sentences restating the ticket in your own words.>
+
+## Stack
+<one paragraph: language(s), build tool, test runner, layout
+conventions you observed.>
+
+## OpenSpec change
+- Slug: `<change-slug>`
+- Path: `openspec/changes/<change-slug>/`
+- Proposal: `openspec/changes/<change-slug>/proposal.md`
+- Design: `openspec/changes/<change-slug>/design.md`
+- Tasks: `openspec/changes/<change-slug>/tasks.md`
+- Spec deltas: <list of capability slugs touched>
+
+## Files to touch
+- `path/to/file` — <what changes, in one line>
+- ...
+
+## Invariants
+- <each invariant the developer must preserve, one per bullet>
+
+## Edge cases
+- <each edge case the developer must handle, one per bullet>
+
+## Validation
+<the exact command(s) the reviewer should run. If no test
+runner exists, propose `node --check` / `python -m py_compile`
+on the touched files as a fallback.>
+
+## Decisions
+- <each non-obvious decision you made, with one-line rationale>
+```
+
+## What you must NOT do
+
+- **Do not** write production source files. Anything under
+  `src/`, `lib/`, `app/`, etc. is the developer's territory.
+- **Do not** write or modify test files. The developer writes
+  tests in the TDD cycle. You only describe the cycles in
+  `tasks.md`.
+- **Do not** spawn further sub-agents — you are already inside one.
+- **Do not** update `.specrails/local-tickets.json` — only the
+  implement orchestrator owns that.
+- **Do not** write to `.claude/agent-memory/`. Codex projects
+  use `.specrails/agent-memory/`.
+
+## How you finish
+
+When BOTH the OpenSpec change package and the plan artefact are
+written:
+
+1. Reply with two lines:
+   ```
+   OpenSpec change: openspec/changes/<slug>/
+   Plan written to <plan-path>; files to touch: <comma-separated list>
+   ```
+2. End your turn. The orchestrator will read your plan + the
+   tasks.md and spawn the developer next.
+
+If you cannot produce a plan (ticket is too ambiguous, repo
+state is corrupt, etc.), instead reply with:
+
+`"BLOCKED: <one-sentence reason>"`
+
+and end your turn. Do not invent fake plans or empty OpenSpec
+packages to keep the pipeline moving.