claude-code-arcane 2.7.1 → 2.9.1

package/docs/USER-GUIDE.md

@@ -2,7 +2,7 @@
 
 ## What is Arcane?
 
-Arcane is a configuration harness for [Claude Code](https://docs.anthropic.com/en/docs/claude-code). It provides a curated library of **437 skills**, **109 agents**, **17 hooks**, and **30 rules** that you selectively deploy into any project. Instead of shipping everything to every project (wasting tokens and degrading performance), you pick a **profile** that matches your stack and only the relevant tools get installed.
+Arcane is a configuration harness for [Claude Code](https://docs.anthropic.com/en/docs/claude-code). It provides a curated library of **437 skills**, **115 agents**, **17 hooks**, and **31 rules** that you selectively deploy into any project. Instead of shipping everything to every project (wasting tokens and degrading performance), you pick a **profile** that matches your stack and only the relevant tools get installed.
 
 ## Table of Contents
 
@@ -392,6 +392,31 @@ my-project/.claude/
 └── docs/                  # General documentation
 ```
 
+### Qué agentes instala un profile
+
+La lista `agents:` de un profile acepta dos formas:
+
+```yaml
+agents:
+  - game                        # la división entera: 30 agentes
+  - quality/security-architect  # solo ese agente
+```
+
+La forma por división es la original y sigue siendo el default. La granular
+existe porque **las divisiones son temáticas, no funcionales**: `qa-lead`,
+`ux-designer` y `performance-analyst` viven en `game/` y los quieren profiles
+que no tienen nada de gamedev. Antes la única manera de alcanzar uno era
+instalar los 30 — justo el peso que los profiles existen para evitar.
+
+Reglas:
+
+- Si un profile ya trae la división entera, una entrada granular de esa misma
+  división es un no-op, no una segunda copia.
+- Al desinstalar, una entrada granular borra solo su archivo, y se lleva el
+  directorio de la división únicamente si queda vacío.
+- Si otro profile activo declara la división completa, esa gana: la entrada
+  granular no borra nada, porque rompería al otro profile.
+
 ### settings.json
 
 Generated automatically with merged permissions from all selected profiles. Includes:

package/docs/agent-hierarchy.md

@@ -21,7 +21,14 @@ Cada división sigue una jerarquía de estudio real con 3 niveles de autoridad:
 
 ---
 
-## Roster Completo (143 Agentes)
+## Roster Completo (115 Agentes)
+
+> Los 109 agentes de abajo son los que existen en `agents/`. El roster
+> original de este documento listaba 143, de los cuales se implementaron
+> 109: los 34 restantes generaban delegaciones a agentes inexistentes.
+> `src/__tests__/agents-integrity.test.ts` verifica que cada delegacion
+> resuelva, asi que agregar un nombre aca sin crear el archivo rompe el
+> build.
 
 ### División 1 — Game Development Studio (44)
 
@@ -150,4 +157,37 @@ Se lanzan desde los skills de `+freelance`. `client-screener` y `proposal-review
 3. **Lead de una división → Lead de otra división** (para colaboración cross-area)
 4. **Director → Director** (para conflictos estratégicos)
 
-**Los agentes NUNCA escriben a archivos directamente.** Todos los writes los hace la main session después de que el agente devuelve análisis/propuestas al usuario.
+## Consultores y ejecutores
+
+Cada agente es una de dos cosas, nunca las dos. La distinción no es de estilo:
+**un subagente no puede hacer preguntas.** `AskUserQuestion` no está en su pool
+de tools y su única salida es el reporte final al parent. Un agente con
+`Write`/`Edit` y la instrucción de pedir aprobación antes de escribir lee,
+formula sus preguntas, no tiene a quién hacérselas, devuelve texto y no toca un
+archivo. Ese fue el bug: 46 de 109 agentes estaban en esa situación.
+
+### Consultores (15) - read-only por diseño
+
+`career/` (4), `freelance/` (4), `clevel/` (6) y `engineering/nextjs-reviewer`.
+
+Existen para dar una lectura independiente: el que escribió el CV no lo puede
+revisar, y el que redactó la propuesta está convencido de su propio texto.
+Declaran `tools` sin `Write`/`Edit` y `disallowedTools: Bash, Write, Edit`.
+Read-only por diseño, no por precaución.
+
+### Ejecutores (94) - escriben
+
+Todo el resto. Declaran `permissionMode: acceptEdits`, que es el campo oficial
+que deja al subagente escribir sin gate interactivo.
+
+Su protocolo no es "preguntá y esperá" sino **declará el supuesto y seguí**:
+ante una ambigüedad eligen la opción más consistente con el código existente,
+la anotan en el reporte en una línea que empieza con `ASSUMPTION:` para que el
+caller pueda grepearla y contradecirla, y avanzan. La disciplina de leer el
+diseño antes de escribir se mantiene; lo que se eliminó es la espera imposible.
+
+### Quién aplica los cambios
+
+El ejecutor escribe sus propios archivos. La main session sigue siendo la que
+decide *a quién* invocar y la que integra los resultados, pero ya no es el
+único camino a disco.

package/docs/collaborative-design.md

@@ -434,6 +434,7 @@ Si alguno es "no" → el agente no fue lo suficientemente colaborativo.
 Este principio debe estar embebido en:
 
 - **CLAUDE.md** — sección de collaboration protocol
-- **Todos los agents** — enforce question-asking antes de Write/Edit
+- **Skills y main session** — enforce question-asking antes de Write/Edit
+- **Subagentes ejecutores** — NO pueden preguntar (`AskUserQuestion` no está en su pool). Declaran el supuesto con `ASSUMPTION:` en el reporte y avanzan. Ver `agent-hierarchy.md` § Consultores y ejecutores.
 - **Todos los skills** — require approval antes de escribir
 - **Team orchestrators** — decision points entre fases

package/docs/directory-structure.md

@@ -27,19 +27,24 @@ Claude-Code-Arcane/
 │   ├── regulatory.profile             # Add-on: Regulatory & compliance
 │   └── ...                            # agile, testing, infra, security, etc.
 │
-├── agents/                            # 80 agent definitions (root level)
-│   ├── game/                          # División 1 — Game Dev (27 agents)
-│   ├── engineering/                   # División 2 — Software Eng (14 agents)
-│   ├── devops/                        # División 3 — DevOps (3 agents)
-│   ├── product/                       # División 4 — Product & Design (5 agents)
-│   ├── management/                    # División 5 — PMO (4 agents)
-│   ├── quality/                       # División 6 — Quality & Security (3 agents)
-│   ├── integrations/                  # División 8 — Tools & Integrations (6 agents)
-│   ├── ai/                            # División 9 — AI & Data Science (4 agents)
-│   ├── clevel/                        # División 10 — C-Suite Advisory (6 agents)
-│   ├── business/                      # División 11 — Business & Finance (3 agents)
-│   ├── marketing/                     # División 12 — Marketing (5 agents)
-│   └── regulatory/                    # División 13 — Regulatory (3 agents)
+├── agents/                            # 115 agent definitions (root level)
+│   ├── ai/                            # 4 agents
+│   ├── audio/                         # 6 agents
+│   ├── business/                      # 3 agents
+│   ├── career/                        # 4 agents
+│   ├── clevel/                        # 6 agents
+│   ├── devops/                        # 4 agents
+│   ├── ecommerce/                     # 1 agent
+│   ├── engineering/                   # 19 agents
+│   ├── freelance/                     # 4 agents
+│   ├── game/                          # 32 agents
+│   ├── integrations/                  # 6 agents
+│   ├── management/                    # 4 agents
+│   ├── marketing/                     # 5 agents
+│   ├── product/                       # 5 agents
+│   ├── quality/                       # 3 agents
+│   ├── regulatory/                    # 3 agents
+│   └── visualnovel/                   # 6 agents
 │
 ├── .claude/                           # Claude Code configuration
 │   ├── settings.json                  # Hooks, permissions, safety

package/hooks/statusline.sh

@@ -15,12 +15,17 @@ fi
 # Skills/agents Claude can actually invoke = global (~/.claude) + project (.claude),
 # deduped by name (project overrides global). Follow -L so .claude/skills junctions count.
 # Top-level only (mindepth/maxdepth 2) so bundled sub-skills don't inflate the total.
+#
+# Names are extracted with a single awk, never `xargs -n1 dirname|basename`: that spawned one
+# process per file (~160 here), which cost ~1.7s of the ~2.5s total on Windows and made the
+# status line miss its execution window under load — Claude Code drops the output on a
+# non-zero exit or an abort, so the bar vanished at random.
 SKILLS=$( { find -L "$HOME/.claude/skills" -mindepth 2 -maxdepth 2 -name "SKILL.md" 2>/dev/null;
             find -L .claude/skills          -mindepth 2 -maxdepth 2 -name "SKILL.md" 2>/dev/null; } \
-          | xargs -n1 dirname 2>/dev/null | xargs -n1 basename 2>/dev/null | sort -u | wc -l | tr -d ' ')
+          | awk -F/ 'NF>1{print $(NF-1)}' | sort -u | wc -l | tr -d ' ')
 AGENTS=$( { find -L "$HOME/.claude/agents" -name "*.md" 2>/dev/null;
             find -L .claude/agents         -name "*.md" 2>/dev/null; } \
-          | xargs -n1 basename 2>/dev/null | sort -u | wc -l | tr -d ' ')
+          | awk -F/ '{print $NF}' | sort -u | wc -l | tr -d ' ')
 
 PYCMD=$(command -v python 2>/dev/null || command -v python3 2>/dev/null || command -v py 2>/dev/null)
 
@@ -117,8 +122,16 @@ PREFIX="🔮 ${PROJECT}"
 
 PARTS="${PREFIX}"
 [ -n "$BRANCH" ] && PARTS="${PARTS} | 🌿 ${BRANCH}"
-PARTS="${PARTS} | 🛠️ ${SKILLS} skills"
-[ "$AGENTS" -gt 0 ] 2>/dev/null && PARTS="${PARTS} | 🤖 ${AGENTS} agents"
+PARTS="${PARTS} | 🛠️ ${SKILLS:-0} skills"
+case "$AGENTS" in
+  ''|*[!0-9]*) ;;
+  0) ;;
+  *) PARTS="${PARTS} | 🤖 ${AGENTS} agents" ;;
+esac
 [ -n "$EXTRA" ] && PARTS="${PARTS} | ${EXTRA}"
 
 echo "$PARTS"
+
+# Claude Code discards the status line on a non-zero exit, so never inherit one from the
+# last conditional above.
+exit 0

package/output-styles/arcane.md

@@ -0,0 +1,53 @@
+---
+name: arcane
+description: Respuestas compactas, tablas para comparar, lenguaje literal y estructura legible — pensado para lectura con TEA y dislexia.
+---
+
+# Arcane
+
+Respondé de forma compacta, literal y estructurada. Estas instrucciones son sobre **la
+forma** de la respuesta, no sobre el alcance del trabajo: no reducen lo que hay que hacer ni
+autorizan entregar menos.
+
+## Largo
+
+- **La respuesta primero.** Primera línea: qué pasó o qué contestás. El detalle va después,
+  para quien lo quiera.
+- **Sin preámbulo.** No repitas la pregunta, no anuncies lo que vas a hacer, no cierres
+  resumiendo lo que acabás de decir.
+- **Un tema por párrafo, tres líneas como máximo.** Si un párrafo crece, partilo o pasalo a
+  lista.
+- **Cortá cuando terminaste.** Nada de relleno, cierres corteses ni ofertas genéricas de
+  ayuda.
+- **No enumeres lo que descartaste.** Si evaluaste opciones y elegiste, decí la elegida y el
+  porqué en una línea.
+
+## Estructura
+
+- **Tabla siempre que compares.** Dos o más cosas con dos o más atributos (opciones,
+  versiones, proyectos, trade-offs) van en tabla, no en prosa ni en bullets paralelos. Una
+  columna por atributo, una fila por cosa.
+- **Listas para pasos y hallazgos.** Prosa solo para el razonamiento que une las cosas.
+- **Títulos cuando hay más de un tema.** Que se pueda saltar a la parte que importa sin
+  leer todo.
+- **`backticks` en todo identificador** — archivos, comandos, ramas, funciones, flags.
+- **Bold para lo importante**, no italics: es más fácil de decodificar. Nunca MAYÚSCULAS
+  para enfatizar, deforman la silueta de la palabra.
+
+## Lenguaje
+
+- **Literal.** Sin ironía, sarcasmo, modismos, metáforas ni preguntas retóricas. Si algo
+  está mal, decilo derecho.
+- **Un término por concepto, siempre el mismo.** No alternes sinónimos para la misma cosa:
+  si es `worktree`, es `worktree` en toda la respuesta.
+- **Oraciones cortas, una idea cada una.** Preferí punto sobre subordinada.
+- **Voz activa y sujeto explícito.** Decí quién hace qué.
+- **La incertidumbre se declara, no se insinúa.** "No sé si X" o "no lo verifiqué", en vez
+  de prosa condicional que deja al lector adivinando el nivel de confianza.
+- **Decí explícitamente qué esperás del otro.** Si hace falta una decisión, que se vea que
+  hace falta y cuáles son las alternativas.
+
+## Números y datos
+
+- **El dato antes que el adjetivo.** "62 commits atrás" en vez de "bastante atrasado".
+- **Unidad y fecha completas.** `2026-09-04`, no "ayer"; `312 KB`, no "poco".

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "claude-code-arcane",
-  "version": "2.7.1",
+  "version": "2.9.1",
   "description": "Skills, agents, hooks and rules for Claude Code — installable via npx claude-code-arcane",
   "type": "module",
   "bin": {
@@ -15,6 +15,7 @@
     "rules/",
     "templates/",
     "docs/",
+    "output-styles/",
     "CHANGELOG.md"
   ],
   "scripts": {

package/profiles/backend-go.yaml

@@ -46,6 +46,7 @@ rules:
 
 agents:
   - engineering
+  - quality/security-architect
 
 permissions:
   allow:

package/profiles/core.yaml

@@ -32,9 +32,13 @@ rules:
     - prototype-code
     - test-standards
     - implementation-workflow
+    - code-comments
   gamedev:
     []
 
+output_styles:
+  - arcane
+
 agents:
   - quality
 

package/profiles/docs.yaml

@@ -8,8 +8,6 @@ skills:
   - xlsx-generator
   - docx-generator
   - architecture-decision
-  - architecture-review
-
 rules:
   universal:
     []

package/profiles/security.yaml

@@ -21,7 +21,7 @@ rules:
     []
 
 agents:
-  []
+  - quality/security-architect
 
 permissions:
   allow:

package/profiles/unity-design.yaml

@@ -20,6 +20,7 @@ skills:
   - playtest-report
   - consistency-check
   - asset-audit
+  - architecture-review
 
 rules:
   universal:
@@ -30,6 +31,7 @@ rules:
 
 agents:
   - game
+  - product/ux-lead
 
 permissions:
   allow:

package/profiles/unity-dev.yaml

@@ -23,6 +23,7 @@ skills:
   - consistency-check
   - doc-gdd
   - playtest-report
+  - architecture-review
 
 rules:
   universal:
@@ -37,6 +38,7 @@ rules:
 
 agents:
   - game
+  - quality/security-architect
 
 permissions:
   allow:

package/profiles/unreal-dev.yaml

@@ -3,6 +3,7 @@ description: "Programador Unreal Engine 5 — C++, Blueprints, GAS, replication,
 category: gamedev
 
 skills:
+  - architecture-review
   # Foundation — read this first, every other ue-* skill depends on it
   - ue-project-context
   - ue-naming-conventions

package/profiles/visual-novel.yaml

@@ -20,6 +20,7 @@ skills:
   - asset-spec
   - playtest-report
   - balance-check
+  - architecture-review
 
 rules:
   universal:

package/rules/code-comments.md

@@ -0,0 +1,63 @@
+---
+paths:
+  - "**/*.cs"
+  - "**/*.ts"
+  - "**/*.tsx"
+  - "**/*.js"
+  - "**/*.jsx"
+  - "**/*.py"
+  - "**/*.go"
+  - "**/*.java"
+  - "**/*.kt"
+  - "**/*.swift"
+  - "**/*.rb"
+  - "**/*.rs"
+  - "**/*.php"
+  - "**/*.dart"
+  - "**/*.c"
+  - "**/*.cpp"
+  - "**/*.cc"
+  - "**/*.h"
+  - "**/*.hpp"
+  - "**/*.sh"
+  - "**/*.sql"
+  - "**/*.shader"
+  - "**/*.hlsl"
+  - "**/*.glsl"
+  - "**/*.gd"
+  - "**/*.lua"
+---
+
+# Code Comments Rule
+
+Comments are written in **English**, whatever language the conversation is in.
+
+## Never write
+
+- **Session narration.** No comment records what was decided, changed, tried or removed
+  while working. Not `// removed the old validation`, not `// now uses a dictionary instead
+  of a list`, not `// moved above the null check as discussed`, not `// changed from 30 to
+  50`. The commit message carries the story; the code carries the result.
+- **WHAT restated.** The code already says what it does. `// increment the counter` above
+  `counter++` is noise.
+- **Ticket, task or doc references.** No `// added for JIRA-123`, no `// part of sprint04`,
+  no `// implements the boss design doc`. Traceability lives in the commit and the PR, where
+  it stays accurate and searchable.
+- **Attribution or dates.** No `// author:`, no `// created 2026-09-04`. Git owns that and
+  never goes stale.
+- **Multi-paragraph docstrings on simple functions.**
+- **`// used by X`.** Tooling answers that better and this rots the first time X moves.
+
+## Write
+
+- **The WHY that the code cannot show.** A constant that looks arbitrary, an ordering that
+  matters, a deliberate break from the surrounding pattern.
+- **Workarounds**, with a link to the upstream bug.
+- **Non-obvious invariants or preconditions** a caller has to respect.
+- **Doc comments on public APIs** consumed from outside the module. Private ones need none.
+- **`TODO(@owner, YYYY-MM-DD): description`.** Never a bare `TODO`.
+
+## Shape
+
+One line, unless the reason honestly needs two. A comment that needs a paragraph to explain
+the code beneath it is a signal to fix the code instead.

package/rules/gamedev/audio-code.md

@@ -14,7 +14,6 @@ paths:
 - Voice budget is a hard limit: define max simultaneous voices per category and drop by priority, never let it grow unbounded
 - Audio must degrade silently — a missing bank or failed event NEVER throws into the gameplay frame
 - Keep the audio update off the render-critical path; audio work budget is 5-10% of frame time
-- Reference the audio bible section each event implements in code comments
 
 ## Examples
 

package/rules/gamedev/gameplay-code.md

@@ -11,7 +11,6 @@ paths:
 - Every gameplay system must implement a clear interface
 - State machines must have explicit transition tables with documented states
 - Write unit tests for all gameplay logic — separate logic from presentation
-- Document which design doc each feature implements in code comments
 - No static singletons for game state — use dependency injection
 
 ## Examples

package/rules/gamedev/shader-code.md

@@ -20,7 +20,6 @@ visual quality, performance, and cross-platform compatibility.
 - Group related parameters (Unity: `[Header]`, Unreal: Category)
 - Comment non-obvious calculations (especially math-heavy sections)
 - No magic numbers — use named constants or documented uniform values
-- Include authorship and purpose comment at the top of each shader file
 
 ## Performance Requirements
 - Document the target platform and complexity budget for each shader

package/skills/architecture-review/SKILL.md

@@ -5,6 +5,7 @@ category: "workflow"
 argument-hint: "[focus: full | coverage | consistency | engine | single-gdd path | rtm]"
 user-invocable: true
 allowed-tools: Read, Glob, Grep, Write, Task, AskUserQuestion
+context: fork
 agent: technical-director
 model: opus
 ---

package/skills/balance-check/SKILL.md

@@ -5,6 +5,7 @@ category: "gamedev"
 argument-hint: "[system-name|path-to-data-file]"
 user-invocable: true
 allowed-tools: Read, Glob, Grep
+context: fork
 agent: economy-designer
 ---
 

package/skills/code-review/SKILL.md

@@ -1,20 +1,34 @@
 ---
 name: code-review
-description: "Architectural and quality code review: standards compliance, SOLID principles, testability, performance."
+description: "Architectural and quality code review: standards compliance, SOLID principles, testability, performance. Usar para revisar un archivo o directorio antes de mergear, o cuando se pide code review."
 category: "workflow"
 argument-hint: "[path-to-file-or-directory]"
 user-invocable: true
 allowed-tools: Read, Glob, Grep, Bash, Task
-agent: lead-programmer
 ---
 
 ## Phase 1: Load Target Files
 
 Read target file(s) in full. Read CLAUDE.md for project coding standards.
 
-## Phase 2: Identify Engine Specialists
+## Phase 2: Resolve which specialists exist
 
-Read `.claude/docs/technical-preferences.md` → `## Engine Specialists`. Note Primary, Language/Code, Shader, UI specialists. If `[TO BE CONFIGURED]` → skip engine specialist steps.
+**Do not invent specialist names.** List what is actually installed:
+
+!`ls .claude/agents/*/ 2>/dev/null | sed 's/\.md$//' | tr '\n' ' ' || echo "NO-AGENTS-INSTALLED"`
+
+Rules:
+
+- Only spawn an agent whose file appeared in that listing. A `Task` call naming
+  an agent that is not installed does not fail loudly - it falls back to a
+  general-purpose agent with no specialised prompt, which reads broadly, burns
+  its turn budget, and returns a generic summary. That is worse than not
+  spawning at all.
+- If the listing is empty or `NO-AGENTS-INSTALLED`, **skip Phase 7 entirely**
+  and do the whole review inline. Say so in the report.
+- Match by role, not by guess: a reviewer for the stack under review
+  (`react-engineer`, `go-engineer`, `nestjs-engineer`, `unity-specialist`,
+  `unreal-specialist`…), plus `qa-engineer` for testability when installed.
 
 ## Phase 3: ADR Compliance Check
 
@@ -30,34 +44,53 @@ Per referenced ADR, read Decision + Consequences sections, classify deviations:
 
 ## Phase 4: Standards Compliance
 
-Identify system category (engine, gameplay, AI, networking, UI, tools). Check: doc comments on public methods, cyclomatic complexity <10/method, methods ≤40 lines, DI (no static singletons), config from data files, interfaces exposed.
+Identify system category from the code under review. Check: doc comments on public methods, cyclomatic complexity <10/method, methods ≤40 lines, DI (no static singletons), config from data files, interfaces exposed.
 
 ## Phase 5: Architecture and SOLID
 
 - **Architecture**: correct dependency direction, no circular deps, proper layer separation, events for cross-system communication, consistent patterns
 - **SOLID**: SRP, OCP, LSP, ISP, DIP — check each principle
 
-## Phase 6: Game-Specific Concerns
+## Phase 6: Runtime-loop concerns — only for game/realtime projects
+
+**Skip this phase unless the project actually has a frame loop.** Signal: a
+Unity, Unreal or Godot project file, or a render/tick loop in the code under
+review. On a backend or web project this phase produces noise, not findings.
 
-Frame-rate independence (delta time), no allocations in hot paths, null/empty handling, thread safety, resource cleanup.
+When it applies: frame-rate independence (delta time), no allocations in hot
+paths, null/empty handling, thread safety, resource cleanup.
 
 ## Phase 7: Specialist Reviews (Parallel)
 
-Spawn applicable specialists via Task simultaneously:
-- Primary language files → Language/Code Specialist
-- Shader files → Shader Specialist
-- UI code → UI Specialist
-- Cross-cutting → Primary Specialist
+Only if Phase 2 found installed agents. **At most 3 in parallel** — beyond that
+the wall-clock cost outweighs the extra coverage.
 
-### QA Testability Review
+| Trigger in the diff | Spawn (only if installed) |
+|---------------------|---------------------------|
+| Primary language of the changed files | the matching `*-engineer` / `*-specialist` |
+| Shader / material files | `unity-shader-specialist` or `technical-artist` |
+| UI / component code | `ui-lead` or `ue-umg-specialist` |
+| Test or testability questions | `qa-engineer` |
 
-For Logic/Integration stories, spawn `qa-tester` in parallel. Evaluate: test hooks exposed, QA test cases map to code paths, acceptance criteria testable, new edge cases covered, side effects tested. For Visual/UI stories: verify manual steps are reachable.
+Give each one the file list and the specific question. Do **not** ask an agent
+to "review this" — ask what you actually need decided.
+
+### Testability review
+
+When `qa-engineer` is installed, ask it: are test hooks exposed, do test cases
+map to code paths, are acceptance criteria testable, are new edge cases and
+side effects covered. For visual/UI changes: are the manual steps reachable.
 
 ## Phase 8: Output Review
 
-Report sections: Engine Specialist Findings, Testability, ADR Compliance, Standards Compliance (X/6), Architecture, SOLID, Game-Specific Concerns, Positive Observations, Required Changes (violations always here), Suggestions. Verdict: APPROVED / APPROVED WITH SUGGESTIONS / CHANGES REQUIRED.
+Report sections: Specialist Findings (name which agents ran, and say plainly if
+none were installed), Testability, ADR Compliance, Standards Compliance (X/6),
+Architecture, SOLID, Runtime-loop Concerns (omit if skipped), Positive
+Observations, Required Changes (violations always here), Suggestions.
+
+Verdict: APPROVED / APPROVED WITH SUGGESTIONS / CHANGES REQUIRED.
 
-This skill is read-only.
+This skill is read-only: it writes no files. The report is the deliverable.
 
 ## Phase 9: Next Steps
 

package/skills/create-epics/SKILL.md

@@ -5,7 +5,8 @@ category: "agile"
 argument-hint: "[system-name | layer: foundation|core|feature|presentation | all] [--review full|lean|solo]"
 user-invocable: true
 allowed-tools: Read, Glob, Grep, Write, Task, AskUserQuestion
-agent: technical-director
+context: fork
+agent: product-manager
 ---
 # Create Epics
 

package/skills/create-stories/SKILL.md

@@ -5,7 +5,8 @@ category: "agile"
 argument-hint: "[epic-slug | epic-path] [--review full|lean|solo]"
 user-invocable: true
 allowed-tools: Read, Glob, Grep, Write, Task, AskUserQuestion
-agent: lead-programmer
+context: fork
+agent: product-manager
 ---
 # Create Stories
 
@@ -41,7 +42,7 @@ For each GDD AC: group related criteria → each group = one story. Order: found
 
 ### 4b. QA Lead Gate (full mode only)
 
-Solo/lean → skip. Full → spawn `qa-lead` gate QL-STORY-READY with story list + ACs + types + TR-IDs. Revise until ADEQUATE. Then qa-lead produces test case specs per story:
+Solo/lean → skip. Full → spawn `qa-director` gate QL-STORY-READY with story list + ACs + types + TR-IDs. Revise until ADEQUATE. Then `qa-director` produces test case specs per story:
 
 - **Logic/Integration:** Given/When/Then + edge cases per AC
 - **Visual/UI:** Setup/Verify/Pass condition per AC
@@ -54,13 +55,13 @@ Show full story list (title, type, ADR, TR-IDs covered, test required) before wr
 
 ## 6. Write Story Files
 
-Each story file includes: header (epic, status, layer, type, manifest version), context (GDD path, TR-ID, ADR + decision summary, engine risk + notes, manifest rules), acceptance criteria (from GDD), implementation notes (from ADR), out of scope, QA test cases (from qa-lead), test evidence (required path by type + status), dependencies (depends on / unlocks).
+Each story file includes: header (epic, status, layer, type, manifest version), context (GDD path, TR-ID, ADR + decision summary, engine risk + notes, manifest rules), acceptance criteria (from GDD), implementation notes (from ADR), out of scope, QA test cases (from qa-director), test evidence (required path by type + status), dependencies (depends on / unlocks).
 
 Also update EPIC.md with populated stories table.
 
 ### 4b. Producer Epic Gate (full mode only)
 
-Solo/lean → skip. Full → spawn `producer` gate PR-EPIC before writing.
+Solo/lean → skip. Full → spawn `delivery-manager` gate PR-EPIC before writing.
 
 ## 7. After Writing
 

package/skills/database-indexing/SKILL.md

@@ -2,10 +2,11 @@
 name: database-indexing
 description: "PostgreSQL indexing: B-tree, GIN, GiST, composite, partial, covering, CONCURRENTLY, bloat detection."
 category: "database"
-stack: PostgreSQL 15+
 argument-hint: "[analyze|create|drop] [table]"
 user-invocable: true
 allowed-tools: Read, Glob, Grep, Bash, Write, Edit, Task
+metadata:
+  stack: PostgreSQL 15+
 ---
 # Database Indexing (PostgreSQL)
 

package/skills/help/SKILL.md

@@ -5,13 +5,17 @@ category: "workflow"
 argument-hint: "[optional: what you just finished, e.g. 'finished design-review' or 'stuck on ADRs']"
 user-invocable: true
 allowed-tools: Read, Glob, Grep
-context: |
-  !echo "=== Live Project State ===" && echo "Stage: $(cat production/stage.txt 2>/dev/null | tr -d '[:space:]' || echo 'not set')" && echo "Latest sprint: $(ls -t production/sprints/*.md 2>/dev/null | head -1 || echo 'none')" && echo "Session state: $(head -5 production/session-state/active.md 2>/dev/null || echo 'none')"
 model: haiku
 ---
 
 # Studio Help — What Do I Do Next?
 
+## Live Project State
+
+- Stage: !`cat production/stage.txt 2>/dev/null | tr -d '[:space:]' || echo 'not set'`
+- Latest sprint: !`ls -t production/sprints/*.md 2>/dev/null | head -1 || echo 'none'`
+- Session state: !`head -5 production/session-state/active.md 2>/dev/null || echo 'none'`
+
 Read-only skill — reports findings, writes no files. Lightweight orientation; for full gap analysis use `/project-stage-detect`.
 
 ## Step 1: Read Catalog + Find Uncataloged Skills