@tacuchi/agent-workflow-cli 20.23.0 → 20.24.0

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.

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 — the pending pipeline by default, the full history under detail — 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 — pass `detalle` for the full inventory)
+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,29 +8,22 @@ allowed-tools:
   ]
 ---
 
-# status — workspace state (read-only)
+# status — workspace state
 
-Single-pass, read-only: no loop, no sessions, writes nothing in `docs/` or `.workflow/`. **Transversal** command (belongs to no flow).
+Read-only single pass: no loop, no session, no writes. Transversal.
 
 ## Run
 
-1. Run `aw status --format human` — add `--detail` when the user asked for the full inventory ("detalle", "todo", "historial").
-2. **Relay its output verbatim.** The CLI already selects, filters, groups and humanizes the dates; re-rendering it here is what made the two drift apart. Do not paraphrase it, do not re-sort it, do not add or drop a line.
-3. **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. No cheap host memory → **omit the section silently**. Never run an expensive transcript scan and **never ask**.
+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.
 
-> **The default view is what is LEFT TO DO** — unrefined specs, refined specs with no plan, plans not `done`. Finished history, sessions and discarded items are still in the model; `--detail` brings them back. If the user asks about something the default hides, re-run with `--detail` instead of explaining its absence.
+> **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.
 
-> **Automation reads JSON.** Through a pipe, and with `--json` or `--format json`, `aw status` emits the same machine-readable envelope it always has. `--detail` belongs to the human projection only.
+> **Automation reads JSON.** Piped or with `--json` / `--format json`, `aw status` emits its machine-readable envelope; `--detail` is human-only.
 
-Uninitialized workspace (`initialized: false`, everything empty) → say the folder is not an agent-workflow workspace and suggest `/w:workspace-init`.
+`initialized: false`, everything empty → say the folder is not an agent-workflow workspace and suggest `/w:workspace-init`.
 
-## Plan mode
+## More context
 
-Same as execution: `aw status --format human` is read-only. There are no changes to apply.
-
-## Resources
-
-- CLI: `aw status` (index `workline-index-service`, projection `status-service`; dates via `humanize-es`)
-- Sibling: `aw resume` — what to pick up next, from the same index
-- 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`
+`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,5 +1,5 @@
 ---
-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:
   [
@@ -10,32 +10,25 @@ allowed-tools:
 
 # 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] --format human
-```
+`aw workspace-init --source alias:path[:branch] [--proyecto <name>] [--main-branch <branch>] [--dry-run] --format human`
 
-> **The CLI writes; this wrapper does not.** Every file below is created by `aw workspace-init` — `Write` and `Edit` are deliberately absent from `allowed-tools`. Use `--dry-run` to show the user what would land, then re-run without it. Relay the CLI's output instead of re-rendering it.
+> **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.
 
 ## 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.
+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.
 
-**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.
+**Idempotent** — a re-run reconciles: it keeps manual configuration and prunes the legacy scaffold.
 
-When done, the user can run `/w:spec-new`, `/w:plan-new` or `/w:quick` directly.
+Done → the user can run `/w:spec-new`, `/w:plan-new` or `/w:quick`.
 
-**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).
+## More context
 
-## Plan mode
+`aw context-plan --command workspace-init --signal <s>` returns the extra documents a case needs; read exactly what it lists:
 
-Resolves the sources and describes the minimal scaffolding it would create (and what a re-run would prune), without writing files.
-
-## Resources
-
-- 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)