@tacuchi/agent-workflow-cli 11.0.1 → 12.0.0

package/skills/agent-workflow/MANUAL-FUNCIONAL.md

@@ -1,298 +0,0 @@
-# Manual funcional — agent-workflow
-
-Manual de uso del workflow universal para usuarios finales.
-
-Audiencia: developers, líderes técnicos y equipos que adoptan el workflow para llevar adelante trabajo estructurado en sesiones.
-
-Esta documentación es del **workflow universal**, no de los plugins downstream específicos.
-
-## 1. Qué resuelve
-
-El workflow `agent-workflow` te da una forma estructurada de:
-
-- **Acordar** qué se va a hacer (OBJETIVO).
-- **Descomponer** el trabajo en tareas accionables (TASKS).
-- **Avanzar** con visibilidad de criterios y decisiones (DECISIONES).
-- **Cerrar** dejando trazas reproducibles (HISTORY + CHECKPOINT).
-
-Está pensado para colaboración con un AI (Claude Code, Codex, etc.), pero el CLI funciona también sin AI.
-
-Beneficios:
-
-- Sesiones aisladas: cada trabajo tiene su carpeta, su rama, su brief.
-- Recuperación post-compact: si el contexto del modelo se libera, retomás con `CHECKPOINT.md`.
-- Historial trazable: `HISTORY.md` lista todas las sesiones del workspace.
-- Portátil: el mismo CLI funciona en cualquier dominio cambiando solo el namespace.
-
-## 2. Conceptos clave
-
-### Sesión
-
-Carpeta `.<ns>/sessions/sessionNNN-<flow>-<slug>/` con artefactos. NNN es correlativo, `<flow>` es el tipo (dev/design/analyze/etc.), `<slug>` es el nombre.
-
-### Workspace
-
-Directorio del proyecto con un bloque `<NS>-PROJECT` declarado en `CLAUDE.md` o `AGENTS.md`. El bloque define las fuentes (paths de los repos), modo (project simple o hub multi-repo), y status.
-
-### Namespace
-
-Identificador del dominio (ej. `workflow`, `acme`, `agent-workflow`). Define dónde viven las sesiones (`.<ns>/`) y el bloque project (`<NS>-PROJECT`).
-
-### Flow
-
-Tipo de trabajo: `dev` (implementación), `design` (UX/UI), `analyze` (investigación). Otros flows pueden agregarse por plugins downstream.
-
-### Plugin downstream
-
-Capa opcional que agrega skills de negocio sobre el workflow universal. Sin plugin, el workflow funciona igual; con plugin, ganás reglas específicas del dominio.
-
-## 3. Las 4 fases
-
-```
-1. planning   →   2. execution   →   3. validation   →   4. closure
-```
-
-### Fase 1 — Planning
-
-Acordás qué hacer.
-
-Salidas:
-- `OBJETIVO.md`: brief, criterios de aceptación, fuera de alcance.
-- `TASKS.md`: lista accionable de tareas.
-
-Comandos típicos:
-```bash
-agent-workflow auto-plan-decide --objetivo-file ...   # ¿el plan necesita ser ligero o detallado?
-agent-workflow specialty-choose --phase planning ...  # ¿qué skills aplican?
-agent-workflow tasks-data --code sessionNNN           # leer estado del plan
-```
-
-### Fase 2 — Execution
-
-Hacés el trabajo.
-
-Salidas:
-- Edits en código / docs / scripts.
-- `DECISIONES.md`: registro de elecciones no obvias.
-- Artefactos opcionales según flow (`EVIDENCIA.md` en analyze, `ENTREGA.md` en design, etc.).
-
-Comandos típicos:
-```bash
-agent-workflow tasks-data --only-open                 # próxima tarea
-agent-workflow check-branch --source <alias>         # rama coincide?
-agent-workflow topic-change-check --request "..."    # ¿cambió el OBJETIVO?
-```
-
-### Fase 3 — Validation
-
-Verificás criterios cumplidos.
-
-Salidas:
-- Tareas marcadas cerradas.
-- Notas de validación en `DECISIONES.md` si aporta.
-
-Comandos típicos:
-```bash
-agent-workflow tasks-data --only-open                 # quedan tareas?
-agent-workflow phase-detect --code sessionNNN         # ¿qué fase soy?
-```
-
-### Fase 4 — Closure
-
-Cerrás y dejás trazas.
-
-Salidas:
-- `CHECKPOINT.md`: estado para retomar luego si hace falta.
-- Fila `closed` en `HISTORY.md`.
-- Artefactos graduados (`docs/decisiones/`, `docs/propuestas/`, etc. — si aplica).
-
-Comandos típicos:
-```bash
-agent-workflow checkpoint-write --code sessionNNN
-agent-workflow graduate --code sessionNNN --decisiones DEC-001-slug
-agent-workflow session-close --code sessionNNN
-```
-
-## 4. Artefactos
-
-| Artefacto | Cuándo aparece | Quién lo escribe | Lector CLI |
-|---|---|---|---|
-| `OBJETIVO.md` | Fase 1 | Vos / el modelo | `objetivo-data` |
-| `TASKS.md` | Fase 1 | Vos / el modelo | `tasks-data` |
-| `DECISIONES.md` | Fase 2 | El modelo registra elecciones | `decisiones-list` |
-| `DEPENDENCIAS.md` | Fase 2 (opcional) | Si hay handoffs entre sesiones | `dependencias-list` |
-| `CHECKPOINT.md` | Fase 4 | El modelo / hook PreCompact | `checkpoint-read` |
-| `HISTORY.md` | Continuo | Auto-mantenido por el CLI | `history-data` |
-| Convencionales (`EVIDENCIA`, `HALLAZGOS`, `RECOMENDACION`, `DISCOVERY`, `ENTREGA`...) | Fase 2 | El modelo según flow del plugin downstream | (no hay reader universal — markdown free-form) |
-
-Regla práctica: si vas a escribir algo a mano, hacelo en el editor. El CLI no edita artefactos por vos — solo los lee y publica fila en HISTORY.
-
-## 5. Flujos día a día
-
-### 5.1 Crear sesión
-
-```bash
-agent-workflow session-create \
-  --flow dev \
-  --name fix-login-loop \
-  --objetivo "Resolver redirect loop tras login en producción" \
-  --branches "core:feature/fix-login,api:feature/fix-login"
-```
-
-Resultado: carpeta `.<ns>/sessions/sessionNNN-dev-fix-login-loop/` con `OBJETIVO.md` scaffold.
-
-Variantes:
-- `--tipo refactor` (sesiones de refactor con phased Phase 0-5).
-- `--modalidad tecnica|datos|incidente` (sesiones analyze).
-- `--from <flow>:NNN` (origen handoff de otra sesión).
-
-### 5.2 Listar sesiones
-
-```bash
-agent-workflow sessions                           # activas
-agent-workflow sessions --all                     # todas
-agent-workflow sessions --include-legacy          # incluir folders legacy (.claude/.codex)
-```
-
-### 5.3 Retomar sesión
-
-```bash
-agent-workflow session-resume --code session042
-agent-workflow checkpoint-read --code session042  # si hay checkpoint
-```
-
-Si retomás en otro día, el CLI te recuerda en qué fase estás (`phase-detect`) y qué tareas quedan abiertas (`tasks-data --only-open`).
-
-### 5.4 Trabajar dentro de la sesión
-
-Loop típico:
-1. `agent-workflow tasks-data --code sessionNNN --only-open` → tomar próxima tarea.
-2. Editar código (el modelo lo hace; el hook `branch-check` te avisa si la rama no coincide).
-3. Marcar la tarea cerrada en `TASKS.md`.
-4. Registrar decisión no obvia en `DECISIONES.md` si aplica.
-5. Volver a 1.
-
-### 5.5 Compactar contexto
-
-Cuando el modelo se acerca al límite de contexto:
-
-```bash
-agent-workflow checkpoint-write --code sessionNNN   # persistir estado
-# Luego /compact en el host (Claude Code, Codex)
-agent-workflow checkpoint-read --code sessionNNN    # reentrar limpio
-```
-
-`auto-compact-on-close` (hook SessionEnd) lo hace por vos al cerrar el cliente.
-
-### 5.6 Cerrar sesión
-
-```bash
-agent-workflow session-close \
-  --code session042 \
-  --graduated-decisions "DEC-001-slug-a,DEC-003-slug-b" \
-  --refs "[CHECKPOINT](.<ns>/sessions/session042-.../CHECKPOINT.md)"
-```
-
-Antes de cerrar, considerá:
-- Graduar decisiones importantes a `docs/decisiones/` con `agent-workflow graduate`.
-- Hacer commits por fuente afectada (cada repo modificado).
-- Compactar si tu cliente lo soporta.
-
-## 6. Workspace mode: project vs hub
-
-### Project mode
-
-Workspace simple con 1 repo. La carpeta donde vivís y trabajás contiene `CLAUDE.md` con un bloque `<NS>-PROJECT` simple.
-
-```bash
-agent-workflow project-md-upsert --init
-```
-
-### Hub mode
-
-Workspace que coordina varios repos pares. Útil cuando un trabajo cruza repositorios (frontend + backend + DB).
-
-```bash
-agent-workflow upgrade-hub-mode --dry-run
-agent-workflow upgrade-hub-mode
-```
-
-El bloque `<NS>-PROJECT` lista cada fuente (alias, path, rama principal). Las sesiones declaran su rama de trabajo por fuente: `--branches alias1:rama1,alias2:rama2`.
-
-`workspace-mode` te dice en qué modo estás:
-
-```bash
-agent-workflow workspace-mode
-```
-
-## 7. Quick start (sin plugin downstream)
-
-Empresa nueva que adopta el workflow desde cero.
-
-```bash
-# 1. Instalar CLI
-npm install -g @tacuchi/agent-workflow-cli
-
-# 2. Instalar skill (si usás Claude Code)
-agent-workflow self install-skill
-
-# 3. Verificar
-agent-workflow self doctor
-# → cli_version, namespace, skill.installed
-
-# 4. Setear namespace de tu organización (opcional, si no usás default)
-echo "acme" > ~/.config/agent-workflow/namespace
-# o per-call: agent-workflow --namespace acme ...
-
-# 5. Inicializar workspace
-cd /path/to/proyecto
-agent-workflow project-md-upsert --init
-# Editar CLAUDE.md / AGENTS.md para completar el bloque ACME-PROJECT (paths, ramas)
-
-# 6. Primera sesión
-agent-workflow session-create \
-  --flow dev \
-  --name primer-feature \
-  --objetivo "Hello world: arrancar el workflow"
-
-# 7. Ver estado
-agent-workflow sessions
-agent-workflow workspace-mode
-
-# 8. Cerrar (cuando termines)
-agent-workflow session-close --code session001
-```
-
-A partir del paso 8 ya tenés `HISTORY.md` poblado y la sesión cerrada con trazas.
-
-## 8. Cuando agregar un plugin downstream
-
-Considerá un plugin downstream cuando:
-
-- Tu equipo necesita reglas específicas (coding standards, formato de scripts SQL, principios de UX).
-- Querés flows propios (ej. `incident-response` además de `dev/design/analyze`).
-- Querés hooks que enforce políticas internas (ej. PR template, branch naming).
-
-El plugin no reescribe el workflow universal — solo agrega capas. Reglas:
-
-- No re-implementar lógica del CLI (parsing, lifecycle, sources).
-- Hooks invocan `agent-workflow ...` directamente.
-- Skills propias solo cubren reglas de negocio del dominio.
-
-Ver `MANUAL-TECNICO.md` sección 7.1 para los pasos.
-
-## 9. Errores frecuentes (para usuarios)
-
-| Síntoma | Probable causa | Acción |
-|---|---|---|
-| `error.code = "NOT_IN_WORKSPACE"` | Estás en un directorio sin bloque `<NS>-PROJECT`, o el namespace activo apunta a otro lado | `agent-workflow self namespace` para ver el resuelto. Si necesitás otro namespace: `--namespace <name>` o setear `~/.config/agent-workflow/namespace`. |
-| El hook bloquea mi edit | La rama actual no matchea la rama declarada en la sesión | `agent-workflow check-branch --source <alias>` para ver mismatch. Hacer checkout o re-declarar la rama. |
-| Las sesiones de la versión vieja no aparecen | Estaban en `.claude/` o `.codex/` (legacy) y no se migraron | `agent-workflow sessions --include-legacy` o ejecutar el migrador del plugin downstream si aplica. |
-| El skill no aparece en el cliente AI | No se instaló o la versión está vieja | `agent-workflow self install-skill --force` |
-
-## 10. Referencias
-
-- API completa del CLI: `SKILL.md` + `references/<familia>.md`.
-- Manual técnico (mantenimiento + extensión): `MANUAL-TECNICO.md`.
-- Test plan: `docs/TEST-PLAN.md`.
-- Repo CLI: github.com/Tacuchi/agent-workflow-cli (la skill vive bundled adentro del tarball; ya no hay repo standalone).

package/skills/agent-workflow/MANUAL-TECNICO.md

@@ -1,271 +0,0 @@
-# Manual técnico — agent-workflow
-
-Manual de implementación y mantenimiento del workflow universal.
-
-Audiencia: developers que mantienen, extienden o integran el CLI `@tacuchi/agent-workflow-cli` y el skill `agent-workflow` que viaja bundled adentro.
-
-Esta es documentación del **workflow universal**, no de plugins downstream específicos.
-
-## 1. Arquitectura
-
-```
-┌────────────────────────────────────────────────────────────┐
-│ Host harness (Claude Code, Codex, Gemini CLI, etc.)        │
-└──────────────────┬─────────────────────────────────────────┘
-                   │ tool calls / hooks
-                   ▼
-┌────────────────────────────────────────────────────────────┐
-│ Skill: agent-workflow (universal, AI-facing, bundled)      │
-│   SKILL.md + 11 references/                                │
-│   Enseña al modelo cuándo y cómo invocar el CLI.           │
-└──────────────────┬─────────────────────────────────────────┘
-                   │ shell exec
-                   ▼
-┌────────────────────────────────────────────────────────────┐
-│ CLI: @tacuchi/agent-workflow-cli (Node 20+, ESM, npm)      │
-│   bin: agent-workflow / aw                                 │
-│   43 subcomandos en 11 familias.                           │
-└──────────────────┬─────────────────────────────────────────┘
-                   │ filesystem + git
-                   ▼
-┌────────────────────────────────────────────────────────────┐
-│ Workspace                                                  │
-│   .<ns>/sessions/sessionNNN-<flow>-<slug>/                 │
-│   .<ns>/HISTORY.md                                         │
-│   CLAUDE.md / AGENTS.md (con bloque <NS>-PROJECT)          │
-└────────────────────────────────────────────────────────────┘
-
-┌────────────────────────────────────────────────────────────┐
-│ Plugin downstream (opcional, específico de un dominio)     │
-│   Solo skills de negocio + hooks que invocan al CLI.       │
-│   NO duplica lógica del workflow universal.                │
-└────────────────────────────────────────────────────────────┘
-```
-
-Componentes:
-
-| Componente | Propósito | Lenguaje | Repo |
-|---|---|---|---|
-| CLI `agent-workflow` (paquete `@tacuchi/agent-workflow-cli`) | runtime ejecutable del workflow | TypeScript (ESM, Node 20+) | github.com/Tacuchi/agent-workflow-cli |
-| Skill `agent-workflow` | manual AI-facing del CLI (bundled en el tarball) | Markdown (frontmatter Anthropic Skill) | bundled en `skills/agent-workflow/` del CLI |
-| Plugin downstream | superficie específica de dominio | Markdown + JSON manifests | (cada empresa / dominio) |
-
-## 2. Contratos
-
-### 2.1 Lifecycle (4 fases)
-
-```
-planning → execution → validation → closure
-   ↑           ↓
-   └───────────┘  (topic-change puede reiniciar)
-```
-
-| Fase | Driver del CLI | Artefactos esperados |
-|---|---|---|
-| planning | `auto-plan-decide`, `specialty-choose`, `objetivo-data`, `tasks-data` | `OBJETIVO.md`, `TASKS.md` |
-| execution | el modelo + skills downstream | `DECISIONES.md`, scripts/, `EVIDENCIA.md`, `HALLAZGOS.md` (si aplica) |
-| validation | `tasks-data --only-open`, criterios releídos | logs, marcado en TASKS |
-| closure | `graduate`, `session-close`, `auto-compact-on-close` | `CHECKPOINT.md`, fila cerrada en `HISTORY.md`, artefactos graduados a `docs/` |
-
-`phase-detect` y `phase-next` permiten al modelo y al harness consultar/avanzar fase.
-
-### 2.2 Artefactos
-
-**Principales (universales, garantizados por el CLI)**:
-
-- `OBJETIVO.md`: brief + criterios de aceptación. Reader: `objetivo-data`.
-- `TASKS.md`: descomposición accionable. Reader: `tasks-data`.
-- `DECISIONES.md`: registro de decisiones no obvias. Reader: `decisiones-list`.
-- `CHECKPOINT.md`: estado pre-compact. Reader: `checkpoint-read`. Writer: `checkpoint-write`.
-- `HISTORY.md`: índice de sesiones. Reader: `history-data`. Writer: `history-update`.
-
-**Convencionales (del plugin downstream)**:
-
-- `EVIDENCIA.md`, `HALLAZGOS.md`, `RECOMENDACION.md` — convención del flow `analyze`.
-- `DISCOVERY.md`, `PROBLEMA.md`, `IDEAS.md`, `ENTREGA.md` — convención del flow `design`.
-- `DEPENDENCIAS.md` — convención cross-flow. Reader: `dependencias-list`.
-
-El CLI los trata como markdown free-form (no parsea estructura). El plugin downstream define el shape.
-
-### 2.3 Output JSON contractual
-
-Todo subcomando devuelve JSON en stdout, exit 0 success / no-cero error con envelope:
-
-```json
-{ "error": { "code": "NOT_IN_WORKSPACE", "message": "...", "details": {} } }
-```
-
-Hooks (`hook branch-check`, `hook sql-mutation-guard`) usan exit 0 (allow) / 2 (block) además del JSON.
-
-## 3. Surface del CLI (43 subcomandos en 11 familias)
-
-| Familia | Comandos |
-|---|---|
-| session-mgmt | `sessions`, `session-create`, `session-resume`, `session-close`, `session-artifacts` |
-| objetivo-tasks | `objetivo-data`, `tasks-data`, `decisiones-list`, `dependencias-list` |
-| history | `history-data`, `history-update` |
-| checkpoint | `checkpoint-read`, `checkpoint-write`, `compress-checkpoint`, `resume-summary`, `auto-compact-on-close` |
-| sources | `sources`, `check-branch`, `workspace-mode`, `project-md-upsert`, `upgrade-hub-mode`, `attach-multiroot`, `detach-multiroot` |
-| orchestration | `auto-plan-decide`, `topic-change-check`, `specialty-choose`, `phase-detect`, `phase-next`, `stack`, `workflows`, `skill-index` |
-| doctor | `plugin-doctor`, `code-scan`, `release-data`, `graduate` |
-| hooks | `hook branch-check`, `hook sql-mutation-guard` |
-| mcp | `mcp dbhub`, `bootstrap-dsn` |
-| dev-only | `harness`, `profiles`, `logs`, `next-number` |
-| self | `self namespace`, `self doctor`, `self update`, `self install-skill` |
-
-Detalle por familia: ver `references/<familia>.md` en este mismo skill.
-
-## 4. Hooks
-
-Eventos del host harness que disparan al CLI:
-
-| Evento | Subcomando | Propósito |
-|---|---|---|
-| SessionStart | (cualquiera, ej. `printf "<ns>" > ~/.config/agent-workflow/namespace`) | Setear namespace activo. |
-| PreToolUse (Edit/Write/MultiEdit/NotebookEdit) | `hook branch-check` | Bloquear edits si la rama no coincide con la sesión. |
-| PreToolUse (MCP execute_sql) | `hook sql-mutation-guard` | Bloquear DML/DDL en MCPs read-only. |
-| PreCompact | `checkpoint-write` | Persistir estado antes de liberar contexto. |
-| PostCompact | `resume-summary` o `project-md-upsert --read` | Recuperar bloque project tras compact. |
-| SessionEnd | `auto-compact-on-close` | Cierre proactivo. |
-
-Stdin/stdout siguen el contrato del harness (Anthropic Claude Code, Codex CLI, etc.). Cada hook es una invocación independiente del proceso `agent-workflow`.
-
-## 5. Namespace resolver (4 niveles)
-
-Precedencia de mayor a menor:
-
-1. Flag `--namespace <name>` (per-call).
-2. Env vars `AW_NAMESPACE` o `AGENT_WORKFLOW_NAMESPACE`.
-3. (v1.2.0+) Workspace local: bloque `<NS>-PROJECT` detectado en `CLAUDE.md` / `AGENTS.md` del directorio actual.
-4. User config: `~/.config/agent-workflow/namespace`.
-5. Default literal: `agent-workflow`.
-
-El namespace controla:
-
-- Carpeta de sesiones: `.<ns>/sessions/`.
-- Bloque project: `<NS>-PROJECT` en CLAUDE.md / AGENTS.md.
-- User root: `~/.<ns>/`.
-
-Comandos relacionados:
-
-```bash
-agent-workflow self namespace               # ver el resuelto y su fuente
-agent-workflow self doctor                  # ver el árbol completo
-```
-
-## 6. MCP integration
-
-El CLI puede actuar como wrapper de MCP servers:
-
-```bash
-agent-workflow mcp dbhub <instance>         # spawn @bytebase/dbhub vía npx
-agent-workflow bootstrap-dsn --dsn-cert ... # persistir DSN sin exponer
-```
-
-El plugin downstream registra el wrapper en su `.mcp.json`:
-
-```json
-{
-  "<server-name>": {
-    "command": "agent-workflow",
-    "args": ["mcp", "dbhub", "cert"]
-  }
-}
-```
-
-Razón: el CLI consolida resolución de namespace + DSN persistido + envoltorio del binario externo.
-
-## 7. Extensibilidad
-
-### 7.1 Nuevo plugin downstream
-
-1. Crear repo del plugin con manifests `.claude-plugin/plugin.json` y/o `.codex-plugin/plugin.json`.
-2. Hook `SessionStart` que setea el namespace deseado:
-   ```sh
-   printf "%s\n" "miempresa" > "${HOME}/.config/agent-workflow/namespace"
-   ```
-3. Skills propias en `skills/<nombre>/SKILL.md` — solo lógica de negocio. NO re-implementar lifecycle, parsing de artefactos, gestión de sesiones (eso lo hace el CLI).
-4. Hooks adicionales (`PreToolUse`, etc.) que invocan `agent-workflow ...` con el namespace ya en `~/.config/...`.
-5. Documentar en CLAUDE.md/AGENTS.md del workspace cliente cómo se compone con el skill universal `agent-workflow`.
-
-### 7.2 Nuevo subcomando del CLI
-
-Pipeline en `/Users/tacuchi/Git/agent-workflow-cli`:
-
-1. Definir contrato JSON en `src/application/<command>/Service.ts`.
-2. Adapter Node en `src/adapters/<command>/`.
-3. CLI binding en `src/cli/<command>Command.ts` con `commander`.
-4. Tests unit en `tests/unit/<command>.test.ts` (vitest).
-5. Si tiene side-effects de filesystem: golden fixture en `tests/fixtures/golden-write/<command>-XX/` + golden test en `tests/golden/`.
-6. Bump en `package.json` + entry en `CHANGELOG.md`.
-7. Update del skill: agregar entry en la reference correspondiente o crear nueva.
-8. Bump del skill `agent-workflow` (frontmatter `version`) si la reference cambió. La skill viaja bundled en `skills/agent-workflow/` del repo del CLI.
-
-### 7.3 Nuevo flow del workflow
-
-Concepto: un flow define la composición de skills durante el lifecycle de una sesión (ej. `dev`, `design`, `analyze`).
-
-1. Crear plugin downstream con `skills/<flow>-workflow/SKILL.md`.
-2. Registrar el workflow vía CLI ya cubre la búsqueda con `workflows` (lectura de los plugins instalados).
-3. La forma del payload registrado se expone vía `agent-workflow workflows --flow <name>`: `session_args`, `artifacts_by_phase`, `skills_by_phase`, `refs_format`, `resume_counters`.
-4. El skill `agent-workflow` no necesita cambios — el flow es dato runtime que el modelo descubre vía `workflows`.
-
-## 8. Versioning + release
-
-CLI:
-- semver estricto en `package.json`.
-- `CHANGELOG.md` con cada release.
-- `agent-workflow self update` reporta delta vs. npm registry.
-- `agent-workflow self doctor` reporta versión instalada + skill instalado.
-
-Skill:
-- `version` en frontmatter de `SKILL.md`.
-- Bump cuando una reference cambia o cuando el CLI agrega/cambia comandos.
-- Política: el skill es "alineable" con la mayor versión del CLI que documenta. No es necesario que matchee 1:1.
-
-Plugins downstream:
-- Cada uno tiene su propia cadencia. Pueden declarar dependencia de versión mínima del CLI o del skill (vía CLAUDE.md, README o manifest custom).
-
-## 9. Decisiones registradas
-
-Las decisiones técnicas que dieron forma a la arquitectura están en los repos respectivos:
-
-- Migración Python → TypeScript: Propuesta 004 en core-workflow-plugin (sesiones 022..032).
-- CLI agnóstico: spec `agent-workflow-agnostic-design` (session034).
-- Skill repo separado: spec sub-proyecto 2 (session035).
-- Plugins namespace propagation: sub-proyecto 3 (session036).
-- Conformance final: sesión 037 — este manual.
-
-## 10. Operación
-
-### 10.1 Diagnóstico básico
-
-```bash
-agent-workflow self doctor
-agent-workflow self namespace
-agent-workflow workspace-mode
-agent-workflow sources
-```
-
-### 10.2 Update operativo
-
-```bash
-agent-workflow self update                      # check
-npm i -g @tacuchi/agent-workflow-cli@latest         # actualizar binario
-agent-workflow self install-skill --force       # actualizar skill
-```
-
-### 10.3 Errores frecuentes
-
-| Error | Causa probable | Acción |
-|---|---|---|
-| `NOT_IN_WORKSPACE` | Namespace apunta a tree no existente | `self namespace` para ver el resuelto; setear `--namespace` o env. |
-| Mismatch entre `self doctor.cli_version` y `package.json` | Binario global desactualizado | `npm i -g @tacuchi/agent-workflow-cli@latest` |
-| Hook `branch-check` bloquea edits inesperadamente | Sesión declara una rama distinta a la actual | `agent-workflow check-branch --source <alias>` para ver expected vs current; checkout o re-declarar. |
-
-## 11. Referencias
-
-- Workflow universal API: `references/<familia>.md` (este skill).
-- Quick start funcional: `MANUAL-FUNCIONAL.md` (este skill).
-- Test plan de aceptación: `docs/TEST-PLAN.md` (graduado de session037).
-- CLI repo: github.com/Tacuchi/agent-workflow-cli (la skill vive bundled adentro del tarball; ya no hay repo standalone).

package/skills/agent-workflow/README.md

@@ -1,74 +0,0 @@
-# agent-workflow
-
-Universal Claude Code / Codex skill for the [`@tacuchi/agent-workflow-cli`](https://www.npmjs.com/package/@tacuchi/agent-workflow-cli) CLI.
-
-This bundled skill — `SKILL.md` plus a `references/` folder — teaches an AI agent how to drive the agent-workflow session-lifecycle CLI: create / resume / close sessions, read & write artifacts (`OBJETIVO.md`, `TASKS.md`, `DECISIONES.md`, `HISTORY.md`, `CHECKPOINT.md`), inspect sources, run hooks, and manage the binary itself.
-
-The skill is bundled inside the CLI tarball — there is no standalone repo. The CLI command `agent-workflow self install-skill` copies it from the bundled location to `~/.claude/skills/agent-workflow/`.
-
-## Quick start
-
-```bash
-# 1. Install the CLI globally (one time)
-npm install -g @tacuchi/agent-workflow-cli
-
-# 2. Install this skill into ~/.claude/skills/agent-workflow/
-agent-workflow self install-skill
-```
-
-The second command copies the bundled skill (shipped inside the CLI tarball) to `~/.claude/skills/agent-workflow/`. Claude Code auto-discovers the skill on the next session start.
-
-To preview without writing:
-
-```bash
-agent-workflow self install-skill --dry-run
-```
-
-To install from a local checkout (useful for skill development):
-
-```bash
-agent-workflow self install-skill --from /path/to/agent-workflow-cli/skills/agent-workflow --force
-```
-
-## Repo layout
-
-```
-skills/agent-workflow/
-├── SKILL.md              # Skill entry point with frontmatter
-├── README.md             # This file
-├── LICENSE               # AGPL-3.0-or-later
-└── references/           # Per-family command documentation
-    ├── session-mgmt.md   # sessions, session-create, session-resume, session-close, session-artifacts
-    ├── objetivo-tasks.md # objetivo-data, tasks-data, decisiones-list, dependencias-list
-    ├── history.md        # history-data, history-update
-    ├── checkpoint.md     # checkpoint-read, checkpoint-write, compress-checkpoint, resume-summary, auto-compact-on-close
-    ├── sources.md        # sources, check-branch, workspace-mode, project-md-upsert, upgrade-hub-mode, attach/detach-multiroot
-    ├── orchestration.md  # auto-plan-decide, topic-change-check, specialty-choose, phase-detect, phase-next, stack, workflows, skill-index
-    ├── doctor.md         # plugin-doctor, code-scan, release-data, graduate
-    ├── hooks.md          # hook branch-check, hook sql-mutation-guard
-    ├── mcp.md            # mcp dbhub, bootstrap-dsn
-    ├── dev-only.md       # harness, profiles, logs, next-number
-    └── self.md           # self namespace, self doctor, self update, self install-skill
-```
-
-## Updating the skill
-
-```bash
-npm install -g @tacuchi/agent-workflow-cli@latest    # update the CLI tarball
-agent-workflow self install-skill --force            # re-install bundled skill
-```
-
-## Uninstall
-
-```bash
-rm -rf ~/.claude/skills/agent-workflow
-```
-
-## Project links
-
-- CLI source: <https://github.com/Tacuchi/agent-workflow-cli>
-- npm: <https://www.npmjs.com/package/@tacuchi/agent-workflow-cli>
-
-## License
-
-Copyright © 2026 Jesús Loayza (Tacuchi). Licensed under **AGPL-3.0-or-later** — see [LICENSE](./LICENSE).