@tacuchi/agent-workflow-cli 20.23.0 → 20.25.0

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)

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)

package/skills/w/commands/resume.md

@@ -1,5 +1,5 @@
 ---
-description: Use when the user asks to resume or pick up pending work — a half-done session, a spec to refine, a plan mid-execution. Backed by `aw resume`, which derives the priority, the progress and the exact re-entry command from the Workline index. An artifact argument (spec, plan or session) skips the survey. Transversal (not a flow), read-only; never touches docs/ or .workflow/.
+description: Use when the user asks to resume or pick up pending work — an open session, a spec to refine, a plan mid-execution. `aw resume` derives the priority and the re-entry command. Read-only, transversal.
 argument-hint: "[docs/specs/… | docs/plans/… | NNN | --code <session>]"
 allowed-tools:
   [
@@ -8,46 +8,30 @@ allowed-tools:
   ]
 ---
 
-# resume — pick up pending work (transversal)
+# resume — pending work
 
-Single-pass, **read-only**: no loop, no session, writes nothing in `docs/` or `.workflow/`. **Transversal** command (belongs to no SPEC/PLAN/QUICK flow). The actionable sibling of `/w:status`: same index, but it answers *what to pick up* instead of *what exists*.
+Read-only **with or without an argument**: no loop, no session, and it writes nothing in `docs/` or `.workflow/`. Sibling of `aw status`; not `aw session-resume` / `aw resume-summary` (internals).
 
-> **Not `aw session-resume` / `aw resume-summary`.** Those are internal session mechanics (reopen a session; the PostCompact payload). `aw resume` is the user-facing command.
-
-> **Hard floor — applies even if you read nothing beyond this file:**
->
-> 1. **Read-only** — never execute the proposed route, with or without an argument. The CLI hands back a command string; the user drives it.
-> 2. **Never re-decide** — priority, ties, the spec→plan relation and the exact command come from the CLI. Do not re-sort by date, do not associate a session to a plan by slug, do not pick a winner the CLI left tied.
-> 3. **Ask via structured-choice** when the CLI returns candidates, never otherwise.
-> 4. **Language** — user-facing output in the **user's language**.
+1. **Read-only** — never run the route; the user does.
+2. **Never re-decide** — priority, ties, the spec→plan link and the command come from the CLI. No re-sort by date, no slug match, no tie broken.
+3. **Ask via structured-choice** only for CLI candidates: one option each, in order, plus `flow`.
+4. Output in the **user's language**.
 
 ## Run
 
-1. Run `aw resume --format human`, forwarding the argument when there is one:
-   - a doc path or number → pass it as the positional (`aw resume docs/plans/009-plan-x.md`);
-   - a session → `aw resume --code <NNN | folder>`;
-   - nothing → no argument, and the CLI walks the pipeline.
-2. **Relay the output verbatim.** It already carries the objective, the progress or checkpoint, the next pending step or blocker, and the exact command.
-3. **When the CLI returns candidates**, present them as a structured-choice, one option per candidate, in the order given — the CLI declares a tie precisely because there is no correct automatic winner. Add the `flow` control. Never break the tie yourself.
-4. **When it returns nothing pending**, say so and stop. Do not ask.
-5. **Host context (optional).** If nothing is pending at the Workline level and the host exposes cheap host-memory ([`../harness/HARNESS.md`](../harness/HARNESS.md) § *host-memory*), you may add a short note about recent focus. Never expensive, never blocking.
+1. `aw resume --format human`. For one artifact, **pass it as the positional** (`aw resume docs/plans/009-plan-x.md` or its `NNN`); for a session, `aw resume --code <NNN | folder>`; none walks the pipeline.
+2. **Relay it verbatim.**
+3. Nothing pending → say so and stop; cheap host-memory may add a recent-focus note, never expensive or blocking.
 
 ## What the CLI decides (do not re-derive)
 
-- **Priority**: spec sin refinar → spec `ready-for-plan` sin plan → plan incompleto → checkpoint no asociado. Within plans, one already started outranks an untouched one.
-- **Ties**: same priority and same progress → candidates. Date and age never break a tie.
-- **The spec→plan relation**: proven by the plan's `Derived from` header, an explicit spec path in its `## Origin`, or an unambiguous `Spec NNN` there — never by slug. A plan whose provenance is unproven leaves its spec visible as still unplanned.
-- **The route**: `/w:spec-refine`, `/w:plan-new`, `/w:plan-exec`, or `aw session-resume --reopen`, with the path already filled in.
-
-> A plan is not finished because its boxes are ticked. `aw resume` re-enters at the first phase that is not `validada`, reports a `bloqueada` phase with its declared reason, and, when everything is green but the plan never closed, says the final validation is what remains. A plan that declares `done` over open work comes back as inconsistent — repair before implementing.
-
-## Plan mode
+- **Priority**: unrefined spec → refined spec with no plan → incomplete plan → loose checkpoint; started plans first.
+- **Ties**: equal priority and progress → candidates; date never splits.
+- **Spec→plan link**: the plan's `Derived from` or `## Origin`, never the slug; unproven stays unplanned.
+- **The route**: `/w:spec-refine`, `/w:plan-new`, `/w:plan-exec` or `aw session-resume --reopen`.
 
-Read-only already: run `aw resume --format human` and describe the proposal (and the choice it would offer), without asking or writing.
+> A plan is not finished because its boxes are ticked. `aw resume` re-enters at the first phase not `validada`, names a `bloqueada` phase with its declared reason, and when the phases are green but the plan never closed, the final validation remains. A plan declaring `done` over open work comes back as inconsistent — repair first.
 
-## Resources
+## More context
 
-- CLI: `aw resume` (service `resume-service` over `workline-index-service`) · sibling `aw status`
-- Session mechanics: `aw session-resume --code <NNN> [--reopen]` · `aw resume-summary`
-- Continuity rule: [`../SKILL.md`](../SKILL.md) § *Operating context*
-- Design reference: `docs/referencias/workflow-skills/resume.md`
+`aw context-plan --command resume --signal <s>` returns the extra documents a case needs; read exactly what it lists.