@tacuchi/agent-workflow-cli 20.22.0 → 20.24.0

package/skills/w/commands/resume.md

@@ -1,6 +1,6 @@
 ---
-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, or work with no Workline flow at all. Composes /w:status and proposes how to continue via structured-choice routed to the right command; an artifact argument (spec, plan or session) skips the survey and gets its exact re-entry route. Transversal (not a flow), read-only; never touches docs/ or .workflow/. Backed by aw status + aw resume-summary.
-argument-hint: "[docs/specs/… | docs/plans/… | session NNN]"
+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:
   [
     "Bash",
@@ -8,67 +8,30 @@ allowed-tools:
   ]
 ---
 
-# resume — pick up pending work (transversal)
+# resume — pending work
 
-Summarizes what is pending in the workspace and proposes how to continue. 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`**: it composes the `/w:status` summary and adds a proposal layer. With an **argument** (a spec, plan or session) it skips the survey and proposes the exact re-entry route for that artifact (§ *Directed resume*). User-facing output in the user's language.
+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` / `create_or_resume`.** Those are internal session mechanics (reopen a session, the PostCompact payload, loop resume). `/w:resume` is the **user-facing** command that *summarizes + proposes*; it never runs the pending work — it routes to the command that does.
-
-> **Hard floor — applies even if you read nothing beyond this file:**
->
-> 1. **Read-only** — never execute the pending work and never write `docs/` or `.workflow/`, **with or without an argument**. Routing means handing off to the target command; the user drives it.
-> 2. **Summary always, question only when pending** — without an argument, show the prioritized summary every time and ask **only** when there is at least one pending item; with an argument, the directed route (§ *Directed resume*) replaces the survey.
-> 3. **Ask via structured-choice** — the proposal is a structured-choice with the top ≤3 concrete options, recommendation first. Never route silently.
-> 4. **Language** — headings in English (parse contract); user-facing output in the **user's language**.
-
-## Directed resume (optional argument)
-
-`$ARGUMENTS` may name an artifact: a spec (`docs/specs/NNN-spec-<slug>.md`), a plan (`docs/plans/PPP-plan-<slug>.md`) or a session (`NNN` code or `NNN-<slug>-<flow>` folder). Empty → the survey flow below (`## Run`). With an argument:
-
-1. **Derive the slug** from the artifact name (session code `NNN` → resolve the folder via `aw sessions --state all`).
-2. **Locate the candidate sessions**: `aw sessions --state all` (and `aw resume-summary --include-recent-closed` for checkpoint detail) filtered by that slug.
-3. **Confirm by `## Origin`**: read the candidates' `SESSION.md` — the `## Origin` names the spec/plan the session came from; it, not the slug match, decides the association.
-4. **Propose the exact route** via structured-choice, per the `## Routing` table with the artifact's path filled in (`Retomar` recommended, `Descartar`/`Cerrar` secondary). No candidate session and no clear stage → say so and fall back to the survey flow.
-
-Same hard floor: this mode **proposes** the route — it never starts the target command itself.
+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. **Workline level — compose `/w:status`.** Read-and-follow [`status.md`](status.md) to produce the prioritized summary (it already renders `aw status` and, when available, the host-context section). Do **not** re-implement the summary. For deeper session detail, `aw resume-summary [--include-recent-closed]` gives the primary session's CHECKPOINT state, and `aw session-resume --code <NNN>` the full checkpoint of any other active or closed session.
-2. **Interpret the stage marks.** Map each signal to its stage: the spec's `status` (`draft`/`refining` = SPEC work still open · `ready-for-plan` = it can go to PLAN) + `open_questions`; plan progress on **all three axes** — checkboxes (`tasks_done` / `tasks_total`), validated phases (`phases_validated` / `phases_total`) and closure (`plan_state`, with `final_validation_pending` and `blocked_phases[]`); session `checkpoint_present`. A `status` that is absent, empty or unknown reads `draft`: that work stays in SPEC and never routes to PLAN on an unreadable mark. Associate a session to its plan or spec by **slug** — there is no linkage field in the `aw status` output, so infer it from `folder` / `slug`; when precision matters, confirm by the session's `## Origin` (§ *Directed resume*).
-3. **Build the prioritized pending list** — fixed order: **session with CHECKPOINT > plan half-done > spec not ready > host context**.
-4. **Host level (second source).** If the workline level does not explain the pending work (or no Workline flow was used), rely on the host-context already surfaced by `/w:status`; escalate it to a proposal and, only if needed, use the host-memory *deep* tier or ask the user (universal fallback: git / `docs/` signals + a question). See [`../harness/HARNESS.md`](../harness/HARNESS.md) § *host-memory*.
-5. **Propose (only when ≥1 pending).** One structured-choice with the top ≤3 options by the priority order; each option **routes** to its command (table below). Every proposal carries `Retomar` (recommended) and `Descartar` / `Cerrar` (secondary).
-6. **Nothing pending.** Show the `/w:status` summary and state clearly that there is nothing pending — **do not ask**.
-
-## Routing (stage → command)
-
-Priority: **session+CHECKPOINT > plan half-done > spec not ready > host context**.
-
-> **Every box ticked is not a finished plan.** A plan with `phases_validated` below `phases_total` still has functional state to reach — work implemented, not validated — so it counts as half-done and routes to `/w:plan-exec`, which re-enters at the first phase that is not `validada`. A phase left `bloqueada` routes the same way: `/w:plan-exec` re-enters **through it** to run the validation still pending, and the plan stays open until that phase reads `validada`. A plan with `phases_total: 0` is a legacy plan (no phase marks) and is judged by its checkboxes alone.
-
-> **`plan_state` decides whether a plan is resumable at all.** Only `done` is finished; everything else routes back to `/w:plan-exec` with a different re-entry point. `final_validation_pending: true` means the phases are green but the final validation never ran — the plan re-enters **at that validation**, not at a phase. `inconsistent` means the document contradicts itself (`done` declared over open work, or an unreadable value): the re-entry is **repairing the state first**, and the proposal says so instead of pretending there is work to implement.
-
-| Pending detected | `Retomar` (recommended) | Secondary |
-|---|---|---|
-| spec not ready (`draft` / `refining`, or a `status` absent or unreadable) | `/w:spec-refine` | `Descartar` |
-| spec `ready-for-plan`, no plan | `/w:plan-new` | `Descartar` |
-| plan `open` — open checkboxes **or** phases not `validada` | `/w:plan-exec` | `Cerrar` |
-| plan `open` with `final_validation_pending` — everything validated, no closure | `/w:plan-exec`, from the final validation | `Cerrar` |
-| plan `inconsistent` — `done` over open work, or an unreadable value | `/w:plan-exec`, repairing the state first | `Cerrar` |
-| plan `done` | — not resumed automatically | — |
-| active session with CHECKPOINT | continue / reopen (`aw session-resume --reopen`) | `Cerrar` |
-| host context only (no workline) | best next step for what was found | `Descartar` |
+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.
 
-Reuses the continuity rule of [`../SKILL.md`](../SKILL.md) § *Operating context* — it synthesizes the route from the `/w:status` summary + that rule; it does not re-implement it.
+## What the CLI decides (do not re-derive)
 
-## 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: compose `/w:status`, describe the prioritized summary and the proposal it would offer (top ≤3 routed options; with an argument, the exact route it would propose), 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
 
-- Composes: [`status.md`](status.md) (the summary) · Capability: `host-memory` ([`../harness/HARNESS.md`](../harness/HARNESS.md))
-- CLI: `aw status` · `aw resume-summary [--include-recent-closed]` · `aw session-resume --code <NNN> [--reopen]`
-- 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.

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

@@ -1,5 +1,5 @@
 ---
-description: Use when the user wants to capture a NEW requirement, idea or wish as a spec — not to refine an existing draft (that's spec-refine). Generates a specification draft (docs/specs/NNN-spec-<slug>.md) from a prompt, in a single pass: a bounded reconnaissance of the workspace sources first, then the scope decision — one spec, or several sibling specs (split gate). Step 1 of the SPEC flow; starts no loop.
+description: "Use when a NEW requirement, idea or wish must be captured as a spec draft (docs/specs/NNN-spec-<slug>.md) in one pass — not to refine an existing draft (that is spec-refine). Step 1 of the SPEC flow; starts no loop."
 argument-hint: <prompt with the requirement or idea>
 allowed-tools:
   [
@@ -15,60 +15,21 @@ Generates `docs/specs/NNN-spec-<slug>.md` in a single pass from the prompt in `$
 
 > ## ⛔ Single-pass — BOUNDED RECONNAISSANCE, NO DEEP RESEARCH (hard rule)
 >
-> This command frames the user's input into the draft schema after a **single, bounded look** at the context. It is **one sequential pass**: read `$ARGUMENTS` → adopt what the conversation already settled → **reconnaissance** (see § *Bounded reconnaissance*) → scope hypothesis → (split gate: at most ONE structured-choice — see § *Split gate (multi-spec)*) → fill the sections → write the file(s). Nothing else. It must take **seconds, not minutes**.
+> One sequential pass: read `$ARGUMENTS` → adopt what the conversation already settled → reconnaissance → scope hypothesis → split gate (at most ONE structured-choice) → fill the sections → write the file(s). Nothing else. It must take **seconds, not minutes**.
 >
-> **FORBIDDEN**, no exceptions: launching sub-agents/workflows (`Task`/`Agent`/`Workflow`), research sessions, web searches, following implementation chains, running code/tests/apps, querying databases — **even if the harness is in a maximum-effort/depth mode** (e.g. ultracode/max-effort in Claude Code).
+> **FORBIDDEN**, no exceptions: launching sub-agents/workflows (`Task`/`Agent`/`Workflow`), research sessions, web searches, following implementation chains, running code/tests/apps, querying databases — **even if the harness is in a maximum-effort/depth mode**. This **overrides** any mode or session instruction saying "run a workflow for every substantial task".
 >
-> This **overrides** any mode or session instruction saying "run a workflow for every substantial task". Those modes do **not** apply to `spec-new`: this command overrides them. If a section stays uncertain after the reconnaissance, **do not dig further** — declare it under `## Open questions` or `## Assumptions` and move on.
->
-> Deep investigation (closing gaps, mapping code, querying DB, autonomous research) is **`spec-refine`** work, not this command's.
-
-With a raw user prompt, first run the **§ Bounded reconnaissance** pass, then the **§ Split gate (multi-spec)** assessment (both below): the split offer, if any, happens **before writing anything**. Then:
-
-1. Run `aw next-number docs/specs` (the only shell tool needed beyond the reconnaissance): it returns JSON — use the `next` field as `NNN`. This command builds the slug.
-2. Derive the `<slug>`: short kebab-case from the Requirement — only `[a-z0-9-]`, ≤ ~5 words / ≤ 40 chars.
-3. Create `docs/specs/NNN-spec-<slug>.md` framing `$ARGUMENTS` into the draft schema (below); the reconnaissance findings land **only** where the filling notes allow. On an accepted split: repeat steps 1-3 per part, minting immediately before each write.
-4. Show the generated file(s) and the suggested next step (`/w:spec-refine docs/specs/NNN-spec-<slug>.md`).
-
-## Bounded reconnaissance
-
-A scope decision taken from the prompt alone mistakes **technical** boundaries for **functional** ones. So, before deciding, take **one** shallow look at the terrain — enough to form a reasonable hypothesis of the functional unit, never enough to answer how it will be built.
-
-**Scope:** it runs **only on a raw user prompt** (direct invocation, or the `plan-new` mode-3 handoff). The reuse entries at the end of this file skip it: the quick escalation and the `persist` adoption arrive with their context **already established**, and adopting it is transcription, not reconnaissance (**NO RESEARCH** — chassis § *Adopted context*).
+> A section still uncertain after the reconnaissance → **do not dig further**: declare it under `## Open questions` or `## Assumptions` and move on. Deep investigation (closing gaps, mapping code, querying DB, autonomous research) is **`spec-refine`** work.
 
-One pass, in this order: **adopt** what the conversation already settled (never re-derive it), **identify** the candidate sources, **look** at their surface, **stop**.
+## Run
 
-- **Sources allowed** (a permission, not an obligation to read them all):
-  - the workspace's registered sources — `aw sources --no-git`, or the `WORKSPACE` block;
-  - each candidate source's main instructions file, plus the head of its `README`;
-  - build manifests: `package.json`, `pom.xml`, `build.gradle`, `requirements.txt`, equivalents;
-  - a top-level directory listing per candidate source;
-  - one or two entry points the prompt itself names, plus a handful of search hits.
-- **Budget: ≤5 reads + ≤3 searches.** Read a whole file only when a head or a search will not do. The ceiling is a **cap, never a target**.
-- **Stop at the first of these:**
-  - the evidence already decides one spec vs sibling specs;
-  - the next question needs a deep technical chain;
-  - it would need running code, tests or services;
-  - it would need an external source that is not available;
-  - the remaining uncertainty does not block a first draft;
-  - the digging starts answering *how it will be built* instead of *what functional unit was asked for*.
-- **Never:** follow a full import/call chain, run anything, query a database, search the web, or open a source the prompt gives no reason to open.
+1. **Reconnaissance** — one shallow look at the terrain before any scope decision: adopt what the conversation settled, identify the candidate sources (`aw sources --no-git`, or the `WORKSPACE` block), look at their surface, stop. **Budget: ≤5 reads + ≤3 searches** — a cap, never a target. Never run code, query a database or search the web. Full rules: module `RECONNAISSANCE`.
+2. **Split gate** — before writing anything, judge whether the prompt bundles several **independent functional outcomes**. Borderline or thin evidence → **one spec, no question** (hypothesis to `## Assumptions`, doubt to `## Open questions`). Only clear signals earn the command's single structured-choice offer. Full rules: module `SPLIT-GATE`.
+3. **Number and slug** — `aw next-number docs/specs` returns JSON; use `next` as `NNN`. Derive `<slug>` from the Requirement: short kebab-case, only `[a-z0-9-]`, ≤ ~5 words / ≤ 40 chars.
+4. **Write** `docs/specs/NNN-spec-<slug>.md`, framing `$ARGUMENTS` into the draft schema below; reconnaissance findings land **only** where the filling notes allow. On an accepted split: repeat 3-4 per part, minting immediately before each write.
+5. **Report** the generated file(s) and the next step (`/w:spec-refine docs/specs/NNN-spec-<slug>.md`).
 
-**Scope hypothesis (internal).** The pass ends in a short judgement: functional outcome · likely sources · apparent responsibility of each · coupling · independent acceptance · recommended shape · confidence. It is **reasoning, not an artifact** — never persisted, never printed verbatim. It exists so the cut is never intuitive but opaque; its only visible residue is what the filling notes admit.
-
-**Degrade safely.** A missing workspace, unreachable sources or contradictory evidence **never** block the command and **never** justify a speculative cut. Keep **one spec**, declare the assumption used, and record the uncertainty for `spec-refine`. Prefer the functional outcome the user declared over any inference drawn from the code.
-
-## Split gate (multi-spec)
-
-Right after the reconnaissance and **before writing anything**, assess whether the prompt bundles **several independent outcomes**. The unit is the **functional outcome**, not the technical boundary: distinct repos, a frontend/backend pair, several microservices, a migration plus the code it enables — all **secondary evidence**, never on their own a reason to divide.
-
-**Divide only when each part is a result that can be refined, accepted and planned on its own** — its own purpose, its own acceptance criteria, worth delivering even if the other part is dropped. The gate fires **only on clear signals** (≥2 of: independent deliverables/goals · explicit enumeration of distinct features · different requested moments or order · users or value that do not depend on each other). Borderline, or evidence too thin to tell → **one spec, no question**: the hypothesis goes to `## Assumptions` and the doubt to `## Open questions`. It applies only to a **raw user prompt** (direct invocation, or the `plan-new` mode-3 handoff); it **never fires** on the reuse entries below — the quick escalation and the `persist` adoption arrive already scoped to one objective.
-
-- **The offer** — the command's **only** interaction: **one** structured-choice (≤2 content questions + the `flow` control; `Cerrar` = abort, nothing is written yet). The question body shows the proposed cut in the **user's language**: per part, a name + slug, a 1-line scope and the suggested order. Labels: `Dividir en varias specs` (recommended when the signals hold) | `Una sola spec`. A free-form answer adjusts the cut (merge/rename/drop parts); if one part remains, proceed as a single spec.
-- **The second content question** is allowed **only** for a functional ambiguity with two incompatible readings that would change the number of specs (or leave the requested outcome unidentifiable). Anything smaller — confirming an observable technology, closing an implementation detail, raising confidence from medium to high — is **not** asked: it goes to `## Assumptions` or `## Open questions`.
-- **On acceptance** — still single-pass: the cut comes from the prompt plus the reconnaissance already done, never from a second look. Per part, mint with `aw next-number docs/specs` **immediately before each write**, then write that draft. Numbers come out consecutive, so every sibling path is known after the first mint.
-- **Sibling contract**: each `## Origin` records the shared prompt + `split (part i/N)` + the **siblings by path** + the suggested order; each `## Scope` Out points to the sibling that owns the excluded part. Cross-reference by path, never by bare number.
-- **Report**: list the N files and suggest the next step per spec (`/w:spec-refine` on the first — each sibling refines and plans at its own moment).
+Steps 1-2 run **only on a raw user prompt** (direct invocation, or the `plan-new` mode-3 handoff). The reuse entries at the end skip them: their context arrives already established, and adopting it is transcription, not investigation.
 
 ## Draft schema (`NNN-spec-<slug>.md`)
 
@@ -82,7 +43,7 @@ status: draft
 ## Origin            (opt.)
 Original prompt / prior doc / reference that originated the spec
 (e.g. "adopted from host conversation" when it captures an analysis already established there;
-or "split (part i/N)" + sibling spec paths + suggested order — § Split gate (multi-spec)).
+or "split (part i/N)" + sibling spec paths + suggested order).
 
 ## Requirement
 The what + why (brief). In the user's language.
@@ -115,31 +76,29 @@ Assumed facts.
 Pending doubts. ← the spec-refine-loop closes them.
 ```
 
-> **`Open questions` goes last** — the refined spec **inserts before `Open questions`** `## UI spec` (if there is UI) + `## Decisions`, and may add `## Affected capabilities` / `## Behavioral changes` right after `Context` when the change touches behavior that already exists (refined schema in the [`spec-refine-loop`](../loops/spec-refine-loop/LOOP.md); the refine drops `Open questions` when it empties). Same skeleton: the draft and the refined spec share the order.
+> **`Open questions` goes last** — the refined spec **inserts before `Open questions`** `## UI spec` (if there is UI) + `## Decisions`, and may add `## Affected capabilities` / `## Behavioral changes` right after `Context` when the change touches behavior that already exists (refined schema in the [`spec-refine-loop`](../loops/spec-refine-loop/LOOP.md); the refine drops `Open questions` when it empties). Draft and refined spec share the same skeleton and order.
 
 **Filling notes:**
 
-- The draft's **content** is written in the **user's language** (the schema headings stay as-is).
+- The draft's **content** is written in the **user's language** (schema headings stay as-is).
 - No `Type` field — `plan-new` infers the how.
-- **`status: draft`** in the frontmatter is the draft's maturity mark. This command writes no other value: only the `spec-refine` gate promotes a spec to `ready-for-plan`.
-- `Scope` always carries `Out` (what stays out).
-- **Where the reconnaissance lands** — `Context`: the facts that place the request (sources apparently involved, a module's observed responsibility, the relevant technology), with **at most one path per component** as an anchor; never a technical inventory. `Assumptions`: the inferences that let the draft advance. `Open questions`: what would need walking the implementation, a human decision, or a source that is not available.
-- **The code found never widens `Scope`** and never becomes a requirement: **acceptance criteria derive from the user's intent**. The reconnaissance may lend the right vocabulary, name existing actors and boundaries, and avoid obvious contradictions. It must not invent behavior nobody asked for, turn a current technical decision into a user requirement, or impose an implementation as a criterion.
-- **Acceptance criteria = static testable criteria** (the "what"): `plan-exec` validates them, but progress is tracked in the PLAN (its Tasks), never by ticking these `- [ ]` in the spec; the spec never mutates by execution, only by a re-refine.
-- **Scenarios = behavior made concrete** (uppercase GIVEN/WHEN/THEN/AND): draft them only when the prompt already describes behavior — deriving the rest is spec-refine work, not this command's. A scenario earns its place only when it adds GIVEN setup or edge semantics the criterion does not capture — **never restate a criterion 1:1**.
-- If **UI** is involved, mention it in `Requirement`/`Context`; the `## UI spec` is authored in `spec-refine` (via the `ui-design` capability). "UI unspecified" is a first-class refinement gap.
+- **`status: draft`** is the draft's maturity mark. This command writes no other value: only the `spec-refine` gate promotes a spec to `ready-for-plan`.
+- `Scope` always carries `Out`.
+- **Where the reconnaissance lands** — `Context`: the facts that place the request (sources apparently involved, a module's observed responsibility, the relevant technology), **at most one path per component** as an anchor, never a technical inventory. `Assumptions`: the inferences that let the draft advance. `Open questions`: what would need walking the implementation, a human decision, or an unavailable source.
+- **The code found never widens `Scope`** and never becomes a requirement: **acceptance criteria derive from the user's intent**. The reconnaissance may lend vocabulary, name existing actors and boundaries, and avoid obvious contradictions. It must not invent behavior nobody asked for, turn a current technical decision into a user requirement, or impose an implementation as a criterion.
+- **Acceptance criteria = static testable criteria** (the "what"): `plan-exec` validates them, but progress is tracked in the PLAN (its Tasks), never by ticking these `- [ ]`; the spec never mutates by execution, only by a re-refine.
+- **Scenarios = behavior made concrete** (uppercase GIVEN/WHEN/THEN/AND): draft them only when the prompt already describes behavior — deriving the rest is spec-refine work. A scenario earns its place only when it adds GIVEN setup or edge semantics the criterion does not capture — **never restate a criterion 1:1**.
+- If **UI** is involved, mention it in `Requirement`/`Context`; `## UI spec` is authored in `spec-refine` (via the `ui-design` capability). "UI unspecified" is a first-class refinement gap.
 - The **gaps** the loop detects = weak sections of the schema (vague Requirement, Scope without `Out`, untestable criteria, open questions, undeclared assumptions, contradictions) **+ UI unspecified** when the requirement involves UI.
-- Equivalent alternative: the user creates the draft by hand. Both paths produce the same `docs/specs/NNN-spec-<slug>.md`.
+- Equivalent alternative: the user writes the draft by hand. Both paths produce the same file.
 
-> **Reuse by escalation:** the live escalation from `/w:quick` (see [`../loops/quick-loop/LOOP.md`](../loops/quick-loop/LOOP.md) § *QUICK delta*) materializes its draft following **this same procedure** (steps 1-3: same schema, same single-pass hard rule — with **NO RESEARCH** and no reconnaissance: the objective and its context arrive adopted), with `## Origin` = "escalated from `/w:quick`" + the original prompt. No need to type `/w:spec-new`: the consent in the structured-choice equals invoking it.
+> **Reuse by escalation:** the live escalation from `/w:quick` (see [`../loops/quick-loop/LOOP.md`](../loops/quick-loop/LOOP.md) § *QUICK delta*) materializes its draft with **this same procedure** (same schema, same single-pass hard rule — **NO RESEARCH**, no reconnaissance: objective and context arrive adopted), with `## Origin` = "escalated from `/w:quick`" + the original prompt. The consent in the structured-choice equals invoking this command.
 >
-> **Reuse by adoption:** [`/w:persist`](persist.md) (requirement-shaped content) materializes its spec draft with this same procedure, with `## Origin` = "adopted from host conversation" + attribution. Paraphrasing conclusions **already established in this conversation** is still single-pass, and needs no reconnaissance — adoption is transcription, not investigation (chassis § *Adopted context*).
-
-## Plan mode
+> **Reuse by adoption:** [`/w:persist`](persist.md) (requirement-shaped content) materializes its spec draft the same way, with `## Origin` = "adopted from host conversation" + attribution. Paraphrasing conclusions **already established in this conversation** is still single-pass and needs no reconnaissance — adoption is transcription, not investigation.
 
-Resolves `NNN` by reading `docs/specs/`, runs the same bounded reconnaissance (read-only in either mode) and describes the draft(s) it would generate — split gate included: it reports the proposed cut — without writing any file.
+## More context
 
-## Resources
+`aw context-plan --command spec-new --signal <s>` returns the extra documents a case needs; read exactly what it lists:
 
-- Design reference: `docs/referencias/workflow-commands/spec-new.md`
-- Loop that refines this draft: `../loops/spec-refine-loop/LOOP.md`
+- `reconnaissance` — the terrain is unfamiliar and the scope decision needs a bounded look first → [`../modules/RECONNAISSANCE.md`](../modules/RECONNAISSANCE.md)
+- `split` — the prompt may carry more than one independent outcome → [`../modules/SPLIT-GATE.md`](../modules/SPLIT-GATE.md)

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

@@ -1,5 +1,5 @@
 ---
-description: Use when a spec draft exists and needs disambiguating or completing before planning (close the blocking functional gaps, sharpen criteria, hand the technical ones to PLAN) — not for the first draft (that's spec-new). Starts or resumes the specification refinement loop (spec-refine-loop). Input: docs/specs/NNN-spec-<slug>.md (from spec-new, hand-written, or the quick escalation). Updates it in place and marks it status: ready-for-plan.
+description: Use when a spec draft needs disambiguating before planning — closes the blocking functional gaps and marks it status ready-for-plan. Not the first draft (that is spec-new). Starts or resumes spec-refine-loop over docs/specs/NNN-spec-<slug>.md, in place.
 argument-hint: <docs/specs/NNN-spec-<slug>.md>
 allowed-tools:
   [
@@ -12,53 +12,28 @@ allowed-tools:
 
 # spec-refine — trampoline to the refinement loop
 
-This command does not refine the spec itself: it delegates to `spec-refine-loop` (Layer 2), which iterates, closes the blocking gaps and leaves the spec ready for planning.
+Delegates to `spec-refine-loop` (Layer 2), which iterates, closes the blocking gaps and leaves the spec ready for planning.
 
 > **Hard floor — applies even if you read nothing beyond this file:**
 >
 > 1. **Session first** — create/resume the run's session before working: `aw session-create --type refine --name <slug>-spec-refine --objetivo "<one-line objective>"`; keep its `CHECKPOINT.md` updated (`## Completed` · `## Pending / Next`; `## Open questions` only while live doubts exist).
 > 2. **Ask, don't invent** — user-dependent decisions go through questions with a recommended option first (≤3 content questions + the `flow` control `Compactar`/`Cerrar`).
-> 3. **Write boundary** — this flow edits only `docs/specs/…` (in place, with confirmation), stamping the spec's frontmatter `status: ready-for-plan` on save; nothing else lands in `docs/`.
+> 3. **Write boundary** — this flow edits only `docs/specs/…` (in place, with confirmation), stamping `status: ready-for-plan` on save; nothing else lands in `docs/`.
 > 4. **Language** — everything user-facing (questions, option labels, the doc's content) goes in the **user's language**.
 > 5. **Converge, do not close everything** — the target is `ready-for-plan`, not a spec without unknowns: close what can change **what** gets built; hand architecture and implementation questions to `PLAN`, recorded in `## Open questions` with their destination.
-> 6. **Shape before gaps** — if the investigation shows the spec must be **split** or **replaced**, ask and resolve that **before** the gap questions, in its own question, and record the answer in `CHECKPOINT`. Never mix it into the gap batch.
-
-## The two shape branches are not the same question
-
-The loop's *change-shape gate* can find that one spec is the wrong container. `split` and `replace` are different findings, so they ask different things and do different things — reusing one for the other asks about cardinality when what changed was purpose:
-
-| Finding | What it asks | What it writes |
-|---|---|---|
-| **`split`** — independent functional outcomes discovered | `Dividir en varias specs` \| `Una sola spec` | the original, rewritten reduced, **plus** one new file per extracted outcome |
-| **`replace`** — the purpose itself changed | `Crear una nueva spec` \| `Reformular esta spec` | `Crear` → one **new** file, this spec untouched · `Reformular` → **no new file**: this same file, same number, same path |
-
-Both branches keep the `Cerrar` control, which closes the run **without applying the change**. No file — new or overwritten — is written without confirmation.
+> 6. **Shape before gaps** — if the spec must be **split** or **replaced**, ask and resolve that **before** the gap questions, in its own question, and record the answer in `CHECKPOINT`. Never mix it into the gap batch.
 
 ## Run the loop
 
-`spec-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/spec-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: spec-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 the existence of a "refined" file):
-
-1. Find the spec's refinement session under `.workflow/sessions/` 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 spec is not `status: ready-for-plan`) → start from zero reading the spec (`NNN-spec*.md`).
-4. **Already ready / re-refine on demand** (no open CHECKPOINT but the spec **already declares** `status: ready-for-plan`) → **first-class operation**: while the flow stays in SPEC you can re-run this command over the same spec **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 **spec itself**; on `Guardar`, edits in place with confirmation.
-
-> **Compat (legacy):** a spec with no frontmatter that carries `## Refinement decisions` (or the older `## Q&A traceability`) counts as ready — case 4 — but the mark does **not** exempt it from the gate: the re-refine runs it in full and, on `Guardar`, renames that section to `## Decisions` in the same write that stamps `status`. The `NNN-spec*.md` glob also catches old `NNN-spec.md` / `NNN-spec-refined.md` specs; re-running spec-refine edits them in place from then on.
+1. `aw context-plan --command spec-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.
 
-## Plan mode
+> `spec-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.
 
-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 spec-refine --signal <s>` returns the extra documents a case needs; read exactly what it lists:
 
-- Loop manual: `../loops/spec-refine-loop/LOOP.md`
-- Design reference: `docs/referencias/workflow-commands/spec-refine.md`
+- `shape` — the loop's change-shape gate fired and you must tell `split` from `replace` → [`../modules/SPEC-CHANGE-SHAPE.md`](../modules/SPEC-CHANGE-SHAPE.md)
+- `resume` — a prior refinement of this spec may exist → [`../modules/SPEC-REFINE-KEYS.md`](../modules/SPEC-REFINE-KEYS.md)
+- `web` — the solution space looks unexplored and the loop opens its ideation step → [`../modules/IDEATION-GATE.md`](../modules/IDEATION-GATE.md)

package/skills/w/commands/status.md

@@ -1,6 +1,6 @@
 ---
-description: Use when the user asks "what's the state", "what got done", or "where are we". Read-only workspace dashboard — what got done / what is missing / what was discarded, with dates humanized in the user's language, optionally enriched with host context when the host exposes cheap memory. Backed by `aw status`. Transversal command (not a flow); writes nothing.
-argument-hint: (no arguments)
+description: Use when the user asks what got done, what is pending, or where the work stands. Read-only workspace dashboard: pending pipeline by default, full history under `detalle`. Backed by `aw status`; writes nothing.
+argument-hint: (none — pass `detalle` for the full inventory)
 allowed-tools:
   [
     "Bash",
@@ -8,65 +8,22 @@ allowed-tools:
   ]
 ---
 
-# status — workspace state (read-only)
+# status — workspace state
 
-Shows, simple and direct, the workspace state grouped as **Done / Missing / Discarded**. Single-pass, read-only: no loop, no sessions, writes nothing in `docs/` or `.workflow/`. **Transversal** command (belongs to no flow). When the host exposes cheap memory it *opportunistically* adds a host-context section — additive, never blocking, never asked.
+Read-only single pass: no loop, no session, no writes. Transversal.
 
 ## Run
 
-1. Run `aw status` (returns JSON; backed by `status-service`).
-2. Render a readable summary from the JSON — do **not** show the raw JSON. Use the `relative` field verbatim (it comes pre-humanized in the user's language — Spanish). Head it with `workspace.name`.
-3. Group into three blocks (the dashboard is user-facing → render it in the user's language; the canonical Spanish labels below):
-   - `▸ HECHO` — specs whose `status` is `ready-for-plan` (the JSON keeps `refined: true` as its boolean mirror); plans whose `plan_state` is `done`, with their progress (`tasks_done`/`tasks_total`, `progress_pct`) **and** their validated phases (`phases_validated`/`phases_total`); `closed` sessions.
-   - `▸ FALTA` — `active` sessions; plans whose `plan_state` is `open` (pending tasks `tasks_total − tasks_done`, phases still to validate `phases_total − phases_validated`, or a final validation that never ran); plans whose `plan_state` is `inconsistent`, **naming the contradiction**; specs whose `status` is `draft` or `refining`; specs with `open_questions > 0`.
-   - `▸ DESCARTÓ` — every item in `discarded[]` (`kind: deferred` = deferred in BACKLOG; `kind: excluded` = excluded in CHECKPOINT), with its `text`.
-4. Every line ends with its relative date after ` · ` (e.g. `· ayer en la mañana`). An empty section shows `— (nada)`. Never invent data not present in the JSON.
-5. **Say what blocks a phase.** Every entry of `blocked_phases[]` is rendered with its `number`, its `name` and its `blocker` — `• F3 — Persistencia real — bloqueada: falta aplicar la migración`. A `blocker: null` is a legacy block that stated no reason: render it as `bloqueada` with `motivo no declarado`, never a guess.
-6. If `workspace.initialized` is `false` and everything is empty → say the folder is not an agent-workflow workspace (no `.workflow/`) and suggest `/w:workspace-init`.
-7. **Host context (opportunistic, read-only).** After the dashboard, if the host exposes *cheap* host-memory (see [`../harness/HARNESS.md`](../harness/HARNESS.md) § *host-memory* — e.g. the auto-memory `MEMORY.md` on Claude Code), append a `▸ CONTEXTO DEL HOST` section with a few signals of recent focus relevant to this workspace. If there is no cheap host memory, **omit the section silently**. Never run an expensive transcript scan here and **never ask** — this is a read-only dashboard; the enrichment is additive and must not slow the default output.
+1. `aw status --format human`; `--detail` for the full inventory ("detalle", "todo", "historial").
+2. **Relay it verbatim.** The CLI already selects, groups and humanizes. Never paraphrase, re-sort, add or drop a line.
+3. **Host context, opportunistic.** Host with *cheap* host-memory → append a `▸ CONTEXTO DEL HOST` section with a few recent-focus signals. Otherwise omit silently. Never scan transcripts, never ask.
 
-> **Three axes, none of them a substitute for another.** A task completed answers *what work was done* (`tasks_done`/`tasks_total`); a phase validated answers *what functional state was demonstrated* (`phases_validated`/`phases_total`); a plan closed answers *whether the whole solution was validated* (`plan_state`). `progress_pct` stays checkbox-derived — it never reads the phase marks. A plan at 100% with `phases_validated: 0` is **work implemented, not validated**: report it in both blocks and say so. `phases_total: 0` means a legacy plan with no phase marks — show only its checkbox progress, never a `0/0`.
+> **The default view is what is LEFT TO DO** — unrefined specs, refined specs with no plan, plans not `done`. `--detail` brings back history, sessions and discarded items — re-run rather than explain an absence.
 
-> **`plan_state` is derived, never declared alone.** `open` (or nothing declared) keeps the plan in `▸ FALTA`, **including** a plan whose every box is ticked and every phase validated: that one carries `final_validation_pending: true` and is reported as `validación final pendiente` — the work is complete, the final validation never ran. `done` reaches `▸ HECHO` only when the counters back the declaration. `inconsistent` means the document declares `done` while tasks or phases stay open, or declares a value nobody can read: it belongs in `▸ FALTA` **with the contradiction named** (`declara done con 2 tareas abiertas`), because only a human repairs it.
+> **Automation reads JSON.** Piped or with `--json` / `--format json`, `aw status` emits its machine-readable envelope; `--detail` is human-only.
 
-> **A blocked phase says what it waits on.** A `bloqueada` phase is the implemented-not-validated gap made explicit — every box ticked, its verification still pending — and belongs in both blocks: the work under `▸ HECHO`, the phase under `▸ FALTA` with its `> Bloqueo:` reason, so the reader knows the next action instead of only the state.
+`initialized: false`, everything empty → say the folder is not an agent-workflow workspace and suggest `/w:workspace-init`.
 
-> **The frontmatter governs spec maturity.** The spec's `status` (`draft` | `refining` | `ready-for-plan`) is the primary source, and readiness is never inferred from a section the spec happens to carry. A `status` that is absent, empty or unknown reads `draft` and the spec is reported as pending; only a spec with **no frontmatter at all** falls back to the two legacy marks (`## Refinement decisions`, `## Q&A traceability`).
+## More context
 
-Suggested format (plain text; user-facing labels in Spanish):
-
-```
-Workspace: <name>
-
-▸ HECHO
-  • plan <slug> — cerrado · <done>/<total> tareas (<pct>%) · <validadas>/<fases> fases validadas · <relative>
-  • spec <slug> — lista para plan · <relative>
-  • <folder> (<type>) — cerrada · <relative>
-
-▸ FALTA
-  • <folder> (<type>) — activa · <relative>
-  • plan <slug> — <pendientes> tareas pendientes · <sin validar> fases sin validar
-  • plan <slug> — validación final pendiente (todo validado, sin cierre)
-  • plan <slug> — inconsistente: declara done con <n> tareas abiertas
-  • F3 — Persistencia real — bloqueada: falta aplicar la migración
-  • spec <slug> — borrador · <relative>
-  • spec <slug> — <n> preguntas abiertas
-
-▸ DESCARTÓ
-  • <text> (<kind>) · <relative>
-
-▸ CONTEXTO DEL HOST   (solo si hay memoria barata; se omite si no)
-  • <foco reciente / hilo relevante>
-```
-
-## Plan mode
-
-Same as execution: run `aw status` (read-only) and show the summary. There are no changes to apply.
-
-## Resources
-
-- CLI: `aw status` (service `status-service`; dates via `humanize-es`)
-- Capability: `host-memory` ([`../harness/HARNESS.md`](../harness/HARNESS.md)) — cheap tier only, opportunistic, silent-omit, never asks
-- Design reference: `docs/referencias/workflow-skills/status.md`
-
-> **Note:** the host-context section is an opportunistic addendum — originally `/status` was a pure `aw status` dashboard. It composes the `host-memory` capability and is purely additive (the fast dashboard is unchanged).
+`aw context-plan --command status --signal <s>` returns the extra documents a case needs; read exactly what it lists.

package/skills/w/commands/workspace-init.md

@@ -1,41 +1,34 @@
 ---
-description: Use when starting Workline in a folder that has no workspace yet. Turns the current folder into an agent-workflow workspace (minimal scaffold — .workflow/sessions + skills.toml + WORKSPACE block + CLI-owned .gitignore; docs/ folders are born on demand). Replaces hub-init + project-init — no project/hub distinction. Run once before any flow; idempotent, re-running reconciles (prunes legacy empty scaffold).
+description: "Use when starting Workline in a folder with no workspace yet — turns it into one (minimal scaffold: sessions marker, skills.toml, WORKSPACE block, .gitignore). Run once before any flow. Backed by `aw workspace-init`."
 argument-hint: --source alias:path[:branch] [--proyecto <name>] [--main-branch <branch>] [--dry-run]
 allowed-tools:
   [
     "Bash",
     "Read",
-    "Write",
-    "Edit",
   ]
 ---
 
 # workspace-init — workspace bootstrap
 
-Runs `aw workspace-init` to turn the current folder into a Workline workspace. A workspace has **1+ sources** (repos); "standalone" = a single source. There are no project/hub modes — the model is unified.
+Turns the current folder into a Workline workspace: **1+ sources** (repos), one source = standalone. No project/hub modes.
 
-```bash
-aw workspace-init --source alias:path[:branch] [--proyecto <name>] [--main-branch <branch>] [--dry-run]
-```
+`aw workspace-init --source alias:path[:branch] [--proyecto <name>] [--main-branch <branch>] [--dry-run] --format human`
 
-## Interactive steps
-
-1. **Detect/confirm sources** — the CLI detects the repo path(s); the user confirms aliases, paths and branches. Multiple `--source` accepted.
-2. **Pick default skills** — the catalog of available capabilities (roles) is presented. Per role: `built-in default`, override to a third-party skill (`skills.sh`), or `off`. The result is written to `.workflow/skills.toml`. Config cascade: `built-in → ~/.workflow/skills.toml (global) → .workflow/skills.toml (workspace)`. The template also ships a commented `[compaction]` section — the `mode` switch for the loops' context self-regulation (`auto` is the opt-in; `confirm` is the default — chassis § *Self-regulation (proactive compaction)*).
-3. **Write the MINIMAL scaffolding** — only the activation set: `.workflow/sessions/` (the marker that activates the operating context), `.workflow/skills.toml`, the `WORKSPACE` block in CLAUDE.md/AGENTS.md (sources + metadata) and the `.gitignore` policy (below). **Nothing else upfront**: each `docs/<category>` folder (`specs/`, `plans/`, `scripts/`, `manuals/`, `diagrams/`, `reports/`) is born on demand at its first numbered write — `aw next-number docs/<cat>` creates it (skills stay unchanged); launch artifacts (`.workflow/launch/<alias>/`) and `docs/logs/` are generated by the launch flow at the first launch.
-4. **External sources** — for every source living OUTSIDE the workspace folder (any count, including a single external source), configures multi-root visibility (settings.local.json + config, gitignored) and reconciles sources.
+> **The CLI writes; this wrapper does not** — `Write` and `Edit` are deliberately absent from `allowed-tools`. Use `--dry-run` to preview, then re-run without it. Relay the CLI's output; do not re-render it.
 
-**Versioning policy (CLI-owned `.gitignore`)** — init writes and owns the full set: ignored = `.workflow/sessions/` (machine-local live log), `.workflow/.lock`, `.workflow/processes.json`, `.workflow/launch/`, `docs/logs/`, and — with external sources — `.claude/settings.local.json*` / `.codex/config.toml*` (patterns cover the `.bak.<epoch>` backups). Versioned = `.workflow/skills.toml`, `docs/**` (deliverables) and `.workflow/HISTORY.md` — the durable record: `aw session-close` upserts each closed session's row there.
+## Interactive steps
 
-When done, the user can run `/w:spec-new`, `/w:plan-new` or `/w:quick` directly.
+1. **Sources** — the CLI detects the repo path(s); the user confirms aliases, paths, branches. Multiple `--source` accepted.
+2. **Default skills** — present the catalog of capabilities (roles). Per role: `built-in default`, a third-party skill (`skills.sh`), or `off`; the result lands in `.workflow/skills.toml`. Cascade: `built-in → ~/.workflow/skills.toml (global) → .workflow/skills.toml (workspace)`. The template also ships a commented `[compaction]` section — the `mode` switch for the loops' context self-regulation (`confirm` default, `auto` opt-in).
+3. **Minimal scaffold** — only the activation set: `.workflow/sessions/` (the marker that activates the operating context), `.workflow/skills.toml`, the `WORKSPACE` block in CLAUDE.md/AGENTS.md and the CLI-owned `.gitignore`. **Nothing else upfront**: each `docs/<category>` folder is born on demand at its first numbered write (`aw next-number docs/<cat>`); `.workflow/launch/<alias>/` and `docs/logs/` at the first launch.
+4. **External sources** — a source outside the workspace folder gets multi-root visibility (gitignored) and a reconcile.
 
-**Idempotent + reconcile**: re-running reconciles (no duplicate entries, no overwriting manual configuration) and **prunes the legacy upfront scaffold**: `.gitkeep`-only taxonomy folders, stray `.gitkeep` files, an empty `docs/logs/` and a released `.workflow/.lock` leftover are removed; the `.gitignore` is completed to the current set (entries merge under the existing header, never duplicated).
+**Idempotent** — a re-run reconciles: it keeps manual configuration and prunes the legacy scaffold.
 
-## Plan mode
+Done → the user can run `/w:spec-new`, `/w:plan-new` or `/w:quick`.
 
-Resolves the sources and describes the minimal scaffolding it would create (and what a re-run would prune), without writing files.
+## More context
 
-## Resources
+`aw context-plan --command workspace-init --signal <s>` returns the extra documents a case needs; read exactly what it lists:
 
-- Design reference: `docs/referencias/workflow-commands/workspace-init.md`
-- Skills config: `docs/referencias/workflow-roles/` (available capabilities/roles and the binding cascade)
+- `scaffold` — the folder already carries a workspace, or you need what init versions, ignores and prunes → [`../modules/WORKSPACE-SCAFFOLD.md`](../modules/WORKSPACE-SCAFFOLD.md)