@tacuchi/agent-workflow-cli 20.23.0 → 20.24.0

package/skills/w/commands/export-reports.md

@@ -1,40 +1,24 @@
 ---
-description: Exports a bounded report from N sessions to docs/reports/ as a numbered Markdown document. Backed by `aw export-reports`, which owns the corpus, the numbering and the write. Explicit, separate step — never automatic.
+description: Use to promote findings from N sessions into ONE numbered Markdown report under docs/reports/. Read-only over sessions; `aw export-reports` owns the corpus, the numbering and the write. Never automatic.
 argument-hint: "[--sessions <ids>] [--since <YYYY-MM-DD>] [--source <alias>]"
-allowed-tools:
-  [
-    "Bash",
-    "Read",
-  ]
+allowed-tools: ["Bash", "Read"]
 ---
 
-# export-reports — export a report
-
-Promotes session findings into one numbered report under `docs/reports/`. Single-pass, read-only over sessions. **Transversal**: no flow, no loop, **never creates a session**.
-
 ## Run
 
-1. `aw export-reports prepare --format human [--sessions <a,b>] [--since <YYYY-MM-DD>] [--source <alias>]` (`--detail` prints the full response contract). Returns the corpus, the destination, the required shape and an `input_digest`.
-2. **Synthesize the deliverable.** Compose one JSON answer: `version`, `operation` and `input_digest` copied **verbatim**; `state: "proposed"`; `artifacts` with one `{ path, content }` per file, every path inside the destination the request declares. The `NNN` is consultative — `apply` reassigns it inside the lock.
-3. `echo '<json>' | aw export-reports validate --format human` → preview + `approval_digest`.
-4. **Confirm scope and destination with the user**, showing that preview.
-5. `echo '<json>' | aw export-reports apply --approval <digest> --format human`.
-
-Every rejection names its cause and one valid next action; nothing was written. Fix the answer and repeat from step 3.
-
-> **The CLI owns everything but the synthesis**: corpus selection and filters, numbering, the shape check, the write authorization and the atomic publication. Never write into `docs/` with a file tool — `Write` is deliberately not in `allowed-tools`. A dossier lands whole or not at all.
+1. `aw export-reports prepare --format human` (+ `--sessions`/`--since`/`--source`) → corpus, destination, shape, `input_digest`.
+2. Answer with one JSON: `version`/`operation`/`input_digest` **verbatim**, `state: "proposed"`, `artifacts` = `{ path, content }` per file, all inside the destination; `NNN` is advisory: `apply` renumbers.
+3. `echo '<json>' | aw export-reports validate --format human` → preview + `approval_digest`; confirm scope and destination with the user.
+4. `echo '<json>' | aw export-reports apply --approval <digest>`. On rejection nothing was written: fix and repeat step 3.
 
 ## What it produces
 
 - `docs/reports/NNN-<slug>-YYYY-MM-DD.md`: ONE document that declares its audience and its scope in the opening lines.
-- Does **not** mutate sessions, touch another `docs/` folder, or open/close loops.
-
-## Plan mode
+- Never write into `docs/` with a file tool: one pass, all or nothing, no session or loop created/touched.
+- Authoring ref: no longer loaded on the normal path.
 
-Run `aw export-reports prepare` (read-only) and describe the deliverable and the destination it would publish, without applying.
+## More context
 
-## Resources
+`aw context-plan --command export-reports --signal <s>` returns the extra documents a case needs; read exactly what it lists:
 
-- CLI: `aw export-reports prepare | validate | apply` (service `export-service` over `semantic-operation/`)
-- Report authoring reference: `../exports/export-reports/EXPORT.md` — no longer loaded on the normal path
-- Design reference: `docs/referencias/workflow-exports/README.md`
+- `authoring` — the report's structure or audience is not obvious from the material → [`../exports/export-reports/EXPORT.md`](../exports/export-reports/EXPORT.md), no longer loaded on the normal path

package/skills/w/commands/export-scripts.md

@@ -1,41 +1,24 @@
 ---
-description: Exports DB scripts (type-B SCRIPTS.sql) from N sessions to docs/scripts/ as a bundle with continuous forwards + rollback. Backed by `aw export-scripts`, which validates the bundle shape and NEVER executes SQL. Explicit, separate step — never automatic.
+description: Use to promote the type-B `SCRIPTS.sql` artifacts of N sessions into a docs/scripts/ bundle — continuous forwards plus rollback. `aw export-scripts` checks the bundle shape and NEVER executes SQL. Never automatic.
 argument-hint: "[--sessions <ids>] [--since <YYYY-MM-DD>] [--source <alias>]"
-allowed-tools:
-  [
-    "Bash",
-    "Read",
-  ]
+allowed-tools: ["Bash", "Read"]
 ---
 
-# export-scripts — export DB scripts
-
-Promotes the `SCRIPTS.sql` artifacts (type B — migrations) of N sessions from `.workflow/sessions/` into a bundle under `docs/scripts/`. Single-pass, read-only over sessions. **Transversal**: no flow, no loop, **never creates a session**.
-
 ## Run
 
-1. `aw export-scripts prepare --format human [--sessions <a,b>] [--since <YYYY-MM-DD>] [--source <alias>]` (`--detail` prints the full response contract). Returns the corpus, the destination, the required shape and an `input_digest`.
-2. **Synthesize the deliverable.** Compose one JSON answer: `version`, `operation` and `input_digest` copied **verbatim**; `state: "proposed"`; `artifacts` with one `{ path, content }` per file, every path inside the destination the request declares. The `NNN` is consultative — `apply` reassigns it inside the lock.
-3. `echo '<json>' | aw export-scripts validate --format human` → preview + `approval_digest`.
-4. **Confirm scope and destination with the user**, showing that preview.
-5. `echo '<json>' | aw export-scripts apply --approval <digest> --format human`.
-
-Every rejection names its cause and one valid next action; nothing was written. Fix the answer and repeat from step 3.
-
-> **The CLI owns everything but the synthesis**: corpus selection and filters, numbering, the shape check, the write authorization and the atomic publication. Never write into `docs/` with a file tool — `Write` is deliberately not in `allowed-tools`. A dossier lands whole or not at all.
+1. `aw export-scripts prepare --format human` (+ `--sessions`/`--since`/`--source`) → corpus, destination, shape, `input_digest`.
+2. Answer with one JSON: `version`/`operation`/`input_digest` **verbatim**, `state: "proposed"`, `artifacts` = `{ path, content }` per file, all inside the destination; `NNN` is advisory: `apply` renumbers.
+3. `echo '<json>' | aw export-scripts validate --format human` → preview + `approval_digest`; confirm scope and destination with the user.
+4. `echo '<json>' | aw export-scripts apply --approval <digest>`. On rejection nothing was written: fix and repeat step 3.
 
 ## What it produces
 
-- `docs/scripts/NNN-export-scripts-YYYY-MM-DD/`: `00-ROLLBACK.sql` and `README.md` (both required) + the forwards `NN-<nombre>.sql`, numbered **continuously from 01** — the CLI rejects a gap.
-- The AI **never executes** the SQL, and neither does the CLI: the bundle is for a human/DBA to apply.
-- Does **not** mutate sessions, touch another `docs/` folder, or open/close loops.
-
-## Plan mode
+- `docs/scripts/NNN-export-scripts-YYYY-MM-DD/`: `00-ROLLBACK.sql` and `README.md`, both required, + forwards `NN-<nombre>.sql` numbered **continuously from 01**; the CLI rejects a gap.
+- Neither the AI nor the CLI executes the SQL: the bundle is for a human or DBA to apply.
+- Never write into `docs/` with a file tool: one pass, all or nothing, no session or loop created/touched.
 
-Run `aw export-scripts prepare` (read-only) and describe the deliverable and the destination it would publish, without applying.
+## More context
 
-## Resources
+`aw context-plan --command export-scripts --signal <s>` returns the extra documents a case needs; read exactly what it lists:
 
-- CLI: `aw export-scripts prepare | validate | apply` (service `export-service` over `semantic-operation/`)
-- SQL bundle reference: `../exports/export-scripts/EXPORT.md` (rollback derivation, ordering) — no longer loaded on the normal path
-- Design reference: `docs/referencias/workflow-exports/README.md`
+- `authoring` — the rollback derivation or the ordering is not obvious from the material → [`../exports/export-scripts/EXPORT.md`](../exports/export-scripts/EXPORT.md), no longer loaded on the normal path

package/skills/w/commands/fix-git.md

@@ -1,5 +1,5 @@
 ---
-description: Use when a merge left conflicts to resolve. Backed by `aw fix-git`, which reads the three versions of each conflict, validates the semantic resolution and stages only files still in conflict. You supply the resolved content; the CLI decides which paths stay authorized and owns edit, stage and commit. Git-safe — the merge commit is a separate confirmed action, never push/--amend/--no-verify. Transversal (not a flow), no session, never touches docs/.
+description: Use when a merge left conflicts to resolve. `aw fix-git` hands you the three versions of each conflict, validates your resolution and owns edit, stage and commit. Git-safe, transversal, never touches docs/.
 argument-hint: "[--source <alias> | --path <ruta>]"
 allowed-tools:
   [
@@ -8,45 +8,34 @@ allowed-tools:
   ]
 ---
 
-# fix-git — merge-conflict resolver (transversal)
+# fix-git — merge conflicts
 
-Single-pass, **no loop, no session**, **never writes `docs/`**. **Workspace-agnostic**: any git repo, with or without `.workflow/`. User-facing output in the **user's language**.
+No loop, no session, never writes `docs/`. Any git repo, workspace or not. Output in the **user's language**.
 
-> **Hard floor — applies even if you read nothing beyond this file:**
->
-> 1. **You supply content; the CLI owns the effects.** Never edit a conflicted file, never `git add`, never `git commit` by hand — `Edit` is deliberately not in `allowed-tools`.
-> 2. **Only unambiguous resolutions.** Anything you cannot resolve on evidence is `state: "ambiguous"`, which the CLI turns into a question. Never guess a side.
-> 3. **The commit is a separate action**, always confirmed, and the message is proposed to the user first. Never `--no-verify`, `--amend` or push.
-> 4. **Never `git merge --abort` on your own** — propose it; the user decides.
+**Hard floor:**
 
-## Run
+1. **You supply content; the CLI owns the effects.** Never edit a conflicted file, never `git add` or `git commit` by hand.
+2. **Only unambiguous resolutions** — what evidence cannot settle is `state: "ambiguous"`; never guess a side.
+3. **The commit is separate**, always confirmed, message proposed first. Never `--no-verify`, `--amend` or push.
+4. **Never `git merge --abort` yourself** — propose it; the user decides.
 
-1. `aw fix-git prepare --format human [--source <alias> | --path <ruta>]` (`--detail` prints the response contract and the request size). Returns the merge direction (`theirs → ours`), the conflicted paths, their three index stages and their blob hashes.
-2. **Resolve each conflict from the three versions the request carries** — `base` (common ancestor), `ours` (HEAD) and `theirs` (the incoming branch). Read both sides' *intent*, not just their text: `ours`, `theirs`, a combination, or a rewrite that preserves both intents.
-3. Compose one JSON answer: `version`, `operation` and `input_digest` copied verbatim; `state: "proposed"`; `artifacts` with **one `{ path, content }` per conflicted file**, `content` being the complete resolved file with **no conflict markers**.
-   - Any file you cannot settle on evidence → `state: "ambiguous"` with `reason`. Nothing is written; present the choice to the user.
-   - A binary conflict is rejected by the CLI: propose `git checkout --ours|--theirs` to the user instead.
-4. `echo '<json>' | aw fix-git apply --format human [--source …]`. The invocation authorizes the write **because** the set is unambiguous and still current — a conflict another process resolved meanwhile fails as stale.
-5. **Propose the merge commit** to the user (canonical one-line format). On approval:
-   `aw fix-git commit --message "<mensaje>" --confirm [--source …]`.
+## Run
 
-Every rejection names its cause and one valid next action; nothing was written. Fix the answer and repeat from step 4.
+1. `aw fix-git prepare --format human [--source <alias> | --path <ruta>]` — merge direction (`theirs → ours`), conflicted paths, their three stages and blob hashes; inspector `aw merge-state`.
+2. Resolve each conflict from `base` (ancestor), `ours` (HEAD) and `theirs` (incoming) by *intent*, not text: one side, a combination, or a rewrite of both.
+3. One JSON answer: `version`, `operation`, `input_digest` verbatim, `state: "proposed"`, `artifacts` = one complete `{ path, content }` per conflicted file.
+   - Cannot settle it → `state: "ambiguous"` with `reason`, nothing written. Binary conflict → rejected; propose `git checkout --ours|--theirs`.
+4. `echo '<json>' | aw fix-git apply --format human [--source …]` — authorized while the set is unambiguous and current. A rejection names its cause and next action; nothing was written — fix and repeat.
+5. Propose the merge commit; on approval `aw fix-git commit --message "<mensaje>" --confirm`.
 
-> **No merge in progress?** If the user explicitly asked to merge a branch, run `git -C <path> merge <branch>` and continue. Otherwise report there is nothing to resolve and stop.
+> **No merge in progress?** User asked to merge a branch → run `git -C <path> merge <branch>` and continue; otherwise say nothing is left to resolve.
 
 ## What the CLI decides (do not re-derive)
 
-- **Which paths are writable**: exactly the files still unmerged. A path outside that set is rejected, not silently skipped.
-- **Whether the conflict is still yours**: the blob hashes seal the set; if it moved, `apply` fails stale instead of overwriting someone else's resolution.
-- **Whether the content is really resolved**: leftover `<<<<<<<` / `=======` / `>>>>>>>` is a rejection.
-- **Whether the merge can close**: `commit` refuses while any file stays unmerged.
-
-## Plan mode
-
-Run `aw fix-git prepare` (read-only), report **origin ↔ destination** and the per-file conflicts, and describe the resolution you would propose — without applying or committing.
+- **Writable paths**: only files still unmerged — anything else is rejected, and blob hashes seal the set: a moved conflict fails stale.
+- **Resolved**: leftover `<<<<<<<` / `=======` / `>>>>>>>` is a rejection.
+- **Can close**: `commit` refuses while a file stays unmerged.
 
-## Resources
+## More context
 
-- CLI: `aw fix-git prepare | apply | commit` (service `fix-git-service` over `semantic-operation/`) · `aw merge-state` (read-only inspector)
-- Reference: `../roles/git/ROLE.md` § *Merge-conflict resolution* — the reasoning about intent; the mechanics now live in the CLI
-- Design reference: `docs/referencias/workflow-skills/fix-git.md`
+`aw context-plan --command fix-git --signal <s>` returns the extra documents a case needs; read exactly what it lists.

package/skills/w/commands/generate-launch.md

@@ -1,5 +1,5 @@
 ---
-description: "(Re)generates the per-source launch scripts (.workflow/launch/<alias>/ — launch.json + run.sh + run.ps1) by detecting each source's stack and launch mode (interactive TUI vs server). Idempotent: pristine files regenerate, hand-edited ones are preserved (--force overwrites). Confirms the mode/command via structured-choice when it matters. Backed by `aw generate-launch --format human`. Transversal command (not a flow); no session, never touches docs/."
+description: "Use when the launch artifacts under `.workflow/launch/<alias>/` must be built or refreshed — a new start script, or a launch that runs the wrong way. Backed by `aw generate-launch`. Transversal, never writes `docs/`."
 argument-hint: "[--source <alias>] [--mode interactive|server] [--command <cmd>] [--force] [--dry-run]"
 allowed-tools:
   [
@@ -10,41 +10,22 @@ allowed-tools:
 
 # generate-launch — (re)generate source launch scripts (transversal)
 
-Single-pass, **no loop, no session**, **never writes `docs/`**. **Transversal** command (belongs to no SPEC / PLAN / QUICK flow). Everything user-facing (questions, summary) goes in the **user's language**.
-
-Rebuilds the launch artifacts the local-run flow uses (`.workflow/launch/<alias>/`). They are normally born on demand at the first launch; this command lets you build or refresh them explicitly — after adding a start script, changing `.env` profiles, or to fix a launch that runs the wrong way.
+Single-pass, no loop, no session, **never writes `docs/`**. **Transversal** (no flow). User-facing text in the **user's language**. Rebuilds `.workflow/launch/<alias>/` (launch.json + run.sh + run.ps1), otherwise born on demand at first launch.
 
 ## Run
 
-1. **Detect** — run `aw generate-launch --dry-run [--source <alias>]` to get, per source: `stack`, `launchable`, the detected `run` command, and the launch `mode` (`interactive` | `server`).
-2. **Confirm the launch (structured-choice)** — for each **launchable** source, confirm how it should run via *structured-choice* (recommended = the detected mode). Options:
-   - **Interactive** — the app owns the terminal (foreground, real TTY). Required by TUIs / REPLs / interactive CLIs.
-   - **Server** — background + log window (monitor live, close-to-stop). For dev servers and long-running services.
-   - **Custom command** — the user provides the exact run command (optional).
-
-   Batch the questions; skip when the answer is unambiguous. Never silently pick a mode the user might not want — the bug this guards: a **TUI launched as `server` shows no UI**, because its stdout is a pipe, not a TTY, so it falls back to help/CLI output.
-3. **Generate** — write with the confirmed choice: `aw generate-launch --source <alias> [--mode interactive|server] [--command "<cmd>"] [--force]`. Without `--mode`/`--command`, the heuristic default is used.
-4. **Report** — render a readable summary from the JSON (per source: `stack`, `launchable`, `mode`, `run`, per-file outcome `created` / `regenerated` / `preserved` / `overwritten`). Do **not** dump raw JSON. Report `unknown_aliases` / `missing_sources` when present. A non-launchable source is a genuine non-app (e.g. a docs/plugins repo); a real app that lands there is a detection gap worth reporting.
-
-## Detection (how "run the project locally" is derived)
-
-- **npm** — a run script first (`dev` > `start` > `serve`, → `server`); else a CLI/app entry (`bin` > `main`) run with `node`, **building first** (`npm run build`) when a `build` script exists — a TypeScript CLI runs from its compiled output (→ `interactive`).
-- **gradle** / **maven** — `./gradlew bootRun` / `./mvnw spring-boot:run` (`server`). **angular** — `npm start` (`server`).
-- **Launch mode** governs how the TUI "Lanzar" (and the wrapper) run the app: `interactive` = foreground, owns the TTY (the UI appears); `server` = backgrounded, output tee'd to the log. The heuristic guesses it; `--mode` overrides. A `build` step, when present, runs before the launch in both modes.
-
-## Behavior
-
-- **Idempotent** — a pristine generated file is refreshed; a hand-edited one (its hash marker no longer matches) is **preserved**. `--force` overwrites hand-edited files too (reported as `overwritten`).
-- **`--source <alias>`** (repeatable) restricts to the given sources; default = every declared source.
-- **`--mode interactive|server`** overrides the detected mode for the selected source(s).
-- **`--command "<cmd>"`** overrides the run command for a **single** selected source (self-contained: drops the auto build).
-- **`--dry-run`** classifies every file and writes nothing.
+1. **Detect** — `aw generate-launch --dry-run [--source <alias>]`. Per source: `stack`, `launchable`, the detected `run` and `mode` (`interactive` | `server`).
+2. **Confirm (structured-choice)** — per **launchable** source; recommended = the detected mode.
+   - **Interactive** — foreground, owns a real TTY. TUIs / REPLs / interactive CLIs.
+   - **Server** — background + log window (close-to-stop). Dev servers, services.
+   - **Custom command** — the user gives the exact run command (optional).
 
-## Plan mode
+   Batch questions; skip when unambiguous. Never silently pick a mode. The bug this guards: a **TUI launched as `server` shows no UI** — its stdout is a pipe, not a TTY, so it falls back to help output.
+3. **Generate** — `aw generate-launch --source <alias> [--mode interactive|server] [--command "<cmd>"] [--force]`.
+4. **Report** — from the JSON, per source: `stack`, `launchable`, `mode`, `run` and each file's outcome (`created` / `regenerated` / `preserved` / `overwritten`). Never dump raw JSON. Report `unknown_aliases` / `missing_sources`. A real app reported non-launchable is a detection gap worth naming.
 
-Run `aw generate-launch --dry-run` and report, per source, the detected `run` + `mode` and what it would create / regenerate / preserve — without writing any file or asking.
+## More context
 
-## Resources
+`aw context-plan --command generate-launch --signal <s>` returns the extra documents a case needs; read exactly what it lists:
 
-- CLI: `aw generate-launch` (service `generate-launch-service`; engine `source-launch-scripts-service`)
-- Related: the launch flow generates these on demand at the first launch; `/w:workspace-init` scaffolds nothing here.
+- `detection` — the CLI's automatic detection of how to run the project was wrong or ambiguous → [`../modules/LAUNCH-DETECTION.md`](../modules/LAUNCH-DETECTION.md)

package/skills/w/commands/persist.md

@@ -1,5 +1,5 @@
 ---
-description: Use when work already produced in this conversation (analysis, conclusions, a plan) should be saved into docs/ — classifies its shape and routes it. analysis → docs/research/ · requirement → spec draft (docs/specs) · plan → plan adoption (docs/plans). Backed by `aw persist`, which owns the inventory, the anti-duplicate check, the numbering, the destination and the write. Transversal (no flow, no loop, no session); records ## Origin + attribution.
+description: Use when work already produced in this conversation (analysis, conclusions, a plan) should be saved into docs/ — classifies its shape and routes it to research, spec draft or plan adoption. Backed by `aw persist`, which owns the inventory, numbering, destination and the write. Transversal: no flow, no loop, no session.
 argument-hint: [what to persist — empty = the conversation's latest finished deliverable]
 allowed-tools:
   [
@@ -10,7 +10,7 @@ allowed-tools:
 
 # persist — persist in-conversation work into `docs/`
 
-Captures **work already produced in this conversation** — with or without host-native features (a `/goal` run, plan mode, plain chat analysis) — and persists it into `docs/`, classified by shape. The explicit form of *direct no-flow authoring* (`../SKILL.md` § *Operating context*, row 3) and the doctrinal entry for **host as producer** (`../loops/CHASSIS.md` § *Adopted context*). The host→`docs/` counterpart of `export-*`.
+Captures **work already produced in this conversation** — with or without host-native features (a `/goal` run, plan mode, plain chat analysis) — and persists it into `docs/`, classified by shape. The host→`docs/` counterpart of `export-*`.
 
 > **Hard floor — applies even if you read nothing beyond this file:**
 >
@@ -28,39 +28,18 @@ Captures **work already produced in this conversation** — with or without host
 
 1. `aw persist prepare --format human` (`--detail` prints the full response contract). Returns the inventory of the three categories, the consultative numbering, the allowed destinations, the limits and an `input_digest`.
 2. **Classify and write.** Compose one JSON answer:
-   - `version`, `operation`, `input_digest` copied **verbatim** from the request;
-   - `state`: `proposed`, or `ambiguous` when the inventory already holds this work (explain in `reason` — the CLI turns that into a question, never a write);
-   - `decisions`: `{ category, slug, mode }`, plus `target` + `target_digest` when `mode` is `update`;
-   - `artifacts`: exactly one `{ path, content }`.
+   - `version`, `operation`, `input_digest` — copied **verbatim** from the request;
+   - `state` — `proposed`, or `ambiguous` when the inventory already holds this work (explain in `reason`; the CLI turns that into a question, never a write);
+   - `decisions` — `{ category, slug, mode }`, plus `target` + `target_digest` when `mode` is `update`;
+   - `artifacts` — exactly one `{ path, content }`.
 3. `echo '<json>' | aw persist validate --format human` → preview + `approval_digest`.
 4. **Confirm classification and destination** with the user via structured-choice, showing that preview.
 5. `echo '<json>' | aw persist apply --approval <digest> --format human`.
 
 Every rejection names its cause and one valid next action; nothing was written. Fix the answer and repeat from step 3.
 
-## Classification → routing
-
-| Shape | Signals | Category → destination |
-|---|---|---|
-| **Analysis / conclusions / design notes** | findings, comparisons, diagnoses, adjudications, recommendations | `research` → `docs/research/NNN-research-<slug>.md` |
-| **Requirement** | describes a *wish*: what should exist/change, acceptance criteria derivable | `spec` → `docs/specs/NNN-spec-<slug>.md`, born `status: draft`, `## Origin` = "adopted from host conversation" → offer `/w:spec-refine` |
-| **Plan** | already answers the *how*: phases/tasks/solution — e.g. the host plan-mode output | `plan` → `docs/plans/NNN-plan-<slug>.md` (adoption, [`plan-new`](plan-new.md) § *Input resolution* mode 4) → offer `/w:plan-refine` / `/w:plan-exec` |
-| Mixed / ambiguous | e.g. analysis that ends in a requirement | one `persist` per document, each confirmed; a research doc plus a spec draft that cites it is a valid split |
-
 Requires a **workspace** (`docs/` is the managed surface). Without one → degrade: propose `/w:workspace-init`.
 
-## `docs/research/` — the analysis home (owned by this command)
-
-`docs/research` hosts standalone analyses: neither spec nor plan, but worth keeping. Belongs to **no flow**; `export-*` never writes it; loops never read it implicitly (a flow uses it by **reference** — cited in a spec's `## Origin` or a quick prompt). It is git-shareable, unlike sessions (gitignored, machine-local, loop-owned), which makes it the exchange surface for **N agents analyzing the same situation**.
-
-> **Anti-duplicate is a decision, not an accident.** The inventory carries each existing document's summary and digest. Same work already there → `mode: "update"` (proving you saw the current bytes via `target_digest`) or `state: "ambiguous"` so the user chooses between updating and writing a sibling perspective. A second near-identical document is never created silently.
-
-## Plan mode
-
-Describe the classification, the destination and the document it would write. Running `prepare` is fine (read-only); never `apply`.
-
-## Resources
+## More context
 
-- CLI: `aw persist prepare | validate | apply` (service `persist-service` over `semantic-operation/`)
-- Siblings: the four `export-*` commands (session → `docs/`), same handshake
-- Design reference: `docs/referencias/workflow-skills/persist.md`
+`aw context-plan --command persist --signal classification` returns the routing table — which shape goes to `docs/research/`, which becomes a spec draft, which is a plan adoption — plus the anti-duplicate rule: [`../modules/PERSIST-ROUTING.md`](../modules/PERSIST-ROUTING.md). Read exactly what it lists.

package/skills/w/commands/plan-exec.md

@@ -1,5 +1,5 @@
 ---
-description: Use when a plan is ready to implement — this is where the real work happens: code edits, proposed SQL scripts, created tools. Starts or resumes the execution loop (plan-exec-loop) over an existing plan, phase by phase, validating each phase before closing it. Checks executability on entry; structural or functional deviations return to plan-refine / spec-refine. Git-safe (proposes commits, never push/--amend/--no-verify). Not for creating or refining the plan (plan-new / plan-refine).
+description: Use when a plan is ready to implement — the real work: code edits, proposed SQL scripts, created tools. Starts or resumes plan-exec-loop over docs/plans/PPP-plan-<slug>.md, phase by phase, validating each before closing it. Git-safe (proposes commits, never push/--amend).
 argument-hint: <docs/plans/PPP-plan-<slug>.md>
 allowed-tools:
   [
@@ -12,7 +12,7 @@ allowed-tools:
 
 # plan-exec — trampoline to the execution loop
 
-Starts or resumes `plan-exec-loop` (Layer 2), which executes the real work phase by phase — each phase a **verifiable state of the system**, not a batch of technical chores. The plan (`docs/plans/PPP-plan-<slug>.md`) is a living document the loop keeps updated: each `### Fn` carries its own `> Estado:` line (`pendiente` | `en ejecución` | `bloqueada` | `validada`) next to its task checkboxes.
+Starts or resumes `plan-exec-loop` (Layer 2), which executes the real work phase by phase — each phase a **verifiable state of the system**, not a batch of technical chores. The plan is a living document the loop keeps updated: each `### Fn` carries its own `> Estado:` line (`pendiente` | `en ejecución` | `bloqueada` | `validada`) next to its task checkboxes.
 
 > **Hard floor — applies even if you read nothing beyond this file:**
 >
@@ -23,37 +23,21 @@ Starts or resumes `plan-exec-loop` (Layer 2), which executes the real work phase
 
 ## Run the loop
 
-`plan-exec-loop` is **not** a skill invocable by name — it is this command's operating manual (a sibling doc in the bundle). **Load it and execute it end to end**:
+1. `aw context-plan --command plan-exec` — read exactly the documents it lists, in order.
+2. Follow the loop manual end to end, taking `$ARGUMENTS` as input: it checks executability on entry, executes phase by phase (git-safe, DB scripts-only), keeps the plan alive and reports.
 
-1. **Read** `../loops/plan-exec-loop/LOOP.md` (inside the installed `w` skill — e.g. `~/.claude/skills/w/loops/…`).
-2. **Follow** its instructions taking `$ARGUMENTS` as input: it detects CHECKPOINT/resume, executes phase by phase (git-safe, DB scripts-only), keeps the plan alive and reports.
+> `plan-exec-loop` is **not** a skill invocable by name — it is this command's operating manual. The command **is** the entry; the loop is its body. It is **resumable**: an existing CHECKPOINT continues from there.
 
-> Do not try `Skill: plan-exec-loop` — it is not registered as a skill. The command **is** the entry; the loop is its body.
+## Two gates that send work back
 
-## What the loop does (summary)
+- **Entry gate** — a plan that would force execution to invent its own structure is not run in silence. A minor gap is normalized **with your consent**; a structural one hands off to `/w:plan-refine`.
+- **Deviation gate** — local detail is resolved inline. A **structural** deviation (a contract, the participating components, the phase order, the simulation boundary) stops execution and returns to `/w:plan-refine`; a **functional** change (result, scope, business rule, acceptance criterion) returns to `/w:spec-refine`.
 
-- **Executability check on entry**: reads the plan **and its spec** and verifies each phase declares its result, its exit condition and its proof, and — **only when the change carries temporary behavior** — that its simulation boundary and retirement phase are identifiable. A minor gap is normalized **with your consent** (`Normalizar y ejecutar` | `Ir a plan-refine`); a structural one is recorded and handed off to `/w:plan-refine` — it never invents the plan's structure (see `../loops/plan-exec-loop/LOOP.md` § *Entry gate — executability*).
-- **Deviation gate**: local detail (a name, a helper, internal layout) is resolved inline. A **structural** deviation — a contract, the participating components, the phase order, the simulation boundary — stops execution and returns to `/w:plan-refine`; a **functional** change (result, scope, business rule, acceptance criterion) returns to `/w:spec-refine` (§ *Deviation gate*).
-- **Validation before closing each phase**: the phase's own proof plus the justified focused tests run first; the phase flips to `validada` only with the exit condition true and the review gate green — **never** just because its checkboxes are ticked (§ *Delta 4*). A proof that **cannot be run** (a migration nobody applied yet) leaves the phase `bloqueada`, with its reason on a `> Bloqueo:` line: the work stays ticked, the plan stays open, and the state only becomes `validada` once that proof runs and passes.
-- Reads and updates `docs/plans/PPP-plan-<slug>.md` (living doc: phase state, task checkboxes, deferrals).
-- Edits code in the workspace sources (a single execution session per run; execution is still phase by phase, there is just no session per phase).
-- If it creates a tool/utility, the ambient `creating-tools` skill documents it in `docs/tools/` (auto-discovered; Workline does not bind it).
-- **Closing review gate** at every phase boundary, **before proposing the commits**: re-reads the diff (independent pass) applying the **installed ambient conventions** and fixes or defers findings — nothing reaches a commit unreviewed (see `../loops/plan-exec-loop/LOOP.md` § *Delta 5*).
-- **Probe (PoC) tasks** run as throwaway code in the session folder — never committed; verdict recorded (`CONCLUSIONS`/`DECISION`), failed probes surface to the human (see `../loops/plan-exec-loop/LOOP.md` § *Delta 7*).
-- Proposes commits per source (git-safe: verifies the branch, proposes, never push/--amend/--no-verify).
-- Generates session artifacts (`DECISION`, `SCRIPTS.sql`) under `.workflow/sessions/`.
-- **Never exports** to `docs/scripts`, `docs/manuals`, `docs/diagrams`, `docs/reports` — the `export-*` do that as a separate step.
-- DB scripts (migrations) go to `SCRIPTS.sql` type B; the AI **never executes DML/DDL**, only read-only reads via MCP.
+## More context
 
-## Resumable
+`aw context-plan --command plan-exec --signal <s>` returns the extra documents a case needs; read exactly what it lists:
 
-Same pattern as the other loops: it detects an existing CHECKPOINT and continues from there.
-
-## Plan mode
-
-The skill describes, phase by phase, what it would execute, which files it would touch, and which commits it would propose, without applying changes.
-
-## Resources
-
-- Loop manual: `../loops/plan-exec-loop/LOOP.md`
-- Design reference: `docs/referencias/workflow-commands/plan-exec.md`
+- `db` — the plan touches a database → [`../modules/EXEC-DB-POLICY.md`](../modules/EXEC-DB-POLICY.md)
+- `probe` — a task is a PoC → [`../modules/EXEC-PROBE-TASKS.md`](../modules/EXEC-PROBE-TASKS.md)
+- `simulation` — **only when the change carries temporary behavior**, its boundary is declared and its retirement identified → [`../modules/SIMULATION-LIFECYCLE.md`](../modules/SIMULATION-LIFECYCLE.md)
+- `ui` — the plan references design SPECs → [`../modules/PLAN-DESIGN-SPECS.md`](../modules/PLAN-DESIGN-SPECS.md)

package/skills/w/commands/plan-new.md

@@ -1,5 +1,5 @@
 ---
-description: Use when a spec is ready to become an executable plan — not to refine an existing plan (plan-refine) nor execute one (plan-exec). Starts or resumes the planning loop (plan-new-loop) from a spec. Turns the "what" (spec) into the "how" (plan). Ideal input: an already refined docs/specs/NNN-spec-<slug>.md. Also adopts an externally-built plan (host plan mode, hand-written, another agent) as the plan-doc — mode 4 of its input resolution. May split into sibling plans (split gate).
+description: Use when a spec is ready to become an executable plan — not to refine one (plan-refine) nor execute one (plan-exec). Starts plan-new-loop from docs/specs/NNN-spec-<slug>.md, turning the "what" into the "how". Also adopts an externally-built plan. May split into sibling plans.
 argument-hint: <docs/specs/NNN-spec-<slug>.md | prompt>
 allowed-tools:
   [
@@ -21,49 +21,22 @@ SPEC → PLAN bridge. Turns the "what" (refined spec) into the "how" (plan). Del
 > 3. **Write boundary** — this flow writes only `docs/plans/…` (with confirmation if it exists); nothing else lands in `docs/`.
 > 4. **Language** — everything user-facing (questions, option labels, the plan's content) goes in the **user's language**.
 
-## Input resolution
-
-The skill evaluates `$ARGUMENTS` (specs live in place — `docs/specs/NNN-spec-<slug>.md`; locate via the `docs/specs/NNN-spec-*.md` glob or the exact path):
-
-1. **Ready spec** (`docs/specs/NNN-spec-<slug>.md` whose frontmatter declares `status: ready-for-plan`) → ideal. Proceed straight to `plan-new-loop`.
-2. **Spec not ready** (`status: draft` / `refining`, or no mark at all) → **soft-suggest** running `/w:spec-refine` first; planning over a solid spec produces better plans. It is a suggestion, **never a block**: the user may proceed. Questions the spec left with destination `PLAN` are this flow's **input**, not a reason to send it back.
-3. **prompt** (no spec referenced) → propose using the SPEC flow; **by default launch `/w:spec-new`** with that prompt to create the draft, and continue the natural flow from there.
-4. **External plan content** — the argument/conversation carries an **already-built plan** (host plan mode output, hand-written, another agent's) → **adopt it**. Single pass, **NO RESEARCH**: materialize as `docs/plans/PPP-plan-<slug>.md` (`aw next-number docs/plans`), normalized to the rich-plan schema (`../loops/plan-new-loop/LOOP.md` § *Delta 1*) with only what the source provides. `## Origin` = "adopted from <source>" + attribution (host · model · date). Then offer `/w:plan-refine` (closes schema gaps) or `/w:plan-exec`. Anti-duplicate: a plan whose `## Origin` matches this objective → recommend resuming it, never a second one. Adoption **never regenerates over** an existing plan-doc.
-
-> **Mode 3 vs 4:** a prompt that *describes a wish* → SPEC (mode 3); content that *already is a plan* → adopt (mode 4). Doctrine: `../loops/CHASSIS.md` § *Adopted context*.
-
-> **Ready vs not** is read from the spec's frontmatter `status`, never from the filename (there is no `-refined` anymore). **Legacy compat:** a spec with no frontmatter that carries `## Refinement decisions` — or the older `## Q&A traceability` — counts as ready the same way.
-
 ## Run the loop
 
-`plan-new-loop` is **not** a skill invocable by name — it is this command's operating manual (a sibling doc in the bundle). **Load it and execute it end to end**:
-
-1. **Read** `../loops/plan-new-loop/LOOP.md` (inside the installed `w` skill — e.g. `~/.claude/skills/w/loops/…`).
-2. **Follow** its instructions taking `$ARGUMENTS` as input (resolved per the 4 rules above): it detects state/resume, runs the gap-driven engine, creates and manages sessions, converges and reports. *(Mode 4 — adoption — is single-pass: materialize + offer the next step; no loop is started.)*
+1. `aw context-plan --command plan-new` — read exactly the documents it lists, in order.
+2. Follow the loop manual end to end, taking `$ARGUMENTS` as input (resolved per the module below): it detects state/resume, runs the gap-driven engine, manages sessions, converges and reports.
 
-> Do not try `Skill: plan-new-loop` — it is not registered as a skill. The command **is** the entry; the loop is its body.
+> `plan-new-loop` is **not** a skill invocable by name — it is this command's operating manual. The command **is** the entry; the loop is its body.
 
 ## Phases are functional states
 
-The plan is born with `### Fn` phases that each leave a **verifiable state of the system** — each with its `> Estado:` line, its primary evidence and its exit condition — never a list of files, classes or layers. The blocks beyond those are **conditional**: a phase with no temporary behavior gets no `Límite de simulación`, and one with nothing excluded gets no `Diferido` — a heading is never written empty to satisfy a template. The plan itself is born `> Estado: open` under the title; only `plan-exec` closes it. Contract: `../loops/plan-new-loop/LOOP.md` § *Phase contract (canonical)*.
-
-## Numbering notes
-
-The plan is named `docs/plans/PPP-plan-<slug>.md`. `aw next-number docs/plans` returns JSON (field `next` = `PPP`); the loop builds the full name (slug = short kebab-case from the Requirement: `[a-z0-9-]`, ≤ ~5 words / ≤ 40 chars). It does **not inherit the spec's `NNN`**. The link to the spec is established by reference (`## Origin` / "Derived from") in the plan, never by number.
-
-## UI → design SPECs
-
-If the plan **includes UI**, the loop composes the `ui-design` capability and produces per-screen **design SPECs** (`NNN-SPEC-<SLUG>.md`) as artifacts of its session — the plan's UI Tasks reference them (see `../loops/plan-new-loop/LOOP.md` § *Delta 4* and `../artifacts/artifacts-design/SPEC.md`).
-
-## Risky assumptions → probe (PoC) tasks
-
-When the plan rests on a runnable unknown (external connection, SDK, UI behavior), the loop encodes an **early probe task** — or runs an inline probe if the solution itself depends on the answer (see `../loops/plan-new-loop/LOOP.md` § *Delta 5*; doctrine: `../loops/CHASSIS.md` § *Proof of concept*).
-
-## Plan mode
+The plan is born with `### Fn` phases that each leave a **verifiable state of the system** — each with its `> Estado:` line, its primary evidence and its exit condition — never a list of files, classes or layers. The blocks beyond those are **conditional**: a phase with no temporary behavior gets no `Límite de simulación`, and one with nothing excluded gets no `Diferido` — a heading is never written empty to satisfy a template. The plan itself is born `> Estado: open`; only `plan-exec` closes it.
 
-The skill resolves the input per the 4 rules above and describes the loop actions it would run (mode 4: the plan-doc it would materialize), without starting the iteration or writing files.
+## More context
 
-## Resources
+`aw context-plan --command plan-new --signal <s>` returns the extra documents a case needs; read exactly what it lists:
 
-- Loop manual: `../loops/plan-new-loop/LOOP.md`
-- Design reference: `docs/referencias/workflow-commands/plan-new.md`
+- `input` — the argument is not plainly a `ready-for-plan` spec → [`../modules/PLAN-INPUT.md`](../modules/PLAN-INPUT.md)
+- `split` — the spec may need more than one plan → [`../modules/PLAN-SPLIT-GATE.md`](../modules/PLAN-SPLIT-GATE.md)
+- `ui` — the plan includes UI, so it composes `ui-design` → [`../modules/PLAN-DESIGN-SPECS.md`](../modules/PLAN-DESIGN-SPECS.md)
+- `probe` — the plan rests on a runnable unknown → [`../modules/PLAN-PROBE-TASKS.md`](../modules/PLAN-PROBE-TASKS.md)

package/skills/w/commands/plan-refine.md

@@ -1,5 +1,5 @@
 ---
-description: Use when a plan must become executable before running it — new requirements, scope tweaks, phases shaped as file lists, or a structural deviation returned by plan-exec. Not to generate one (plan-new) nor execute it (plan-exec). Starts or resumes plan-refine-loop, which re-shapes the plan in place into a sequence of verifiable functional states. Input: a docs/plans/PPP-plan-<slug>.md — from plan-new, hand-written or adopted. May extract tranches into sibling plans.
+description: Use when a plan must become executable before running it — new requirements, scope tweaks, phases shaped as file lists, or a structural deviation returned by plan-exec. Starts plan-refine-loop, which re-shapes docs/plans/PPP-plan-<slug>.md in place into verifiable functional states.
 argument-hint: <docs/plans/PPP-plan-<slug>.md>
 allowed-tools:
   [
@@ -12,9 +12,7 @@ allowed-tools:
 
 # plan-refine — trampoline to the plan refinement loop
 
-An **auxiliary, NOT mandatory** step of the PLAN flow: `spec-refine`'s twin, but over the **plan**. `plan-new` already produces a plan from the refined spec; `plan-refine` exists for when — **before executing** — changes arise (new requirements, scope adjustments, deps or risks spotted while re-reading the plan) worth incorporating without regenerating the plan from scratch.
-
-This command does not refine the plan itself: it delegates to `plan-refine-loop` (Layer 2), which iterates, closes gaps and edits the plan **in place**.
+`spec-refine`'s twin, over the **plan**. An **auxiliary, NOT mandatory** step: `plan-new` already produces a plan from the refined spec, and `plan-exec` runs **any** plan that is already executable. This exists for when changes arise before executing — new requirements, scope adjustments, deps or risks spotted while re-reading — worth incorporating without regenerating from scratch.
 
 > **Hard floor — applies even if you read nothing beyond this file:**
 >
@@ -23,47 +21,21 @@ This command does not refine the plan itself: it delegates to `plan-refine-loop`
 > 3. **Write boundary** — this flow edits only `docs/plans/…` (in place, with confirmation); nothing else lands in `docs/`.
 > 4. **Language** — everything user-facing (questions, option labels, the plan's content) goes in the **user's language**.
 
-> **Not mandatory.** `plan-exec` runs **any** plan that is already executable, refined or not — no gate requires passing through here. Use it when the plan needs adjustments before executing, or when execution cannot start without inventing structure.
->
-> **Spec-less plans (hand-written / adopted).** A plan with no source spec is legitimate input. The coherence gate **degrades gracefully**: criteria trace to the plan's own Final behavior block (in `## Solution`) / acceptance criteria instead of spec criteria — the "spec criteria uncovered" gap does not apply (see `../loops/plan-refine-loop/LOOP.md`).
-
-## Input resolution
-
-The skill evaluates `$ARGUMENTS` (plans live in place — `docs/plans/PPP-plan-<slug>.md`; locate via the `docs/plans/PPP-plan-*.md` glob or the exact path):
-
-1. **Existing plan** (`docs/plans/PPP-plan-<slug>.md`) → proceed to `plan-refine-loop` — **regardless of provenance**: generated by `plan-new`, hand-written, or adopted from a host planner (existence is the only requirement).
-2. **No plan** (the arg references no plan, or none exists) → **soft-suggest** running `/w:plan-new` first (there is nothing to refine yet); the user decides.
-3. **Returned by `plan-exec`** (its entry check found the plan unexecutable, or execution stopped on a structural deviation) → proceed to `plan-refine-loop` carrying that finding: phases already `validada` stay, only pending work is re-designed (see `../loops/plan-refine-loop/LOOP.md` § *Replanning executed work*).
-
-> **Expected output: an executable plan.** The loop converges on its **executability gate** — each phase a verifiable state with its evidence, its exit condition and, **only when the change carries temporary behavior**, its simulation boundary — so `plan-exec` implements it without inventing contracts, observable states, order or evidence.
-
 ## Run the loop
 
-`plan-refine-loop` is **not** a skill invocable by name — it is this command's operating manual (a sibling doc in the bundle). **Load it and execute it end to end**:
-
-1. **Read** `../loops/plan-refine-loop/LOOP.md` (inside the installed `w` skill — e.g. `~/.claude/skills/w/loops/…`).
-2. **Follow** its instructions taking `$ARGUMENTS` as input: it detects state/resume, runs the gap-driven engine, creates and manages sessions, converges and reports.
-
-> Do not try `Skill: plan-refine-loop` — it is not registered as a skill. The command **is** the entry; the loop is its body.
-
-## State resolution (resumable)
-
-The skill detects prior state before starting, **keying off the `CHECKPOINT`** (never a "refined" file):
-
-1. Find the plan's refinement session under `.workflow/sessions/` (descriptor `<slug>-plan-refine` + `## Origin`) and its `CHECKPOINT.md`.
-2. **In progress** (a CHECKPOINT exists) → continue from the recorded progress (resolved gaps, Q&A).
-3. **No progress** (no CHECKPOINT and the plan does **not** have `## Refinement decisions`) → start from zero reading the plan (`PPP-plan-*.md`).
-4. **Already refined / re-refine on demand** (no open CHECKPOINT but the plan **already has** that section) → **first-class operation**: while the flow stays in PLAN you can re-run `/w:plan-refine` over the same plan **as many times as needed** (new requirements, scope changes, re-reads). The loop does `create_or_resume` — it locates the existing refine session (even closed) and **reopens** it instead of duplicating — and re-refines reading the **plan itself**; on `Guardar`, edits in place with confirmation.
-
-## UI → design SPECs
+1. `aw context-plan --command plan-refine` — read exactly the documents it lists, in order.
+2. Follow the loop manual end to end, taking `$ARGUMENTS` as input: it detects state/resume, runs the gap-driven engine, manages sessions, converges and reports.
 
-If the refine **touches UI**, the loop composes `ui-design` and produces/updates **design SPECs** (`NNN-SPEC-<SLUG>.md`) in its own session — scoped to the new/changed screens — and re-points the plan references (see `../loops/plan-refine-loop/LOOP.md` § *Delta 4*).
+> `plan-refine-loop` is **not** a skill invocable by name — it is this command's operating manual. The command **is** the entry; the loop is its body.
 
-## Plan mode
+**Expected output: an executable plan.** The loop converges on its **executability gate** — each phase a verifiable state with its evidence, its exit condition and, **only when the change carries temporary behavior**, its simulation boundary — so `plan-exec` implements it without inventing contracts, observable states, order or evidence.
 
-The skill resolves the state and describes the actions the loop would run (gaps it would close, questions it would ask), without starting the iteration.
+## More context
 
-## Resources
+`aw context-plan --command plan-refine --signal <s>` returns the extra documents a case needs; read exactly what it lists:
 
-- Loop manual: `../loops/plan-refine-loop/LOOP.md`
-- Design reference: `docs/referencias/workflow-commands/plan-refine.md`
+- `input` — where this plan came from, and what a plan returned by `plan-exec` means → [`../modules/PLAN-INPUT.md`](../modules/PLAN-INPUT.md)
+- `resume` — a prior refinement of this plan may exist → [`../modules/PLAN-REFINE-KEYS.md`](../modules/PLAN-REFINE-KEYS.md)
+- `replan` — work already executed has to be re-planned around → [`../modules/REPLANNING.md`](../modules/REPLANNING.md)
+- `simulation` — the change carries temporary behavior, so **only when** it does, its boundary is declared → [`../modules/SIMULATION-LIFECYCLE.md`](../modules/SIMULATION-LIFECYCLE.md)
+- `ui` — the refine touches UI → [`../modules/PLAN-REFINE-DESIGN-SPECS.md`](../modules/PLAN-REFINE-DESIGN-SPECS.md)