docs(workflow): invocation & arguments reference for every user-invocable skill

Closes #43

Author: gtrabanco

CHANGELOG.es.md

@@ -282,6 +282,7 @@ Cómo funciona el pinning realmente, **verificado** contra el CLI `skills`:
 #### `audit-docs`
 | Versión | Fecha | Tipo | Qué cambió |
 |---|---|---|---|
+| 2.0.1 | 2026-07-11 | parche | Añadido el `argument-hint: "[--fix]"` que faltaba en el frontmatter (el modo `--fix` existía en el cuerpo pero era invisible en los menús de los agentes) — parte de #43, la referencia de invocación y argumentos en `docs/workflow/SKILLS.md`. |
 | 2.0.0 | 2026-07-10 | mayor | **Cambio incompatible:** se elimina la sección `## Machine envelope` y su cláusula de emisión en el contrato de turno — el contrato del envelope se traslada a la capa de orquestación; `workflow-status` sigue siendo el único emisor en línea. Ver `docs/workflow/MIGRATION.md`. |
 | 1.7.0 | 2026-07-05 | menor | Nuevo check 13 — procedencia de docs generadas (solo cuando hay bloque `Docs site` declarado): las páginas con `generated-by: agentic-workflow/generate-docs` cuya `source-unit` ya no existe son huérfanas (MEDIA); las páginas cuya unidad mergeó después de su fecha `updated` con commits en sus rutas son obsoletas (BAJA). Bloque de disciplina del workflow renumerado a 10–14. |
 | 1.6.0 | 2026-07-05 | menor | Envelope máquina: cada invocación termina ahora con un bloque JSON fijo (state, unit, phase, pr, findings, blockers, dependencies, next + pista de tier de modelo) para orquestación programática — esquema en la skill interna `orchestration-envelope`, protocolo en `docs/workflow/ORCHESTRATION.md`. |

CHANGELOG.md

@@ -280,6 +280,7 @@ How pinning actually works, verified against the `skills` CLI:
 #### `audit-docs`
 | Version | Date | Type | What changed |
 |---|---|---|---|
+| 2.0.1 | 2026-07-11 | patch | Added the missing `argument-hint: "[--fix]"` frontmatter (the `--fix` mode existed in the body but was invisible in agents' slash menus) — part of #43, the invocation & arguments reference in `docs/workflow/SKILLS.md`. |
 | 2.0.0 | 2026-07-10 | major | **Breaking:** dropped the `## Machine envelope` section and its turn-contract emission clause — the envelope contract moved to the orchestration layer; `workflow-status` remains the sole inline emitter. See `docs/workflow/MIGRATION.md`. |
 | 1.7.0 | 2026-07-05 | minor | New check 13 — generated-docs provenance (only when a `Docs site` block is declared): pages carrying `generated-by: agentic-workflow/generate-docs` whose `source-unit` no longer exists are orphans (MEDIUM); pages whose unit merged after their `updated` date with commits on their subject paths are stale (LOW). Workflow-discipline block renumbered to 10–14. |
 | 1.6.0 | 2026-07-05 | minor | Machine envelope: every invocation now ends with a fixed JSON block (state, unit, phase, pr, findings, blockers, dependencies, next + model-tier hint) for programmatic orchestration — schema in the internal `orchestration-envelope` skill, protocol in `docs/workflow/ORCHESTRATION.md`. |

README.es.md

@@ -80,6 +80,11 @@ así que **nunca se requiere una skill de revisión externa**, en ningún agente
 con ningún modelo. Un único camino disciplinado:
 **design → plan → execute → review → audit → merge.**
 
+> Las formas de invocación y flags de cada skill (`--fix`, `--force`,
+> `--adversarial N`, `--next`, `--fullauto`, …) están catalogadas en la
+> [referencia de invocación y argumentos](docs/workflow/SKILLS.md#invocation--arguments-reference)
+> (en inglés; su traducción llega con [#37](https://github.com/gtrabanco/agentic-workflow/issues/37)).
+
 ### Configuración inicial
 
 | Skill            | Qué hace                                                                                                                                                                                                            |

README.md

@@ -78,6 +78,10 @@ engine, the `orchestration-envelope` contract, and the workflow's **own 9-skill
 review skill is ever required**, on any agent, with any model. One disciplined
 path: **design → plan → execute → review → audit → merge.**
 
+> Every skill's invocation forms and flags (`--fix`, `--force`,
+> `--adversarial N`, `--next`, `--fullauto`, …) are catalogued in the
+> [Invocation & arguments reference](docs/workflow/SKILLS.md#invocation--arguments-reference).
+
 ### Setup
 
 | Skill            | What it does                                                                                                                                                                                          |

docs/workflow/SKILLS.md

@@ -99,6 +99,31 @@ sensor, and the repo-only `bump-skill` maintenance helper.
 |---|---|
 | `bump-skill` | After editing a SKILL.md: bump `version:`, add CHANGELOG.md + CHANGELOG.es.md rows, update the README skill/model tables. Repo-only — its description keeps it from triggering in other projects |
 
+## Invocation & arguments reference
+
+Every user-invocable skill's invocation forms and what each argument/flag does
+— the human-readable mirror of each skill's `argument-hint` frontmatter.
+Brackets `[…]` = optional; `|` separates alternative forms. A skill invoked
+with no arguments uses the default stated here.
+
+| Skill | Invocation | Arguments & flags |
+|---|---|---|
+| `audit-docs` | `/audit-docs [--fix]` | No args: report-only, findings ranked by severity. `--fix`: additionally applies the **low-risk** fixes — docs are never rewritten without it (or an explicit user go-ahead). |
+| `audit-pr` | `/audit-pr [pr-number]` | Defaults to the current branch's PR. A number targets another PR. |
+| `bump-skill` | `/bump-skill` | No arguments — detects the edited `SKILL.md` files itself. Repo-maintenance only. |
+| `design-feature` | `/design-feature <idea \| NN-slug> [instruction]` | A raw idea → interview from zero. A bare existing `NN-slug` → **review mode**: prints a summary of what the feature will do and asks what to add/remove/change. `NN-slug + instruction` → applies the change directly, no questions, scoped to the instruction. Upsert always — the only from-zero reset is an explicit "delete and redesign" in the instruction. |
+| `execute-phase` | `/execute-phase <NN> [P<k>] \| --fix <n> [P<k>] \| [--force]` | `NN` alone → single-pass (XS/S SPEC-only features). `NN P<k>` → exactly one phase of an M/L feature. `--fix <n>` → implement the fix unit `docs/fix/<n>-*`. `--force` → override the dependency/status gate (user-only escape hatch; the override is recorded in `decisions.md`; the autopilot never passes it). |
+| `generate-docs` | `/generate-docs [NN-slug \| fix-n \| path/glob] [--review]` | Scope defaults to the current branch's diff vs the default branch; a slug/fix/path narrows or redirects it. `--review` → additionally export the most recent `review-change` report as a docs page (opt-in, never automatic). |
+| `init-workspace` | `/init-workspace [target-dir]` | Defaults to the current directory. On a repo that already has the scaffold it auto-switches to **upgrade mode** (proposes only the new/missing template blocks; additive-only). |
+| `log-session` | `/log-session [note]` | The optional note is prepended to the entry's Summary. |
+| `plan-feature` | `/plan-feature <NN-slug \| #N> \| --from-issue N \| --scaffold <slug> \| --next` | A slug or issue reference is auto-detected; flags force a path: `--from-issue N` (issue → scoped product half), `--scaffold <slug>` (straight to engineering-half scaffolding), `--next` (next roadmap entry). An undesigned feature (roadmap row below `defined`) → stops and redirects to `/design-feature` — no bypass flag. |
+| `plan-fix` | `/plan-fix <issue-number>` | Required. Drafts `docs/fix/<n>-<topic>/SPEC.md` on a fix branch and stops for review. |
+| `product-audit` | `/product-audit [path-or-area]` | Defaults to the whole product; a path/area narrows the sweep. Proposes only — never fixes. |
+| `review-change` | `/review-change [path-or-glob] [--adversarial N]` | Defaults to the current change (branch diff vs the default branch); a path widens/narrows. `--adversarial N` → N independent, context-clean, diff-only adversarial reviewers in parallel, findings merged and deduped (opt-in; auto-recommended for `L`/sensitive changes). |
+| `ship-roadmap` | `/ship-roadmap [--fullauto]` · `/ship-roadmap --continue [--fullauto]` | Default: opens PRs, the human merges. `--fullauto` → merges MERGE-READY PRs under the non-negotiable safety floors. `--continue` → resume an existing run by one stage (the external-driver loop re-invokes this). |
+| `triage-issue` | `/triage-issue <n> [n…]` | One or many issue numbers — batch runs produce independent verdicts plus one summary table. |
+| `workflow-status` | `/workflow-status [--json-only] [--last-envelope <json\|path>]` | Default: human summary + the machine envelope. `--json-only` → envelope only (driver mode). `--last-envelope` → the driver's persisted envelope as a crash-recovery **hint** (diffed against recomputed state; never authoritative). No argument passing on your agent? Paste the JSON in the message — the last fenced json block of the *request* is read as the hint. |
+
 ## Built-in companions (Claude Code)
 
 `/code-review` (correctness + simplification), `/security-review` (security pass),

skills/audit-docs/SKILL.md

@@ -1,7 +1,8 @@
 ---
 name: audit-docs
 user-invocable: true
-version: 2.0.0
+version: 2.0.1
+argument-hint: "[--fix]"
 author: "Gabriel Trabanco <gtrabanco@users.noreply.github.com>"
 license: MIT
 description: >