@ikon85/agent-workflow-kit 0.10.0

package/.agents/skills/improve-codebase-architecture/SKILL.md

@@ -0,0 +1,88 @@
+---
+name: improve-codebase-architecture
+disable-model-invocation: true
+description: "Find deepening opportunities in a codebase, informed by the domain language in CONTEXT.md and the decisions in docs/adr/. Use when the user wants to improve architecture, find refactoring opportunities, consolidate tightly-coupled modules, or make a codebase more testable and AI-navigable."
+---
+
+# Improve Codebase Architecture
+
+Surface architectural friction and propose **deepening opportunities** — refactors that turn shallow modules into deep ones. The aim is testability and AI-navigability.
+
+For a quick one-off map of an unfamiliar area without the report/grilling loop below, use `zoom-out` instead.
+
+## Glossary
+
+Use these terms exactly in every suggestion. Consistent language is the point — don't drift into "component," "service," "API," or "boundary." Full definitions in [LANGUAGE.md](LANGUAGE.md).
+
+- **Module** — anything with an interface and an implementation (function, class, package, slice).
+- **Interface** — everything a caller must know to use the module: types, invariants, error modes, ordering, config. Not just the type signature.
+- **Implementation** — the code inside.
+- **Depth** — leverage at the interface: a lot of behaviour behind a small interface. **Deep** = high leverage. **Shallow** = interface nearly as complex as the implementation.
+- **Seam** — where an interface lives; a place behaviour can be altered without editing in place. (Use this, not "boundary.")
+- **Adapter** — a concrete thing satisfying an interface at a seam.
+- **Leverage** — what callers get from depth.
+- **Locality** — what maintainers get from depth: change, bugs, knowledge concentrated in one place.
+
+Key principles (see [LANGUAGE.md](LANGUAGE.md) for the full list):
+
+- **Deletion test**: imagine deleting the module. If complexity vanishes, it was a pass-through. If complexity reappears across N callers, it was earning its keep.
+- **The interface is the test surface.**
+- **One adapter = hypothetical seam. Two adapters = real seam.**
+
+This skill is _informed_ by the project's domain model. The domain language gives names to good seams; ADRs record decisions the skill should not re-litigate.
+
+## Process
+
+### 1. Explore
+
+Read the project's domain glossary and any ADRs in the area you're touching first.
+
+<!-- mirror-xform:start codex-explorer-dispatch -->
+When the user has authorized subagent delegation, use `spawn_agent` with `agent_type: explorer` to walk the codebase; otherwise explore locally. Don't follow rigid heuristics — explore organically and note where you experience friction:
+<!-- mirror-xform:end -->
+
+- Where does understanding one concept require bouncing between many small modules?
+- Where are modules **shallow** — interface nearly as complex as the implementation?
+- Where have pure functions been extracted just for testability, but the real bugs hide in how they're called (no **locality**)?
+- Where do tightly-coupled modules leak across their seams?
+- Which parts of the codebase are untested, or hard to test through their current interface?
+
+Apply the **deletion test** to anything you suspect is shallow: would deleting it concentrate complexity, or just move it? A "yes, concentrates" is the signal you want.
+
+### 2. Present candidates as an HTML report
+
+Write a self-contained HTML file to the OS temp directory so nothing lands in the repo. Resolve the temp dir from `$TMPDIR`, falling back to `/tmp` (or `%TEMP%` on Windows), and write to `<tmpdir>/architecture-review-<timestamp>.html` so each run gets a fresh file. Open it for the user — `xdg-open <path>` on Linux, `open <path>` on macOS, `start <path>` on Windows — and tell them the absolute path.
+
+The report uses **Tailwind via CDN** for layout and styling, and **Mermaid via CDN** for diagrams where a graph/flow/sequence reliably communicates the structure. Mix Mermaid with hand-crafted CSS/SVG visuals — use Mermaid when relationships are graph-shaped (call graphs, dependencies, sequences), and hand-built divs/SVG when you want something more editorial (mass diagrams, cross-sections, collapse animations). Each candidate gets a **before/after visualisation**. Be visual.
+
+For each candidate, the same template as before, but rendered as a card:
+
+- **Files** — which files/modules are involved
+- **Problem** — why the current architecture is causing friction
+- **Solution** — plain English description of what would change
+- **Benefits** — explained in terms of locality and leverage, and how tests would improve
+- **Before / After diagram** — side-by-side, custom-drawn, illustrating the shallowness and the deepening
+- **Recommendation strength** — one of `Strong`, `Worth exploring`, `Speculative`, rendered as a badge
+
+End the report with a **Top recommendation** section: which candidate you'd tackle first and why.
+
+**Use CONTEXT.md vocabulary for the domain, and [LANGUAGE.md](LANGUAGE.md) vocabulary for the architecture.** If `CONTEXT.md` defines "Order," talk about "the Order intake module" — not "the FooBarHandler," and not "the Order service."
+
+**ADR conflicts**: if a candidate contradicts an existing ADR, only surface it when the friction is real enough to warrant revisiting the ADR. Mark it clearly in the card (e.g. a warning callout: _"contradicts ADR-0007 — but worth reopening because…"_). Don't list every theoretical refactor an ADR forbids.
+
+See [HTML-REPORT.md](HTML-REPORT.md) for the full HTML scaffold, diagram patterns, and styling guidance.
+
+Do NOT propose interfaces yet. After the file is written, ask the user: "Which of these would you like to explore?"
+
+### 3. Grilling loop
+
+Once the user picks a candidate, drop into a grilling conversation. Walk the design tree with them — constraints, dependencies, the shape of the deepened module, what sits behind the seam, what tests survive.
+
+Side effects happen inline as decisions crystallize:
+
+- **Naming a deepened module after a concept not in `CONTEXT.md`?** Add the term to `CONTEXT.md` — same discipline as `/grill-with-docs` (see [CONTEXT-FORMAT.md](CONTEXT-FORMAT.md)). Create the file lazily if it doesn't exist.
+- **Sharpening a fuzzy term during the conversation?** Update `CONTEXT.md` right there.
+- **User rejects the candidate with a load-bearing reason?** Offer an ADR, framed as: _"Want me to record this as an ADR so future architecture reviews don't re-suggest it?"_ Only offer when the reason would actually be needed by a future explorer to avoid re-suggesting the same thing — skip ephemeral reasons ("not worth it right now") and self-evident ones. See [ADR-FORMAT.md](ADR-FORMAT.md).
+- **Want to explore alternative interfaces for the deepened module?** See [INTERFACE-DESIGN.md](INTERFACE-DESIGN.md).
+
+> `ADR-FORMAT.md` / `CONTEXT-FORMAT.md` in this skill dir are **vendored snapshots** of the canonical `grill-with-docs` versions (self-containment: no sibling-skill reach; **no sync promise** —).

package/.agents/skills/improve-codebase-architecture/THIRD-PARTY-NOTICES.md

@@ -0,0 +1,29 @@
+# Third-Party Notices
+
+This skill is adapted from **Matt Pocock's skills**
+(https://github.com/mattpocock/skills), `skills/engineering/improve-codebase-architecture` @ d574778, Copyright (c) 2026 Matt Pocock,
+used under the MIT License. Locally adapted (fork-and-own); see PROVENANCE.md.
+
+```
+MIT License
+
+Copyright (c) 2026 Matt Pocock
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+```

package/.agents/skills/kit-release/SKILL.md

@@ -0,0 +1,56 @@
+---
+name: kit-release
+description: "Prepare a verified release PR for agent-workflow-kit with an explicit Semver confirmation, regenerated manifest, full tests, and pack audit, then delegate landing to wrapup."
+---
+
+# Kit Release
+
+Prepare a release deterministically. This skill owns the shipped-delta decision,
+metadata preparation, and verification. It does not implement commit, push, PR,
+merge, registry publishing, tags, or release creation.
+
+## Workflow
+
+1. Run the read-only plan:
+
+   ```sh
+   npm run release:prepare
+   ```
+
+   Report every added, removed, and changed shipped path plus the recommended
+   Patch, Minor, or Major bump. The recommendation is deterministic: removals
+   recommend Major, additions recommend Minor, and changed content recommends
+   Patch.
+
+2. Ask the user to confirm exactly one target Semver. Do not change release
+   metadata before confirmation. A recommendation is advice; the confirmed
+   target is authority.
+
+3. Prepare that exact version:
+
+   ```sh
+   npm run release:prepare -- --version <confirmed-version>
+   ```
+
+   The script updates `package.json`, adds the release-notes section,
+   regenerates `agent-workflow-kit.package.json`, runs the full test gate, and
+   performs `npm pack --dry-run`. If a gate fails, report the error and keep the
+   prepared tree. Re-running the same target resumes that state without another
+   bump or duplicate release notes.
+
+4. Inspect the resulting delta and invoke **`$wrapup`**. Wrapup and
+   `scripts/wrapup-land.py` exclusively own commit, push, PR creation, merge,
+   and cleanup. Do not reproduce those operations here.
+
+5. After merge, the release is not complete until the repository's configured
+   publishing flow has produced the matching registry package and GitHub
+   tag/release and verified their parity. If that flow is not configured, stop
+   and report the missing post-merge capability; never publish ad hoc.
+
+## Guard contract
+
+`npm run release:guard -- --base <base-ref>` freshly builds the shipped
+manifest and compares it with both the base and the checked-in manifest. It
+blocks an unbumped shipped delta, a stale manifest, a too-small Semver bump, or
+a dead manifest entry and prints the concrete paths. CI runs the same command;
+there is no separately remembered shipped-file list.

package/.agents/skills/local-ci/SKILL.md

@@ -0,0 +1,94 @@
+---
+name: local-ci
+"description": "Run the repo's local CI gate before opening a PR — the stand-in for GitHub required status checks when your plan or repo visibility can't enforce them (a Free-plan private repo has no branch protection). Use before every PR, when a guard/test red is suspected on a branch, or when wiring/repairing the pre-push guard backstop. Triggers — \"local ci\", \"run local ci\", \"pre-PR check\", \"why is main red\", \"did a guard land red\"."
+---
+
+# Local CI
+
+A guard only protects if it runs on a **gate**. When your host can't enforce a
+required status check at merge — **GitHub Free + Private has no branch protection
+and no rulesets** ([GitHub Docs: protected
+branches](https://docs.github.com/en/repositories/configuring-branches-and-merges-in-your-repository/managing-protected-branches/about-protected-branches))
+— the gate has to be **local**. This skill is that gate.
+
+> Fault class: *Detection without Enforcement.* A guard that runs only in a
+> manual, opt-in step is not a gate — the drift it catches still merges. Fix the
+> gate class, not the one field that slipped through.
+
+The exact commands, guard names, hook wiring and the project's own incident lore
+live in the **project layer** for this skill (its `docs/agents/skills/local-ci.md`,
+seeded as an empty stub by `/setup-workflow` and filled per project). This
+skeleton names the two profiles generically; run the two your project layer names.
+
+## When
+
+- **Before opening ANY PR** → run the full local gate. Red → fix it, or defer a
+  *single* failure ONLY with an explicit written reason in the PR body (never
+  silently — a skipped gate framed as done is a fake quality gate).
+- A guard/test red is suspected on a branch ("why is main red").
+- Wiring or repairing the pre-push backstop / adding a new guard.
+
+## The two profiles
+
+Two commands, one fast and one full — your project layer names the exact
+invocations:
+
+- **Fast static guards** — no DB, ~seconds. Run automatically at **pre-push** so a
+  red drift guard cannot leave the machine.
+- **Full gate** — typecheck + lint + the test suites a CI job would run, ~a minute.
+  Too slow for a hook → the **agent's named pre-PR step**, explicit not automatic.
+
+## Enforcement model
+
+- **pre-push** runs the fast guards automatically → a red drift guard cannot be
+  pushed. Keep any emergency escape hatch explicit and logged — never a silent one.
+- **pre-commit** gates typecheck + lint, and should block a committed focused-test
+  marker (`.only` / `fit` / `fdescribe`) so a focused test can't silently gut a
+  file's coverage (green-but-empty).
+- The **full gate** is the agent's named pre-PR step: the full suite is too slow
+  for a hook, so it is explicit, not automatic. Run it; report the result honestly.
+
+## Contention — stop the dev server before the full gate
+
+The full gate runs several test runners at once. A dev server running in parallel
+oversubscribes the cores → **boot-contention false reds**: hook/boot timeouts in
+*unrelated* tests that are green in isolation. Symptom = "Hook timed out" in tests
+that pass on their own.
+
+- Stop the dev server before the full gate. Verify a suspicious red as a false red
+  by running that one test in isolation — green in isolation = contention, not a
+  real red.
+- Kill the dev server by **PID-via-port, not a process-name match**. A name match
+  (`vite`) also hits the test runner (`vitest`), and matching your own command line
+  kills the running command. Resolve the PID from the listening port instead.
+
+## On a red
+
+1. Read the failing test's message — a good guard prints the exact drift
+   (`file:line`, the offending token, the missing allowlist key).
+2. Fix the source. If a guard legitimately can't be satisfied yet, add its
+   **documented allowlist entry with a reason** — never widen a guard silently
+   (that re-opens the blind spot the guard exists to close).
+3. Iterate on the single file, then the full gate for sign-off.
+
+## Adding a new guard
+
+Prefer a **glob-discovered** guard config so a new fast static guard joins the
+pre-push set automatically — no hand-maintained list. Name it to match the include
+glob and keep it **DB-free** (pre-push must stay ~seconds); DB-bound tests belong
+to the full gate, not the fast pre-push set.
+
+## Baseline-green first
+
+If your success criterion is "gate green" and you do NOT know the base's green
+status — you are **hardening the gate itself**, or building against a `main` that a
+rename/schema cascade is landing on piecemeal — run the relevant gate part ONCE on
+the **unmodified base** before your first edit. It separates pre-existing breakage
+from your work; otherwise foreign reds surface one at a time as you build (an abort
++ scope question each).
+
+## When the host CAN enforce
+
+If the repo moves to a plan/visibility with required checks: add a CI workflow
+running the full gate on PR and make it a **required status check** — then the gate
+is machine-enforced at merge, not just local. Until then, local is the gate.

package/.agents/skills/orchestrate-wave/SKILL.md

@@ -0,0 +1,261 @@
+---
+name: orchestrate-wave
+"description": "Use when the user hands you a whole WAVE / cluster of pre-planned, file-disjoint slices and wants you to ORCHESTRATE building, verifying AND landing it end-to-end — often AFK / \"ultracode\". Triggers: \"orchestriere Welle #N\" (or any wording that delegates wave-landing responsibility to you), \"ultracode diese Welle / diesen Cluster\", or a wave-anchor issue (a cluster/umbrella issue with file-disjoint sub-issues whose specs are already locked) handed over to land. NOT for a single slice (just `tdd` it), NOT for finding/clustering a wave (that's `board-to-waves`), NOT for planning specs (that's `grill-with-docs`/`to-issues`)."
+---
+
+# Orchestrate Wave
+
+You are the orchestrator. The user gives you a wave anchor (a cluster/umbrella
+issue with file-disjoint sub-issues whose specs/decisions are already locked) and
+says "land it". You decide inline-vs-delegate; you are responsible for it landing
+correctly, AFK. Subagents BUILD; **you** integrate + verify + land.
+
+The anchor, its sub-issues and the locked plan doc contain the verbatim contracts
+you must NOT paraphrase.
+
+> **Phase 0 probes a project layer.** Concrete tooling — exact test/verify
+> commands, a DB/tunnel setup, a headless login recipe, brand checks, deploy
+> lockstep — is project-specific and lives in a **project layer** this skill reads
+> at runtime, not in this skeleton. The skeleton names the layer's sections
+> (`§Setup`, `§Builder Commands`, `§Builder Hard Rules`, `§Integration Suites`,
+> `§Verify Recipe`, `§Headless Login`, `§Landing`) and falls back to generic
+> instructions when the layer is absent. See **Phase 0**.
+
+## Standing rules (all phases)
+
+- **AFK heartbeat.** A wave run may take time but must never look stuck: during any
+  long-running gate (dispatch wait, integration suite, full verify, browser/E2E,
+  migration) send a short status update at least every ~30 s and on every phase
+  change — current gate, last green milestone, next step, visible blocker/risk. A
+  still-running tool session is stated as such; never wait silently for the final
+  result.
+- **Degrade by subtraction, never by improvisation.** The defined failure paths:
+  - **Slice stays red after escalation** (2-strikes rule, see Routing): pull the
+    slice — do not merge it (or revert its merge), pull every dependent that
+    consumes its artifacts (Phase-1 graph), land the remaining green subset, create
+    a tracking issue, leave its anchor row open, report the pull prominently.
+  - **Schema wave degraded:** if a pulled slice owns a migration/schema that a
+    remaining slice reads, the ONE-lockstep-window premise no longer holds → STOP,
+    land nothing schema-dependent, report.
+  - **Plan-level error** (integration/verify reveals a wrong LOCKED decision, not a
+    slice bug): STOP the wave. No improvised redesign AFK — keep worktrees intact,
+    report findings + options.
+- **Routing = one axis: how expensive is a wrong result to catch?** Mechanically
+  caught (test/screenshot/lint) → default tier at medium/low effort; plausible-but-
+  wrong / subtle logic / architecture → top tier at high effort + main-thread
+  re-verify; review/verify verdicts never below high. Concrete tier→model mapping
+  lives in your dispatch/model doctrine, if present — no model names here.
+  Escalate a repeatedly-failing slice one tier/effort up on the 2-strikes rule (2×
+  same problem despite concrete feedback, or structurally wrong approach — NOT the
+  first red test). The same axis sets how hard you re-verify. Borderline → default
+  tier + re-verify beats blanket top tier.
+
+## Phase 0 — Setup
+
+1. **Read everything**: the anchor body, every sub-issue body (each has a Handoff
+   block: scope, blast-radius, live-verify, PR line), and the locked plan /
+   plan-review doc in the planning worktree (file-exact).
+2. **Probe the project layer.** Read the project layer doc for this skill (the
+   consumer's `docs/agents/skills/orchestrate-wave.md` or the path your project
+   uses). If its `§`-sections carry **filled** content, follow the project recipe
+   wherever a phase below points at a `§`-section. If the file is only a
+   `setup-workflow` sentinel stub (empty headings, no real content) or absent,
+   treat the layer as **ABSENT** → use the generic fallback in each phase and warn
+   **once** that `/setup-workflow` plus project maintenance fill the layer (the
+   commands/tunnel/login can't be guessed). Never treat an empty heading as a
+   verify recipe.
+3. **Wave worktree**: reuse the planning worktree (never re-create; the handoff
+   points there). Bring its branch to current `main`:
+   `git -C <wave> merge --ff-only origin/main` (if your repo guards destructive
+   git, ff-merge is the safe path — not `reset --hard`). Install dependencies with
+   your package manager after (the lockfile may have moved). A gitignored plan doc
+   survives the merge.
+4. **Run project setup steps (`§Setup`)** the later verify needs — e.g. a DB
+   tunnel or service the live-verify depends on. Absent layer → start whatever your
+   live-verify environment requires before Phase 4.
+
+**Done when:** anchor + every sub-issue + plan read · project layer probed
+(filled → project recipe; stub/absent → generic + one-time warning) · wave branch
+ff'd to `origin/main` + deps installed · project setup steps running.
+
+## Phase 1 — Disjointness recon (the load-bearing step)
+
+Zero merge conflicts later depends entirely on getting this right.
+
+- Delegate to a read-only investigator agent: for EACH slice the exact file path of
+  every named component + resolve ambiguous targets, then a **FILE → SLICES** table
+  listing every file that appears in ≥2 slices.
+- Build the **overlap graph**. Identify the **conflict hub** (the slice whose new
+  artifacts other slices reuse). **Build the hub first**, merge it, THEN the
+  dependents stop conflicting.
+- Cut into **waves of fully file-disjoint slices**. Edited-by-≥2 = serialize across
+  waves; only-shared-via-import = safe. A new primitive edited by one slice but
+  *consumed* by others is NOT a conflict.
+- **Native blocking edges are the frontier authority.** Read the anchor's
+  buildable frontier from the tracker's native issue dependencies:
+  `python3 scripts/board-sync.py frontier <anchor#>` → `FREI` / `BLOCKED by #…` /
+  `done` per sub-issue. A body `## Blocked by` section is only the machine-written
+  MIRROR of those edges (on conflict the API wins) — never derive build order from
+  body text or table order alone. The frontier must AGREE with your Phase-1
+  dependency order; a contradiction is a plan finding to reconcile before dispatch,
+  not a detail.
+- **Reconcile contradictory sub-issue ACs against the plan BEFORE dispatch — the
+  plan is authority.** `to-issues` cuts slices independently, so a shared
+  append-only file (a query-key registry, a barrel, a shared types module) is often
+  claimed by *every* slice, with duplicate/clashing adds. **The hub slice OWNS the
+  shared-mutable file: it pre-adds ALL the wave's keys/types/helpers; dependents
+  CONSUME only and never touch it.** Embed verbatim in each dependent's contract:
+  "X already exists in `<file>` — do NOT add it, consume only." (Real case: all 14
+  sub-issues claimed the same registry adds + 4 contradictions — hub expanded to
+  own all 20 keys, batch merged conflict-free.)
+
+**Done when:** FILE→SLICES table exists · every ≥2-slice file has exactly ONE
+owning slice · disjoint waves cut in dependency order · every dependent contract
+carries its verbatim consume-only lines.
+
+## Phase 2 — Dispatch one wave in parallel (isolated worktree per implementer)
+
+Phase 2+3 repeat **per disjoint wave** from Phase 1 — the conflict-hub wave first.
+Within ONE wave, all slices dispatch at once. **Dispatch only `FREI` slices** —
+re-read the native frontier (`frontier <anchor#>`) before each wave; a
+gate-before-build edge clears only when its blocker actually lands (never
+"unblock" by editing body text — remove the edge via `dep-remove` if the plan
+genuinely changed). Two per-slice calls first: **(a)
+inline vs delegate** — a tiny mechanical bit (a rename, a 1-2-line tweak) you do
+yourself — and **(b) tier + effort** (Standing rules → Routing). For each
+delegated slice:
+
+- **One worktree per agent** off the wave-branch HEAD, own index so parallel agents
+  never share a git index. Use your project's worktree-setup command (`§Setup`),
+  else plain `git worktree add <path> -b feat/<anchor>-<slug>`.
+- **Build the prompt from [`references/builder-contract.md`](references/builder-contract.md)**
+  — fill the slots with the slice's VERBATIM What+AC, plan decision, recon
+  file:line map and consume-only lines; never paraphrase (paraphrase drift has
+  produced real contract errors). The template is the SSOT for the builder's hard
+  rules, test/typecheck commands, workflow order and report format.
+- **Capture reusable names** from the hub agent's report (the new component/helper
+  paths) and embed them into the dependent slices' contracts.
+
+**Done when:** every dispatched slice reported back with commit SHA + green
+package tests + green fast gate (`§Builder Commands`) — or a STOP item you resolved
+(answered / re-dispatched) before integration.
+
+## Phase 3 — Serial integration
+
+In the wave worktree: `git merge --no-ff <slice-branch>` per slice (disjoint →
+conflict-free). After EACH wave, on the integrated branch:
+
+- Typecheck both packages + the **FULL suite** — catches sibling/consumer test
+  breaks the agent ownership didn't cover (hardcoded count/tab asserts). Exact
+  commands = `§Integration Suites` (absent layer → your project's full test +
+  typecheck for every package the wave touched).
+- **Run EVERY test framework the wave's files belong to**, not just the primary
+  one: a kit/tooling/scripts wave may also have a separate unit-test runner and a
+  separate script-test runner the main suite does NOT cover (real case: a
+  second-framework red rode 3 integrations before surfacing). `§Integration Suites`
+  names each framework for this project.
+
+**Done when:** every framework green on the integrated branch — before dispatching
+the next wave.
+
+## Phase 4 — Central verify (YOURS, serial — the user explicitly wants this)
+
+Live-verify asserts USER OUTCOME (a DB-/UI value compared), not a tech metric.
+A single browser + single dev DB ⇒ verify is serial and yours. **A subagent's
+"PASS" is a hypothesis, not a gate** — implementers repeatedly mis-report green
+(real case: "gate PASS" while a size gate was red; files declared missing that
+existed). Never merge on the subagent's word.
+
+- **Re-run your project's full CI/verify gate CENTRALLY yourself** (`§Verify
+  Recipe`). On an integrated verify/coordinator branch (no per-slice issue number)
+  a branch-name-derived guard can BLOCK with no matching baseline — a branch-naming
+  artifact, not a coverage gap (each slice branch carried its own); `§Verify
+  Recipe` names the skip/override for that. Absent layer → run your project's
+  verification command or a project-provided verification skill (e.g. the kit's
+  **`/local-ci`** gate), if one exists; if the project has neither, run its full
+  test + typecheck and assert each slice's AC as a user-visible outcome by hand.
+- **Schema-/reader-changing waves** additionally run the COMBINED integration suite
+  against the refreshed snapshot before merge (`§Verify Recipe`) — per-slice-
+  isolated runs miss cross-slice seed/reader breaks.
+- **ONE dev server / one shared dev DB only.** ⚠ A second backend against a shared
+  dev DB can reaper-kill a live job (`§Verify Recipe` names the project's gotcha).
+  Stop the first dev server before starting another worktree's, or verify in the
+  same worktree.
+- **Headless login into the session-MCP profile** (AFK, no password in the
+  transcript). First navigate the MCP browser to the app root: no `/login`
+  redirect = already authenticated → skip the login (an authed profile makes a
+  login script time out on the e-mail field — looks like a selector bug, is not).
+  Otherwise: full recipe, profile-resolution lore + script = `§Headless Login`.
+- **Per surface**: browser snapshot + screenshot; assert each slice's AC visibly
+  gone/fixed + no regression. Run the project's design/brand checks (tokens, no
+  hardcoded values, formatters, chart-axis rules — `§Verify Recipe`) +
+  cross-surface consistency.
+- **Standardisation wave → CROSS-CONSUMER uniformity assert, NOT just per-slice
+  ACs.** If the wave unifies a shared pattern across ≥2 consumers, per-slice-green
+  is NOT enough — measure the standardised property on ALL N consumers and assert
+  they are EQUAL (e.g. `table.left - card.left` identical across every table;
+  export column-set identical), not just "present on each". Divergence only shows
+  in the cross-consumer diff. The shared component must OWN the standardised
+  property; this verify proves it actually does.
+- **DB-compare** the outcome value against the SQL source of truth. Watch
+  type-coercion traps your project layer flags (`§Verify Recipe`) — e.g. a `date`
+  column that shifts a day through a naive ISO round-trip.
+- **Console-clean** where required: read the browser console at warning level → 0
+  errors / 0 warnings.
+- **Gap the agents missed?** 1-file mechanical → fix inline; else **freshly
+  re-dispatch** a new agent into the existing slice worktree/branch with the prior
+  findings embedded — a continuation is NOT available in the parallel-wave flow;
+  stopped/background agents are re-dispatched, not resumed.
+
+**Done when — count it, don't remember it:** own central gate green (+ combined
+integration where schema/reader) · **N/N slice ACs** visually asserted with
+screenshot · cross-consumer equality measured (standardisation wave) · brand/design
+checks pass · console 0/0 · DB outcome value compared.
+
+## Phase 5 — Land
+
+- **One PR** for the whole wave (one merge for the user) OR per-slice — your call;
+  one PR with per-slice commits is usually kindest AFK.
+- **Schema-/migration waves: land as ONE combined PR — NOT incremental
+  auto-merge.** If merges to the main branch auto-deploy, per-slice merges race a
+  manually-gated prod migration → prod errors ×N slices. One combined PR = ONE
+  deploy = ONE prod-migration lockstep window. Incremental merge only for
+  byte-neutral waves (no new schema the deployed code reads). Project specifics
+  (deploy trigger, migration command, done-signal) = `§Landing`.
+- **`Closes #N` needs the keyword before EACH issue, one per line** — `Closes #a,
+  #b` only closes the first. Anchor → `Part of #<anchor>`, never `closes`
+  (premature close).
+- **Anchor tracker: `python3 scripts/board-sync.py anchor-sync <anchor#>`** — first
+  `--dry-run`, review the diff, then write; gate symbol + stable cells of freshly
+  appended rows by hand. Mandatory at EVERY slice event: PR-create AND merge.
+- **Stacked follow-up PRs** that build on the unmerged wave: base on the **wave
+  branch** (not main) — the platform auto-retargets them when the wave PR merges.
+  Note the merge order in the body.
+- New issues via `scripts/board-sync.py` (never bare `gh issue create`); write
+  multi-paragraph PR/issue bodies via `--body-file` (an inline body with backticks
+  can crash the shell).
+
+**Done when:** PR(s) open with correct `Closes`/`Part of` lines · anchor-sync
+written · merge order documented.
+
+## Phase 6 — Cleanup + close
+
+- Stop the dev server(s) you started, by port (`lsof -ti:<port> | xargs kill` —
+  your own processes, targeted by the worktree's assigned ports, never blind).
+  Remove temp verify scripts (a login helper, DB-check scripts).
+- **Before removing any slice worktree, read its `ANNAHMEN.md`** (an assumptions
+  log, gitignored at worktree-root) and propagate each build-time assumption marker
+  to the sibling issue it carries. A hand-driven multi-PR / migration landing does
+  NOT run `wrapup`'s assumption-propagation step — this is the only place it
+  happens; `worktree remove` deletes the log.
+- **Post-merge:** run `anchor-sync` again; verify every leaf issue actually closed
+  (the same checks `wrapup` runs, by hand when landing outside `wrapup`). The
+  anchor closes manually — a parent is not auto-closed on sub-issue completion.
+- A skill edited during the wave → run `codex-adapter-sync` (lives in
+  `.agents/skills/`) in the SAME PR — the mirror-presence-parity lint is a
+  pre-PR gate and blocks a dual-surface skill PR without its mirror.
+- Leave slice worktrees for the user to inspect, or note they're
+  post-merge-removable.
+
+**Done when:** no orphan process · ANNAHMEN propagated · anchor reconciled + leaf
+closes verified · final report lists landed/pulled slices as **X of Y**.

package/.agents/skills/orchestrate-wave/references/builder-contract.md

@@ -0,0 +1,67 @@
+# Builder Contract — template (fill slots, embed VERBATIM)
+
+SSOT for every delegated slice prompt in `orchestrate-wave` Phase 2. The
+orchestrator copies the block below and fills the `{{SLOTS}}` with verbatim
+material from the locked plan/issue — never paraphrased (paraphrase drift has
+produced real contract errors). Tier + effort per SKILL.md §Standing rules →
+Routing.
+
+The **Hard rules** and **Commands** sections below carry generic defaults so the
+template is never shipped with an unresolved project slot. When a project layer
+is present (`orchestrate-wave` Phase 0 probe → `§Builder Hard Rules` /
+`§Builder Commands`), the orchestrator REPLACES the generic lines with the
+project's exact rules and commands before dispatch — the builder must see exact
+commands, not "your project's tests".
+
+```text
+You are the implementer for slice #{{ISSUE}} of wave #{{ANCHOR}}.
+Worktree: {{WORKTREE_PATH}} (branch {{BRANCH}}) — work ONLY here.
+
+## Scope (verbatim from issue/plan — do not reinterpret)
+{{WHAT_AND_AC_VERBATIM}}
+
+## Plan decisions that bind you
+{{PLAN_DECISIONS_VERBATIM}}
+
+## File map (recon)
+{{FILE_LINE_MAP}}
+{{CONSUME_ONLY_LINES}}
+
+## Hard rules
+- Follow this project's UI/content conventions (from the project layer
+  §Builder Hard Rules — e.g. UI-text language, design tokens, formatters).
+  Absent a project layer: match the surrounding code's conventions exactly.
+- Size gates (recommended default): no new file >300 lines, no function >50
+  lines — unless the project sets its own limit.
+- If your slice adds a guard/helper/auth-check: WIRE it into its consumer + add a
+  negative test — an unwired helper is dead code.
+- STOP + report on any contract ambiguity — do NOT guess (this discipline has
+  caught real contract errors).
+- Do NOT run a browser/E2E or a dev server — the orchestrator verifies centrally.
+
+## Commands (exact — deviations produce false reds)
+Run, for EVERY package you edit: your package's unit tests for the files you
+touched, a typecheck, and the project's fast pre-PR gate. State the EXACT
+commands here from the project layer §Builder Commands. Absent a project layer,
+use: run your package tests + typecheck + fast gate, and name the exact
+invocation for each in this prompt so the builder cannot guess a wrong one.
+
+## Workflow order (non-negotiable)
+1. Implement (red→green test-first where the slice has logic).
+2. Commit your ONE commit on the slice branch FIRST — before any longer verify
+   (verify-then-forget-to-commit leaves the orchestrator hand-committing your
+   worktree). Do NOT push. Do NOT `--no-verify` (pre-commit hooks must pass).
+3. Run the commands above. Never end your turn with a background command still
+   running.
+
+## Report back (concise)
+Files touched · decisions taken · test results (exact output) · commit SHA ·
+STOP items · what the orchestrator should visually verify.
+```
+
+Orchestrator notes:
+
+- `{{CONSUME_ONLY_LINES}}` come from the Phase-1 reconciliation, e.g.
+  "X already exists in `<file>` — do NOT add it, consume only."
+- For dependent slices, fill hub artifact paths from the hub agent's report
+  (Phase 2 "capture reusable names"), not from the plan's guesses.