claude-code-arcane 2.7.0 → 2.8.0

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 **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.
 
 ## 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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "claude-code-arcane",
-  "version": "2.7.0",
+  "version": "2.8.0",
   "description": "Skills, agents, hooks and rules for Claude Code — installable via npx claude-code-arcane",
   "type": "module",
   "bin": {

package/profiles/backend-go.yaml

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

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

package/skills/hotfix/SKILL.md

@@ -19,7 +19,7 @@ allowed-tools: Read, Glob, Grep, Write, Edit, Bash, Task
 
 ## Phase 2: Create Hotfix Record
 
-Draft record with: short description, date, severity, reporter, status IN PROGRESS, sections for Problem (player impact), Root Cause (fill during investigation), Fix (fill during implementation), Testing, Approvals (lead-programmer, qa-tester, producer checkboxes), Rollback Plan.
+Draft record with: short description, date, severity, reporter, status IN PROGRESS, sections for Problem (player impact), Root Cause (fill during investigation), Fix (fill during implementation), Testing, Approvals (qa-engineer, qa-director, delivery-manager checkboxes), Rollback Plan.
 
 Ask to write to `production/hotfixes/hotfix-[date]-[short-name].md`.
 
@@ -33,11 +33,19 @@ Minimal change only — NO refactoring, cleanup, or features alongside. Run targ
 
 ## Phase 5: Collect Approvals (Parallel)
 
-Spawn via Task: `lead-programmer` (correctness/side effects), `qa-tester` (regression tests), `producer` (deploy timing/comms). All three must APPROVE before proceeding.
+Spawn via Task, **only the ones installed in `.claude/agents/`** (check first: an uninstalled name falls back to a general-purpose agent that reads broadly and returns nothing useful):
+
+| Agent | Question to ask it |
+|-------|--------------------|
+| `qa-engineer` | correctness and side effects of the fix |
+| `qa-director` | regression scope: what else must be re-tested |
+| `delivery-manager` | deploy timing and comms |
+
+Every agent that ran must APPROVE before proceeding. If none is installed, do the three checks inline and record that in the hotfix record instead of claiming approvals that never happened.
 
 ## Phase 5b: QA Re-Entry Gate
 
-Spawn `qa-lead` with hotfix description, affected system, regression results, caller list (grep).
+Spawn `qa-director` (or `qa-engineer` if that is what is installed) with hotfix description, affected system, regression results, caller list (grep).
 
 | QA Verdict | Action |
 |------------|--------|

package/skills/patch-notes/SKILL.md

@@ -6,7 +6,8 @@ argument-hint: "[version] [--style brief|detailed|full]"
 user-invocable: true
 allowed-tools: Read, Glob, Grep, Write, Bash
 model: haiku
-agent: community-manager
+context: fork
+agent: release-manager
 ---
 
 ## Phase 1: Parse Arguments

package/skills/perf-profile/SKILL.md

@@ -4,7 +4,6 @@ description: "Performance profiling workflow: identify bottlenecks, measure agai
 category: "testing"
 argument-hint: "[system-name or 'full']"
 user-invocable: true
-agent: performance-analyst
 allowed-tools: Read, Glob, Grep, Bash
 ---
 

package/skills/prototype/SKILL.md

@@ -5,8 +5,6 @@ category: "design"
 argument-hint: "[concept-description] [--review full|lean|solo]"
 user-invocable: true
 allowed-tools: Read, Glob, Grep, Write, Edit, Bash, Task
-agent: prototyper
-isolation: worktree
 ---
 
 ## Phase 1: Define the Question

package/skills/qa-plan/SKILL.md

@@ -5,7 +5,8 @@ category: "testing"
 argument-hint: "[sprint | feature: system-name | story: path]"
 user-invocable: true
 allowed-tools: Read, Glob, Grep, Write, AskUserQuestion
-agent: qa-lead
+context: fork
+agent: qa-director
 ---
 
 # QA Plan

package/skills/retrospective/SKILL.md

@@ -5,9 +5,11 @@ category: "agile"
 argument-hint: "[sprint-N|milestone-name]"
 user-invocable: true
 allowed-tools: Read, Glob, Grep, Write
-context: |
-  !git log --oneline --since="2 weeks ago" 2>/dev/null
 ---
+## Commits de las ultimas 2 semanas
+
+!`git log --oneline --since="2 weeks ago" 2>/dev/null || echo "sin commits"`
+
 ## Phase 1: Parse & Check Existing
 
 Determine scope: sprint (`sprint-N`) or milestone. Check for existing retro (`production/retrospectives/retro-[slug]-*.md` or `production/sprints/sprint-[N]-retrospective.md`). If found → offer update existing or start fresh.

package/skills/security-audit/SKILL.md

@@ -5,7 +5,8 @@ category: "security"
 argument-hint: "[full | network | save | input | quick]"
 user-invocable: true
 allowed-tools: Read, Glob, Grep, Bash, Write, Task
-agent: security-engineer
+context: fork
+agent: security-architect
 ---
 
 # Security Audit

package/skills/skill-auditor/SKILL.md

@@ -38,7 +38,19 @@ Parse the YAML block between `---` markers. Check against our spec (see `referen
 | `user-invocable` | yes | present, boolean |
 | `allowed-tools` | yes | present, comma-separated list of valid tool names |
 
-Flag **alirezarezvani format** if frontmatter contains `license`, `metadata`, `version`, `author`, or `updated` fields -- these need conversion.
+Flag **legacy imported format** if frontmatter contains `version`, `author`, `updated`, `python-tools`, or `tech-stack` -- these need conversion.
+
+Do NOT flag `license` or `metadata`: both are official Claude Code fields. `metadata` is a free-form map that Claude Code deliberately ignores, and it is the correct home for repo-local keys.
+
+Also check the `agent:` / `context:` pair:
+
+| Check | Fail condition |
+|-------|----------------|
+| `agent:` needs `context: fork` | `agent:` present without `context: fork` -- the field is inert |
+| `context:` value | any value other than `fork` |
+| `agent:` target exists | the named agent has no file in `agents/` |
+| `agent:` reachable | a profile shipping this skill does not install the agent's division |
+| unknown field | any key outside the official list plus `category` |
 
 ### 1.2 Measure weight
 
@@ -77,7 +89,7 @@ Compute grade from checks:
 | **A** | All 5 frontmatter fields correct, <= 200 lines, 2+ sections, no hallucinations |
 | **B** | Frontmatter complete but minor issues (description too long, missing handoff) |
 | **C** | Frontmatter incomplete (1-2 missing fields) OR 201-400 lines |
-| **D** | Frontmatter uses alirezarezvani format OR 400+ lines OR hallucinations found |
+| **D** | Frontmatter uses legacy imported format OR `agent:` without `context: fork` OR 400+ lines OR hallucinations found |
 | **F** | No frontmatter at all OR file is empty/broken |
 
 ### 1.6 Output report
@@ -92,10 +104,10 @@ Given a path to a SKILL.md, apply fixes in order:
 
 ### 2.1 Convert frontmatter
 
-If alirezarezvani format detected (has `license`, `metadata`, `version`, `author`):
+If legacy imported format detected (has `version`, `author`, `updated`, `python-tools`, `tech-stack`):
 
 1. Keep `name` and `description` (trim description to under 200 chars if needed)
-2. Drop `license`, `metadata` block, `version`, `author`, `updated`, `python-tools`, `tech-stack`
+2. Drop `version`, `author`, `updated`, `python-tools`, `tech-stack`. Keep `license` and `metadata` -- both are official. Move any repo-local key into the `metadata:` map instead of deleting it.
 3. Add `category` -- infer from parent folder: `skills-backend` -> `"backend"`, `skills-ai` -> `"ai"`, etc.
 4. Add `user-invocable: true` (default; set `false` only for sub-skills under another skill's directory)
 5. Add `allowed-tools: Read, Glob, Grep, Bash` (default read-only set; upgrade to include `Write, Edit` if skill body contains authoring/generation instructions)