@tacuchi/agent-workflow-cli 10.2.1 → 10.3.0

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

@@ -1,5 +1,5 @@
 ---
-description: Inicializa un workspace en modo Hub (multi-repo) — bloque AW-PROJECT con Mode hub, captura ≥2 fuentes con sus rutas y ramas de trabajo. La rama principal default es `certificacion` (constante interna del CLI).
+description: Inicializa un workspace en modo Hub (multi-repo) — escribe el bloque AW-PROJECT con Mode hub y ≥2 fuentes (rutas + ramas) y SIEMPRE configura la visibilidad multi-root (settings.local.json + config.toml, gitignored), reconciliando fuentes. La forma interactiva vive en el TUI.
 argument-hint: (opcional) --proyecto "descripción" | --fuente alias:path | --working-branch alias:rama | --main-branch <rama>
 allowed-tools:
   [
@@ -12,66 +12,42 @@ allowed-tools:
 
 # Hub Init (agent-workflow)
 
-Inicializa un **hub workspace** — un directorio que coordina ≥2 repos pares. Escribe el bloque `<!-- AW-PROJECT-START -->` en `CLAUDE.md` y `AGENTS.md` del directorio actual con el marcador `Mode: hub` y la lista de fuentes (alias / path / rama principal) + ramas de trabajo actuales por fuente.
+Inicializa un **hub workspace** — un directorio que coordina ≥2 repos pares. Escribe el bloque `<!-- AW-PROJECT-START -->` en `CLAUDE.md` y `AGENTS.md` del CWD con `Mode: hub` + la lista de fuentes (alias / path / rama) + ramas de trabajo. Además del bloque, **siempre** configura la visibilidad multi-root (gitignored) — sin preguntar.
 
-> Distinto de `/agent-workflow:project-init` (single-repo). Hub mode activa heurísticas en el resto de la familia agent-workflow-*: `session` itera ramas por fuente, `implement` valida paths cross-repo, `release` agrupa por alias, etc.
+> Distinto de `/agent-workflow:project-init` (single-repo). Hub mode activa heurísticas en el resto de la familia: `session` itera ramas por fuente, `implement` valida cross-repo, `release` agrupa por alias.
 
-## Cuándo usar
+## La vía más simple: el TUI
 
-- Workspace que coordina ≥2 repos pares (ej. `qtc-plugin-marketplace` con 4 plugins, microservicios que cambian juntos, monorepo distribuido).
-- Sesiones cross-cutting que tocan múltiples repos a la vez.
+`agent-workflow` → tab **Project** → **Initialize as hub**. Form interactivo (nombre + paths + rama base, alias inferido de la carpeta) dentro del TUI. Sin flags ni comandos a mano.
 
-## Flujo
+## Flujo (host) — mínimo
 
-1. **Detectar bloque existente** vía `agent-workflow workspace-mode`.
-   - Si `mode=hub` → mostrar fuentes actuales y preguntar si **agregar fuentes** o **reiniciar**.
-   - Si `mode=project` (o sin `Mode:`) **y ≥1 fuente declarada** → preguntar si **promover a hub** preservando la fuente original.
-   - Si no hay bloque → flujo limpio.
-
-2. **Capturar descripción** (1-3 líneas, debe mencionar que coordina N repos).
-
-3. **Capturar fuentes** (mínimo 2 en flujo limpio; ≥1 nueva en flujo "agregar"). Por cada una pedir solo:
-   - **Alias** kebab-case (único).
-   - **Path absoluto** al repo (validado: existe + es repo git).
-   - **Rama de trabajo actual** (default sugerido: `git -C <path> rev-parse --abbrev-ref HEAD`).
-   - **NO se pregunta la rama principal**: el CLI usa `certificacion` como default interno. Override con `--main-branch`.
-
-4. **Validaciones cross-fuente**:
-   - Aliases únicos.
-   - Paths absolutos y existentes (`os.path.isdir`).
-   - Cada path es repo git (`<path>/.git/` o `git -C <path> rev-parse`).
-   - Si la rama de trabajo declarada no coincide con la rama actual del repo → advertir (no bloquear).
-
-5. **Auto-detectar stack del CWD** (probablemente workspace base sin stack propio). Si no hay stack detectable, escribir `_Workspace base — stack heterogéneo (ver fuentes individuales)._`.
-
-6. **Persistir** vía:
+1. **Detectar** vía `agent-workflow workspace-mode`. Si ya es hub → agregar/reiniciar. Si es `project` con fuentes → ofrecer promover. Bloque de una topología legacy → delegar a `/agent-workflow:migrate`.
+2. **Reunir**: descripción (1 línea), ≥2 fuentes (alias + path) — el **set completo** que querés, porque `hub-init` reemplaza el bloque (para agregar/remover, leé las actuales con `workspace-mode` y pasá el set final) — y rama base (default `certificacion`). El alias se infiere de la carpeta si no se da.
+3. **Escribir + sincronizar** (un solo comando):
    ```
-   agent-workflow project-md-upsert --init \
-       --mode hub \
+   agent-workflow hub-init \
        --proyecto "<descripción>" \
-       --fuente "alias1:path1" \
-       --fuente "alias2:path2" \
-       --working-branch "alias1:rama1" \
-       --working-branch "alias2:rama2"
+       --fuente "alias1:path1" --fuente "alias2:path2" \
+       [--working-branch "alias1:rama1" ...] [--main-branch <rama>]
    ```
+   Rutas Windows (`C:\Source\...`) van directo. Escribe `CLAUDE.md` + `AGENTS.md` **y** configura la visibilidad multi-root (siempre, ver abajo).
+4. **Reportar** fuentes registradas + próximo paso (`/agent-workflow:session "<objetivo>"`).
 
-7. **Reportar** archivos modificados, fuentes registradas, ramas de trabajo capturadas. Sugerir próximos pasos (`/agent-workflow:session "<objetivo>"` o configurar visibilidad multi-root del cliente — ver README de agent-workflow).
-
-## Visibilidad multi-root del cliente
-
-`/agent-workflow:hub-init` solo captura los datos en el bloque AW-PROJECT. Para que Claude Code o Codex CLI vean los paths de las fuentes como writable, configurarlos manualmente:
+## Visibilidad multi-root (automática, siempre)
 
-- **Claude Code**: editar `~/.claude/settings.json` y agregar paths a `permissions.additionalDirectories`. Alternativa por sesión: `/add-dir <path>` por fuente.
-- **Codex CLI**: editar `~/.codex/config.toml` con `additional_writable_roots = [...]` y entradas `[projects."<path>"]` con `trust_level = "trusted"`.
+`hub-init` la configura en cada run, sin preguntar:
 
-Snippets completos en el README de agent-workflow. Iteración futura podrá automatizarlo vía `/agent-workflow:hub-attach`.
+- **Gitignored** (rutas machine-specific): `<hub>/.claude/settings.local.json` (`permissions.additionalDirectories`) + `<hub>/.codex/config.toml` (`additional_writable_roots` + `[projects.'<path>'] trust_level`). Asegura el `.gitignore`.
+- **Reconcile**: attachea las fuentes actuales y detachea las removidas vs el bloque previo (agregar/remover quedan sincronizados).
+- Diagnóstico: `agent-workflow visibility doctor --workspace .` (lee `settings.json` y `settings.local.json`).
 
 ## Argumentos
 
-Sin argumentos: flujo interactivo.
+Sin argumentos: el host arma el flujo mínimo de arriba (o usá el TUI).
 
 - `--proyecto "<texto>"`
-- `--fuente "alias:path[:rama]"` — repetible.
+- `--fuente "alias:path[:rama]"` — repetible (mín 2).
 - `--working-branch "alias:rama"` — repetible.
 - `--main-branch <rama>` — override del default `certificacion`.
 
@@ -79,4 +55,4 @@ Sin argumentos: flujo interactivo.
 
 ## Skill asociada
 
-Ver `skills/hub-init/SKILL.md` para el detalle del flujo, validaciones cross-fuente y promoción project→hub.
+Ver `doctrine/hub-init/SKILL.md` para el flujo, la promoción project→hub y la visibilidad multi-root.

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

@@ -1,157 +1,75 @@
 ---
 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
+description: Inicializa workspace Hub multi-repo — escribe el bloque AW-PROJECT en modo hub (≥2 fuentes con rutas y ramas) y SIEMPRE configura la visibilidad multi-root (settings.local.json + config.toml, gitignored), reconciliando fuentes agregadas/removidas. Sin prompt. La forma interactiva vive en el TUI (tab Project → Initialize as hub). Invocado vía /agent-workflow:hub-init.
+version: 2.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.
+> **Profile parametrization**: lee `claude_md_block` de `profile.json` (cascade 5 capas). Ver [`references/profile-parametrization.md`](../../references/profile-parametrization.md).
 
 # 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 agent-workflow.
+Escribe el bloque AW-PROJECT para un workspace **multi-repo** (hub mode). El marcador `Mode: hub` activa heurísticas hub-aware en el resto de la familia. Además del bloque, **siempre** configura la visibilidad multi-root para que los hosts (Claude Code / Codex) vean los repos fuente — sin preguntar, en cada run.
 
-## Cuándo usar
+## La vía fácil: el TUI
 
-- Workspace que coordina ≥2 repos pares (sesiones cross-cutting).
-- Promover un workspace existente que ya creció a multi-repo.
+Lo más simple es el form interactivo: `agent-workflow` → tab **Project** → **Initialize as hub**. Pide nombre + paths de fuentes (alias inferido de la carpeta) + rama base, todo dentro del TUI. No hay que recordar flags.
 
-## Diferencias vs `/agent-workflow:project-init`
+## Cuándo usar la vía CLI/host
 
-| 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) |
+- Workspace que coordina ≥2 repos pares.
+- Promover un workspace `project` que creció a multi-repo.
+- Agregar o remover una fuente de un hub existente (re-correr con el set nuevo).
 
-## Flujo detallado
+## Flujo (host) — mínimo
 
-### 1. Detectar bloque existente
+No sobre-validar ni preguntar de más. El comando persiste lo declarado y sincroniza la visibilidad solo.
 
-```
-agent-workflow workspace-mode
-```
+1. **Detectar bloque** (rápido): `agent-workflow workspace-mode` → `{mode, is_hub, ...}`. Si ya es hub → preguntar si agregar/reiniciar. Si es `project` con fuentes → ofrecer promover. Bloque legacy `<!-- QTC-WORKFLOW-START -->` → delegar a `/agent-workflow:migrate`.
+2. **Reunir datos**: descripción (1 línea), ≥2 fuentes (alias + path), rama base (default `certificacion`). El alias se infiere del nombre de la carpeta si no se da.
+3. **Escribir + sincronizar** (un solo comando):
 
-Output: `{mode, sources, working_branches, sources_count, is_hub}`.
+   ```
+   agent-workflow hub-init \
+     --proyecto "<descripción>" \
+     --fuente "alias1:path1" --fuente "alias2:path2" \
+     [--working-branch "alias1:rama1" ...] \
+     [--main-branch <rama>]
+   ```
 
-| 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. |
+   Rutas Windows (`C:\Source\...`) van directo — el parser respeta el colon de unidad. Escribe `CLAUDE.md` + `AGENTS.md` (`## Proyecto` Mode: hub + `## Fuentes` + `## Stack` + `## Status`) **y** configura la visibilidad multi-root (ver abajo). No hace falta un paso aparte.
+4. **Reportar**: fuentes registradas, paths con visibilidad, y próximo paso (`/agent-workflow:session "<objetivo>"`).
 
-### 2. Capturar descripción del workspace
+## Visibilidad multi-root (automática, siempre)
 
-Pedir 1-3 líneas que mencionen que coordina N repos. Va a `## Proyecto`.
+`hub-init` configura la visibilidad en **cada** run, sin prompt:
 
-### 3. Capturar fuentes
+- **Target gitignored**: `<hub>/.claude/settings.local.json` (`permissions.additionalDirectories`) + `<hub>/.codex/config.toml` (`additional_writable_roots` + `[projects.'<path>'] trust_level`). Las rutas son absolutas/machine-specific, así que van en archivos per-máquina; `hub-init` también asegura el `.gitignore`.
+- **Reconcile**: attachea las fuentes actuales y detachea las que estaban en el bloque previo y ya no (agregar/remover quedan sincronizados).
+- Diagnóstico: `agent-workflow visibility doctor --workspace .` (lee `settings.json` **y** `settings.local.json`). Legacy global contaminado: `visibility doctor --global` + `detach-multiroot --global --from-sources`.
 
-Loop por cada fuente:
+## Flags
 
-- **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.
+- `--main-branch <rama>` — override del default `certificacion`.
+- `--workspace <DIR>` — override si el CWD no es la raíz del hub.
+- `--dry-run` — previsualizar sin escribir (bloque + paths que se attachearían).
 
 ## 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.
+- **Mínimo 2 fuentes**. Si quiere 1 → `/agent-workflow:project-init`.
+- **Set autoritativo**: el `--fuente` declarado **reemplaza** el bloque (no merge). Para agregar/remover fuentes, pasá el set completo deseado (el form del TUI ya lo hace; por CLI, leé las fuentes actuales con `workspace-mode` y pasá el set final). `hub-init` reconcilia la visibilidad: detacha las removidas, attacha las actuales.
+- **Visibilidad siempre**: se configura sola, sin preguntar, en init y en cualquier cambio de fuentes. No hay opt-out (salvo `--dry-run`, que no escribe nada).
+- **Idempotente**: re-ejecución con datos idénticos es no-op (attach ya presente, sin cambios).
 - **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.
+Si `agent-workflow workspace-mode|hub-init|attach-multiroot|visibility` falla (no está en PATH, exit ≠ 0), **cortá la acción y reportá**: pedí verificar `npm install -g @tacuchi/agent-workflow-cli`. No hay flujo Python alterno.
 
 ## 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.
+`../session/references/sandbox-readonly-rules.md`. En plan mode describí: archivos a crear (`CLAUDE.md`, `AGENTS.md`, `.claude/settings.local.json`, `.codex/config.toml`, `.gitignore`) y el bloque AW-PROJECT (fuentes + ramas + `Mode: hub`). NO ejecutar `hub-init` / `attach-multiroot` en plan mode.
 
-## Recursos adicionales
+## Recursos
 
-- **`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.
+- **`references/multiroot-manual.md`** — detalle de la visibility / formato de cada archivo.
 - **`/agent-workflow:project-init`** — equivalente single-repo.
-- **CLI `--main-branch <rama>`** — override de la rama principal (default interno: `certificacion`).