@tacuchi/agent-workflow-cli 4.0.0

package/skills/agent-workflow/SKILL.md

@@ -0,0 +1,111 @@
+---
+name: agent-workflow
+description: Universal skill for the @tacuchi/agent-workflow-cli CLI. Teach Claude Code how to drive session-lifecycle workflows (planning → execution → validation → closure), history bookkeeping, source/branch checks, checkpoints, doctor, hooks, and self-management. Use whenever the user works with session-based development inside a workspace that hosts an `.agent-workflow/` (or `.qtc/` for the QTC plugin family) artifact tree.
+version: 1.1.0
+---
+
+# agent-workflow — universal CLI skill
+
+`@tacuchi/agent-workflow-cli` is a generic, namespace-aware CLI that runs the canonical session-lifecycle workflow used by the qtc-* plugin family and any other plugin that opts into the same artifact contract.
+
+This skill teaches Claude Code:
+
+- when to invoke the CLI vs. handing the work to a slash command,
+- the 43 top-level subcommands grouped by family,
+- the namespace contract that lets the same binary serve multiple plugin ecosystems without forks.
+
+For each command family there is a dedicated reference under `references/`. Read the matching reference *before* invoking commands you have not used in the current conversation — flags and contracts evolve.
+
+## Invocation contract
+
+```
+agent-workflow [--namespace <name>] [--flow <core|dev|design|analyze>]
+               [--plugin-root <path>] [--plugin-version <semver>] [--compat <range>]
+               <command> [args...]
+```
+
+Short alias: `aw`.
+
+### Namespace resolution (highest precedence first)
+
+1. CLI flag `--namespace <name>`
+2. Env var `AW_NAMESPACE` (or `AGENT_WORKFLOW_NAMESPACE`)
+3. User config `~/.config/agent-workflow/namespace`
+4. Default literal: `agent-workflow`
+
+For QTC plugin compatibility, qtc-* plugins export `AW_NAMESPACE=qtc` from their SessionStart hooks; the CLI then reads/writes `~/.qtc/`, `.qtc/sessions/`, and the `QTC-PROJECT` block in `CLAUDE.md` / `AGENTS.md`.
+
+When you invoke the CLI from a fresh shell where no plugin has set the env, use `--namespace <name>` explicitly or the binary will operate on the default `agent-workflow` namespace and miss the QTC artifacts.
+
+### Output contract
+
+Every command returns JSON on stdout (no decoration), exit code 0 on success and non-zero on error with a structured error envelope. Pipe to `jq` to extract fields.
+
+```bash
+agent-workflow sessions | jq '.next_number'
+agent-workflow objetivo-data --code session035 | jq '.criterios_aceptacion'
+```
+
+## When to invoke this CLI
+
+Invoke `agent-workflow` (directly or via the registered slash commands) whenever:
+
+- the user asks to **create / resume / close / list** sessions,
+- the user asks to **read or update** an artifact (`OBJETIVO.md`, `TASKS.md`, `DECISIONES.md`, `HISTORY.md`, `CHECKPOINT.md`),
+- you need to **detect workspace state** (sources, branches, mode, stack, harness),
+- a host hook (`PreToolUse`, `SessionEnd`, `PostCompact`) routes to the binary,
+- the user wants to **manage the CLI itself** (doctor / update / install-skill / namespace).
+
+Do *not* invoke the CLI for ad-hoc file edits, code refactors, business validation, or anything outside the session-lifecycle contract.
+
+## Command families
+
+The 43 top-level subcommands group into 11 families. Open the matching reference before composing a command.
+
+| Family | Reference | What lives there |
+|---|---|---|
+| Session management | [references/session-mgmt.md](references/session-mgmt.md) | sessions, session-create, session-resume, session-close, session-artifacts |
+| Objetivo / Tasks | [references/objetivo-tasks.md](references/objetivo-tasks.md) | objetivo-data, tasks-data, decisiones-list, dependencias-list |
+| History | [references/history.md](references/history.md) | history-data, history-update |
+| Checkpoint | [references/checkpoint.md](references/checkpoint.md) | checkpoint-read, checkpoint-write, compress-checkpoint, resume-summary, auto-compact-on-close |
+| Sources / branches | [references/sources.md](references/sources.md) | sources, check-branch, workspace-mode, project-md-upsert, upgrade-hub-mode, attach-multiroot, detach-multiroot |
+| Orchestration | [references/orchestration.md](references/orchestration.md) | auto-plan-decide, topic-change-check, specialty-choose, phase-detect, phase-next, stack, workflows, skill-index |
+| Doctor / release | [references/doctor.md](references/doctor.md) | plugin-doctor, code-scan, release-data, graduate |
+| Hooks | [references/hooks.md](references/hooks.md) | hook branch-check, hook sql-mutation-guard |
+| MCP / DSN | [references/mcp.md](references/mcp.md) | mcp dbhub, bootstrap-dsn |
+| Dev-only | [references/dev-only.md](references/dev-only.md) | harness, profiles, logs, next-number |
+| Self | [references/self.md](references/self.md) | self namespace, self doctor, self update, self install-skill |
+
+## Quick start cheatsheet
+
+```bash
+# Discover state
+agent-workflow sessions
+agent-workflow workspace-mode
+agent-workflow sources
+
+# Create + drive a session
+agent-workflow session-create --flow dev --name fix-login --objetivo "Bug: login redirect loop"
+agent-workflow session-resume --code session042
+agent-workflow tasks-data --code session042 --only-open
+agent-workflow checkpoint-write --code session042
+agent-workflow session-close --code session042
+
+# Diagnostics
+agent-workflow self doctor
+agent-workflow self namespace
+agent-workflow plugin-doctor --plugin-root /path/to/plugin
+```
+
+## Discovery rules
+
+1. If unsure which family a command belongs to, run `agent-workflow --help` (top-level) and pick the family from the table above.
+2. If unsure about flags, read the corresponding `references/*.md`. The references list every supported flag with example payloads.
+3. If a command returns `error.code = "NOT_IN_WORKSPACE"`, the namespace points at a filesystem tree that does not exist — re-check `--namespace` / env, or run `self namespace` to see the resolved value.
+
+## Cross-references
+
+- CLI repo: <https://github.com/Tacuchi/agent-workflow-cli>
+- npm: <https://www.npmjs.com/package/@tacuchi/agent-workflow-cli>
+- This skill is bundled in the CLI tarball — no standalone repo. `agent-workflow self install-skill` copies it from the bundled location to `~/.claude/skills/agent-workflow/`.
+- Install: `npm i -g @tacuchi/agent-workflow-cli && agent-workflow self install-skill`

package/skills/agent-workflow/docs/TEST-PLAN.md

@@ -0,0 +1,163 @@
+# Test plan — Workflow universal (CLI agent-workflow + skill agent-workflow)
+
+Specs (no implementación). Validan los 3 contratos arquitecturales.
+
+Generable a `skills/agent-workflow/docs/TEST-PLAN.md` para que cualquier consumidor del workflow tenga la batería de aceptación.
+
+## Convenciones
+
+- Cada test tiene: id, contrato, precondición, pasos, criterio de éxito, frontera (lo que NO valida).
+- Estados esperados expresados como JSON observable o efectos de filesystem.
+- Implementación recomendada: vitest (unit/golden) para Contract A; bash/CI smoke para Contract B; bash + namespace alterno para Contract C.
+
+## Contract A — CLI ↔ skill
+
+Cada comando que el skill referencia ejecuta y devuelve la forma JSON declarada por la reference.
+
+### A1 — Surface match
+
+- **Precondición**: CLI instalado globalmente, skill instalado en `~/.claude/skills/agent-workflow`.
+- **Pasos**:
+  1. Listar comandos del CLI (`agent-workflow --help`).
+  2. Para cada comando: parse top-level del SKILL.md y de las 11 references; verificar que aparece exactamente en 1 reference.
+- **Criterio**: 43 comandos listados, 43 menciones en exactamente 1 reference cada uno. 0 huérfanos.
+- **Frontera**: no valida la forma del JSON ni la implementación de cada comando.
+
+### A2 — JSON contract por comando
+
+- **Precondición**: workspace de prueba con `qtc-PROJECT` block y al menos una sesión.
+- **Pasos** (por cada comando read-only):
+  1. Ejecutar `agent-workflow <cmd> [flags] | jq '.'`.
+  2. Validar que `jq` retorna 0 (JSON parseable).
+  3. Validar que las claves top-level matchean lo declarado en la reference.
+- **Criterio**: 100% de comandos read-only retornan JSON parseable con shape declarado.
+- **Frontera**: no valida correctness semántica de los valores (solo shape).
+
+### A3 — Error envelope
+
+- **Precondición**: workspace donde el namespace activo no existe.
+- **Pasos**:
+  1. Correr `agent-workflow --namespace invalid sessions`.
+  2. Capturar stdout + stderr + exit code.
+- **Criterio**: exit code ≠ 0, stderr o stdout incluye `error.code = "NOT_IN_WORKSPACE"` (o equivalente declarado).
+- **Frontera**: no valida cobertura exhaustiva de error codes.
+
+## Contract B — Skill ↔ usuario externo
+
+Una empresa nueva (sin plugins QTC) instala skill + CLI y completa un workflow E2E sin tocar plugins.
+
+### B1 — Install path
+
+- **Precondición**: máquina sin `agent-workflow` ni skill instalado.
+- **Pasos**:
+  1. `npm install -g @tacuchi/agent-workflow`.
+  2. `agent-workflow self install-skill`.
+  3. `agent-workflow self doctor`.
+- **Criterio**: doctor reporta `cli_version >= 1.2.0`, `skill.installed = true`, `skill.path` apunta al directorio correcto.
+- **Frontera**: no valida ediciones de `~/.claude/settings.json` ni hook registration.
+
+### B2 — Workflow E2E (fresh namespace)
+
+- **Precondición**: directorio `/tmp/acme-test` vacío, `git init` ejecutado.
+- **Pasos**:
+  1. `cd /tmp/acme-test && agent-workflow --namespace acme project-md-upsert --init`.
+  2. `agent-workflow --namespace acme session-create --flow dev --name first-feature --objetivo "Implementar lo que sea"`.
+  3. `agent-workflow --namespace acme tasks-data --code session001`.
+  4. `agent-workflow --namespace acme checkpoint-write --code session001`.
+  5. `agent-workflow --namespace acme checkpoint-read --code session001`.
+  6. `agent-workflow --namespace acme session-close --code session001`.
+- **Criterio**:
+  - Tras paso 1: `CLAUDE.md` (o `AGENTS.md`) contiene bloque `<!-- ACME-PROJECT-START -->`.
+  - Tras paso 2: directorio `.acme/sessions/session001-dev-first-feature/` con `OBJETIVO.md`.
+  - Tras paso 6: `HISTORY.md` muestra fila con state = closed.
+- **Frontera**: no valida invocación desde Claude Code real (eso es B3).
+
+### B3 — Skill consumption en Claude Code (manual)
+
+- **Precondición**: B1 + B2 ejecutados; Claude Code abierto en `/tmp/acme-test`.
+- **Pasos**:
+  1. Pedirle al modelo: "create a session for fixing the login bug".
+  2. Observar si el modelo invoca el skill `agent-workflow`.
+  3. Observar comandos ejecutados por el modelo.
+- **Criterio**: el modelo lee SKILL.md, identifica `session-create`, lo ejecuta con namespace correcto.
+- **Frontera**: depende de que la SessionStart del entorno setee `AW_NAMESPACE` o el modelo use `--namespace`.
+
+## Contract C — Plugins QTC sin lógica universal
+
+El workflow universal opera con namespace alternativo (sin plugins QTC) y produce resultados equivalentes.
+
+### C1 — Equivalencia operacional
+
+- **Precondición**: workspace QTC real (con plugins instalados) + workspace alternativo "vanilla" (sin plugins, con bloque `<NS>-PROJECT` propio).
+- **Pasos**: ejecutar la misma secuencia (`session-create → tasks-data → checkpoint-write → session-close`) en ambos workspaces, con namespaces respectivos.
+- **Criterio**: ambos generan estructuras isomorfas (`.<ns>/sessions/sessionNNN-dev-<slug>/OBJETIVO.md` + fila en `HISTORY.md` + bloque `<NS>-PROJECT` actualizado). Diferencias permitidas: contenido de `OBJETIVO.md` (texto), header del bloque project (`QTC-PROJECT` vs `ACME-PROJECT`).
+- **Frontera**: no valida los skills de negocio QTC (coding-standards, sql-organizer) — esos son específicos del namespace.
+
+### C2 — Plugins QTC no implementan lifecycle
+
+- **Precondición**: repos `qtc-core/dev/design/analyze` accesibles.
+- **Pasos**:
+  1. `grep -rn "def session_create\|function sessionCreate\|create_session" qtc-{core,dev,design,analyze}/skills/` (debe retornar 0 hits).
+  2. `find qtc-{core,dev,design,analyze} -name "*.py"` (debe retornar 0 archivos).
+  3. Para cada hook en `hooks.json`: validar que invoca `agent-workflow ...` (no script local).
+- **Criterio**: 0 funciones de lifecycle, 0 archivos Python, 100% de hooks invocan al CLI.
+- **Frontera**: no valida que los skills de negocio sean correctos — solo que no duplican lógica universal.
+
+### C3 — `AW_NAMESPACE` propagation
+
+- **Precondición**: nuevo Claude Code session en workspace QTC.
+- **Pasos**:
+  1. Esperar SessionStart hook.
+  2. Verificar `cat ~/.config/agent-workflow/namespace`.
+  3. Correr `agent-workflow self namespace`.
+- **Criterio**: archivo contiene `qtc`, comando reporta `{ namespace: "qtc", source: "user-config" }` (o "workspace" si v1.2.0 detectó bloque local).
+- **Frontera**: no valida cómo otros plugins (no-QTC) propagan su namespace.
+
+## Contract D — Hooks (cobertura faltante en tests del CLI)
+
+Estos tests cierran H4 (gap de tests existentes en agent-workflow/tests/).
+
+### D1 — `hook branch-check`
+
+- **Precondición**: workspace con sesión que declara `expected_work_branch = main`; checkout en `feature/x`.
+- **Pasos**: `echo '{"tool_input":{"file_path":"src/foo.ts"}}' | agent-workflow hook branch-check`.
+- **Criterio**: exit 2 (block), stdout JSON con `{ match: false, expected: "main", current: "feature/x" }`.
+- **Frontera**: no valida MultiEdit/NotebookEdit (covered por Anthropic harness).
+
+### D2 — `hook sql-mutation-guard`
+
+- **Precondición**: payload de MCP con SQL DML.
+- **Pasos**: `echo '{"tool_input":{"sql":"UPDATE foo SET x=1"}}' | agent-workflow hook sql-mutation-guard`.
+- **Criterio**: exit 2, stdout JSON con `{ blocked: true, reason: "DML detected" }` (o equivalente).
+- **Frontera**: no valida SELECT/EXPLAIN (deben pasar — cubrir en D2.b).
+
+### D3 — `mcp dbhub` smoke
+
+- **Precondición**: DSN persistido vía `bootstrap-dsn`.
+- **Pasos**: `agent-workflow mcp dbhub cert` con stdin/stdout MCP frame de `initialize`.
+- **Criterio**: el binario lanza `@bytebase/dbhub` vía npx y devuelve respuesta MCP válida.
+- **Frontera**: no valida queries ejecutadas (las hace dbhub).
+
+### D4 — `plugin-doctor`
+
+- **Precondición**: plugin root válido (ej. `qtc-core`).
+- **Pasos**: `agent-workflow plugin-doctor --plugin-root /Users/tacuchi/Git/core-workflow-plugin`.
+- **Criterio**: JSON con `status: "ok"` o `findings: []`. Si manifests no declaran `exportedSkills`, dejar warning explícito (no error).
+- **Frontera**: no valida correctness de los skills exportados — solo presencia.
+
+## Resumen
+
+| Contract | Tests | Severidad |
+|---|---|---|
+| A — CLI ↔ skill | 3 (A1, A2, A3) | crítica |
+| B — Skill ↔ usuario externo | 3 (B1, B2, B3) | alta |
+| C — Plugins QTC sin lógica universal | 3 (C1, C2, C3) | alta |
+| D — Hooks gap | 4 (D1, D2, D3, D4) | media |
+| **Total** | **13 specs** | |
+
+Implementación recomendada (no en alcance):
+- A1, A2, A3 → vitest unit en `agent-workflow/tests/unit/`.
+- B1, B2 → bash + golden fixtures en `agent-workflow/tests/golden/external-namespace.test.ts`.
+- B3 → manual + grabado en `skills/agent-workflow/MANUAL-FUNCIONAL.md`.
+- C1, C2, C3 → bash + workspace fixture comparativo.
+- D1..D4 → vitest unit con stdin mock + spawn snapshot.

package/skills/agent-workflow/references/checkpoint.md

@@ -0,0 +1,59 @@
+# Checkpoint
+
+CHECKPOINT.md is the single artifact that lets a fresh conversation resume work without re-exploring the codebase. It is written before `/compact` (PreCompact hook) or at session end (SessionEnd hook), and read on resume.
+
+## checkpoint-read
+
+Read `CHECKPOINT.md` of the active (or specified) session.
+
+```bash
+agent-workflow checkpoint-read
+agent-workflow checkpoint-read --code session035
+```
+
+Returns the raw markdown payload plus parsed metadata (phase, last-updated, refs).
+
+## checkpoint-write
+
+Write a CHECKPOINT.md draft for the active (or specified) session. Includes the canonical sections (Lo último que hice / Próximo paso / Decisiones recientes / Archivos tocados / Contexto crítico / Refs).
+
+```bash
+agent-workflow checkpoint-write
+agent-workflow checkpoint-write --code session035
+agent-workflow checkpoint-write --force          # overwrite even if recent
+```
+
+Flags: `--code <sessionNNN>`, `--force`.
+
+The output is intentionally a *draft*: the AI typically fills in the placeholder sections (`_[AI: ...]_`) with the real content before the file is committed.
+
+## compress-checkpoint
+
+Identify long artifacts that should be compressed before checkpoint generation (HALLAZGOS.md, EVIDENCIA.md, DISCOVERY.md, etc.). Returns a list of files exceeding the threshold so you can summarize them in place.
+
+```bash
+agent-workflow compress-checkpoint --code session035
+agent-workflow compress-checkpoint --code session035 --threshold 12000   # bytes
+```
+
+Flags: `--code <sessionNNN>`, `--threshold <bytes>` (default ~10000).
+
+## resume-summary
+
+Compact resume payload for the PostCompact hook. Returns the minimal information needed to greet the user with "Resumen — sesión activa: ..." right after `/compact`.
+
+```bash
+agent-workflow resume-summary
+```
+
+No flags. Reads the active session and its CHECKPOINT.md (if present).
+
+## auto-compact-on-close
+
+SessionEnd hook target. Walks every active session and writes a checkpoint for each.
+
+```bash
+agent-workflow auto-compact-on-close
+```
+
+You should rarely call this manually; it is wired into the host harness via the SessionEnd hook configured by the plugin's installer.

package/skills/agent-workflow/references/dev-only.md

@@ -0,0 +1,50 @@
+# Dev-only utilities
+
+Operational helpers for plugin authors and harness diagnostics. Not part of the everyday session flow.
+
+## harness
+
+Detect which host harness is running the CLI: `claude-code`, `codex`, or `unknown`.
+
+```bash
+agent-workflow harness
+```
+
+Output:
+
+```json
+{ "harness": "claude-code", "evidence": ["env:CLAUDE_PROJECT_DIR"] }
+```
+
+## profiles
+
+Resolve user preferences from the namespace's `user-config.md`.
+
+```bash
+agent-workflow profiles
+```
+
+Returns the parsed key-value preferences (e.g. `delegate_to_subagent`, `compact_threshold`).
+
+## logs
+
+View or clear the CLI log file.
+
+```bash
+agent-workflow logs                # dump full log
+agent-workflow logs --tail 50      # last 50 lines
+agent-workflow logs --clear        # truncate
+```
+
+The log file lives at `~/.<namespace>/lib/logs/agent-workflow.log` (or equivalent for the resolved namespace).
+
+## next-number
+
+Compute the next NNN correlative for a directory. Used by `session-create` and the SQL release tooling, but available standalone for plugin authors building their own correlatives.
+
+```bash
+agent-workflow next-number /path/to/sessions
+agent-workflow next-number .qtc/sessions
+```
+
+The directory argument is positional (not a flag).

package/skills/agent-workflow/references/doctor.md

@@ -0,0 +1,61 @@
+# Doctor / release / scan / graduate
+
+Diagnostics and release-prep commands. Read-only by default (`graduate` writes documentation, not code).
+
+## plugin-doctor
+
+Health check for a plugin: validates frontmatter, manifest version, hooks, MCP entries, and exported skills.
+
+```bash
+agent-workflow plugin-doctor --plugin-root /Users/me/Git/core-workflow-plugin
+agent-workflow plugin-doctor --plugin-root /path --plugin-name qtc-core --plugin-version 3.24.0
+agent-workflow plugin-doctor --plugin-root /path --compat-range "^3.0.0"
+agent-workflow plugin-doctor --plugin-root /path --exports-file plugin.json
+```
+
+Exits 1 when validation fails; 0 when clean.
+
+## code-scan
+
+Scan files for release-critical patterns: hardcoded `localhost`, exposed secrets, TODO/FIXME markers, debug prints, etc. Used by the release skill.
+
+```bash
+agent-workflow code-scan
+agent-workflow code-scan --since 2026-04-01            # only files changed since date
+agent-workflow code-scan --source core                 # restrict to one declared source
+```
+
+## release-data
+
+Consolidated dump for the release / release-scripts skills: which sessions are graduated, which scripts ship, etc.
+
+```bash
+agent-workflow release-data
+agent-workflow release-data --since 2026-04-01
+agent-workflow release-data --source core
+agent-workflow release-data --include-graduated
+agent-workflow release-data --no-open --no-closed --skip-content   # narrow scope
+agent-workflow release-data --verbose
+```
+
+## graduate
+
+Promote a session-local artifact (DEC-NNN, TASKS, RFC, design entrega) into a workspace-level `docs/` location.
+
+```bash
+# Graduate a decision DEC-005 from session023
+agent-workflow graduate --kind decision --session session023 --id DEC-005 --slug auto-plan-thresholds
+
+# Graduate the full plan
+agent-workflow graduate --kind plan --session session023 --slug cli-npm-agent-workflow
+
+# Graduate an analyze RFC / data / postmortem
+agent-workflow graduate --kind rfc --session session022 --slug cli-npm-agent-workflow
+agent-workflow graduate --kind data --session session004 --slug precarga-objetos-bd
+agent-workflow graduate --kind postmortem --session sessionNNN --slug incident-foo
+
+# Graduate a design entrega
+agent-workflow graduate --kind design --session sessionNNN --slug system-foo
+```
+
+Required: `--kind`, `--session`, plus `--id` (decisions) or `--slug` (everything else).

package/skills/agent-workflow/references/history.md

@@ -0,0 +1,40 @@
+# History
+
+`<workspace>/.<namespace>/HISTORY.md` is a markdown table that lists every session in the workspace. Two CLI commands maintain it.
+
+## history-data
+
+Read-only aggregator. Walks the `.<namespace>/sessions/` tree and returns the data you would need to (re)build `HISTORY.md` from scratch, plus optional graduated-doc references.
+
+```bash
+agent-workflow history-data
+agent-workflow history-data --verbose
+agent-workflow history-data --include-docs   # also enumerate docs/scripts, docs/rfcs, etc.
+```
+
+Use this to detect drift between `HISTORY.md` and the on-disk session folders, or when you need to regenerate the table.
+
+## history-update
+
+Upsert a row in `HISTORY.md`. Used by `session-create` and `session-close` internally; you typically only invoke it directly to repair a row.
+
+```bash
+agent-workflow history-update \
+  --code session035 \
+  --state active \
+  --sesion "aw-skill-repo" \
+  --date 2026-05-05 \
+  --summary "Sub-proyecto 2 del spec ..." \
+  --refs "[OBJETIVO](.qtc/sessions/session035-dev-aw-skill-repo/OBJETIVO.md)"
+```
+
+Flags:
+
+| Flag | Notes |
+|---|---|
+| `--code <sessionNNN>` | Required. |
+| `--state <active\|closed>` | Required. |
+| `--sesion <slug>` | Visible session slug (without `sessionNNN-flow-` prefix). |
+| `--date <YYYY-MM-DD>` | Defaults to today if omitted in some callers; pass explicitly to be safe. |
+| `--summary <text>` | Replaces the Resumen cell. |
+| `--refs <markdown>` | Replaces the Refs cell. |

package/skills/agent-workflow/references/hooks.md

@@ -0,0 +1,35 @@
+# Hooks
+
+Hook targets the host harness invokes via `PreToolUse` / `SessionEnd` / `PostCompact` events. Each hook reads JSON on stdin, may print a message on stderr, and returns a meaningful exit code.
+
+You rarely call these by hand — they are wired into `hooks.json` by the plugin installer. Document them here so the AI knows what to expect when a hook fires.
+
+## hook branch-check
+
+PreToolUse guard for `Edit` / `Write`. Reads the tool input from stdin, resolves the target file, finds the owning source by path, and verifies the current branch matches the declared work branch.
+
+```bash
+echo '{"tool":"Edit","tool_input":{"file_path":"/path/to/file"}}' \
+  | agent-workflow hook branch-check
+```
+
+Exit codes:
+
+| Code | Meaning |
+|---|---|
+| 0 | Branch matches expected (silent). |
+| 0 + stderr | Warning logged, but proceed. |
+| Non-zero | Block the tool call. |
+
+## hook sql-mutation-guard
+
+PreToolUse guard for MCP SQL execution tools. Reads the tool input, matches against the runtime config's `mcpGuards.sqlMutation` patterns, and blocks `INSERT`/`UPDATE`/`DELETE`/DDL against the configured "no-mutate" servers.
+
+```bash
+echo '{"tool":"mcp__plugin_qtc-dev_qtc-cert__execute_sql","tool_input":{"sql":"UPDATE x SET ..."}}' \
+  | agent-workflow hook sql-mutation-guard
+```
+
+The patterns live in `~/.<namespace>/lib/config/<namespace>-runtime.json` — for the `qtc` namespace this blocks mutations against `qtc-cert` and `qtc-prod`.
+
+Exit codes: same conventions as `branch-check`.

package/skills/agent-workflow/references/mcp.md

@@ -0,0 +1,31 @@
+# MCP / DSN
+
+CLI helpers for MCP server lifecycle and the DSN bootstrap shared by qtc-* hooks.
+
+## mcp dbhub <instance>
+
+Launch the `@bytebase/dbhub` MCP server pre-wired with the namespace's DSN file. The CLI resolves the DSN, sets up environment, and execs `npx @bytebase/dbhub` with the right transport.
+
+```bash
+agent-workflow mcp dbhub cert      # qtc-cert instance
+agent-workflow mcp dbhub prod      # qtc-prod instance
+```
+
+Instance names map to environment variables in `~/.<namespace>/lib/dsn.env`:
+
+| Instance | Reads | Default behavior on missing DSN |
+|---|---|---|
+| `cert` | `DB_CERT_DSN` | stderr message, exit 1 |
+| `prod` | `DB_PROD_DSN` | stderr message, exit 1 |
+
+The launcher is the entry point referenced by the plugin's `.mcp.json`. You usually do not invoke it manually — Claude Code / Codex starts it.
+
+## bootstrap-dsn
+
+Persist `DB_CERT_DSN` and `DB_PROD_DSN` from the current shell into the namespace's `dsn.env` file (so subsequent CLI / hook invocations have them).
+
+```bash
+DB_CERT_DSN=postgres://... DB_PROD_DSN=postgres://... agent-workflow bootstrap-dsn
+```
+
+Exit code 2 + `MISSING_DSN` error when neither DSN is set. Writes to `~/.<namespace>/lib/dsn.env`.

package/skills/agent-workflow/references/objetivo-tasks.md

@@ -0,0 +1,64 @@
+# Objetivo / Tasks / Decisions
+
+Read-only parsers for the four canonical session artifacts.
+
+| Artifact | Reader | Purpose |
+|---|---|---|
+| `OBJETIVO.md` | `objetivo-data` | requirement, type, modalidad, criterios |
+| `TASKS.md` | `tasks-data` | open/closed counts, item list, optional verbose body |
+| `DECISIONES.md` | `decisiones-list` | DEC-NNN headers + previews |
+| `DEPENDENCIAS.md` | `dependencias-list` | dependency table rows |
+
+All four accept `--code <sessionNNN>`. Without it, the active session is used (errors if there are 0 or >1 active sessions).
+
+## objetivo-data
+
+Parses `OBJETIVO.md` into structured JSON: requirement, contexto, criterios de aceptación (with checked/unchecked state), tipo (`feature`/`refactor`/`bugfix`), modalidad (`tecnica`/`datos`/`incidente`), temas.
+
+```bash
+agent-workflow objetivo-data --code session035 | jq '.criterios_aceptacion'
+agent-workflow objetivo-data --code session035 | jq '.tipo'
+```
+
+## tasks-data
+
+Parses `TASKS.md` into open/closed counts plus the full item list. Supports phased plans (`## Phase X — Title` sections) and surfaces them as task groups.
+
+```bash
+agent-workflow tasks-data --code session035
+agent-workflow tasks-data --code session035 --only-open    # filter completed items
+agent-workflow tasks-data --code session035 --verbose      # include raw markdown body
+```
+
+Output:
+
+```json
+{
+  "code": "session035",
+  "counts": { "total": 22, "open": 22, "closed": 0 },
+  "phases": [
+    { "name": "Phase 0 — Mapeo+Contrato", "open": 4, "closed": 0 },
+    ...
+  ],
+  "items": [
+    { "id": "T0.1", "phase": "Phase 0", "text": "...", "done": false }
+  ]
+}
+```
+
+## decisiones-list
+
+Lists `DECISIONES.md` entries — DEC-NNN headers with short previews. Pass `--full` to include the full body of each decision.
+
+```bash
+agent-workflow decisiones-list --code session023
+agent-workflow decisiones-list --code session023 --full
+```
+
+## dependencias-list
+
+Lists `DEPENDENCIAS.md` rows as JSON — useful when a session declares cross-source dependencies.
+
+```bash
+agent-workflow dependencias-list --code session035
+```