@tacuchi/agent-workflow-cli 6.1.0 → 7.0.0

package/skills/agent-workflow/commands/agent-workflow-project-init.md

@@ -0,0 +1,60 @@
+---
+description: Inicializa el bloque AW-PROJECT en CLAUDE.md y AGENTS.md del proyecto con las 4 secciones gestionadas (Proyecto, Fuentes, Stack, Status). Para workspaces multi-repo usar `/agent-workflow:hub-init`.
+argument-hint: (opcional) --proyecto "descripción" | --fuente alias:path[:rama] | --main-branch <rama>
+allowed-tools:
+  [
+    "Read",
+    "Write",
+    "Bash",
+    "AskUserQuestion",
+  ]
+---
+
+# Project Init (agent-workflow)
+
+Inicializa o reinicia el bloque `<!-- AW-PROJECT-START -->` en `CLAUDE.md` y `AGENTS.md` del directorio actual. Ese bloque es la memoria permanente del proyecto: quién es, qué repos tiene, qué stack, qué sesiones hay activas.
+
+**Se ejecuta una vez por proyecto.** Después, `/agent-workflow:session` (en sus variantes: crear, retomar, cerrar) actualiza el bloque automáticamente vía `agent-workflow project-md-upsert`.
+
+> Este comando vive en agent-workflow (Fase B; antes en qtc-core v2.5+, previamente en qtc-dev). Es agnóstico al flow — no requiere tener qtc-dev instalado. Para workspaces que coordinan **múltiples repos** (≥2 fuentes), usar `/agent-workflow:hub-init` que valida cross-fuente y persiste el marcador `Mode: hub`.
+
+## Flujo
+
+1. Ejecutar `agent-workflow project-md-upsert --read` (lee con cache si está disponible).
+2. Si ya existe un bloque AW-PROJECT válido, mostrarlo al usuario y preguntar si quiere **reiniciarlo** (sobreescritura) o **abortar**.
+3. Si no existe:
+   - Pedir al usuario la descripción del proyecto (qué es + por qué existe) con `AskUserQuestion` o campo libre.
+   - Preguntar por la fuente afectada: `alias`, `path` local al repo. La rama principal default es `certificacion` (constante interna del CLI) salvo override con `--main-branch`.
+   - Si el usuario declara ≥2 fuentes en este flujo → sugerir cambiar a `/agent-workflow:hub-init` que está pensado para hub workspaces y captura ramas de trabajo cross-fuente.
+   - Auto-detectar el stack con `agent-workflow stack` — mostrarlo al usuario y confirmar antes de escribirlo.
+   - Invocar:
+     ```
+     agent-workflow project-md-upsert --init \
+         --mode project \
+         --proyecto "<descripción>" \
+         --fuente "alias:path"
+     ```
+4. Si existe bloque `<!-- QTC-WORKFLOW-START -->` legacy en los mismos archivos, avisar al usuario y recomendar ejecutar `/agent-workflow:migrate --upgrade-topology` antes de continuar. No borrar el legacy automáticamente.
+
+## Qué NO hace
+
+- No crea `.workflow/sessions/`. Eso es responsabilidad de `/agent-workflow:session <descripción>`.
+- No escribe en repos fuera del CWD — sólo en `CLAUDE.md` y `AGENTS.md` del directorio actual.
+- No ejecuta `git` ni valida ramas — eso lo hace `/agent-workflow:session` al crear/retomar.
+- No persiste `Mode: hub` (eso lo hace `/agent-workflow:hub-init`).
+
+## Argumentos
+
+Sin argumentos: flujo interactivo (pregunta todo).
+
+Con argumentos: no-interactivo cuando se pasan todos los datos.
+
+- `--proyecto "<texto>"` — descripción del proyecto.
+- `--fuente "alias:path[:rama]"` — declarar la fuente. Repetible (pero ≥2 sugiere `/hub-init`).
+- `--main-branch <rama>` — override del default `certificacion` (raro).
+
+**Argumentos:** $ARGUMENTS
+
+## Skill asociada
+
+Ver `skills/project-init/SKILL.md` para el detalle del flujo, validaciones y manejo de bloques pre-existentes.

package/skills/agent-workflow/commands/agent-workflow-resume.md

@@ -0,0 +1,22 @@
+---
+description: Lee CHECKPOINT.md de la sesión activa y presenta resumen para retomar el trabajo. Fallback a session-resume base si no hay checkpoint.
+argument-hint: (sin args)
+allowed-tools:
+  [
+    "Bash",
+    "Read",
+  ]
+---
+
+# Resume — agent-workflow
+
+Invoca el skill `resume` (canónico de agent-workflow).
+
+## Acción
+
+1. Detectar sesión(es) activa(s) via `resume-summary`.
+2. Leer CHECKPOINT.md si existe; fallback a `session-resume`.
+3. Presentar resumen estructurado al usuario.
+4. Preguntar si continúa.
+
+Ver `skills/resume/SKILL.md` para detalles.

package/skills/agent-workflow/commands/agent-workflow-rules.md

@@ -0,0 +1,40 @@
+---
+description: Bundle invokable de reglas transversales agent-workflow-* — carga los 7 anchors canónicos (commits, sandbox plan-mode, MCP read-only, redacción, coding-standards, graduación, branch verification) en un solo entry point. No requiere sesión activa.
+argument-hint: (sin args)
+allowed-tools:
+  [
+    "Read",
+  ]
+---
+
+# Rules — Reglas transversales agent-workflow-*
+
+Invoca el skill `rules` (canónico de agent-workflow).
+
+## Cuándo correrlo
+
+- Antes de un commit ad-hoc fuera de `/agent-workflow:session close` (para refrescar política).
+- Antes de editar código en una fuente agent-workflow-* sin sesión activa.
+- Antes de ejecutar una query vía MCP `<mcp-cert>`/`<mcp-prod>` (read-only canon).
+- Durante onboarding de un usuario nuevo a agent-workflow-*.
+- En conversaciones largas donde el contexto qtc se diluyó.
+
+## Qué carga
+
+Los 7 anchors canónicos del runtime agent-workflow-*:
+
+1. `agent-workflow:commits-policy` — formato y prohibiciones de commits.
+2. `agent-workflow:sandbox-readonly` — comportamiento en plan mode.
+3. `agent-workflow:mcp-readonly` — política SELECT-only para MCP.
+4. `agent-workflow:redaccion-simple` — estilo transversal para prosa agent-workflow-*.
+5. `agent-workflow:coding-standards` — estándares por stack + FE-BE R1-R6 + seguridad.
+6. `agent-workflow:graduacion-routing` — 6 kinds graduables + routing hub vs project.
+7. `agent-workflow:branch-verification` — gate de rama por fuente + hard gate cross-fuente.
+
+## Plan mode
+
+Read-only. Skill imprime el bundle sin ejecutar nada.
+
+## Recursos
+
+Ver `skills/rules/SKILL.md` para el contenido extendido de cada anchor.

package/skills/agent-workflow/commands/agent-workflow-session.md

@@ -0,0 +1,35 @@
+---
+description: Lifecycle universal de sesiones agent-workflow-* (4 fases: planning → execution → validation → closure). Crea, retoma, lista o cierra sesiones componiendo skills de especialidad según el OBJECTIVE.
+argument-hint: (sin args | <slug-objetivo> | sessionXXX | XXX | list | close)
+allowed-tools:
+  [
+    "Bash",
+    "Read",
+    "Write",
+    "Edit",
+    "Glob",
+    "Grep",
+  ]
+---
+
+# Session — Lifecycle universal agent-workflow-*
+
+Invoca el skill `session` (canónico de agent-workflow) con `$ARGUMENTS`.
+
+## Resolución de intención
+
+El skill evalúa `$ARGUMENTS` en orden:
+
+1. `close` → flujo de cierre.
+2. `list` → flujo de listado.
+3. Matchea `sessionXXX` o `XXX` (3 dígitos) → flujo de retomar.
+4. Texto descriptivo → flujo de crear (con prompts adicionales para slug + ramas).
+5. Sin args → escanear estado y proponer.
+
+## Plan mode
+
+Skill resuelve la intención normalmente y describe acciones en el plan file en lugar de ejecutarlas.
+
+## Recursos
+
+Ver `skills/session/SKILL.md` para el árbol de decisión completo y los recursos de referencia.

package/skills/agent-workflow/doctrine/README.md

@@ -0,0 +1,15 @@
+# doctrine/
+
+Reglas universales del lifecycle que aplican siempre, agnóstico de empresa.
+
+Contenido esperado (T2 PR2):
+
+- `commits-policy.md` — propose-then-execute, M1, sin firmas auto, ≤72 chars.
+- `branch-verification.md` — gate de rama por fuente (casos A/B/C).
+- `redaccion-simple.md` — estilo de prosa para artefactos.
+- `sandbox-readonly-rules.md` — plan mode = sin mutaciones.
+- `mcp-readonly.md` — MCP SELECT/EXPLAIN sí, DDL/DML no.
+- `graduacion-routing.md` — defaults por kind + hub vs fuente.
+- `prompts-catalog.md` — M1/M10/S2/S3/S6/S7 prompts canónicos.
+
+Refs cruzadas (`[[name]]`) entre archivos permitidas. Léxico empresa-específico se inyecta vía `profile.lexicon_path`.

package/skills/agent-workflow/doctrine/compact/SKILL.md

@@ -0,0 +1,145 @@
+---
+name: compact
+description: Persiste estado de la sesión activa en CHECKPOINT.md y dispara /compact host. Invocado vía /agent-workflow:compact, NL como compactá/guardá estado/checkpoint, automáticamente desde el SessionEnd hook al cerrar el cliente, o como último paso del cierre de sesión.
+version: 2.4.0
+---
+
+# Compact — qtc v2.2
+
+Persiste el estado de la sesión activa antes de un compact del contexto. Combina:
+
+1. **Auto-extracción** (CLI `agent-workflow checkpoint-write`): phase, TASKS counts, decisiones recientes, archivos tocados, branches.
+2. **Síntesis del AI**: "Last action", "Next step", "Critical context to resume" (legacy ES: "Lo último que hice", "Próximo paso", "Contexto crítico para retomar").
+3. **Hand-off al host**: `/compact` nativo de Claude Code/Codex.
+
+El resultado: `.workflow/sessions/<folder>/CHECKPOINT.md` escrito + contexto liberado.
+
+## Dos caminos al compact
+
+Hay dos formas de compactar contexto en CC/Codex y producen calidad de síntesis distinta:
+
+| Camino | Cuándo usar | Síntesis | Calidad |
+|---|---|---|---|
+| `/agent-workflow:compact` (skill) | Antes de un compact planeado, cuando querés cierre limpio. | **Pre-compact con contexto vivo**: el AI rellena placeholders mirando la conversación entera + diffs + decisiones. | Alta — el AI tiene todo. |
+| `/compact` directo (host) | Compact ad-hoc o automático por umbral de contexto. | **Post-compact con `resume-summary`**: el AI rellena placeholders después del compact, leyendo el JSON del hook + CHECKPOINT.md draft + TASKS.md + DECISIONS.md de disco. | Reducida — el AI ya no ve la conversación previa, solo lo que quedó persistido en disco. |
+
+**Regla**: si para algún placeholder en el camino post-compact no tenés info suficiente, escribí `_(sin info — completar al retomar)_` en lugar de inventar. El usuario completa al hacer `/agent-workflow:resume` si necesita.
+
+El camino post-compact lo coordinan los hooks `PreCompact` y `PostCompact` del plugin (ver `hooks/hooks.json`). Importante: por bug del host ([anthropics/claude-code#13572](https://github.com/anthropics/claude-code/issues/13572)) el `PreCompact` puede no disparar en `/compact` manual. El `PostCompact` mitiga este caso: si `checkpoint_status == "missing"` el AI regenera el draft via `checkpoint-write` y luego rellena.
+
+## Triggers
+
+- **Slash explícito**: `/agent-workflow:compact`.
+- **NL del usuario**: "compactá", "guardá estado", "checkpoint", "vamos a compactar".
+- **Automático en SessionEnd hook**: al cerrar Claude Code/Codex, el hook escribe CHECKPOINT.md (no dispara `/compact` host porque la sesión ya termina).
+- **Automático en cierre de qtc-session**: el último paso de la skill `session` (closure) invoca `compact`.
+- **AI auto-trigger por contexto >75%**: cuando el AI estima carga de contexto >75% del modelo activo (heurística manual, no medición exacta), disparar `AskUserQuestion` con spec de M11 (`../session/references/prompts-catalog.md#M11`). Header `context`, 3 opciones (Compact ahora / Seguir, compact después / Cerrar sesión). Si elige "Compact ahora" → continuar con los pasos 1-5 abajo. Si elige otra → respetar la elección y dejar nota informal en CHECKPOINT.md cuando corresponda. **Si la sesión está en `closure`**: skip M11 (closure ya dispara compact opcional). NO narrar la pregunta en texto plano.
+
+## Acción
+
+### 1. Detectar sesión activa
+
+```
+agent-workflow project-md-upsert --read
+```
+
+Si no hay activa → mensaje "no hay sesión activa para checkpointar" y stop.
+
+Si hay UNA → continuar.
+
+Si hay VARIAS → preguntar al usuario cuál (o hacer una por una).
+
+### 2. Escribir draft auto-extraído
+
+```
+agent-workflow checkpoint-write --code <CODE> --force
+```
+
+`--force` asegura draft fresco aunque exista un CHECKPOINT.md sintetizado previo (su síntesis estaría desactualizada respecto al estado actual de la sesión).
+
+Esto crea `.workflow/sessions/<folder>/CHECKPOINT.md` con:
+
+- Header con timestamp, fase, avance %.
+- Decisión más reciente (si hay).
+- Archivos tocados (git diff vs HEAD).
+- Refs (origen, ramas, artefactos presentes).
+
+Y deja **placeholders** `_[AI: …]_` en los campos que requieren juicio:
+
+- "Last action"
+- "Next step"
+- "Critical context to resume"
+- Propósito de cada archivo tocado
+- Skills usadas en la sesión
+
+### 3. Completar los placeholders
+
+El AI lee el CHECKPOINT.md draft y reemplaza CADA placeholder con texto sintetizado de la conversación reciente:
+
+- **Last action** (legacy ES: "Lo último que hice"): 1-3 oraciones del último avance concreto. Mirá los últimos diffs aplicados, la última entrada de DECISIONS.md.
+- **Next step** (legacy ES: "Próximo paso"): 1-2 oraciones de qué falta. Mirá el primer item abierto de TASKS.md y cualquier blocker mencionado.
+- **Critical context to resume** (legacy ES: "Contexto crítico para retomar"): 2-3 párrafos con info mínima para continuar sin re-explorar. Qué descubriste, qué decisiones tomadas, qué tener presente.
+- **Propósito de archivos**: 1 línea por archivo tocado.
+- **Skills usadas**: lista de skills invocadas durante la sesión (implement, coding-standards, sql-script-organizer, etc.).
+
+Editá el archivo con `Edit` tool — preservá la estructura, sólo cambiá el placeholder por el contenido real.
+
+### 4. Disparar /compact host
+
+Tras editar el CHECKPOINT.md:
+
+> Decir al usuario: "Estado guardado en `.workflow/sessions/<folder>/CHECKPOINT.md`. Ahora corro `/compact` para liberar contexto."
+
+Y ejecutar `/compact` (comando nativo).
+
+Si el trigger fue **SessionEnd hook**, **NO disparar /compact** — la sesión ya termina; sólo escribir y salir.
+
+### 5. Resumir al usuario
+
+1-2 líneas. Path del CHECKPOINT, fase actual, próximo paso. Útil si está por cerrar la PC.
+
+## Ejemplo de invocación
+
+Usuario: "compactá"
+
+AI:
+1. Detecta `session046-dev-jobs-async` activa.
+2. Corre `agent-workflow checkpoint-write --code 046`. Output:
+   ```json
+   {
+     "session": "session046-dev-jobs-async",
+     "checkpoint_path": ".workflow/sessions/session046-dev-jobs-async/CHECKPOINT.md",
+     "phase": "execution",
+     "progress_pct": 60,
+     "tasks_open": 2,
+     "tasks_closed": 3,
+     "files_touched_count": 4
+   }
+   ```
+3. Lee el CHECKPOINT.md draft, edita los placeholders con síntesis.
+4. Confirma al usuario: "Estado guardado. Disparo `/compact`."
+5. Corre `/compact`.
+
+## Política — sin fallback al CLI
+
+Si `agent-workflow checkpoint-write` o `agent-workflow project-md-upsert` falla (no está en PATH, comando no reconocido, exit code != 0), **cortá la acción y reportá al usuario**: pedile que verifique `npm install -g @tacuchi/agent-workflow-cli`. No hay flujo alternativo Python.
+
+## Sandbox read-only
+
+Reglas universales en `../session/references/sandbox-readonly-rules.md` (canon agent-workflow).
+
+En plan mode esta skill **no ejecuta** `agent-workflow checkpoint-write`, ni `Edit` sobre CHECKPOINT.md, ni `/compact`. Describe en el plan file:
+
+- `.workflow/sessions/<folder>/CHECKPOINT.md` — crearía/sobrescribiría con formato §17 shared-contract. Resumir: timestamp, fase, avance %, lo último (sintetizado por AI), próximo paso, contexto crítico, refs.
+- Síntesis del AI a aplicar a placeholders: enumerar campos (`Last action`, `Next step`, `Critical context to resume`, propósito de archivos tocados, skills usadas).
+- Confirmación de que se dispararía `/compact` host (o NO si el trigger es SessionEnd hook).
+
+No invocar el sub-comando `checkpoint-write` ni siquiera con `--dry-run` salvo que el comando expusiera ese flag explícitamente — hoy no lo expone, así que abstenerse.
+
+## Recursos
+
+- `agent-workflow checkpoint-{read,write}` — comandos CLI que leen/escriben el CHECKPOINT.md.
+- shared-contract.md §17 — formato canónico de CHECKPOINT.md.
+- shared-contract.md §18 — close-triggers-compact convention.
+- **`agent-workflow:redaccion-simple`** — guía de redacción para los placeholders `_[AI: ...]_` de CHECKPOINT.md. Aplicar al rellenar (frases cortas, sin párrafos, sin relleno).
+- **`../session/references/commits-policy.md`** — el `compact` **no commitea** CHECKPOINT.md por iniciativa propia; el commit (si aplica) lo dispara el closure de `session` o el usuario explícitamente.

package/skills/agent-workflow/doctrine/doctor/SKILL.md

@@ -0,0 +1,86 @@
+---
+name: doctor
+description: "Health check read-only de la familia qtc-*. Orquesta `agent-workflow plugin-doctor` por fuente declarada en `agent-workflow sources` (hub mode) o sobre el cwd (single-repo). Default scope = all en hub, cwd en single-repo. Reporta versión del manifest, integridad de hooks, presencia de SKILL.md con frontmatter completo, runtime.json instalado y MCP config si aplica. Sin acciones ni mutaciones — sólo diagnóstico."
+version: 1.0.0
+---
+
+> **Profile parametrization**: lee `mcp_databases[]` de `profile.json` (resuelto vía cascade 5 capas). Ver [`references/profile-parametrization.md`](../../references/profile-parametrization.md) para el contrato completo y comportamiento por defecto cuando el profile está vacío.
+
+# Doctor — qtc-* health check (orquestador)
+
+Skill canónica del comando `/agent-workflow:doctor`. Orquesta diagnósticos read-only sobre los plugins qtc-* declarados en el workspace. El trabajo pesado lo hace el CLI runtime (`@tacuchi/agent-workflow-cli`); esta skill resuelve el scope, llama al CLI por plugin y agrega los resultados.
+
+## Cuándo se invoca
+
+- Comando `/agent-workflow:doctor` (tanto Claude Code como Codex).
+- NL: "¿está sano el plugin?", "diagnóstico de qtc", "doctor de plugins", "health check del hub".
+- Pre-release: antes de publicar el plugin se chequea con `--scope <plugin>`.
+
+## Scope resolution
+
+1. Leer args:
+   - `--scope <alias|all>` explícito.
+   - `--plugin-root PATH` directo (single-repo o testing).
+2. Si no hay args: `agent-workflow workspace-mode`. Si retorna `hub` → `--scope all`. Si `project` → `--plugin-root <cwd>`.
+3. `--scope all` (hub): `agent-workflow sources` → filtrar fuentes con manifest `.claude-plugin/plugin.json` o `.codex-plugin/plugin.json` y aplicar `plugin-doctor` a cada path.
+
+## Ejecución por plugin
+
+```
+agent-workflow plugin-doctor --plugin-root <path>
+```
+
+Output esperado (por plugin):
+
+- `status` ∈ `ok` | `warn` | `error`.
+- `plugin_version` desde el manifest.
+- `manifests` = comparación claude vs codex (versiones coincidentes).
+- `hooks` = parseo de `hooks/hooks.json` y `codex-hooks/hooks.json`.
+- `skills` = barrer `skills/*/SKILL.md`, validar frontmatter (`name`, `description`, `version` semver) y matching `name == dirname`.
+- `runtime` = presencia de `~/.workflow/agent-workflow/runtime.json` (agent-workflow only).
+- `mcp_config` = `.mcp.json` si aplica.
+- `errors[]` y `warnings[]`.
+
+## Salida
+
+### Tabla compacta (scope=all)
+
+```
+plugin                       version    status   findings
+──────────────────────────   ────────   ──────   ────────
+agent-workflow          2.2.2      ok       —
+otro-plugin                  1.0.0      warn     SKILL.md sin version
+```
+
+Resumen final: `<N>/M plugins ok` o lista de findings.
+
+### Detallado (scope=<alias> o --plugin-root)
+
+Mostrar el JSON completo de `plugin-doctor` + interpretación humana.
+
+## Accionables típicos
+
+- `agent-workflow CLI not found in PATH` → `npm install -g @tacuchi/agent-workflow-cli`.
+- `manifest version mismatch claude vs codex` → editar y bumpear coordinado.
+- `runtime.json missing` → reload del cliente (SessionStart hook lo escribe).
+- `SKILL.md sin frontmatter completo` → ver `agent-workflow:redaccion-simple` para canon.
+
+## Sandbox read-only
+
+Canon universal en `../session/references/sandbox-readonly-rules.md`. Read-only por construcción — el subcomando CLI `agent-workflow plugin-doctor` sólo consulta estado (versiones, namespaces, paths, fuentes registradas) sin mutar plugins ni fuentes.
+
+En plan mode: describir en el plan file los checks que correrían (per-fuente, scope `all`/`hub`/`single-repo`) sin invocar el CLI. NO ejecuta `Write`, `Edit`, ni comandos que muten estado de plugins/fuentes/workspace.
+
+Compatible con plan mode sin restricciones adicionales.
+
+## Composición
+
+| Skill | Cuándo |
+|---|---|
+| `agent-workflow` (CLI skill) | Ejecuta el `plugin-doctor` por fuente. |
+| `agent-workflow:hub-init` / `agent-workflow:project-init` | Si `workspace-mode` no detecta el bloque AW-PROJECT. |
+
+## Referencias
+
+- `commands/doctor.md` — entry point del slash command (Claude Code y Codex).
+- `agent-workflow plugin-doctor --help` — flags disponibles del CLI runtime.

package/skills/agent-workflow/doctrine/hub-init/SKILL.md

@@ -0,0 +1,157 @@
+---
+name: hub-init
+description: Inicializa workspace Hub multi-repo con bloque AW-PROJECT en modo hub. Captura ≥2 fuentes con rutas y ramas de trabajo, valida cross-fuente y persiste marcador Mode hub que activa heurísticas hub-aware en sessions/implement/release. Promociona workspaces project con múltiples fuentes. Invocado vía /agent-workflow:hub-init.
+version: 1.1.0
+---
+
+> **Profile parametrization**: lee `claude_md_block` de `profile.json` (resuelto vía cascade 5 capas). Ver [`references/profile-parametrization.md`](../../references/profile-parametrization.md) para el contrato completo y comportamiento por defecto cuando el profile está vacío.
+
+# Hub Init
+
+Bootstrap del bloque AW-PROJECT para un workspace **multi-repo** (hub mode). Hub mode introduce el marcador `Mode: hub` que activa heurísticas hub-aware en el resto de la familia qtc-*.
+
+## Cuándo usar
+
+- Workspace que coordina ≥2 repos pares (sesiones cross-cutting).
+- Promover un workspace existente que ya creció a multi-repo.
+
+## Diferencias vs `/agent-workflow:project-init`
+
+| Aspecto | project-init | hub-init |
+|---|---|---|
+| Fuentes | 1 (mín y máx) | ≥2 (mínimo) |
+| Marcador `Mode:` | `project` | `hub` |
+| Captura ramas de trabajo | No | Sí, por fuente, en Status |
+| Validación cross-fuente | No | Sí (aliases únicos, paths git válidos, comparación con `git rev-parse`) |
+| Stack auto-detect | Sobre CWD | Sobre CWD; suele caer en `_Workspace base_` |
+| Heurísticas hub-aware | Off | On (sessions, implement, release, doctor) |
+
+## Flujo detallado
+
+### 1. Detectar bloque existente
+
+```
+agent-workflow workspace-mode
+```
+
+Output: `{mode, sources, working_branches, sources_count, is_hub}`.
+
+| Caso | Acción |
+|---|---|
+| `mode=hub` | Mostrar fuentes actuales y preguntar: ¿agregar nuevas? ¿reiniciar? ¿abortar? |
+| `mode=project` con ≥1 fuente | Detectar promoción: mostrar fuente original y preguntar "¿Promover a hub?". Si confirma, continuar al paso 2 con la fuente original ya cargada. |
+| Sin bloque | Flujo limpio. |
+| Bloque legacy `<!-- QTC-WORKFLOW-START -->` | Recomendar `/agent-workflow:migrate --upgrade-topology` antes. Abortar. |
+
+### 2. Capturar descripción del workspace
+
+Pedir 1-3 líneas que mencionen que coordina N repos. Va a `## Proyecto`.
+
+### 3. Capturar fuentes
+
+Loop por cada fuente:
+
+- **Alias** kebab-case único.
+- **Path absoluto** al repo. Validar `os.path.isdir(path)` y que sea repo git (`<path>/.git/` o `git -C <path> rev-parse --git-dir`).
+- **Rama de trabajo actual**: default sugerido = `git -C <path> rev-parse --abbrev-ref HEAD`. Usuario acepta o sobreescribe.
+
+**NO preguntar la rama principal**: el CLI usa `"certificacion"` como default interno. Override sólo con `--main-branch <rama>` (raro).
+
+Mínimo 2 fuentes en flujo limpio. En "agregar a hub existente", mínimo 1 nueva.
+
+### 4. Validaciones cross-fuente
+
+Antes de persistir:
+
+- **Aliases únicos**: si duplicó, error y reintenta.
+- **Paths existen + son git repos**: si falla, error y reintenta esa entrada.
+- **Rama declarada vs actual**: comparar con `git -C <path> rev-parse --abbrev-ref HEAD`. Si difieren → advertir (no bloquear). Sugerir `git checkout` o aceptar la actual.
+
+### 5. Auto-detectar stack del CWD
+
+```
+agent-workflow stack
+```
+
+En hub workspaces el CWD suele ser un directorio "base" sin stack propio. Si auto-detección falla → `_Workspace base — stack heterogéneo (ver fuentes individuales)._` en `## Stack`.
+
+Para stack de cada fuente individual: `agent-workflow stack --all-sources` (después del init).
+
+### 6. Persistir bloque + visibilidad (atómico desde v1.1.0)
+
+Una sola invocación atómica al CLI. `agent-workflow hub-init` (introducido en v1.1.0, soportado por `agent-workflow-cli`) orquesta `project-md-upsert --init` + `attach-multiroot --from-sources` en un solo paso. Garantiza que el workspace queda consistente: bloque AW-PROJECT persistido **y** visibility configurada per-workspace, sin pasos separados que el AI pueda olvidar.
+
+```
+agent-workflow hub-init \
+    --proyecto "<descripción>" \
+    --fuente "alias1:path1" --fuente "alias2:path2" \
+    --working-branch "alias1:rama1" --working-branch "alias2:rama2"
+```
+
+El comando:
+
+- Escribe `CLAUDE.md` y `AGENTS.md` del CWD con bloque `## Proyecto` (Mode: hub), `## Fuentes`, `## Stack`, `## Status` con `- Ramas de trabajo actuales:` + sesiones activas.
+- Mergea paths en `<CWD>/.claude/settings.json → permissions.additionalDirectories` con backup `.bak.<timestamp>`.
+- Mergea paths en `<CWD>/.codex/config.toml → additional_writable_roots` + bloques `[projects.'<path>'] trust_level = "trusted"` con backup.
+- Output JSON consolidado: `{ok, dry_run, workspace, project_md:{…}, attach_multiroot:{scope,scope_dir,paths_input,claude:{…},codex:{…}}}`.
+
+Reportar al usuario: paths registrados, ubicación de cada archivo (énfasis en que están dentro del hub, no en `~`), backups generados.
+
+#### Flags adicionales
+
+- `--main-branch <rama>`: override del default interno `certificacion`.
+- `--workspace <DIR>`: override cuando el CWD no es la raíz del hub.
+- `--skip-attach`: opt-out del paso de visibility (usar si el usuario prefiere configuración manual o la corre con `attach-multiroot` directamente).
+- `--dry-run`: previsualizar sin escribir.
+
+#### Si el usuario prefiere visibility manual
+
+Si `--skip-attach`, el AI debe avisar al usuario que tiene que correr `attach-multiroot` después o configurar manualmente. Snippets de referencia en `references/multiroot-manual.md`.
+
+#### Revertir contaminación global previa
+
+Si en versiones anteriores los paths quedaron en `~/.claude/...` / `~/.codex/...` (legacy v3.3.3 o pre-v1.1.0), correr el inspector y la limpieza:
+
+```
+agent-workflow visibility doctor --workspace . --global
+agent-workflow detach-multiroot --global --from-sources
+```
+
+`visibility doctor --global` reporta paths del hub presentes en scope global con sugerencia explícita; `detach-multiroot --global` los remueve idempotentemente.
+
+### 7. Reportar
+
+- Archivos modificados (CLAUDE.md, AGENTS.md, settings.json, config.toml).
+- N fuentes registradas con aliases, paths, ramas.
+- Estado de visibilidad multi-root (paths registrados + scope).
+- Próximos pasos: `/agent-workflow:session "<objetivo>"` para crear primera sesión cross-cutting.
+
+## Reglas
+
+- **Mínimo 2 fuentes** en flujo limpio. Si quiere 1, redirigir a `/agent-workflow:project-init`.
+- **Promoción auto-detectada**: bloques `mode=project` con ≥1 fuente se detectan; sin flag `--promote`.
+- **Idempotente**: re-ejecución con datos idénticos es no-op.
+- **No tocar legacy QTC-WORKFLOW**: avisar y delegar a migrate.
+- **Visibilidad multi-root atómica** (v1.1.0+): el paso 6 colapsa init + attach en `agent-workflow hub-init`. Idempotente con backup. Si el usuario quiere opt-out: `--skip-attach` (la skill avisa que la visibility queda pendiente).
+
+## Política — sin fallback al CLI
+
+Si `agent-workflow workspace-mode|stack|hub-init|attach-multiroot|detach-multiroot|visibility` falla (no está en PATH, comando no reconocido, exit code != 0), **cortá la acción y reportá al usuario**: pedile que verifique `npm install -g @tacuchi/agent-workflow-cli`. No hay flujo alternativo Python.
+
+## Sandbox read-only
+
+`../session/references/sandbox-readonly-rules.md`. Plan describe:
+
+- Archivos a crear/modificar: `CLAUDE.md`, `AGENTS.md`, `<CWD>/.claude/settings.json`, `<CWD>/.codex/config.toml`.
+- Bloque AW-PROJECT a escribir: fuentes + ramas + `Mode: hub`.
+- Validaciones cross-fuente que se correrían (sin ejecutar `git` ni mutar).
+- Si reemplaza bloque existente o promociona desde project, indicarlo.
+
+NO ejecutar `hub-init`, `project-md-upsert --init`, `attach-multiroot`, ni `git rev-parse` en plan mode.
+
+## Recursos adicionales
+
+- **`references/multiroot-manual.md`** — snippets de configuración manual si el usuario declina la automatización.
+- **shared-contract §27** (Hub mode) — definición canónica del modo, API, marcador.
+- **`/agent-workflow:project-init`** — equivalente single-repo.
+- **CLI `--main-branch <rama>`** — override de la rama principal (default interno: `certificacion`).

package/skills/agent-workflow/doctrine/hub-init/references/multiroot-manual.md

@@ -0,0 +1,51 @@
+# Multi-root manual — snippets de referencia
+
+Si el usuario declina la automatización de `attach-multiroot`, o si solo usa uno de los dos clientes, mostrarle estos snippets para configurar manualmente.
+
+## Claude Code (`<workspace>/.claude/settings.json` o `~/.claude/settings.json`)
+
+```json
+{
+  "permissions": {
+    "additionalDirectories": [
+      "C:/Source/repo-1",
+      "C:/Source/repo-2"
+    ]
+  }
+}
+```
+
+Alternativa por sesión: `/add-dir <path>` por fuente.
+
+## Codex CLI (`<workspace>/.codex/config.toml` o `~/.codex/config.toml`)
+
+```toml
+additional_writable_roots = [
+  "C:/Source/repo-1",
+  "C:/Source/repo-2"
+]
+
+[projects."C:/Source/repo-1"]
+trust_level = "trusted"
+
+[projects."C:/Source/repo-2"]
+trust_level = "trusted"
+```
+
+## Recomendación
+
+- **Per-workspace** es preferible (`<workspace>/...`) para no contaminar la config global con paths específicos del hub.
+- **Global** sólo si todos tus workspaces comparten el mismo set de repos.
+
+## Comandos automáticos equivalentes
+
+```
+# Per-workspace (default desde v3.3.4):
+agent-workflow attach-multiroot --from-sources
+
+# Global (legacy):
+agent-workflow attach-multiroot --from-sources --global
+
+# Revertir global:
+agent-workflow detach-multiroot --from-sources --global
+```