spexcode 0.2.8 → 0.4.0

package/spec-cli/templates/spec/project/{.config → .plugins}/extract/spec.md

@@ -7,7 +7,7 @@ desc: Reverse-engineer a faithful spec tree out of existing code — responsibil
 kind: mutating
 ---
 Reverse-engineer a spec tree for the target source area(s) below — code that has no specs yet. Aim for a
-tree where every governed file is claimed and `spex lint` is clean, with bodies at contract altitude and in
+tree where every governed file is claimed and `spex spec lint` is clean, with bodies at contract altitude and in
 the codebase's own primary language (a predominantly-Chinese repo → Chinese specs).
 
 {{targets}}
@@ -42,11 +42,11 @@ Then grow nodes under that spine:
   dignifying it with a confident spec.
 
 **Give every frontend node a loss signal.** A node that governs UI or visual code (`.tsx`/`.jsx`/`.vue`/
-`.svelte`/`.css`, or the dashboard) is a blind spot until it carries a `yatsu.md` — so write one as you
+`.svelte`/`.css`, or the dashboard) is a blind spot until it carries a `eval.md` — so write one as you
 extract it: a **real user-path** scenario — a goal and the steps to reach it through the running app (never a
 bare render-check), covering a failure/empty/edge state — with a **description** of those steps and the
-**expected** zero-loss result. Frontend scenarios are measured by looking (YATU) — a screenshot filed with
-`spex yatsu eval <node> --image <png> --pass`. Backend nodes don't need one yet; run `spex yatsu scan` to
+**expected** zero-loss result. Frontend scenarios are measured by looking — through the running product, as a real user would — a screenshot filed with
+`spex eval add <node> --image <png> --pass`. Backend nodes don't need one yet; run `spex eval lint` to
 list the frontend nodes still uncovered.
 
 **Extract incrementally — don't plan the whole tree before writing.** For a large area (hundreds of files),
@@ -57,4 +57,4 @@ one subtree uncommitted, so progress survives context limits.
 
 Confirm `spexcode.json`'s `governedRoots` points at the real source dirs first — lint reads silently empty
 otherwise. Commit one node per commit (`spec: <id> — extract from <area>`) with a `Session:` trailer, and
-run `spex lint` after each: it must reach 0 errors, 0 coverage warnings, 0 altitude warnings.
+run `spex spec lint` after each: it must reach 0 errors, 0 coverage warnings, 0 altitude warnings.

package/spec-cli/templates/spec/project/{.config → .plugins/prompts}/forge-link/spec.md

@@ -6,4 +6,4 @@ hue: 280
 desc: A config plugin — agents link an issue they open to the spec node it serves via a `Spec: <id>` body line.
 code:
 ---
-When you open a GitHub issue, link it to the spec node(s) it serves by adding a line to the issue **body**: `Spec: <node-id>` (comma-separate several). The id is the node's **leaf** name — the folder under `.spec/…/<id>/spec.md`, e.g. `sessions`, never the slash-path. An unrecognized id silently links nothing, so use a real node id (`spex board` lists them). A pull request needs no marker: opening it from your `node/<id>` branch links it for free.
+When you open a GitHub issue, link it to the spec node(s) it serves by adding a line to the issue **body**: `Spec: <node-id>` (comma-separate several). The id is the node's **leaf** name — the folder under `.spec/…/<id>/spec.md`, e.g. `sessions`, never the slash-path. An unrecognized id silently links nothing, so use a real node id (`spex graph --json` lists them). A pull request needs no marker: opening it from your `node/<id>` branch links it for free.

package/spec-cli/templates/spec/project/{.config → .plugins/prompts}/reproduce-before-fix/spec.md

@@ -10,9 +10,9 @@ code:
 
 If your task is to FIX A BUG, reproduce it *first*, as a measurement — before you touch the fix. A claim that something is broken is worth nothing until the loss signal shows it broken; a claim that you fixed it is worth nothing until the same signal shows it passing. So a bug fix is bracketed by two readings of ONE scenario:
 
-- **A — reproduce (fail).** Find the yatsu scenario whose expected the bug violates (if none fits, ADD one to the node's `yatsu.md` — a description + the expected correct behaviour), run it, and file the failing reading with evidence that SHOWS the bug: `spex yatsu eval <node> --scenario <s> --fail --note "<what's wrong>"` plus an `--image`/`--video` of the actual broken behaviour. This is not ceremony — reproducing is how you learn what actually breaks, and a fix aimed at an unreproduced bug aims at a guess.
-- **B — fix, then re-measure (pass).** Make the code honor the spec, run the SAME scenario again, and file the passing reading with evidence of the corrected behaviour: `spex yatsu eval <node> --scenario <s> --pass`.
+- **A — reproduce (fail).** Find the eval scenario whose expected the bug violates (if none fits, ADD one to the node's `eval.md` — a description + the expected correct behaviour), run it, and file the failing reading with evidence that SHOWS the bug: `spex eval add <node> --scenario <s> --fail --note "<what's wrong>"` plus an `--image`/`--video` of the actual broken behaviour. This is not ceremony — reproducing is how you learn what actually breaks, and a fix aimed at an unreproduced bug aims at a guess.
+- **B — fix, then re-measure (pass).** Make the code honor the spec, run the SAME scenario again, and file the passing reading with evidence of the corrected behaviour: `spex eval add <node> --scenario <s> --pass`.
 
-The two readings on the same scenario are the **A/B** — the error→correct transition, the fix's proof-of-work. yatsu keeps per-scenario reading history, so the pair is durable and navigable end to end.
+The two readings on the same scenario are the **A/B** — the error→correct transition, the fix's proof-of-work. eval keeps per-scenario reading history, so the pair is durable and navigable end to end.
 
 Don't skip A because the fix looks obvious — an obvious fix with no reproduced failure leaves the loss signal blind to exactly the regression you just closed. This does not apply to building new intent (there is no prior failure to reproduce) — it is the discipline for **repair**: keep the loss signal honest across a bug's whole lifecycle, not just at the end.

package/spec-cli/templates/spec/project/.plugins/prompts/spec.md

@@ -0,0 +1,20 @@
+---
+title: prompts
+status: active
+hue: 110
+desc: Grouping shelf for the auxiliary `surface: system` prompt contracts — single-body always-on prose. `core` is not a resident — the core contract subsystem is a direct `.plugins` child. A shelf, not a surface — routing stays field-driven.
+---
+# prompts
+
+The **auxiliary** `surface: system` prompt contracts live here: leaf plugins whose whole substance is one
+prose body an agent must always carry — materialized (in name order, together with every other system
+body) into the `<!-- spexcode -->` contract block — rather than a verb it invokes. Grouping them keeps
+`.plugins/` legible at a glance: peripheral prompt contracts on this shelf; the invocable surfaces
+(command/skill/agent) and `core` as flat children beside it.
+
+The shelf boundary is **leafness, not surface**: a single-body prose contract shelves here, while a
+contract that anchors its own subtree outranks the shelf — `core`, the contract subsystem whose children
+are the `surface: hook` gates, is a *peer* of this shelf, never a resident.
+
+This node is a **shelf, not a surface**: it declares no `surface` field and gathers nothing itself.
+Discovery is recursive and field-driven, so residents plug in exactly as they would at the root.

package/spec-cli/templates/spec/project/{.config → .plugins}/regroup/spec.md

@@ -18,8 +18,8 @@ Read before you move: the over-broad node's spec, every child's spec, and the `[
 
 Honor these:
 
-- **Reparent, never rewrite.** Move a node by `git mv`-ing its folder; its id (= folder basename), its `[[links]]`, its `code:` governance, and its `yatsu.md` all ride along untouched. If a child needs its body edited to belong in a group, it doesn't belong.
+- **Reparent, never rewrite.** Move a node by `git mv`-ing its folder; its id (= folder basename), its `[[links]]`, its `code:` governance, and its `eval.md` all ride along untouched. If a child needs its body edited to belong in a group, it doesn't belong.
 - **Fewest, deepest-justified parents.** Don't trade one flat layer for six two-child wrappers — that relocates the sprawl instead of resolving it. Between two passing groupings, take the one that adds fewer nodes.
 - Parent ids name the concept (kebab-case); give the parent a `hue` near its children's family.
 
-Work the order: (1) read everything; (2) write each candidate seam with the one-sentence intent that justifies it — kill the unjustifiable, and mark each survivor as reparent-under-existing or new-parent; (3) make the moves, one reviewable commit per group (`spec: <parent> — regroup <children>`, with a `Session:` trailer); (4) run `spex lint` and confirm breadth is resolved with no new errors. Uncommitted `git mv`s churn the drift count transiently — committing settles it; don't chase it.
+Work the order: (1) read everything; (2) write each candidate seam with the one-sentence intent that justifies it — kill the unjustifiable, and mark each survivor as reparent-under-existing or new-parent; (3) make the moves, one reviewable commit per group (`spec: <parent> — regroup <children>`, with a `Session:` trailer); (4) run `spex spec lint` and confirm breadth is resolved with no new errors. Uncommitted `git mv`s churn the drift count transiently — committing settles it; don't chase it.

package/spec-cli/templates/spec/project/.plugins/spec.md

@@ -0,0 +1,18 @@
+---
+title: .plugins
+status: active
+hue: 110
+desc: The instance home — this repo's DIY dev-flow plugins live here as skill-shaped plugin nodes.
+---
+`.plugins/` is the **instance** of the plugin system: the concrete dev-flow plugins this repo ships for
+working in it. Each plugin is a skill-shaped node — its folder *is* the unit (a `spec.md` plus any
+co-located scripts) — carrying a `surface: command|system|…` field that names where it plugs in.
+Discovery is recursive and field-driven, so plugins may sit under a grouping shelf: the auxiliary
+`surface: system` prompt contracts live under `prompts/`, while `core` — the contract subsystem whose
+children are the `surface: hook` gates — and invocable presets (command/skill/agent) are flat
+children here.
+
+The launcher's system gather and the new-session dropdown read from here. Only **active** plugins
+gather: a `pending` node is declared intent, not yet an active plugin. The seed ships `core`
+(`surface: system` — the spec-discipline contract folded into every agent) plus command presets like
+`tidy`; add your own by creating a sibling node with a `surface` field.

package/spec-cli/templates/spec/project/.plugins/supervisor/spec.md

@@ -0,0 +1,8 @@
+---
+title: supervisor
+surface: command
+status: active
+hue: 280
+desc: Launch a supervisor agent that manages other agents from the main checkout to drive a goal to completion.
+---
+You are a SpexCode supervisor — a **manager**, not a feature worker. Your work base is the main checkout (the repository root), NOT your own worktree: do all git via `git -C <root>`, everything else via the `spex` CLI, and never write feature code. **FIRST, read the project's agent notes (`<root>/CLAUDE.md` / `AGENTS.md`, including the materialized `<!-- spexcode -->` contract block)** for project-specific rules; the loop below (dispatch → monitor → review → merge → close, parallelizing independent tasks) is your playbook. Then drive the goal: decompose it into worker-sized tasks and dispatch one worker per independent task (`spex session new "<task>"` — give each ONLY its task; a task about one specific node mentions it as `[[<id>]]`, which only sets the branch name and board attribution; the session's real node links come from what it edits), monitor with `spex session watch`, review proposals with `spex session review <id>`, merge good ones with `git -C <root> merge --no-ff <branch>`, then close. Never let a worker self-merge; keep `spex spec lint` at 0 errors. To WAIT on a worker, POLL one-shot (`spex session review <id>` or `spex session ls` — both return immediately); never block on `spex session watch`, which STREAMS forever and will freeze your turn. One footgun that bites a fresh supervisor: before `spex session close <id>`, confirm the merge landed (`git -C <root> log -1` shows HEAD at the new merge commit) — closing an unmerged branch discards the work. Report progress as you go and when the goal is complete. Your goal follows:

package/spec-cli/templates/spec/project/{.config → .plugins}/tidy/spec.md

@@ -22,4 +22,4 @@ For each target, in its own commit:
 - **Cut redundancy and narration** — say each thing once, at the altitude a maintainer needs.
 - **Stay a living document** — rewrite in place; never add `## vN` history (git carries versions).
 
-Commit per node (`spec: <id> — tidy to contract altitude`) with a `Session:` trailer. Run `spex lint` after each — it must stay at 0 errors.
+Commit per node (`spec: <id> — tidy to contract altitude`) with a `Session:` trailer. Run `spex spec lint` after each — it must stay at 0 errors.

package/spec-cli/templates/spec/project/spec.md

@@ -12,7 +12,7 @@ made it. This node is the founding spec everything else hangs from — **rewrite
 your own project**, then grow child package/feature nodes beneath it (each its own directory with a
 `spec.md`).
 
-`.config/` holds the dev-flow plugins this instance ships — skill-shaped flat child nodes, each tagged
+`.plugins/` holds the dev-flow plugins this instance ships — skill-shaped child nodes, each tagged
 with a `surface` field: a `surface: system` node folds into every launched agent's system prompt as
 always-on contract (the seed ships `core`), and a `surface: command` node is a prompt preset the
 new-session dropdown composes over target nodes (the seed ships `tidy`). Add, edit, or