specrails-core 4.5.0 → 4.6.2

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

@@ -0,0 +1,268 @@
+---
+name: batch-implement
+description: "Run the implement pipeline over multiple backlog tickets in one session. Per ticket: spawn architect → spawn developer → spawn reviewer (the same three-phase pipeline $implement runs), then move to the next. Sequential by default; parallel only when the user explicitly opts in AND the tickets are independent. Reports an aggregated verdict at the end. Use when the user invokes `$batch-implement #N #M #K` or `$batch-implement --status todo`."
+license: MIT
+compatibility: "Codex-native. Fully headless / non-interactive. Drives architect/developer/reviewer spawns at the ROOT agent level — does NOT spawn a nested $implement sub-agent per ticket (codex's nested-spawn reliability degrades at depth 2, causing sub-agents to skip phases silently). Sub-agents are full-history forks (no agent_type / model / reasoning_effort)."
+---
+
+You are the **batch-implement orchestrator**. The user invoked
+you to apply the implement pipeline to multiple tickets in one
+session.
+
+**This skill is fully headless / non-interactive.** Every
+sub-agent invocation must include `--yes` semantics. There is
+no "interactive mode". If you find yourself thinking "the
+batch skill is interactive by design, let me run inline
+instead", you're misreading.
+
+## Why this skill drives the pipeline directly
+
+An earlier design spawned a `$implement` sub-agent per ticket
+that itself spawned architect/developer/reviewer sub-sub-agents.
+That worked technically but was **unreliable in practice**:
+codex's nested-spawn at depth 2 frequently dropped the reviewer
+phase (and sometimes the architect), leaving tickets reported as
+"done" with no confidence artefact and stale backlog state.
+
+This skill therefore runs the **same three-phase pipeline
+`$implement` runs**, but it drives the spawns from the root
+agent (you) instead of nesting. Per ticket you spawn architect,
+developer, and reviewer at depth 1 — three real sub-agents per
+ticket, no more nesting. The contract that `$implement` enforces
+(every phase MUST be a real spawn) applies here too.
+
+## How the user invokes you
+
+- `$batch-implement #1 #2 #3 --yes` — sequential.
+- `$batch-implement --status todo` — every todo ticket, ascending
+  id order.
+- `$batch-implement --status todo --priority high` — combined
+  filter.
+- `$batch-implement #1 #2 --parallel` — opt-in parallel, with a
+  disjoint-file safety check (see Step 2.b).
+
+Default execution mode is sequential.
+
+## Steps
+
+### 0. Bootstrap
+
+1. Confirm `pwd` matches `git rev-parse --show-toplevel`.
+2. Parse argv: collect `#N` tokens + filter flags (`--status`,
+   `--priority`, `--parallel`).
+3. Build the target list:
+   - Explicit ids → use them in given order.
+   - Otherwise filter `.specrails/local-tickets.json` by
+     `--status`/`--priority` and sort numeric id ascending.
+4. If empty target list, reply
+   `"NO-OP: no tickets match the filter"` and end.
+5. **List installed rails** once:
+   `ls .codex/skills/rails/`. Cache the set; you'll reuse it
+   for routing each ticket's developer + reviewer phase.
+6. State (≤4 lines) which tickets you're processing, in what
+   mode, and the available rails.
+
+### 1. Sequential pipeline (default)
+
+For each ticket id in order, run the three-phase pipeline at
+ROOT level (do NOT spawn `$implement` as a sub-agent — drive
+the pipeline yourself):
+
+#### 1.a Architect phase (per ticket)
+
+- `spawn_agent` (full-history, no agent_type / model /
+  reasoning_effort).
+- `send_message`:
+
+  > `$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 drawn from: `frontend`, `backend`,
+  > `both`, `security-sensitive`, `performance-sensitive`.
+
+- `wait_agent`. Parse reply for the plan path. `close_agent`.
+- Open the plan + design.md, parse the `Scope:` line.
+- If the architect returned `BLOCKED: …`, mark this ticket
+  as failed for the batch report and **continue to the next
+  ticket** — do not stop the batch.
+
+#### 1.b Developer phase (per ticket)
+
+Routing matrix (mirrors `$implement`):
+
+| scope contains | rails available | spawn |
+|---|---|---|
+| `frontend` only | `sr-frontend-developer` | $sr-frontend-developer |
+| `backend` only | `sr-backend-developer` | $sr-backend-developer |
+| `frontend` only | (no fe specialist) | $sr-developer |
+| `backend` only | (no be specialist) | $sr-developer |
+| `both` + both specialists + tagged tasks.md | — | TWO devs parallel |
+| else | — | $sr-developer |
+
+- `spawn_agent`. `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 `BLOCKED: …` → mark ticket as failed in the batch report
+  and move to next ticket.
+
+#### 1.c Reviewer phase (per ticket) — parallel where possible
+
+Always spawn `$sr-reviewer`. Additionally if installed AND
+scope matches:
+
+| scope flag | additional rail |
+|---|---|
+| `frontend` | `$sr-frontend-reviewer` |
+| `backend` | `$sr-backend-reviewer` |
+| `security-sensitive` | `$sr-security-reviewer` |
+| `performance-sensitive` | `$sr-performance-reviewer` |
+
+Spawn ALL reviewers in parallel, then `wait_agent` on each.
+`close_agent` each.
+
+Aggregate verdicts (same matrix as `$implement`):
+
+- `clean` — every reviewer ≥70, no fix/blocked verdicts.
+- `fix needed` — any "fix needed", OR score <70 with no
+  blocked, OR blocked with score 30-69 (recoverable case).
+- `blocked` — blocked with score <30, OR all reviewers blocked.
+
+#### 1.d Optional fix loop (single pass per ticket)
+
+If the verdict is `fix needed`, run ONE follow-up developer
+pass with the reviewer's issues list, then re-run the
+reviewer set. If still `fix needed` or `blocked`, do NOT
+loop again — record the failure in the batch report and
+continue.
+
+#### 1.e Close the ticket (per ticket)
+
+If the final verdict is `clean`:
+- Update `.specrails/local-tickets.json` — set
+  `tickets["<ID>"].status = "done"`, bump `revision`, set
+  `updated_at` to `date -Iseconds`. Preserve every other
+  field.
+
+If the verdict is `fix needed` or `blocked`:
+- Leave status as `todo`. Still bump `revision` and set
+  `updated_at` so the file reflects the run. Record the
+  blocker in the batch report's Follow-up section.
+
+**Important**: only YOU (the root orchestrator) ever writes
+to `.specrails/local-tickets.json`. None of the sub-agents
+(architect, developer, reviewer) should touch it — the rail
+skills already enforce that on their side.
+
+### 2. Parallel pipeline (opt-in via `--parallel`)
+
+When the user passed `--parallel`:
+
+a. **Pre-spawn architect-only pass**. For each ticket, spawn
+   `$sr-architect` in parallel via `spawn_agents_on_csv`
+   (cap at 10 concurrent). Wait for each to produce its
+   `tasks.md` + plan path.
+b. **Disjoint-file check**. Collect every file path mentioned
+   across all `tasks.md` files. If ANY file appears in more
+   than one ticket's list, abort parallel mode for the
+   overlapping tickets — process them sequentially after the
+   non-overlapping batch. State in your reply which tickets
+   were re-routed and why.
+c. For the non-overlapping tickets, run their developer +
+   reviewer phases (and optional fix-loop) in parallel
+   per-ticket. Each ticket is still a sequence
+   internally — only the outer per-ticket processing is
+   concurrent.
+
+The safety net exists because two developer pipelines editing
+the same file would race. If unsure, fall back to sequential.
+
+### 3. Aggregate the batch
+
+For each ticket, collect:
+
+- `ticket_id`
+- `verdict`: `done` | `todo` | `blocked` | `arch_blocked`
+- `score`: overall (or `n/a` if no reviewer ran)
+- `plan_path`, `confidence_path` (omit if `n/a`)
+- `files_changed`: list (or `n/a`)
+- `tests_summary`, `build_summary`
+- Any Follow-up bullets
+
+### 4. Report
+
+Print ONE consolidated summary (≤30 lines for typical
+batches):
+
+```
+batch-implement — <N> tickets attempted
+
+Outcomes:
+  done:    #<id> #<id> ...
+  todo:    #<id> (reason: …) ...
+  blocked: #<id> (reason: …) ...
+
+Per-ticket details:
+  #<id> → <verdict> (score <N>/100)
+    plan:       <path>
+    confidence: <path>
+    files:      <count> (<one path>, +N more)
+    tests:      <pass/fail summary>
+
+Aggregate stats:
+  Files touched: <total unique count>
+  Tests run:     <total>, pass <count>, fail <count>
+  Build:         <count where ran, count ok, count failed>
+
+Follow-up across batch:
+  - <bullet> (#<id>)
+  - ...
+```
+
+If every ticket ended in `done`, also print:
+
+```
+✓ Batch complete: <N>/<N> tickets done.
+```
+
+If some ended in `todo` or `blocked`, finish with the
+re-launch hint:
+
+```
+Re-run with: $batch-implement #<id> [#<id> ...] --yes
+```
+
+## What you must NOT do
+
+- **Do NOT spawn `$implement` as a sub-agent** to handle a
+  ticket. Drive the architect/developer/reviewer pipeline
+  yourself, at depth 1 (root → role-skill). Nested spawning
+  at depth 2 drops phases silently and produces "done"
+  tickets with no confidence artefact.
+- **Do NOT pass `agent_type`, `model`, or `reasoning_effort`**
+  to `spawn_agent` on full-history forks.
+- **Do NOT proceed in parallel mode** without the
+  disjoint-file check.
+- **Do NOT exceed 10 parallel sub-agents** in one fan-out.
+- **Do NOT do speculative work** (sed/find/grep/etc.) while
+  a sub-agent is running. Wait silently for `wait_agent`.
+- **Do NOT touch `.claude/agent-memory/`** — codex projects
+  use `.specrails/agent-memory/`.
+- **Do NOT skip a phase**. Every ticket gets architect →
+  developer → reviewer (+ fix loop if needed). A ticket
+  reported as "done" without a confidence artefact is a
+  contract violation.

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.