lv-spec

Files (1)

• SKILL.md

SKILL.md (first lines)

# Spec Role

**`help` / `--help`:** if that is the whole argument, print the `## Usage` block at the end of this file verbatim and stop.

You are in **spec mode**. Your job is to convert decided briefs into precise, step-by-step implementation plans that another Claude session can execute without judgment calls.

## Unattended mode

If `LV_UNATTENDED=1` is set in your environment, you were launched by the orchestrator and **there is no human reading your output**. A question asked here hangs the pipeline.

Rules, in force for the whole session:

0. **Claim the artifact before you read anything** — the shared rule in [Claiming](#claiming), with `--if-free` so you stand down instead of racing:
   ```bash
   scripts/lv-exec.sh lv-claim.sh PLN-NNN-<slug> --if-free   # a plan
   scripts/lv-exec.sh lv-claim.sh BRF-NNN --if-free          # a brief, no plan folder yet
   scripts/lv-exec.sh lv-claim.sh BUG-NNN --if-free          # a bug, likewise
   ```
   Exit 2 means **another** live session is already on it — print the message and exit 0. Exit 0 includes `already held on your behalf by the dispatcher`, which is the normal unattended case and means carry on: the claim names your own PID, and treating that as somebody else's is how the test role spun (WFI-073/075). Claiming *after* the work is claiming after the race: client-a ran two unattended lv-spec workers over one plan for twenty minutes, and the second wrote its `## Review` block on top of the first's, leaving plan.md with two contradicting verdicts (WFI-067). The dispatcher now claims at spawn, so under the orchestrator this is usually already held on your behalf — it costs one call to be sure.
1. If your instructions name an artifact (`PLN-NNN`, `BUG-NNN`, `BRF-NNN`), skip the selection menu entirely and work that artifact.
2. Prompts marked **[AUTO]** below resolve to their stated default. Take it and move on.
3. Prompts marked **[GATE]** below must never be guessed. Park the work instead:
   ```bash
   scripts/lv-exec.sh lv-gate-open.sh <ID> <gate-name> "<question>" --context <path> --skill lv-spec
   ```
   Then **exit cleanly** without changing REGISTRY state. The dispatcher skips gated artifacts; `/lv-attend` will bring a human to it.

   **The claim is released for you.** `lv-gate-open.sh` drops it once the gate is up — gate first, claim second, so the plan is never both unguarded and parked (`docs/guard-ordering.md`). You do not call `lv-unclaim.sh` on a gate exit, and calling it anyway is harmless: the release is idempotent.

   **Whatever happens — a finished plan, a blocked brief, nothing to do, or a parked gate — this skill never ends holding a claim.** Every exit path below says so again where it applies, but the rule is unconditional. It is written here because it was once true of only some of them: the Replanning path left a worker holding a claim on a plan it had just moved to `active`, which is WFI-012, and the fix went in there and nowhere else.
4. **Never guess.** If you are about to ask something that isn't in the table, treat it as a [GATE] — use gate name `needs-input`.

| Step | Prompt | Mode | Unattended behavior |
|-|-|-|-|
| Entry | Work selection menu | [AUTO] | Use the artifact named in your instructions |
| 1 | Deferred criteria to include | [AUTO] | Include none — do not widen scope unattended |
| 4b | Goal confirmation | [AUTO] | Accept your own draft if it is concrete and specific. If you cannot write a concrete goal from the source artifact, [GATE] `goal-missing` |
| 4c | Tag assignment | [AUTO] | Assign from `lv-list-tags.sh` based on slug, goal, and touched paths |
| 7c | Auto-test promotion (y/n) | [AUTO] | **Yes** — promote, the same as attended since WFI-006 |
| Review gate | Plan approval | **[GATE]** or [AUTO] | Depends on `specApproval.mode` — see below |
| 6a (replan) | An amendment narrows the Goal | **[GATE]** | `scope-reduction` — always, whatever the verdict and whatever the mode |

### The review gate

Read the mode before you exit — do not assume either behavior:

```bash
SPEC_MODE=$(scripts/lv-exec.sh lv-config-get.sh specApproval.mode verdict)
MAX_ROUNDS=$(scripts/lv-exec.sh lv-config-get.sh specApproval.maxReviewRounds 3)
GATE_TAGS=$(scripts/lv-exec.sh lv-config-get.sh specApproval.gateTags --list)
```

**`gate`** — the hard stop on *approval*. A spec may be written unattended; it may not be **approved** unattended. Park as `spec-approval` and exit.

**`verdict` (default since WFI-006)** — **the verdict is the gate**, not the plan's existence. An approved plan goes to `ready` with no human.

**`gateTags`** — plans carrying one of these tags always gate, whatever the verdict. The escape hatch, and not overridable.

**The review itself runs unattended in all three cases.** It is a read-only analysis that decides nothing; what differs is what its verdict is *allowed to do*. Every unattended exit goes through [Exit — unattended](#exit--unattended).

That ordering was once the other way around, and the tag path parked the plan *before* any review ran. Two consequences, both measured in a single drain: a tagged plan got **less** automated scrutiny than an untagged one and sat idle waiting for a human to commission a review a machine could have run immediately (one waited 3h20m unreviewed); and the human was handed approvable and unapprovable plans identically, so two of four gates were consumed only to end at `draft` with findings — exactly where an unattended Blocked verdict routes them anyway. A Blocked verdict needs no human. An Approved one is the only thing worth interrupting for.

Why the second mode exists, so you can judge whether the run in front of you fits it: in a measured 16-plan program the review found Critical findings in **8 of 8** plans drained with a human present. Not one was approvable as drafted, so the human's decision was never *"is this good?"* — it was always *"proceed with the fix loop the reviewer just specified."* The gate sat in front of the mechanism that does the filtering, admitting everything to a step that then rejected everything. Total human input across those 8 gates: the word "approve", then the word "all".

What that mode costs, stated plainly: some Criticals are found by *cross-plan* reasoning a per-plan reviewer cannot reach, and were caught only because a human skimming a queue of 15 plans noticed a contradiction. The [cross-plan consistency pass](#cross-plan-consistency) is the compensating control. If it is disabled, `verdict` mode is running without a safety net.

## IMMEDIATE STARTUP — run in parallel before reading further

1. Run branch check (do not prompt the user):
   ```bash
   scripts/lv-exec.sh lv-branch-check.sh develop true
   ```

   **Exit 2 means the check refused to switch.** Another session is holding this
   shared checkout, and switching it would move a ref out from under them. Two
   cases, both refused:

   - parked on a branch the pipeline does not own — how four commits for one
     plan landed on a human's topic branch (WFI-123);
   - parked on `release` or `main` — a `/lv-release` or `/lv-deploy` is running.
     The orchestrator never leaves the checkout there and never dispatches those
     skills, so this is always somebody's deploy mid-flight. Switching sent a
     deploy's last seven commits to `develop` instead of `main` (WFI-157).

   Stop — do not `git checkout` past it. Under `LV_UNATTENDED=1` exit 0 without
   claiming anything; the dispatcher offers the work again once the checkout is
   back on develop.

2. Spawn a **haiku subagent** to fetch and format the worklist:

```
Agent(model: haiku, prompt: "Run `scripts/lv-exec.sh lv-list-specable.sh` in the current directory.
Parse the tab-separated output (sections: # replanning, # bugs, # briefs).

Format as TWO markdown tables:

**Table 1 — Available work** (actionable items with sequential numbering):
| # | Priority | Type | ID | Name | Detail |
|-|-|-|-|-|-|
- Replans: the third tab field is priority (show it). Type = Replan.
- Bugs: priority = '—', second field = severity, third = title. Type = Bug.
- Briefs: priority = '—', second field = name, third = description. Type = Brief.
  If a brief's detail says 'Already has plan PLN-NNN', put it in Table 2 instead.
- A detail beginning 'GATED(<name>)' means the artifact is parked on an open gate.
  Put it in Table 3 instead of Table 1, and do NOT give it a number.

**Table 3 — Parked on a gate** (informational, no numbering):
| Type | ID | Name | Gate |
|-|-|-|-|
Omit this table if empty.

**Table 2 — Already planned** (informational, no numbering):
| Type | ID | Name | Plan |
|-|-|-|-|
Only briefs that already have a plan go here. Omit this table if empty.

After the tables add: Mark a plan urgent: \`u <number>\` (replans only)

If no actionable items, say 'No specable work found.' — but still print Table 3 if it has rows.

From slicedBread-marc/levain, MIT.

More from slicedBread-marc/levain