feat(f2): plugin subagents pos-code-reviewer + pos-architect

.claude/rules/skills-map.md

@@ -44,15 +44,15 @@ Canonical order pre-PR: **`simplify → pre-commit-review`**. Reduce primero, re
 | Skill | Lifecycle | Modelo | Context | Qué hace |
 |---|---|---|---|---|
 | `simplify` | Fase N+1 (pre-PR) | sonnet | main (writer-scoped) | Reduce redundancia / ruido / complejidad accidental / abstracción prematura en archivos ya presentes en `git diff --name-only main..HEAD`. **Writer-scoped strict**: edita vía `Edit` sólo archivos del diff; no crea archivos nuevos; no toca archivos fuera del diff; no cambia comportamiento; no busca bugs; no hace refactor mayor. Cierra con reporte "qué simplificó / what was simplified" + "qué decidió no tocar / what it chose not to touch". |
-| `pre-commit-review` | Fase N+2 (pre-PR) | sonnet | main + Agent-tool hybrid delegation (`code-reviewer`) | Main prepara context (branch kickoff + invariantes de `.claude/rules/*.md` aplicables al diff); delega vía `Agent(subagent_type="code-reviewer", ...)` con `git diff main..HEAD` completo + asks explícitos (bugs + logic + security + scope adherence + invariant violations); subagent corre en fork real y devuelve summary confidence-filtered; main folds (dedup + file:line + severity order + veredicto de una línea). Fallback a `general-purpose` si el runtime enum no expone `code-reviewer`. **Nunca edita, nunca abre PR, nunca sustituye a `simplify`**. |
+| `pre-commit-review` | Fase N+2 (pre-PR) | sonnet | main + Agent-tool hybrid delegation (`pos-code-reviewer` plugin agent post-F2) | Main prepara context (branch kickoff + invariantes de `.claude/rules/*.md` aplicables al diff); delega vía `Agent(subagent_type="pos-code-reviewer", ...)` con `git diff main...HEAD` completo + asks explícitos (bugs + logic + security + scope adherence + invariant violations); subagent corre en fork real y devuelve summary confidence-filtered; main folds (dedup + file:line + severity order + veredicto de una línea). Fallback a `general-purpose` si el runtime no expone agents del plugin. **Nunca edita, nunca abre PR, nunca sustituye a `simplify`**. |
 | `compress` | on-demand (contexto >120k) | sonnet | main | Read-only advisory planner: propone qué `.claude/logs/*.jsonl` comprimir (edad, tamaño, importancia). No edita ni elimina archivos; usuario decide. E2b advisory-only. |
 | `audit-plugin` | antes de instalar community tool (MCP/plugin) | sonnet | main | Read-only advisory gate: audita contra SAFETY_POLICY.md 6-checklist, retorna GO/NO-GO/NEEDS_MORE_INFO. No instala, no enforza, no modifica policy.yaml. E2b advisory-only; enforcement diferido. |
 
 ## Pattern + Test (entregado en E3)
 
 | Skill | Lifecycle | Modelo | Context | Qué hace |
 |---|---|---|---|---|
-| `compound` | post-merge (trigger by touched_paths, policy-driven) | opus | main (writer-scoped strict) | Lee merged diff; delega análisis a `code-architect` subagent (fallback `general-purpose`); escribe patrones a `.claude/patterns/` (formato canónico: `# Pattern:` + secciones `##`). No refactoring de código, solo propuestas de patrones. **STOP**: usuario revisa + aprueba merge de patrón. |
+| `compound` | post-merge (trigger by touched_paths, policy-driven) | opus | main (writer-scoped strict) | Lee merged diff; delega análisis a `pos-architect` plugin agent post-F2 (fallback `general-purpose`); escribe patrones a `.claude/patterns/` (formato canónico: `# Pattern:` + secciones `##`). No refactoring de código, solo propuestas de patrones. **STOP**: usuario revisa + aprueba merge de patrón. |
 | `pattern-audit` | Fase N+3 post-merge (manual invoke) | sonnet | main (main-strict, no delegation) | Lee entradas `.claude/patterns/`; busca signals en codebase (Grep/Bash); detecta drift (signal/examples/rule inconsistency). Emite reporte diagnóstico sin mutar archivos. **STOP**: usuario revisa y decide acción (actualizar patrón / invocar compound). |
 | `test-scaffold` | al crear archivo sin test pair | sonnet | main (writer-scoped strict) | Detecta convención de tests (co-located vs `tests/`) sobre el repo; si ≥80% claro → genera **solo** el test pair skeleton del archivo source que el usuario provee; si ambigua → STOP + propone opciones. **NO** modifica source code, **NO** ejecuta pytest/vitest, **NO** modifica thresholds/config. Allowed-tools: `Glob`, `Grep`, `Read`, `Write`, `Bash(find:*)`, `Bash(git grep:*)`, logger. |
 | `test-audit` | on-demand / pre-release | sonnet | main (main-strict, no delegation) | Read-only advisory: declara **candidate signals** (no "detecta") via static analysis sobre archivos test — flaky risk (asserts en loops/conditionals), orphan tests (imports a paths que no existen), trivial assertions (`assert True`/`False`/empty). **NO** ejecuta pytest/vitest, **NO** modifica archivos. Cierra con disclaim de no-exhaustividad. Allowed-tools: `Glob`, `Grep`, `Read`, `Bash(find:*)`, `Bash(git grep:*)`, `Bash(wc:*)`, logger. |
@@ -66,6 +66,26 @@ Canonical order pre-PR: **`simplify → pre-commit-review`**. Reduce primero, re
 | `/pos:pr-description` | pre-PR | sonnet | main | Genera descripción del PR desde commits + kickoff |
 | `/pos:release` | en tag | sonnet | main | Valida versión + publica + notifica |
 
+## Subagents del plugin (entregado en F2)
+
+Plugin-owned subagents en `agents/<slug>.md`. **Shape distinto al skill primitive**: frontmatter `{name, description, tools, model}`, donde `tools` es comma-separated string (oficial Claude Code subagent format), no YAML list `allowed-tools`. Sin campos inventados. Namespace `pos-*` obligatorio para evitar colisión con built-ins de Claude Code (`code-reviewer`, `code-architect`, `Plan`, `Explore`, `general-purpose`) y con user/project agents externos.
+
+| Agent | Consumido por | Modelo | Capacidad | Hard limits |
+|---|---|---|---|---|
+| `pos-code-reviewer` | `pre-commit-review` (E2a) | sonnet | Branch-diff review: bugs / logic errors / security vulnerabilities / scope adherence / invariant violations. Output findings agrupados por severidad (blocker/high/medium/nit), confidence-filtered, `file:line` refs. | No `Edit`, no `Write`, no PR, no invocación de otras skills/subagents. |
+| `pos-architect` | `compound` (E3a) | sonnet | Pattern extraction (≥2 repeticiones, regla #7) + architectural design + cross-file consistency. Output patterns en formato canónico (Name/Context/Signal/Rule/Examples/Rationale) listo para fold en `.claude/patterns/<slug>.md`. | No refactor, no `Edit`, no overwriting de patterns existentes. |
+
+**Contract tests** en `agents/tests/test_agent_frontmatter.py` parametrizados por `ALLOWED_AGENTS = ["pos-code-reviewer", "pos-architect"]`: 4 clases (structure, frontmatter keys ⊆ `{name, description, tools, model}` + namespace `pos-*` + tools comma-separated string + model ∈ `{sonnet, opus, haiku}`, body substantive >100 chars, capability surfaces).
+
+**Fallback `general-purpose`** explícito en bodies de skills consumidoras — protege contra runtimes que no exponen agents del plugin (Claude Code antes de discovery del directorio `agents/`, entornos minimal).
+
+**Diferidos en F2 (regla #7 CLAUDE.md)**:
+
+- `pos-auditor` — sin consumer real hoy. Reabrir cuando una skill futura lo requiera.
+- `policy.yaml.agents_allowed` — sin enforcement consumer (Stop hook lee `skills.jsonl`, no hay log de invocaciones de subagents). Reabrir cuando un hook futuro requiera enforcement.
+
+**Forward-compat negation**: main-strict skills (`pattern-audit` E3a, `audit-session` F1) **nunca** deben referenciar plugin subagents. Tests negation list incluye `pos-architect` / `pos-code-reviewer` desde F2.
+
 ## Disabled until earned
 
 Ninguna skill adicional se registra en `policy.yaml` hasta que pasa `/pos:audit-plugin --self`.

.claude/rules/skills.md

@@ -40,22 +40,26 @@ Ver [skills-map.md § Shape canónico](skills-map.md) para el shape autoritativo
 
 El primitive no soporta `context: fork` declarativamente. Si una skill requiere cross-file analysis pesado (≥3 archivos no triviales), **delegar inline vía Agent tool** desde el body de la SKILL.md es el patrón correcto.
 
-La skill debe escoger el `subagent_type` **por capacidad**, no por nombre hardcoded — los nombres concretos son defaults de Claude Code y pueden variar entre releases/entornos. Regla operativa: inspeccionar el enum `subagent_type` de la tool `Agent` en runtime y matchear por capacidad. Los nombres abajo reflejan los defaults de Claude Code hoy:
+La skill debe escoger el `subagent_type` **por capacidad**, no por nombre hardcoded — los nombres concretos pueden variar entre releases/entornos. Regla operativa: inspeccionar el enum `subagent_type` de la tool `Agent` en runtime y matchear por capacidad. Desde F2 los subagents críticos para review + arquitectura son **propiedad del plugin** (definidos en `agents/<slug>.md` con namespace obligatorio `pos-*`); el resto reusan defaults built-in de Claude Code:
 
-- **Planning independiente** (cross-check contra el plan de la skill) — Claude Code hoy: `Plan`.
-- **Segunda opinión arquitectónica** (crítica de diseño) — Claude Code hoy: `code-architect`.
-- **Context gathering cross-files** (explora y devuelve digest) — Claude Code hoy: `Explore`.
-- **Review de diff de rama** (confidence-filtered review) — Claude Code hoy: `code-reviewer`. **Primera consumidora: `pre-commit-review` (E2a)**. Patrón: main prepara context ligero (branch kickoff + invariantes de `.claude/rules/*.md` aplicables al diff); delega via `Agent(subagent_type="code-reviewer", ...)` con `git diff main..HEAD` completo + asks explícitos; subagent corre en fork real, devuelve summary confidence-filtered; main folds (dedup + file:line + severity). Hardcode del nombre `code-reviewer` en el body **con disclaimer** + fallback a `general-purpose` si el runtime enum no lo expone — decisión A5 de E2a: una sola consumidora hoy no justifica helper runtime (regla #7 CLAUDE.md). Reabrir si una segunda skill aporta la repetición.
-- **Fallback general** si ninguna capacidad específica encaja — Claude Code hoy: `general-purpose` con task prompt explícito.
+- **Planning independiente** (cross-check contra el plan de la skill) — Claude Code hoy: `Plan` (built-in).
+- **Segunda opinión arquitectónica genérica** (crítica de diseño no-pattern-extraction) — Claude Code hoy: `code-architect` (built-in). Para pattern extraction post-merge usar `pos-architect` (ver abajo).
+- **Context gathering cross-files** (explora y devuelve digest) — Claude Code hoy: `Explore` (built-in).
+- **Review de diff de rama** (confidence-filtered review) — **plugin agent: `pos-code-reviewer`** (entregado en F2; ver `agents/pos-code-reviewer.md`). **Primera consumidora: `pre-commit-review` (E2a)**. Patrón: main prepara context ligero (branch kickoff + invariantes de `.claude/rules/*.md` aplicables al diff); delega via `Agent(subagent_type="pos-code-reviewer", ...)` con `git diff main...HEAD` completo + asks explícitos; subagent corre en fork real, devuelve summary confidence-filtered; main folds (dedup + file:line + severity). Hardcode del nombre `pos-code-reviewer` en el body **con disclaimer** + fallback a `general-purpose` si el runtime no expone agents del plugin — decisión A5 de E2a (una sola consumidora hoy no justifica helper runtime, regla #7 CLAUDE.md) ratificada en F2 con namespace `pos-*` para evitar colisión con built-ins.
+- **Pattern extraction + cross-file design** (post-merge) — **plugin agent: `pos-architect`** (entregado en F2; ver `agents/pos-architect.md`). **Primera consumidora: `compound` (E3a)**. Patrón: main pasa diff merged + lista de patterns existentes; subagent identifica 1–3 patrones que repiten ≥2 veces y devuelve propuestas en formato canónico (Name/Context/Signal/Rule/Examples/Rationale); main folds en `.claude/patterns/<slug>.md`. Hardcode `pos-architect` con fallback `general-purpose`.
+- **Fallback general** si ninguna capacidad específica encaja o el runtime no expone el agent del plugin — Claude Code hoy: `general-purpose` con task prompt explícito.
 
 El subagent corre en fork real; la skill recibe el summary al tool result y lo folds en su output — no paste-through.
 
+**Plugin agent primitive (entregado en F2)**: `agents/<slug>.md` con frontmatter `{name, description, tools, model}`. **Shape distinto al skill primitive**: `tools` es comma-separated string (oficial Claude Code subagent format), no YAML list `allowed-tools`. Sin campos inventados. Namespace `pos-*` obligatorio. Contract tests en `agents/tests/test_agent_frontmatter.py` parametrizados por `ALLOWED_AGENTS`. No hay `agents_allowed` en `policy.yaml` hoy (sin enforcement consumer; el Stop hook lee `skills.jsonl`, no `agents.jsonl`).
+
 **Precedentes**:
 
-- `branch-plan` (E1b) delega cuando el plan es heavy (pick `Plan` / `code-architect` / `Explore` por capacidad).
+- `branch-plan` (E1b) delega cuando el plan es heavy (pick `Plan` / `code-architect` / `Explore` built-in por capacidad).
 - `deep-interview` (E1b) nunca delega — su coste está en el dialog, no en reading.
-- `pre-commit-review` (E2a) delega siempre a `code-reviewer` como hybrid pattern (main prepara context, subagent analiza, main folds) — primer uso del subagent `code-reviewer` en el repo.
-- `project-kickoff` y `writing-handoff` (E1a), `simplify` (E2a) son main-strict por scope acotado.
+- `pre-commit-review` (E2a) delega siempre a `pos-code-reviewer` como hybrid pattern (main prepara context, subagent analiza, main folds) — **primera consumidora del plugin agent post-F2** (antes de F2 apuntaba a `code-reviewer` built-in).
+- `compound` (E3a) delega a `pos-architect` post-merge para pattern extraction — **primera consumidora del plugin agent post-F2** (antes de F2 apuntaba a `code-architect` built-in).
+- `project-kickoff` y `writing-handoff` (E1a), `simplify` (E2a) son main-strict por scope acotado. `pattern-audit` (E3a) y `audit-session` (F1) son main-strict por design — **forward-compat negación**: nunca deben referenciar plugin subagents (negation list de tests incluye `pos-architect` / `pos-code-reviewer` desde F2).
 
 **Precedentes de writer-scope**: `writing-handoff` (E1a) escribe **sólo** en HANDOFF.md con scope por sección declarado en el body; `simplify` (E2a) es la **segunda** writer-scoped del repo — edita **sólo** archivos presentes en `git diff --name-only main..HEAD`, con scope check en cada `Edit` call y reclasificación a `skip (out of scope)` si el `file_path` no está en la lista derivada. Ambas cierran con reporte de qué cambiaron y qué decidieron no tocar.
 
@@ -66,7 +70,7 @@ El primitive no soporta `model:` en el frontmatter — la skill corre en el mode
 ## Tests
 
 - **Contract tests** del primitive en `.claude/skills/tests/test_skill_frontmatter.py` — parametrizados por `ALLOWED_SKILLS` (renombrado desde `E1_SKILLS_KNOWN` en E2a cuando la allowlist cruzó el límite de fase; contract-bound al `skills_allowed` del meta-repo, no era-bound: extender = añadir entrada aquí + en `policy.yaml`, no renombrar). Validan: dir + SKILL.md existe; NO `skill.json`; frontmatter keys ⊆ `{name, description, allowed-tools}`; `name` == dir name; description case-insensitive `startswith "use when"`; `allowed-tools` es `list[str]` si presente; `name` sin prefijo `pos:`; body referencia `.claude/skills/_shared/log-invocation.sh`; shared logger existe y es ejecutable.
-- **Behavior tests** del body — añadir una `TestXxxBehavior` class por skill cuando el framing del body sea parte del contrato. Existentes: `TestBranchPlanBehavior` + `TestDeepInterviewBehavior` (E1b — disclaim de marker, opt-in gating, no silent mutation); `TestPreCommitReviewBehavior` + `TestSimplifyBehavior` (E2a — delegation a `code-reviewer`, scope `git diff main..HEAD`, disclaim de escritura / reemplazo de `simplify`, writer-scoped-al-diff, reducer-not-bug-finder, reporte de qué simplificó + qué decidió no tocar).
+- **Behavior tests** del body — añadir una `TestXxxBehavior` class por skill cuando el framing del body sea parte del contrato. Existentes: `TestBranchPlanBehavior` + `TestDeepInterviewBehavior` (E1b — disclaim de marker, opt-in gating, no silent mutation); `TestPreCommitReviewBehavior` + `TestSimplifyBehavior` (E2a — delegation a `pos-code-reviewer` post-F2, scope `git diff main...HEAD`, disclaim de escritura / reemplazo de `simplify`, writer-scoped-al-diff, reducer-not-bug-finder, reporte de qué simplificó + qué decidió no tocar); `TestCompoundBehavior` (E3a, flippeada en F2 — delegation a `pos-architect` con fallback `general-purpose`); negation lists de `TestPatternAuditBehavior` (E3a) y `TestAuditSessionBehavior` (F1) extendidas con `pos-*` desde F2 (forward-compat: main-strict skills nunca referencian plugin subagents).
 - **Integration contract** logger ↔ Stop hook en `hooks/tests/test_skills_log_contract.py`. Añadir un caso `test_all_N_skills_end_to_end` (o renombrar el existente) cuando la allowlist crezca. Precedente: `test_all_four_e1_skills_end_to_end` (E1b) → `test_all_six_e1_e2a_skills_end_to_end` (E2a).
 
 ## Logging — best-effort via helper

.claude/skills/compound/SKILL.md

@@ -21,7 +21,7 @@ Extract and register reusable patterns when a merged branch exhibits extractable
 
 You MAY:
 - Read the merged diff (`main...HEAD`).
-- Delegate deep pattern analysis to `code-architect` subagent via Agent tool (hybrid pattern: main prepares context, subagent analyzes, main writes).
+- Delegate deep pattern analysis to `pos-architect` subagent via Agent tool (hybrid pattern: main prepares context, subagent analyzes, main writes).
 - Create `.claude/patterns/<name>.md` with pattern entries (write-only, strict scope).
 
 You MUST NOT:
@@ -67,11 +67,11 @@ Mandatory fields: Context, Signal, Rule, Examples. Last observed: timestamped by
    - List touched top-level dirs + file count.
    - Collect `.claude/patterns/*.md` existing entries (to avoid duplicates).
 
-3. **Delegate to `code-architect`** via Agent tool (with fallback):
+3. **Delegate to `pos-architect`** via Agent tool (with fallback):
    - Full diff: `git diff main...HEAD`.
    - Existing patterns (so subagent can avoid re-proposing).
    - Explicit task: "identify 1–3 patterns that repeat ≥2 times across the diff and would reduce future duplication. Output: pattern proposals (no code refactoring, no file changes)."
-   - Preferred subagent: `code-architect` (pattern extraction via architecture lens).
+   - Preferred subagent: `pos-architect` (pattern extraction via architecture lens).
    - Fallback if unavailable: `general-purpose` with same task (generic analysis acceptable).
    - Subagent returns a summary (not raw code).