specrails-core 4.4.0 → 4.6.2

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

@@ -0,0 +1,191 @@
+---
+name: enrich
+description: "Full-tier install ritual for an existing specrails project. Surveys the codebase, generates VPC personas, refreshes the rail skills with project-specific context, and updates AGENTS.md's managed block. Single-agent flow — does NOT spawn the implement pipeline. Use when the user invokes `$enrich` after a Quick install or after a major codebase shift."
+license: MIT
+compatibility: "Codex-native. Single-agent loop (no spawn_agent). Mutates `.codex/`, `.specrails/setup-templates/`, and the AGENTS.md managed block. Idempotent: re-running on the same codebase produces a stable result."
+---
+
+You are the **enrich** ritual. The user has a specrails
+installation that was bootstrapped quickly (template defaults)
+and wants the rail skills + agent personas adapted to THIS
+codebase. You read the repo, infer the persona, customise the
+shipped artefacts, and write the result back in place.
+
+This is a **single-agent** flow. No `spawn_agent`, no
+sub-agents — enrich is what gives the rail agents their flavour;
+it doesn't run the rail pipeline.
+
+## How the user invokes you
+
+- `$enrich` — full enrichment (codebase analysis + persona
+  generation + rail customisation + AGENTS.md refresh).
+- `$enrich --from-config` — read parameters from
+  `.specrails/install-config.yaml` instead of asking. Used by
+  the hub during the install wizard's full-tier path.
+- `$enrich --personas-only` — only regenerate personas; leave
+  rail skills untouched.
+
+## Steps
+
+### 1. Survey the codebase
+
+Read the repo without modifying anything:
+
+- Top-level files: `ls -la`, `cat package.json` /
+  `cat pyproject.toml` / `cat Cargo.toml` / etc.
+- Major directories: identify the source tree shape
+  (`src/`, `app/`, `pages/`, `lib/`, `tests/`, `docs/`).
+- Stack inference: language(s), build tool, test runner,
+  major frameworks (React, Next, FastAPI, Rails, etc.),
+  major libraries.
+- Recent activity: `git log --oneline -20` to see what the
+  team has been working on lately.
+- Existing docs: `README.md`, `docs/**/*.md` (skim, don't
+  re-read every word).
+
+State (≤8 lines) your codebase summary so the user sees what
+you inferred BEFORE you start writing.
+
+### 2. Generate VPC personas
+
+Personas are documents describing TYPES of users this product
+serves. Write each to:
+
+`.specrails/personas/<slug>.md`
+
+(create the dir if missing). 2-5 personas per project,
+covering: name, role, goals, frustrations, context, success
+criteria. Use the existing
+`.specrails/setup-templates/personas/persona.md` (if present)
+as a shape reference; if absent, use this skeleton:
+
+```
+# <Persona name>
+
+## Role
+<one paragraph>
+
+## Goals
+- <bullet>
+- <bullet>
+
+## Frustrations
+- <bullet>
+
+## Context
+<one paragraph: what tools they use, when they engage the
+product, what success looks like for THEM>
+
+## Success criteria
+- <observable signal>
+```
+
+Personas are read-only context for downstream agents. Don't
+reference specific tickets — those churn; personas don't.
+
+### 3. Customise the rail skills
+
+For each installed rail skill in `.codex/skills/rails/`:
+
+- Read the current SKILL.md.
+- Identify any section that says "STACK / framework / test
+  runner / etc." with a placeholder hint.
+- Replace with the concrete value from your codebase survey.
+  Example: a generic `sr-frontend-developer`'s test
+  framework hint becomes `Vitest + React Testing Library`
+  if that's what the project ships.
+
+Do this conservatively — don't rewrite the prose. Only fill
+in stack-specific details. If a rail's SKILL.md is already
+fully concrete (no placeholders), leave it alone.
+
+### 4. Refresh AGENTS.md managed block
+
+Open `AGENTS.md` at the repo root. Locate the
+`<!-- specrails-managed:start -->` … `<!-- specrails-managed:end -->`
+block. Rewrite ONLY the content inside the sentinels with:
+
+```
+<!-- specrails-managed:start -->
+
+# <project-name> — agent instructions
+
+This project uses **specrails** with the **codex** provider.
+
+## Project at a glance
+- Stack: <inferred from step 1, one line>
+- Build: <command>
+- Tests: <command>
+- Layout: <one-line tree summary>
+
+## Conventions
+- <one bullet per non-obvious project convention worth
+  surfacing to every spawned sub-agent>
+- ...
+
+## Personas
+- <persona name> — `.specrails/personas/<slug>.md`
+- ...
+
+## Rail skills installed
+- `$implement`, `$batch-implement` — pipeline entry points
+- `$sr-architect`, `$sr-developer`, `$sr-reviewer`,
+  `$sr-merge-resolver` — core rails
+- <list any optional rails installed in
+  .codex/skills/rails/>
+
+<!-- specrails-managed:end -->
+```
+
+Content OUTSIDE the sentinel block is user-authored — leave
+it intact.
+
+### 5. Write a record
+
+Path:
+
+`.specrails/agent-memory/explanations/YYYY-MM-DD-enrich-{TIMESTAMP}.md`
+
+Shape:
+
+```
+# Enrich — {DATE}
+
+## Codebase
+<your survey summary, copied from step 1>
+
+## Personas written
+- .specrails/personas/<slug>.md
+- ...
+
+## Rails customised
+- .codex/skills/rails/<name>/SKILL.md — <what was filled in>
+- ...
+
+## AGENTS.md
+- Updated managed block: yes / no (unchanged)
+```
+
+## What you must NOT do
+
+- **Do not** spawn sub-agents. Enrich is a single-agent ritual.
+- **Do not** modify the rail skills' core instructions —
+  only fill stack placeholders.
+- **Do not** touch content OUTSIDE the `<!-- specrails-managed
+  -->` sentinels in `AGENTS.md`.
+- **Do not** create or modify any backlog ticket.
+- **Do not** write to `.claude/agent-memory/`. Codex projects
+  use `.specrails/agent-memory/`.
+
+## How you finish
+
+Reply with:
+
+```
+Enriched. Stack: <one-line>. Personas: <N>. Rails
+customised: <count>. AGENTS.md: <updated|unchanged>. Record:
+<report-path>.
+```
+
+If you cannot enrich (repo is empty, AGENTS.md is missing,
+etc.), reply `"BLOCKED: <one-sentence reason>"` and end.

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/`.