@tacuchi/agent-workflow-cli 20.22.0 → 20.24.0

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

@@ -1,33 +1,41 @@
 ---
-description: Use when a merge or rebase left conflicts to resolve. Resolves the conflicts of an in-progress merge for a given or detected source. Identifies origin (theirs) and destination (ours), analyzes both sides' intent and resolves; asks (structured-choice) on ambiguity or incoherence. Git-safe — proposes the merge commit, never push/--amend/--no-verify. Transversal (not a flow), no loop, no session, never touches docs/. Works in any git repo, no initialized workspace required.
-argument-hint: "[<source path | alias>]"
+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:
   [
     "Bash",
     "Read",
-    "Edit",
   ]
 ---
 
-# fix-git — merge-conflict resolver (transversal)
+# fix-git — merge conflicts
 
-Single-pass, **no loop, no session**, **never writes `docs/`**. **Transversal** command (belongs to no SPEC / PLAN / QUICK flow). **Workspace-agnostic**: operates on any git repo — the given `<source>` (path or alias), or the cwd — without requiring `.workflow/`. Everything user-facing (questions, proposals, the report) goes 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:**
+
+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.
 
 ## Run
 
-1. **Detect + identify** — run `aw merge-state [<source>]` (read-only; `--source <alias>` or `--all` when a workspace exists; a direct path otherwise). From the JSON, per repo: `is_merging`, `current_branch` (**destination / ours**), `merge_origin` (**origin / theirs**), `conflicted_files`.
-   - If **no merge is in progress** (`is_merging:false`) and the user named a **target** (e.g. "merge `<branch>`"): that is an explicit request → `git -C <path> merge <branch>` and continue. No target → report there is no merge to resolve and stop.
-2. **Resolve** — **read and follow** the ***Merge-conflict resolution*** section of the `git` role (`../roles/git/ROLE.md`): analyze each conflict's intent (3 versions `git show :1:/:2:/:3:<file>`, `git log --merge`), resolve (ours / theirs / combine / rewrite) and `git add` what is resolved. On **ambiguity or incoherence**, ask via *structured-choice* (never invent the resolution).
-3. **Close** — **propose** the merge commit (propose-then-execute, canonical format, git-safe). Escape hatch: `git merge --abort` after user confirmation.
+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`.
 
-> Do not try `Skill: git` — the role is **read and followed** (it is the capability this command composes). The command **is** the entry; the conflict doctrine lives in the `git` role.
+> **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.
 
-## Plan mode
+## What the CLI decides (do not re-derive)
 
-Run `aw merge-state` (read-only), report **origin ↔ destination** and the per-file conflicts, and describe the **resolution strategy** you would apply — **without** editing files 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
 
-- Capability: `../roles/git/ROLE.md` (section *Merge-conflict resolution*)
-- CLI: `aw merge-state` (read-only merge-state inspector)
-- 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`. 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,101 +1,45 @@
 ---
-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). Transversal (no flow, no loop, no session); records ## Origin + attribution (host · model · date); anti-duplicate aware (update vs sibling perspective). The host→docs/ counterpart of export-*.
+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:
   [
     "Bash",
     "Read",
-    "Write",
-    "Edit",
   ]
 ---
 
 # 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. It is 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*).
+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:**
 >
 > 1. **Adopt, don't re-derive** — single pass, **NO RESEARCH**: transcribe/organize what the conversation already established. New investigation is flow work (`spec-refine`, `quick`), never this command's.
-> 2. **Confirm before writing** — classification and destination go through **structured-choice** (recommendation first). Never write `docs/` silently.
-> 3. **Numbering via `aw next-number docs/<category>`** (it creates the folder when missing) — never invent numbers. **Never creates sessions** (sessions are loop-created only).
-> 4. **Language** — headings in English (parse contract); content in the **user's language**.
+> 2. **You classify and write; the CLI decides everything else** — inventory, anti-duplicate, numbering, destination, authorization and the write itself belong to `aw persist`. Never write into `docs/` with a file tool here; `Write`/`Edit` are deliberately not in `allowed-tools`.
+> 3. **Never invent the number** — the `NNN` you put in the path is consultative; `apply` reassigns it inside the lock. Do not renumber it.
+> 4. **Confirm before writing** — classification and destination go through **structured-choice**; `apply` refuses without the digest `validate` returned. **Never creates sessions** (sessions are loop-created only).
+> 5. **Language** — headings in English (parse contract); content in the **user's language**.
 
 ## Input
 
-`$ARGUMENTS` names what to persist (or is empty → the conversation's most recent finished deliverable). The **source is the conversation itself**: what was analyzed, concluded, designed or planned up to this point. If nothing persistable exists yet, say so and stop — do not manufacture content.
+`$ARGUMENTS` names what to persist (or is empty → the conversation's most recent finished deliverable). The **source is the conversation itself**. If nothing persistable exists yet, say so and stop — do not manufacture content.
 
-## Classification → routing
+## Run
 
-Classify the content by **shape**, recommend the route, confirm via structured-choice:
+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 }`.
+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`.
 
-| Shape | Signals | Route |
-|---|---|---|
-| **Analysis / conclusions / design notes** | findings, comparisons, diagnoses, adjudications, recommendations | `docs/research/NNN-research-<slug>.md` (schema below) |
-| **Requirement** | describes a *wish*: what should exist/change, acceptance criteria derivable | **spec draft** via the [`spec-new`](spec-new.md) procedure (same schema, same NO RESEARCH), `## 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 adoption** via [`plan-new`](plan-new.md) § *Input resolution* mode 4 (`docs/plans/PPP-plan-<slug>.md`) → offer `/w:plan-refine` / `/w:plan-exec` |
-| Mixed / ambiguous | e.g. analysis that ends in a requirement | structured-choice between the candidate routes (split is a valid option: research doc + spec draft referencing it) |
+Every rejection names its cause and one valid next action; nothing was written. Fix the answer and repeat from step 3.
 
-Requires a **workspace** (`docs/` is the managed surface). Without one → degrade: propose `/w:workspace-init` or ask for an explicit destination path.
+Requires a **workspace** (`docs/` is the managed surface). Without one → degrade: propose `/w:workspace-init`.
 
-## `docs/research/` — the analysis home (owned by this command)
+## More context
 
-`docs/research` hosts standalone analyses: neither spec nor plan, but worth keeping. Written by this command (or by direct no-flow authoring following this same schema). Belongs to **no flow**; `export-*` never writes it; loops never read it implicitly (a flow uses it by **reference** — e.g. cited in a spec's `## Origin` or a quick prompt).
-
-```markdown
-# Research NNN — <slug>
-
-## Origin
-adopted from host conversation — <host> · <model> · <YYYY-MM-DD>
-(what prompted the analysis: goal, prior doc, question)
-
-## Objective
-The question/situation the analysis addresses. In the user's language.
-
-## Analysis
-The analysis, transcribed/organized (not re-derived).
-
-## Conclusions
-The settled conclusions — actionable, falsifiable where possible.
-
-## Perspectives        (opt. — multi-agent)
-### <host · model · YYYY-MM-DD>
-An additional agent's view on the same objective (see below).
-
-## Sources             (opt.)
-Docs / repos / prior research docs referenced (for a synthesis: the N crossed docs).
-
-## Open questions      (opt.)
-```
-
-## Anti-duplicate → update vs sibling perspective
-
-Before writing, scan `docs/research/*-research-*.md` for a doc whose `## Origin`/`## Objective` matches this objective. If one exists, **never** silently create a second: structured-choice —
-
-- **`Actualizar`** *(recommended when it is the same line of thought)* — correct/extend the existing doc in place (confirmation to overwrite).
-- **`Agregar perspectiva`** — append a `### <host · model · date>` subsection under `## Perspectives`: same objective, **different agent's view** (this is intentional and legitimate — the multi-host pattern below).
-- **`Documento nuevo`** — only if the objective genuinely differs.
-
-## Multi-host cross-analysis (the docs-mediated pattern)
-
-`docs/research` is git-shareable — unlike sessions (gitignored, machine-local, loop-owned). That makes it the exchange surface for **N agents analyzing the same situation**:
-
-1. **Each host** analyzes in-conversation, then runs `/w:persist` → first agent creates the research doc; the rest **add perspectives** (or sibling docs), always attributed (host · model · date).
-2. **The final cross**: the user picks the strongest host; its input is the N research docs/perspectives (referenced explicitly in the prompt or via this command's argument). The synthesis persists as a **new research doc** whose `## Origin` states "synthesis" and whose `## Sources` lists every doc/perspective crossed — attribution lets it weigh who concluded what.
-3. Sessions stay **out** of the exchange path — no concurrent-session doctrine is needed; hosts meet only in `docs/`.
-
-## What this command is NOT
-
-- **Not export-*** — it never reads sessions; `export-*` remains the only session→`docs/` path.
-- **Not a flow** — no loop, no session, no `CHECKPOINT`; single pass.
-- **Not research** — it investigates nothing (NO RESEARCH); it persists what already exists.
-
-## Plan mode
-
-Classifies the content, resolves `NNN`/destination (`aw next-number --dry-run`) and describes the doc it would write (or the update/perspective it would append) without writing anything.
-
-## Resources
-
-- Adopted-context doctrine: `../loops/CHASSIS.md` § *Adopted context* · `../SKILL.md` § *Host as producer*
-- Spec-draft procedure: [`spec-new.md`](spec-new.md) · Plan adoption: [`plan-new.md`](plan-new.md) § *Input resolution* (mode 4)
-- Session→docs counterpart: [`../exports/README.md`](../exports/README.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)

package/skills/w/commands/quick.md

@@ -1,5 +1,5 @@
 ---
-description: Use when the user asks for a scoped, direct task — a fix, tweak, chore or small change that warrants no spec or plan (e.g. "fix this bug", "rename X", "tidy up Y"). Starts quick-loop with minimal ceremony; never touches docs/. If the objective exceeds a quick or the task grows, it escalates — to SPEC live (with consent), to PLAN deferred.
+description: Use for a scoped, direct task that warrants no spec or plan — a fix, a tweak, a chore ("fix this bug", "rename X"). Starts quick-loop with minimal ceremony; never touches docs/. Escalates when the objective exceeds a quick: to SPEC live with consent, to PLAN deferred.
 argument-hint: <prompt with the scoped task>
 allowed-tools:
   [
@@ -12,7 +12,7 @@ allowed-tools:
 
 # quick — trampoline to the lightweight loop
 
-For scoped, direct tasks that do not justify going through SPEC or PLAN. Creates a light session (traceability + resume) — unless the **entry size gate** escalates to SPEC before starting. Delegates to `quick-loop` (Layer 2).
+Delegates to `quick-loop` (Layer 2). Creates a light session (traceability + resume) — unless the **entry size gate** escalates first.
 
 > **Hard floor — applies even if you read nothing beyond this file:**
 >
@@ -23,27 +23,20 @@ For scoped, direct tasks that do not justify going through SPEC or PLAN. Creates
 
 ## Run the loop
 
-`quick-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 quick` — read exactly the documents it lists, in order.
+2. Follow the loop manual end to end, taking `$ARGUMENTS` as the task: it evaluates the size gate, creates the light session, works with minimal ceremony (git-safe), escalates if the task grows, and reports.
 
-1. **Read** `../loops/quick-loop/LOOP.md` (inside the installed `w` skill — e.g. `~/.claude/skills/w/loops/…`).
-2. **Follow** its instructions taking `$ARGUMENTS` as the task: it evaluates the size gate, creates the light session, works with minimal ceremony (git-safe), escalates if the task exceeds or grows (SPEC live / PLAN deferred), and reports.
+> `quick-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.
 
-> Do not try `Skill: quick-loop` — it is not registered as a skill. The command **is** the entry; the loop is its body.
+## Two things this command never does
 
-## What the loop does
+- **It never touches `docs/`** and it exports nothing.
+- **It never re-derives what the conversation already settled.** Analysis already established here is *input*, seeded into the session with `## Origin` = adopted.
 
-- Edits code in the workspace sources.
-- **Adopts prior context**: analysis/conclusions already established in this conversation (e.g. via a host-native feature) are **input** — seeded into the session with `## Origin` = adopted, never re-derived or re-asked (chassis § *Adopted context*).
-- Minimal session artifacts (lazy DECISION, proposed commit).
-- **Proportional closing review gate** before proposing the single commit: re-reads the diff applying the installed ambient conventions and fixes or defers (see `../loops/quick-loop/LOOP.md` § *Sequence*).
-- **Never touches `docs/`** and exports nothing.
-- **Escalates** when complexity emerges — **entry size gate** (before creating the session) and mid-loop (many files, ≥2 sources, needs architecture, or the change is a feature/refactor). Accepting **SPEC** = **live** transition into the SPEC flow (draft via the spec-new procedure + spec-refine-loop); **PLAN** stays seeded for later. See `../loops/quick-loop/LOOP.md` § *QUICK delta*.
+## More context
 
-## Plan mode
+`aw context-plan --command quick --signal <s>` returns the extra documents a case needs; read exactly what it lists:
 
-The skill describes the changes it would apply and the files it would touch, without executing them. Escalation included: if the gate (entry or mid-loop) would fire, it describes it (options + the spec it would materialize) without writing `docs/` or starting loops.
-
-## Resources
-
-- Loop manual: `../loops/quick-loop/LOOP.md`
-- Design reference: `docs/referencias/workflow-commands/quick.md`
+- `db` — the task reads or writes a database → [`../modules/DB-SCRIPTS-ONLY.md`](../modules/DB-SCRIPTS-ONLY.md)
+- `probe` — a runnable doubt has to be settled by running something → [`../modules/PROBE.md`](../modules/PROBE.md)
+- `adopted` — the conversation already established the analysis → [`../modules/ADOPTED-CONTEXT.md`](../modules/ADOPTED-CONTEXT.md)