specrails-core 2.1.2 → 3.1.0

package/commands/setup.md

@@ -176,8 +176,10 @@ grep -r '{{[A-Z_]*}}' .codex/agents/sr-*.toml 2>/dev/null || echo "OK: no broken
 
 For each command in the "changed commands" list from Phase U3:
 
-1. Read the NEW template from `.claude/setup-templates/commands/sr/<name>.md`
-2. Read stored backlog configuration from `.claude/backlog-config.json` (if it exists) to resolve provider-specific placeholders:
+1. Read the NEW template:
+   - If `cli_provider == "claude"`: from `$SPECRAILS_DIR/setup-templates/commands/sr/<name>.md`
+   - If `cli_provider == "codex"`: from `$SPECRAILS_DIR/setup-templates/skills/sr-<name>/SKILL.md`
+2. Read stored backlog configuration from `$SPECRAILS_DIR/backlog-config.json` (if it exists) to resolve provider-specific placeholders:
    - `BACKLOG_PROVIDER` → `provider` field (`github`, `jira`, or `none`)
    - `BACKLOG_WRITE` → `write_access` field
    - `JIRA_BASE_URL` → `jira_base_url` field
@@ -192,12 +194,19 @@ For each command in the "changed commands" list from Phase U3:
    - `{{BACKLOG_VIEW_CMD}}` → provider-specific view command from backlog config
    - `{{BACKLOG_PREFLIGHT}}` → provider-specific preflight check from backlog config
    - Any other `{{PLACEHOLDER}}` values → use Phase U2 analysis data
-4. Write the updated command to `.claude/commands/sr/<name>.md`
-5. Show: `✓ Updated /sr:<name>`
-
-After updating all changed commands, verify no unresolved placeholders remain in the updated files:
+4. Write the updated file:
+   - If `cli_provider == "claude"`: to `.claude/commands/sr/<name>.md`
+   - If `cli_provider == "codex"`: to `.agents/skills/sr-<name>/SKILL.md`
+5. Show:
+   - If `cli_provider == "claude"`: `✓ Updated /sr:<name>`
+   - If `cli_provider == "codex"`: `✓ Updated $sr-<name>`
+
+After updating all changed commands/skills, verify no unresolved placeholders remain:
 ```bash
+# If cli_provider == "claude":
 grep -l '{{[A-Z_]*}}' .claude/commands/sr/*.md 2>/dev/null || echo "OK: no broken placeholders"
+# If cli_provider == "codex":
+grep -rl '{{[A-Z_]*}}' .agents/skills/sr-*/SKILL.md 2>/dev/null || echo "OK: no broken placeholders"
 ```
 If any placeholders remain unresolved, warn the user:
 > "⚠ Some placeholders in `<filename>` could not be resolved automatically. Please review the file and fill them in manually."
@@ -221,24 +230,32 @@ For each agent in the "new" list:
 
 For each command in the "new commands" list from Phase U3:
 
-1. Read the template from `.claude/setup-templates/commands/sr/<name>.md` to understand what it does (read the title and description)
+1. Read the template:
+   - If `cli_provider == "claude"`: from `$SPECRAILS_DIR/setup-templates/commands/sr/<name>.md`
+   - If `cli_provider == "codex"`: from `$SPECRAILS_DIR/setup-templates/skills/sr-<name>/SKILL.md`
 2. Prompt the user:
-   > "New command available: `/sr:<name>` — [one-line description from template]. Install it? [Y/n]"
+   - If `cli_provider == "claude"`: `"New command available: /sr:<name> — [one-line description]. Install it? [Y/n]"`
+   - If `cli_provider == "codex"`: `"New skill available: $sr-<name> — [one-line description]. Install it? [Y/n]"`
 3. If the user accepts (or presses Enter):
    - Apply placeholder substitution using the same rules as Phase U4b (backlog config + codebase analysis)
-   - Write the command to `.claude/commands/sr/<name>.md`
-   - Show: `✓ Added /sr:<name>`
+   - If `cli_provider == "claude"`: write to `.claude/commands/sr/<name>.md` — show `✓ Added /sr:<name>`
+   - If `cli_provider == "codex"`: write to `.agents/skills/sr-<name>/SKILL.md` — show `✓ Added $sr-<name>`
 4. If the user declines:
-   - Show: `→ Skipped /sr:<name>`
+   - If `cli_provider == "claude"`: show `→ Skipped /sr:<name>`
+   - If `cli_provider == "codex"`: show `→ Skipped $sr-<name>`
 
 ### Phase U6: Update Workflow Commands
 
 If any new agents were added in Phase U5:
 
-1. Read `.claude/commands/sr/implement.md`
+1. Read the implement command/skill:
+   - If `cli_provider == "claude"`: `.claude/commands/sr/implement.md`
+   - If `cli_provider == "codex"`: `.agents/skills/sr-implement/SKILL.md`
 2. Check if the file references agent names in its orchestration steps (look for `sr-architect`, `sr-developer`, `sr-reviewer` etc.)
 3. If newly added agents belong in the implementation pipeline (i.e., they are layer-specific developers such as `sr-frontend-developer` or `sr-backend-developer`), add them to the appropriate step in the implement command — specifically where parallel developer agents are launched
-4. Write the updated `.claude/commands/sr/implement.md` if any changes were made
+4. Write the updated file if any changes were made:
+   - If `cli_provider == "claude"`: `.claude/commands/sr/implement.md`
+   - If `cli_provider == "codex"`: `.agents/skills/sr-implement/SKILL.md`
 5. Show which commands were updated, or "No command updates needed" if nothing changed
 
 This is a lightweight check — only update commands where the sr- agent clearly belongs. Do not restructure the entire command.
@@ -297,21 +314,14 @@ When no flags are passed (the default), run this streamlined 3-question setup. D
 
 ### QS1: Ask the 3 questions
 
-Ask exactly these questions in sequence. Do not ask any other questions.
+Display the following prompt EXACTLY ONCE and then wait for the user's responses. Do NOT repeat the questions — output them a single time only.
 
-```
 Welcome to specrails! Let's get your AI agent team set up in 3 quick questions.
 
 1. What is this project? (one sentence)
-   > _
-
 2. Who are the target users?
-   > _
-
 3. Git access for agents — read-only or read-write?
    (read-only = agents can read and suggest; read-write = agents can commit)
-   > _
-```
 
 Store the answers as:
 - `QS_PROJECT_DESCRIPTION` — answer to question 1
@@ -341,20 +351,31 @@ Store as `QS_IS_EXISTING_CODEBASE=true/false`.
 
 Before generating files, check if this is a re-run:
 
-1. Check if `.claude/commands/sr/` directory exists with any `.md` files:
-   ```bash
-   ls .claude/commands/sr/*.md 2>/dev/null
-   ```
-2. If `.md` files are found → this is a **re-run**. Store `QS_IS_RERUN=true`.
+1. Check if commands/skills already exist:
+   - If `cli_provider == "claude"`: check if `.claude/commands/sr/` directory exists with any `.md` files:
+     ```bash
+     ls .claude/commands/sr/*.md 2>/dev/null
+     ```
+   - If `cli_provider == "codex"`: check if `.agents/skills/sr-*/SKILL.md` files exist:
+     ```bash
+     ls .agents/skills/sr-*/SKILL.md 2>/dev/null
+     ```
+2. If files are found → this is a **re-run**. Store `QS_IS_RERUN=true`.
 3. If the directory does not exist or is empty → this is a **fresh install**. Store `QS_IS_RERUN=false`.
 
-In re-run mode, QS3 executes in **gap-fill mode** for command files:
-- For each command in the list, check if it already exists at `.claude/commands/sr/<name>.md`
-- If it exists: skip it and show `✓ Already installed: /sr:<name>`
-- If it does NOT exist: install it and show `✓ Added /sr:<name> (was missing)`
+In re-run mode, QS3 executes in **gap-fill mode** for command/skill files:
+- For each command in the list, check if it already exists:
+  - If `cli_provider == "claude"`: at `.claude/commands/sr/<name>.md`
+  - If `cli_provider == "codex"`: at `.agents/skills/sr-<name>/SKILL.md`
+- If it exists: skip it and show:
+  - Claude: `✓ Already installed: /sr:<name>`
+  - Codex: `✓ Already installed: $sr-<name>`
+- If it does NOT exist: install it and show:
+  - Claude: `✓ Added /sr:<name> (was missing)`
+  - Codex: `✓ Added $sr-<name> (was missing)`
 - Do NOT prompt the user for confirmation on missing files — install them automatically
 
-For CLAUDE.md and agent files, the existing per-file prompts already handle re-runs (user is asked before overwriting). No change needed there.
+For CLAUDE.md/AGENTS.md and agent files, the existing per-file prompts already handle re-runs (user is asked before overwriting). No change needed there.
 
 ### QS3: Generate files
 
@@ -404,11 +425,21 @@ Core commands (always install if missing):
 
 Do NOT copy `product-backlog.md` or `update-product-driven-backlog.md` (no backlog provider configured).
 
-If `QS_IS_RERUN=false` (fresh install): copy all core commands from `setup-templates/commands/sr/` to `.claude/commands/sr/`.
+**If `cli_provider == "claude"`:**
+
+If `QS_IS_RERUN=false` (fresh install): copy all core commands from `$SPECRAILS_DIR/setup-templates/commands/sr/` to `.claude/commands/sr/`.
 
 If `QS_IS_RERUN=true` (gap-fill mode): for each command in the list above, check if `.claude/commands/sr/<name>.md` already exists:
 - If it exists: skip it — show `✓ Already installed: /sr:<name>`
-- If it does NOT exist: copy from `setup-templates/commands/sr/<name>.md` — show `✓ Added /sr:<name> (was missing)`
+- If it does NOT exist: copy from `$SPECRAILS_DIR/setup-templates/commands/sr/<name>.md` — show `✓ Added /sr:<name> (was missing)`
+
+**If `cli_provider == "codex"`:**
+
+If `QS_IS_RERUN=false` (fresh install): for each core command, copy the corresponding skill from `$SPECRAILS_DIR/setup-templates/skills/sr-<name>/SKILL.md` to `.agents/skills/sr-<name>/SKILL.md` (create the directory first).
+
+If `QS_IS_RERUN=true` (gap-fill mode): for each command in the list above, check if `.agents/skills/sr-<name>/SKILL.md` already exists:
+- If it exists: skip it — show `✓ Already installed: $sr-<name>`
+- If it does NOT exist: copy from `$SPECRAILS_DIR/setup-templates/skills/sr-<name>/SKILL.md` — show `✓ Added $sr-<name> (was missing)`
 
 **4. Cleanup**
 
@@ -954,9 +985,11 @@ Write each persona to `$SPECRAILS_DIR/agents/personas/`:
 - Use the VPC personas generated in Phase 2
 - File naming: kebab-case of persona nickname (e.g., `the-developer.md`, `the-admin.md`)
 
-### 4.3 Generate commands
+### 4.3 Generate commands / skills
 
-For each selected command, read the template and adapt:
+For each selected command, read the template and adapt.
+
+**If `cli_provider == "claude"` (default):**
 - `setup-templates/commands/sr/implement.md` → `.claude/commands/sr/implement.md`
 - `setup-templates/commands/sr/batch-implement.md` → `.claude/commands/sr/batch-implement.md`
 - `setup-templates/commands/sr/propose-spec.md` → `.claude/commands/sr/propose-spec.md`
@@ -967,6 +1000,32 @@ For each selected command, read the template and adapt:
 - `setup-templates/commands/sr/refactor-recommender.md` → `.claude/commands/sr/refactor-recommender.md`
 - `setup-templates/commands/sr/why.md` → `.claude/commands/sr/why.md`
 
+**If `cli_provider == "codex"`:**
+- `setup-templates/skills/sr-implement/SKILL.md` → `.agents/skills/sr-implement/SKILL.md`
+- `setup-templates/skills/sr-batch-implement/SKILL.md` → `.agents/skills/sr-batch-implement/SKILL.md`
+- `setup-templates/commands/sr/propose-spec.md` → `.agents/skills/sr-propose-spec/SKILL.md` (wrap with YAML frontmatter if no skill template exists)
+- `setup-templates/commands/sr/product-backlog.md` → `.agents/skills/sr-product-backlog/SKILL.md` (if `BACKLOG_PROVIDER != none`; wrap with frontmatter)
+- `setup-templates/commands/sr/update-product-driven-backlog.md` → `.agents/skills/sr-update-product-driven-backlog/SKILL.md` (if `BACKLOG_PROVIDER != none`; wrap with frontmatter)
+- `setup-templates/skills/sr-health-check/SKILL.md` → `.agents/skills/sr-health-check/SKILL.md`
+- `setup-templates/skills/sr-compat-check/SKILL.md` → `.agents/skills/sr-compat-check/SKILL.md`
+- `setup-templates/skills/sr-refactor-recommender/SKILL.md` → `.agents/skills/sr-refactor-recommender/SKILL.md`
+- `setup-templates/skills/sr-why/SKILL.md` → `.agents/skills/sr-why/SKILL.md`
+
+**Codex skill frontmatter wrapping:** When a dedicated skill template does not exist in `setup-templates/skills/` for a command, generate the `SKILL.md` by prepending YAML frontmatter to the command content:
+```yaml
+---
+name: sr-<name>
+description: "<one-line description from the command's first heading>"
+license: MIT
+compatibility: "Requires git."
+metadata:
+  author: specrails
+  version: "1.0"
+---
+```
+
+For both providers, create the output directory before writing (`mkdir -p` for `.claude/commands/sr/` or `.agents/skills/sr-<name>/`).
+
 Adapt:
 - CI commands to match detected stack
 - **Persona references** to match generated personas (see substitution rules below)
@@ -980,7 +1039,7 @@ When adapting `update-product-driven-backlog.md` and `product-backlog.md`, subst
 
 | Placeholder | Substitution rule |
 |-------------|------------------|
-| `{{PERSONA_FILE_READ_LIST}}` | One bullet per persona file: `- Read \`.claude/agents/personas/{name}.md\`` |
+| `{{PERSONA_FILE_READ_LIST}}` | One bullet per persona file: `- Read \`$SPECRAILS_DIR/agents/personas/{name}.md\`` |
 | `{{PERSONA_SCORE_HEADERS}}` | Column headers for each persona nickname: e.g., `Alex \| Sara \| Kai` |
 | `{{PERSONA_SCORE_SEPARATORS}}` | One `------` separator per persona column |
 | `{{PERSONA_FIT_FORMAT}}` | Inline score display: e.g., `Alex: X/5, Sara: X/5, Kai: X/5` |
@@ -1017,7 +1076,7 @@ When adapting `update-product-driven-backlog.md` and `product-backlog.md`, subst
 - Issue view: `jira issue view {key}` or REST API
 - VPC scores stored in the issue description body (same markdown format, parsed from description)
 - Pre-flight check: `jira me` or test API connectivity
-- Store JIRA config in `.claude/backlog-config.json`:
+- Store JIRA config in `$SPECRAILS_DIR/backlog-config.json`:
   ```json
   {
     "provider": "jira",
@@ -1033,16 +1092,18 @@ The command templates use `{{BACKLOG_FETCH_CMD}}`, `{{BACKLOG_CREATE_CMD}}`, `{{
 ### 4.4 Generate rules
 
 For each detected layer, read the layer rule template and generate a layer-specific rules file:
-- `setup-templates/rules/layer.md` → `.claude/rules/{layer-name}.md`
+- `setup-templates/rules/layer.md` → `$SPECRAILS_DIR/rules/{layer-name}.md`
 
 Each rule file must:
 - Have the correct `paths:` frontmatter matching the layer's directory
 - Contain conventions specific to that layer (from Phase 1 analysis)
 - Reference actual file paths and patterns from the codebase
 
-### 4.5 Generate root CLAUDE.md
+### 4.5 Generate root instructions file
+
+**If `cli_provider == "claude"`:** If no `CLAUDE.md` exists, generate one from the template. If one already exists, **merge** — add the agent workflow sections without removing existing content.
 
-If no CLAUDE.md exists, generate one from the template. If one already exists, **merge** — add the agent workflow sections without removing existing content.
+**If `cli_provider == "codex"`:** If no `AGENTS.md` exists, generate one from the template. If one already exists, **merge** — add the agent workflow sections without removing existing content.
 
 ### 4.6 Generate settings
 
@@ -1154,13 +1215,14 @@ ls .claude/agent-memory/
 # If cli_provider == "codex":
 ls .codex/agents/sr-*.toml
 ls .codex/agents/personas/*.md
-ls .codex/skills/sr-*/SKILL.md
+ls .agents/skills/sr-*/SKILL.md
 ls .codex/rules/*.md
 ls .codex/agent-memory/
 
 # These should NOT exist (scaffolding):
 # $SPECRAILS_DIR/setup-templates/  — GONE
-# $SPECRAILS_DIR/commands/setup.md  — GONE
+# If cli_provider == "claude": $SPECRAILS_DIR/commands/setup.md  — GONE
+# If cli_provider == "codex": .agents/skills/setup/  — GONE (installer scaffold, not a generated sr-skill)
 ```
 
 If any scaffolding artifact remains, remove it.
@@ -1198,7 +1260,8 @@ Display the complete installation summary:
 [For each user-generated persona:]
 | "[Name]" — The [Role] | $SPECRAILS_DIR/agents/personas/[name].md | Generated |
 
-### Commands Installed
+### Commands / Skills Installed
+[If cli_provider == "claude":]
 | Command | File |
 |---------|------|
 | /sr:implement | .claude/commands/sr/implement.md |
@@ -1210,33 +1273,58 @@ Display the complete installation summary:
 | /sr:compat-check | .claude/commands/sr/compat-check.md |
 | /sr:refactor-recommender | .claude/commands/sr/refactor-recommender.md |
 | /sr:why | .claude/commands/sr/why.md |
-
-Note: Only commands selected during setup are shown. Backlog commands are excluded if no backlog provider was configured.
+[If cli_provider == "codex":]
+| Skill | File |
+|-------|------|
+| $sr-implement | .agents/skills/sr-implement/SKILL.md |
+| $sr-batch-implement | .agents/skills/sr-batch-implement/SKILL.md |
+| $sr-propose-spec | .agents/skills/sr-propose-spec/SKILL.md |
+| $sr-product-backlog | .agents/skills/sr-product-backlog/SKILL.md |
+| $sr-update-product-driven-backlog | .agents/skills/sr-update-product-driven-backlog/SKILL.md |
+| $sr-health-check | .agents/skills/sr-health-check/SKILL.md |
+| $sr-compat-check | .agents/skills/sr-compat-check/SKILL.md |
+| $sr-refactor-recommender | .agents/skills/sr-refactor-recommender/SKILL.md |
+| $sr-why | .agents/skills/sr-why/SKILL.md |
+
+Note: Only commands/skills selected during setup are shown. Backlog commands are excluded if no backlog provider was configured.
 
 ### Rules Created
 | Layer | File |
 |-------|------|
-| Backend | .claude/rules/backend.md |
-| Frontend | .claude/rules/frontend.md |
+| Backend | $SPECRAILS_DIR/rules/backend.md |
+| Frontend | $SPECRAILS_DIR/rules/frontend.md |
 
 ### Scaffolding Removed
 | Artifact | Status |
 |----------|--------|
-| .claude/setup-templates/ | Deleted |
-| .claude/commands/setup.md | Deleted |
+| $SPECRAILS_DIR/setup-templates/ | Deleted |
+[If cli_provider == "claude":] | .claude/commands/setup.md | Deleted |
+[If cli_provider == "codex":] | .agents/skills/setup/ | Deleted |
 | specrails/ | [User's choice] |
 
 ### Next Steps
+[If cli_provider == "claude":]
 1. Review the generated files in .claude/
 2. Run `/sr:product-backlog` to see your backlog (if GitHub Issues exist)
 3. Run `/sr:update-product-driven-backlog` to generate feature ideas
 4. Run `/sr:implement #issue-number` to implement a feature
 5. Commit the .claude/ directory to version control
+[If cli_provider == "codex":]
+1. Review the generated files in .codex/ and .agents/skills/
+2. Run `$sr-product-backlog` to see your backlog (if GitHub Issues exist)
+3. Run `$sr-update-product-driven-backlog` to generate feature ideas
+4. Run `$sr-implement #issue-number` to implement a feature
+5. Commit the .codex/ and .agents/ directories to version control
 
 ### Quick Start
+[If cli_provider == "claude":]
 - `/sr:implement "describe a feature"` — implement something right now
 - `/sr:product-backlog` — see prioritized feature ideas
 - `/sr:update-product-driven-backlog` — discover new features using VPC
+[If cli_provider == "codex":]
+- `$sr-implement "describe a feature"` — implement something right now
+- `$sr-product-backlog` — see prioritized feature ideas
+- `$sr-update-product-driven-backlog` — discover new features using VPC
 ```
 
 ## First Task Prompt (Advanced Mode)
@@ -1248,7 +1336,10 @@ After displaying the setup complete summary above, detect the project type and o
 ✅ Setup complete.
 
 Try your first spec:
+[If cli_provider == "claude":]
   > /sr:product-backlog
+[If cli_provider == "codex":]
+  > $sr-product-backlog
 ```
 
 **Existing codebase** (one or more of the above files found in root):
@@ -1256,7 +1347,10 @@ Try your first spec:
 ✅ Setup complete.
 
 Try your first spec:
+[If cli_provider == "claude":]
   > /sr:health-check
+[If cli_provider == "codex":]
+  > $sr-health-check
 ```
 
 Then stop.

package/install.sh

@@ -44,6 +44,7 @@ SPECRAILS_DIR=""
 INSTRUCTIONS_FILE=""
 HAS_CLAUDE=false
 HAS_CODEX=false
+AGENT_TEAMS=false
 
 while [[ $# -gt 0 ]]; do
     case "$1" in
@@ -98,7 +99,7 @@ if [[ -z "$CUSTOM_ROOT_DIR" && -f "$SCRIPT_DIR/install.sh" && -d "$SCRIPT_DIR/te
     echo -e "${YELLOW}⚠${NC}  You're running the installer from inside the specrails source repo."
     echo -e "   specrails installs into a ${BOLD}target${NC} repository, not into itself."
     echo ""
-    read -p "   Enter the path to the target repo (or 'q' to quit): " TARGET_PATH
+    read -p "   Enter the path to the target repo (or 'q' to quit): " TARGET_PATH || TARGET_PATH="q"
     if [[ "$TARGET_PATH" == "q" || -z "$TARGET_PATH" ]]; then
         echo "   Aborted. No changes made."
         exit 0
@@ -229,7 +230,7 @@ elif [ "$HAS_CLAUDE" = true ] && [ "$HAS_CODEX" = true ]; then
         echo "      1) Claude Code (claude)  → output to .claude/"
         echo "      2) Codex (codex)         → output to .codex/"
         echo ""
-        read -p "    Select provider (1 or 2, default: 1): " PROVIDER_CHOICE
+        read -p "    Select provider (1 or 2, default: 1): " PROVIDER_CHOICE || PROVIDER_CHOICE="1"
         PROVIDER_CHOICE="${PROVIDER_CHOICE:-1}"
         if [[ "$PROVIDER_CHOICE" == "2" ]]; then
             CLI_PROVIDER="codex"
@@ -266,6 +267,35 @@ else
     INSTRUCTIONS_FILE="CLAUDE.md"
 fi
 
+# 1.2b Agent Teams opt-in (Claude Code only)
+if [[ "$CLI_PROVIDER" == "claude" ]]; then
+    echo ""
+    if [ "$AUTO_YES" = true ]; then
+        # --yes flag: default to NOT installing (opt-in, not opt-out)
+        AGENT_TEAMS=false
+        info "Agent Teams commands: skipped (opt-in, use interactive mode to enable)"
+    else
+        echo -e "  ${BOLD}Agent Teams commands are available (experimental):${NC}"
+        echo "    /sr:team-review — Multi-perspective code review with AI reviewers"
+        echo "    /sr:team-debug  — Collaborative debugging with competing hypotheses"
+        echo ""
+        echo "  These require Claude Code Agent Teams (experimental feature)."
+        read -p "  Install Agent Teams commands? (y/n, default: n): " INSTALL_AGENT_TEAMS || INSTALL_AGENT_TEAMS="n"
+        if [[ "$INSTALL_AGENT_TEAMS" == "y" || "$INSTALL_AGENT_TEAMS" == "Y" ]]; then
+            AGENT_TEAMS=true
+            ok "Agent Teams commands will be installed"
+            echo ""
+            info "Remember to set the feature flag before using these commands:"
+            echo ""
+            echo "    export CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1"
+            echo ""
+        else
+            AGENT_TEAMS=false
+            info "Agent Teams commands: skipped"
+        fi
+    fi
+fi
+
 # 1.3 API key / authentication (provider-specific)
 if [[ "$CLI_PROVIDER" == "claude" ]]; then
     CLAUDE_AUTHED=false
@@ -334,7 +364,7 @@ elif [ -f "$REPO_ROOT/node_modules/.bin/openspec" ]; then
 else
     warn "OpenSpec CLI not found."
     if [ "$HAS_NPM" = true ]; then
-        if [ "$AUTO_YES" = true ]; then INSTALL_OPENSPEC="y"; else read -p "    Install OpenSpec CLI globally? (y/n): " INSTALL_OPENSPEC; fi
+        if [ "$AUTO_YES" = true ]; then INSTALL_OPENSPEC="y"; else read -p "    Install OpenSpec CLI globally? (y/n): " INSTALL_OPENSPEC || INSTALL_OPENSPEC="n"; fi
         if [ "$INSTALL_OPENSPEC" = "y" ] || [ "$INSTALL_OPENSPEC" = "Y" ]; then
             info "Installing OpenSpec CLI..."
             npm install -g @openspec/cli 2>/dev/null && {
@@ -439,7 +469,7 @@ fi
 if [ "$EXISTING_SETUP" = true ]; then
     echo ""
     warn "This repo already has some agent/command/openspec artifacts."
-    if [ "$AUTO_YES" = true ]; then CONTINUE="y"; else read -p "    Continue and merge with existing setup? (y/n): " CONTINUE; fi
+    if [ "$AUTO_YES" = true ]; then CONTINUE="y"; else read -p "    Continue and merge with existing setup? (y/n): " CONTINUE || CONTINUE="n"; fi
     if [ "$CONTINUE" != "y" ] && [ "$CONTINUE" != "Y" ]; then
         info "Aborted. No changes made."
         exit 0
@@ -456,7 +486,13 @@ step "Phase 3: Installing specrails artifacts"
 
 # Create directory structure
 mkdir -p "$REPO_ROOT/specrails"
-mkdir -p "$REPO_ROOT/$SPECRAILS_DIR/commands"
+if [[ "$CLI_PROVIDER" == "codex" ]]; then
+    # Codex: install as Agent Skills (Codex doesn't support .codex/commands/)
+    mkdir -p "$REPO_ROOT/.agents/skills/setup"
+    mkdir -p "$REPO_ROOT/.agents/skills/doctor"
+else
+    mkdir -p "$REPO_ROOT/$SPECRAILS_DIR/commands"
+fi
 mkdir -p "$REPO_ROOT/$SPECRAILS_DIR/setup-templates/agents"
 mkdir -p "$REPO_ROOT/$SPECRAILS_DIR/setup-templates/commands"
 mkdir -p "$REPO_ROOT/$SPECRAILS_DIR/setup-templates/skills"
@@ -467,13 +503,46 @@ mkdir -p "$REPO_ROOT/$SPECRAILS_DIR/setup-templates/settings"
 mkdir -p "$REPO_ROOT/$SPECRAILS_DIR/setup-templates/prompts"
 mkdir -p "$REPO_ROOT/$SPECRAILS_DIR/agent-memory/explanations"
 
-# Copy the /setup command
-cp "$SCRIPT_DIR/commands/setup.md" "$REPO_ROOT/$SPECRAILS_DIR/commands/setup.md"
-ok "Installed /setup command"
+# Copy the /setup and /doctor commands (or skills for Codex)
+if [[ "$CLI_PROVIDER" == "codex" ]]; then
+    # Codex uses Agent Skills in .agents/skills/<name>/SKILL.md
+    {
+        echo '---'
+        echo 'name: setup'
+        echo 'description: "Interactive wizard to configure the full specrails agent workflow system for this repository."'
+        echo 'license: MIT'
+        echo 'compatibility: "Requires npm, git."'
+        echo 'metadata:'
+        echo '  author: specrails'
+        echo '  version: "1.0"'
+        echo '---'
+        echo ''
+        cat "$SCRIPT_DIR/commands/setup.md"
+    } > "$REPO_ROOT/.agents/skills/setup/SKILL.md"
+    ok "Installed \$setup skill"
+
+    {
+        echo '---'
+        echo 'name: doctor'
+        echo 'description: "Health check for the specrails agent workflow system — validates agents, commands, rules, and configuration."'
+        echo 'license: MIT'
+        echo 'compatibility: "Requires npm, git."'
+        echo 'metadata:'
+        echo '  author: specrails'
+        echo '  version: "1.0"'
+        echo '---'
+        echo ''
+        cat "$SCRIPT_DIR/commands/doctor.md"
+    } > "$REPO_ROOT/.agents/skills/doctor/SKILL.md"
+    ok "Installed \$doctor skill"
+else
+    # Claude Code uses commands in .claude/commands/
+    cp "$SCRIPT_DIR/commands/setup.md" "$REPO_ROOT/$SPECRAILS_DIR/commands/setup.md"
+    ok "Installed /setup command"
 
-# Copy the /doctor command
-cp "$SCRIPT_DIR/commands/doctor.md" "$REPO_ROOT/$SPECRAILS_DIR/commands/doctor.md"
-ok "Installed /doctor command"
+    cp "$SCRIPT_DIR/commands/doctor.md" "$REPO_ROOT/$SPECRAILS_DIR/commands/doctor.md"
+    ok "Installed /doctor command"
+fi
 
 # Install bin/doctor.sh for standalone use
 mkdir -p "$REPO_ROOT/.specrails/bin"
@@ -482,7 +551,9 @@ chmod +x "$REPO_ROOT/.specrails/bin/doctor.sh"
 ok "Installed specrails doctor (bin/doctor.sh)"
 
 # Copy templates (includes commands, skills, agents, rules, personas, settings)
-cp -r "$SCRIPT_DIR/templates/"* "$REPO_ROOT/$SPECRAILS_DIR/setup-templates/"
+# Use tar to exclude node_modules and package-lock.json for performance
+tar -C "$SCRIPT_DIR/templates" --exclude='node_modules' --exclude='package-lock.json' -cf - . \
+    | tar -C "$REPO_ROOT/$SPECRAILS_DIR/setup-templates/" -xf -
 ok "Installed setup templates (commands + skills)"
 
 # Write OSS detection results for /setup
@@ -503,7 +574,8 @@ cat > "$REPO_ROOT/$SPECRAILS_DIR/setup-templates/.provider-detection.json" << EO
 {
   "cli_provider": "$CLI_PROVIDER",
   "specrails_dir": "$SPECRAILS_DIR",
-  "instructions_file": "$INSTRUCTIONS_FILE"
+  "instructions_file": "$INSTRUCTIONS_FILE",
+  "agent_teams": $AGENT_TEAMS
 }
 EOF
 ok "Provider detection results written ($CLI_PROVIDER → $SPECRAILS_DIR/)"
@@ -550,9 +622,18 @@ echo ""
 echo -e "${BOLD}${GREEN}Installation summary:${NC}"
 echo ""
 echo "  Provider: $CLI_PROVIDER → output to $SPECRAILS_DIR/"
+if [[ "$AGENT_TEAMS" == "true" ]]; then
+    echo "  Agent Teams: installed (/sr:team-review, /sr:team-debug)"
+    echo "  Feature flag: CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1 (required)"
+fi
 echo ""
 echo "  Files installed:"
-echo "    $SPECRAILS_DIR/commands/setup.md          ← The /setup command"
+if [[ "$CLI_PROVIDER" == "codex" ]]; then
+    echo "    .agents/skills/setup/SKILL.md        ← The \$setup skill"
+    echo "    .agents/skills/doctor/SKILL.md       ← The \$doctor skill"
+else
+    echo "    $SPECRAILS_DIR/commands/setup.md          ← The /setup command"
+fi
 echo "    $SPECRAILS_DIR/setup-templates/           ← Templates: commands + skills (temporary, removed after setup)"
 echo "    .specrails-version                       ← Installed specrails version"
 echo "    .specrails-manifest.json                 ← Artifact checksums for update detection"
@@ -574,7 +655,11 @@ echo -e "     ${BOLD}cd $REPO_ROOT && $CLI_PROVIDER${NC}"
 echo ""
 echo "  2. Run the setup wizard:"
 echo ""
-echo -e "     ${BOLD}/setup${NC}"
+if [[ "$CLI_PROVIDER" == "codex" ]]; then
+    echo -e "     ${BOLD}\$setup${NC}"
+else
+    echo -e "     ${BOLD}/setup${NC}"
+fi
 echo ""
 if [[ "$CLI_PROVIDER" == "codex" ]]; then
     echo "  Codex will analyze your codebase, ask about your users,"

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "specrails-core",
-  "version": "2.1.2",
+  "version": "3.1.0",
   "description": "AI agent workflow system for Claude Code — installs 12 specialized agents, orchestration commands, and persona-driven product discovery into any repository",
   "bin": {
     "specrails-core": "bin/specrails-core.js"
@@ -50,6 +50,10 @@
   "bugs": {
     "url": "https://github.com/fjpulidop/specrails-core/issues"
   },
+  "scripts": {
+    "test": "bash tests/run-all.sh",
+    "test:coverage": "bash tests/run-coverage.sh"
+  },
   "license": "MIT",
   "author": "fjpulidop"
 }

package/templates/commands/sr/team-debug.md

@@ -0,0 +1,286 @@
+---
+name: "Team Debug"
+description: "Collaborative debugging using Claude Code Agent Teams. Multiple investigators pursue competing hypotheses independently, challenge each other's findings, and produce a root cause analysis ranked by confidence."
+category: Workflow
+tags: [workflow, debugging, agent-teams, investigation]
+---
+
+Collaborative debugging for **{{PROJECT_NAME}}** using Claude Code Agent Teams. Multiple investigators pursue competing hypotheses about a bug, challenge each other's findings, and produce a confidence-ranked root cause analysis.
+
+**Input:** $ARGUMENTS — required: a bug description in one of these forms:
+- `"Login fails silently when email has uppercase letters"` — free text bug description
+- `tests/auth.test.ts` — a failing test file path
+- `"TypeError: Cannot read property 'id' of undefined"` — an error message or stack trace
+- `#42` — a GitHub issue number
+
+Optional flags:
+- `--scope <paths>` — comma-separated file/directory paths to constrain investigation (default: entire repo)
+- `--depth <level>` — investigation depth: `shallow`, `normal` (default), `deep`
+
+---
+
+## Phase 0: Feature Flag Guard
+
+**This check is mandatory and runs before anything else.**
+
+Check whether Agent Teams is enabled:
+
+```bash
+echo "${CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS:-}"
+```
+
+If the variable is unset or not equal to `1`, print this message and **stop immediately**:
+
+```
+Error: Agent Teams is an experimental feature that requires opt-in.
+
+To enable it, set the environment variable before starting Claude Code:
+
+  export CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1
+
+Agent Teams requires Claude Code v2.1.32 or later.
+```
+
+Do NOT proceed past this point if the guard fails.
+
+---
+
+## Phase 1: Bug Context Gathering
+
+Parse `$ARGUMENTS` to determine the bug context and flags.
+
+**Variables to set:**
+
+- `BUG_DESCRIPTION` — the user's description of the bug
+- `INPUT_TYPE` — `"text"`, `"test"`, `"error"`, or `"issue"`
+- `SCOPE_PATHS` — from `--scope` flag or `["."]` (entire repo)
+- `INVESTIGATION_DEPTH` — from `--depth` flag or `"normal"`
+
+**Detection rules:**
+
+1. If input starts with `#` or is a bare integer -> `INPUT_TYPE="issue"`, fetch issue body via `gh issue view <number> --json title,body`
+2. If input is a file path that exists and contains `test` or `spec` -> `INPUT_TYPE="test"`, run the test to capture failure output
+3. If input contains common error patterns (stack trace, `Error:`, `Exception`, `FATAL`) -> `INPUT_TYPE="error"`
+4. Otherwise -> `INPUT_TYPE="text"`
+
+If `$ARGUMENTS` is empty, print usage and stop:
+```
+Usage: /sr:team-debug <bug-description> [--scope <paths>] [--depth <level>]
+
+Examples:
+  /sr:team-debug "Login fails silently when email has uppercase letters"
+  /sr:team-debug tests/auth.test.ts --depth deep
+  /sr:team-debug "TypeError: Cannot read property 'id' of undefined" --scope src/api
+  /sr:team-debug #42
+```
+
+---
+
+## Phase 2: Hypothesis Generation
+
+Analyze the bug context and generate competing hypotheses:
+
+1. **Analyze symptoms**: Read relevant source files within `SCOPE_PATHS`, examine recent git changes (`git log --oneline -20` for the relevant paths), check related tests
+2. **Generate hypotheses**: Produce 2-3 distinct, testable hypotheses about the root cause. Each must target a different subsystem, mechanism, or failure mode.
+3. **Rank hypotheses**: Order by initial likelihood based on available evidence
+
+Each hypothesis MUST include:
+- **Title**: One-line description of the proposed cause
+- **Rationale**: Why this is plausible given the symptoms
+- **Investigation plan**: Specific files to examine, commands to run, patterns to search for
+- **Expected evidence**: What would confirm or refute this hypothesis
+
+Decide whether to launch 2 or 3 investigators:
+- Default: 2 investigators (Hypothesis A and B)
+- Launch 3 when: `--depth deep` is set, OR the bug description is ambiguous enough to warrant three genuinely distinct hypotheses
+
+Print the hypothesis summary:
+```
+## Bug Analysis
+
+**Input type:** <text / test / error / issue>
+**Scope:** <SCOPE_PATHS>
+**Depth:** <INVESTIGATION_DEPTH>
+
+### Hypotheses
+
+1. **<Hypothesis A title>** (initial confidence: X%)
+   <one-line rationale>
+
+2. **<Hypothesis B title>** (initial confidence: Y%)
+   <one-line rationale>
+
+3. **<Hypothesis C title>** (initial confidence: Z%) [if applicable]
+   <one-line rationale>
+
+Launching <N> investigators...
+```
+
+---
+
+## Phase 3: Launch Investigation Team
+
+Create 2-3 investigator teammates using Agent Teams. Each teammate receives the bug context and their assigned hypothesis.
+
+**IMPORTANT:** Use the Agent Teams teammate mechanism — NOT the Agent tool's `subagent_type`. Teammates share a task list and can message each other via mailbox.
+
+### Investigator A: Primary Hypothesis
+
+**Prompt:**
+```
+You are Investigator A on a debugging team. Your job is to prove or disprove your assigned hypothesis through systematic investigation.
+
+## Bug Context
+<BUG_DESCRIPTION>
+<additional context gathered in Phase 1: test output, error details, issue body>
+
+## Your Hypothesis
+**<Hypothesis A title>**
+<Hypothesis A rationale>
+
+## Investigation Plan
+<Hypothesis A investigation plan>
+
+## Scope
+Limit your investigation to: <SCOPE_PATHS>
+
+## Instructions
+1. Follow your investigation plan systematically
+2. Read source files, search for patterns, examine git history within scope
+3. Collect concrete evidence — file paths, line numbers, code snippets, command output
+4. Determine a confidence level (0-100%) that your hypothesis is the root cause
+5. After completing your investigation, read the other investigators' findings from the task list
+6. If you find evidence that supports or contradicts another investigator's hypothesis, send a mailbox message challenging or endorsing their findings
+7. Do NOT modify any files — this is a read-only investigation
+
+## Report Format
+Post your findings as a task list update:
+
+### Investigator A: <Hypothesis Title>
+
+#### Evidence Found
+| # | Type | Location | Finding |
+|---|------|----------|---------|
+| 1 | code/git/test/config | file:line | What was found |
+
+#### Evidence Against
+<any evidence that contradicts this hypothesis>
+
+#### Confidence: X%
+<explanation of confidence level>
+
+#### Verdict
+<CONFIRMED / REFUTED / INCONCLUSIVE>
+<brief explanation>
+```
+
+### Investigator B: Alternative Hypothesis
+
+Same structure as Investigator A, with Hypothesis B title, rationale, investigation plan, and expected evidence.
+
+### Investigator C: Contrarian Hypothesis (when applicable)
+
+Same structure as Investigator A, with Hypothesis C title, rationale, investigation plan, and expected evidence. Only launched when 3 hypotheses are generated.
+
+### Team Coordination
+
+After launching all investigators:
+
+1. Wait for all investigators to complete their independent investigations (posted to the shared task list)
+2. Allow one round of cross-investigation challenge via mailbox — each investigator may respond to findings from the others
+3. Collect all findings and challenge outcomes
+
+If any teammate fails to respond, proceed with available findings and note the gap in the final report.
+
+---
+
+## Phase 4: Root Cause Synthesis
+
+After all investigations and challenges are complete, the team lead produces the root cause analysis.
+
+### Step 1: Evidence Aggregation
+
+1. Read all investigator reports from the task list
+2. Identify converging evidence (multiple investigators pointing to the same cause)
+3. Identify conflicting evidence and note unresolved disagreements
+4. Read any mailbox challenge messages for cross-investigator insights
+
+### Step 2: Confidence Recalibration
+
+Adjust hypothesis confidence levels based on cross-investigation challenges:
+- A hypothesis endorsed by evidence from another investigator: confidence boost (+10-20%)
+- A hypothesis contradicted by another investigator's evidence: confidence reduction (-10-30%)
+- A hypothesis with no cross-investigation interaction: confidence unchanged
+- Converging evidence from multiple investigators: strongest signal for root cause
+
+### Step 3: Render Report
+
+```markdown
+## Root Cause Analysis
+
+**Bug:** <one-line bug description>
+**Scope:** <SCOPE_PATHS>
+**Depth:** <INVESTIGATION_DEPTH>
+**Investigators:** <N>
+
+---
+
+### Most Likely Root Cause
+
+**<Winning hypothesis title>** — Confidence: X%
+
+<2-3 sentence explanation of the root cause with specific file and line references>
+
+#### Key Evidence
+| # | Location | Finding |
+|---|----------|---------|
+| 1 | file:line | Evidence supporting this conclusion |
+
+#### Suggested Fix
+<specific, actionable fix recommendation with file and line references>
+
+---
+
+### Alternative Hypotheses
+
+| # | Hypothesis | Initial | Final | Verdict | Key Evidence |
+|---|-----------|---------|-------|---------|-------------|
+| 1 | <title> | X% | Y% | CONFIRMED/REFUTED/INCONCLUSIVE | <one-line> |
+| 2 | <title> | X% | Y% | CONFIRMED/REFUTED/INCONCLUSIVE | <one-line> |
+
+### Investigation Trail
+
+<for each investigator, a 2-3 line summary of what they investigated and what they found>
+
+### Cross-Investigation Notes
+
+<any points of challenge or agreement between investigators, with resolution>
+
+---
+
+### Recommended Next Steps
+
+1. <most important action — typically the fix>
+2. <verification step — test to confirm the fix>
+3. <preventive step — how to avoid this class of bug>
+```
+
+### Step 4: Cost Notice
+
+Print a brief cost notice after the report:
+
+```
+Note: Team debug used ~<N>x the tokens of a single-agent investigation (<N> parallel investigators + challenge round).
+```
+
+---
+
+## Rules
+
+- This command is **read-only** — it MUST NOT create, modify, or delete any files
+- All investigators run as Agent Teams teammates, not as Agent tool subagents
+- If Agent Teams is unavailable at runtime (API error, version mismatch), fall back to running 2-3 sequential Agent tool subagents and skip the challenge phase. Print a warning about the fallback.
+- The challenge phase is limited to one round per investigator to control token costs
+- Findings MUST include file paths and line numbers — vague findings are not acceptable
+- Investigation MUST stay within `SCOPE_PATHS` if specified
+- This command is Claude Code only — it is NOT installed when the provider is `codex`

package/templates/commands/sr/team-review.md

@@ -0,0 +1,341 @@
+---
+name: "Team Review"
+description: "Multi-perspective code review using Claude Code Agent Teams. Three specialized reviewers (security, performance, correctness) independently review changes, debate findings, and produce a consolidated report."
+category: Workflow
+tags: [workflow, review, agent-teams, security, performance]
+---
+
+Multi-perspective code review for **{{PROJECT_NAME}}** using Claude Code Agent Teams. Three specialized reviewers analyze changes independently, debate cross-cutting findings, and produce a consolidated report.
+
+**Input:** $ARGUMENTS — required: a review target in one of these forms:
+- `#123` — review a pull request by number
+- `feat/my-feature` — review a branch diff against base
+- `abc1234..def5678` — review a commit range
+
+Optional flags:
+- `--base <branch>` — override base branch for comparison (default: repository default branch)
+- `--focus <areas>` — comma-separated focus areas to weight: `security`, `performance`, `correctness`, `tests`, `types`
+
+---
+
+## Phase 0: Feature Flag Guard
+
+**This check is mandatory and runs before anything else.**
+
+Check whether Agent Teams is enabled:
+
+```bash
+echo "${CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS:-}"
+```
+
+If the variable is unset or not equal to `1`, print this message and **stop immediately**:
+
+```
+Error: Agent Teams is an experimental feature that requires opt-in.
+
+To enable it, set the environment variable before starting Claude Code:
+
+  export CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1
+
+Agent Teams requires Claude Code v2.1.32 or later.
+```
+
+Do NOT proceed past this point if the guard fails.
+
+---
+
+## Phase 1: Input Parsing
+
+Parse `$ARGUMENTS` to determine the review target and flags.
+
+**Variables to set:**
+
+- `REVIEW_TARGET` — the PR number, branch name, or commit range
+- `REVIEW_TYPE` — `"pr"`, `"branch"`, or `"range"`
+- `BASE_BRANCH` — from `--base` flag or detect via `gh repo view --json defaultBranchRef -q '.defaultBranchRef.name'` or fall back to `main`
+- `FOCUS_AREAS` — array from `--focus` flag or `["all"]`
+
+**Detection rules:**
+
+1. If input starts with `#` or is a bare integer → `REVIEW_TYPE="pr"`, strip `#` prefix
+2. If input contains `..` → `REVIEW_TYPE="range"`
+3. Otherwise → `REVIEW_TYPE="branch"`
+
+If `$ARGUMENTS` is empty, print usage and stop:
+```
+Usage: /sr:team-review <target> [--base <branch>] [--focus <areas>]
+
+Examples:
+  /sr:team-review #42
+  /sr:team-review feat/new-auth --focus security
+  /sr:team-review abc123..def456
+```
+
+---
+
+## Phase 2: Gather Diff
+
+Collect the code changes based on `REVIEW_TYPE`:
+
+- **PR**: Run `gh pr diff <REVIEW_TARGET>` and `gh pr diff <REVIEW_TARGET> --name-only`
+- **Branch**: Run `git diff ${BASE_BRANCH}...${REVIEW_TARGET}` and `git diff --name-only ${BASE_BRANCH}...${REVIEW_TARGET}`
+- **Range**: Run `git diff ${REVIEW_TARGET}` and `git diff --name-only ${REVIEW_TARGET}`
+
+Also collect file-level stats: `git diff --stat <appropriate-range>`
+
+**Store these variables for Phase 3:**
+- `DIFF_CONTENT` — full unified diff
+- `CHANGED_FILES` — list of changed file paths
+- `DIFF_STATS` — file-level line count changes
+
+If the diff is empty, print `No changes found for the given review target.` and stop.
+
+Print a summary:
+```
+## Review Target
+Type: <PR / Branch / Range>
+Target: <REVIEW_TARGET>
+Base: <BASE_BRANCH>
+Changed files: <N>
+Focus: <FOCUS_AREAS or "all areas">
+
+<DIFF_STATS output>
+```
+
+---
+
+## Phase 3: Launch Team Review
+
+Create three reviewer teammates using Agent Teams. Each teammate receives the full diff and file list.
+
+**IMPORTANT:** Use the Agent Teams teammate mechanism — NOT the Agent tool's `subagent_type`. Teammates share a task list and can message each other via mailbox.
+
+### Teammate 1: Security Reviewer
+
+**Persona:** sr-security-reviewer (or sr-reviewer with security focus if persona not available)
+
+**Prompt:**
+```
+You are the Security Reviewer on a team code review.
+
+## Your Focus Areas
+- Authentication and authorization flaws
+- Input validation and injection vulnerabilities (SQL, XSS, command injection)
+- Secrets or credentials in code
+- OWASP Top 10 vulnerabilities
+- Insecure dependencies or configurations
+- Missing rate limiting or access controls
+
+## Changed Files
+<CHANGED_FILES>
+
+## Diff
+<DIFF_CONTENT>
+
+## Instructions
+1. Review every changed file through a security lens
+2. Report findings using the format below — be specific about file, line, and fix
+3. After completing your review, read the other reviewers' findings from the task list
+4. If you have security-relevant context on their findings, send a mailbox message
+
+## Report Format
+Post your findings as a task list update:
+
+### Security Review Findings
+
+#### Summary
+<1-2 sentences>
+
+#### Findings
+| # | Severity | File | Line(s) | Finding | Recommendation |
+|---|----------|------|---------|---------|----------------|
+
+#### Verdict
+<APPROVE / REQUEST_CHANGES / COMMENT>
+```
+
+### Teammate 2: Performance Reviewer
+
+**Persona:** sr-performance-reviewer (or sr-reviewer with performance focus if persona not available)
+
+**Prompt:**
+```
+You are the Performance Reviewer on a team code review.
+
+## Your Focus Areas
+- Database query complexity and N+1 queries
+- Missing or broken caching
+- Memory leaks and excessive allocations
+- Algorithmic complexity (O(n^2) or worse in hot paths)
+- Bundle size and lazy loading concerns (frontend)
+- Missing pagination or unbounded data fetching
+
+## Changed Files
+<CHANGED_FILES>
+
+## Diff
+<DIFF_CONTENT>
+
+## Instructions
+1. Review every changed file through a performance lens
+2. Report findings using the format below — be specific about file, line, and fix
+3. After completing your review, read the other reviewers' findings from the task list
+4. If you have performance-relevant context on their findings, send a mailbox message
+
+## Report Format
+Post your findings as a task list update:
+
+### Performance Review Findings
+
+#### Summary
+<1-2 sentences>
+
+#### Findings
+| # | Severity | File | Line(s) | Finding | Recommendation |
+|---|----------|------|---------|---------|----------------|
+
+#### Verdict
+<APPROVE / REQUEST_CHANGES / COMMENT>
+```
+
+### Teammate 3: Correctness Reviewer
+
+**Persona:** sr-reviewer
+
+**Prompt:**
+```
+You are the Correctness Reviewer on a team code review.
+
+## Your Focus Areas
+- Logic errors and edge cases
+- Missing or inadequate test coverage
+- Type safety violations
+- Error handling gaps (uncaught exceptions, missing error paths)
+- API contract mismatches
+- Race conditions and concurrency issues
+
+## Changed Files
+<CHANGED_FILES>
+
+## Diff
+<DIFF_CONTENT>
+
+## Instructions
+1. Review every changed file through a correctness and test coverage lens
+2. Report findings using the format below — be specific about file, line, and fix
+3. After completing your review, read the other reviewers' findings from the task list
+4. If you have correctness-relevant context on their findings, send a mailbox message
+
+## Report Format
+Post your findings as a task list update:
+
+### Correctness Review Findings
+
+#### Summary
+<1-2 sentences>
+
+#### Findings
+| # | Severity | File | Line(s) | Finding | Recommendation |
+|---|----------|------|---------|---------|----------------|
+
+#### Verdict
+<APPROVE / REQUEST_CHANGES / COMMENT>
+```
+
+### Team Coordination
+
+After launching all three teammates:
+
+1. Wait for all three to complete their independent reviews (posted to the shared task list)
+2. Allow one round of cross-review debate via mailbox — each reviewer may respond to findings from the other two
+3. Collect all findings and debate outcomes
+
+If any teammate fails to respond, proceed with available reviews and note the gap in the final report.
+
+---
+
+## Phase 4: Synthesize Consolidated Report
+
+After all reviews and debate are complete, the team lead produces the final report.
+
+### Step 1: Collect and Deduplicate
+
+1. Read all three reviewer reports from the task list
+2. Identify duplicate findings (same file + overlapping lines + similar issue)
+3. For duplicates: keep the highest-severity version, note which reviewers flagged it
+
+### Step 2: Apply Focus Weighting
+
+If `FOCUS_AREAS` is not `["all"]`:
+- Findings in focus areas get their severity preserved
+- Findings outside focus areas: Critical stays Critical, but High→Medium, Medium→Low for display purposes
+- Note the weighting in the report header
+
+### Step 3: Render Report
+
+```markdown
+## Team Review Report
+
+**Target:** <PR #N / branch-name / commit-range>
+**Base:** <BASE_BRANCH>
+**Reviewers:** Security, Performance, Correctness
+**Changed files:** N files (+X/-Y lines)
+**Focus:** <FOCUS_AREAS or "all areas equally weighted">
+
+---
+
+### Critical Findings (action required before merge)
+
+| # | Severity | Domain | File | Line(s) | Finding | Recommendation | Flagged By |
+|---|----------|--------|------|---------|---------|----------------|------------|
+
+### High-Priority Findings
+
+| # | Severity | Domain | File | Line(s) | Finding | Recommendation | Flagged By |
+|---|----------|--------|------|---------|---------|----------------|------------|
+
+### Medium & Low Findings
+
+| # | Severity | Domain | File | Line(s) | Finding | Recommendation |
+|---|----------|--------|------|---------|---------|----------------|
+
+### Praise (things done well)
+<positive observations from reviewers>
+
+---
+
+### Cross-Review Notes
+<any points of debate or disagreement between reviewers, with resolution>
+
+---
+
+### Reviewer Verdicts
+
+| Reviewer | Verdict | Critical | High | Medium | Low | Info |
+|----------|---------|----------|------|--------|-----|------|
+| Security | APPROVE/REQUEST_CHANGES | N | N | N | N | N |
+| Performance | APPROVE/REQUEST_CHANGES | N | N | N | N | N |
+| Correctness | APPROVE/REQUEST_CHANGES | N | N | N | N | N |
+
+### Overall Verdict: <APPROVE / REQUEST_CHANGES>
+
+<one-paragraph summary: key risks, recommended actions, and overall assessment>
+```
+
+### Step 4: Cost Notice
+
+Print a brief cost notice after the report:
+
+```
+Note: Team review used ~3x the tokens of a single-reviewer run (3 parallel reviewers + debate round).
+```
+
+---
+
+## Rules
+
+- This command is **read-only** — it MUST NOT create, modify, or delete any files
+- All three reviewers run as Agent Teams teammates, not as Agent tool subagents
+- If Agent Teams is unavailable at runtime (API error, version mismatch), fall back to running three sequential Agent tool subagents with `subagent_type: sr-reviewer` and skip the debate phase. Print a warning about the fallback.
+- The debate phase is limited to one round per reviewer to control token costs
+- Findings MUST include file paths and line numbers — vague findings are not acceptable

package/update.sh

@@ -94,7 +94,7 @@ if [[ -z "$CUSTOM_ROOT_DIR" && -f "$SCRIPT_DIR/install.sh" && -d "$SCRIPT_DIR/te
     echo -e "${YELLOW}⚠${NC}  You're running the updater from inside the specrails source repo."
     echo -e "   specrails updates a ${BOLD}target${NC} repository, not itself."
     echo ""
-    read -p "   Enter the path to the target repo (or 'q' to quit): " TARGET_PATH
+    read -p "   Enter the path to the target repo (or 'q' to quit): " TARGET_PATH || TARGET_PATH="q"
     if [[ "$TARGET_PATH" == "q" || -z "$TARGET_PATH" ]]; then
         echo "   Aborted. No changes made."
         exit 0
@@ -107,7 +107,7 @@ if [[ -z "$CUSTOM_ROOT_DIR" && -f "$SCRIPT_DIR/install.sh" && -d "$SCRIPT_DIR/te
     }
     if [[ ! -d "$REPO_ROOT/.git" ]]; then
         echo -e "${YELLOW}⚠${NC}  Warning: $REPO_ROOT does not appear to be a git repository."
-        read -p "   Continue anyway? (y/n): " CONTINUE_NOGIT
+        read -p "   Continue anyway? (y/n): " CONTINUE_NOGIT || CONTINUE_NOGIT="n"
         if [[ "$CONTINUE_NOGIT" != "y" && "$CONTINUE_NOGIT" != "Y" ]]; then
             echo "   Aborted. No changes made."
             exit 0
@@ -658,7 +658,7 @@ except Exception:
         fi
 
         local answer
-        read -p "    Regenerate agents? (y/N): " answer
+        read -p "    Regenerate agents? (y/N): " answer || answer="n"
         if [[ "$answer" == "y" ]] || [[ "$answer" == "Y" ]]; then
             NEEDS_SETUP_UPDATE=true
             ok "Will regenerate agents via /setup --update"