@menghuan1918/dsh-apollo 0.0.0-stage → 0.4.0

package/skills/brainstorming/spec-document-reviewer-prompt.md

@@ -0,0 +1,50 @@
+# Spec Document Reviewer Prompt Template
+
+Use this template when dispatching a spec document reviewer via the `subagent` tool (fresh read-only child, quality tier).
+
+**Purpose:** Verify a master Spec or sub-Spec is complete, consistent, and ready for implementation.
+
+**Dispatch after:** Spec document is written to the workspace's spec directory (`.workspace-docs/specs/` where that convention exists, otherwise the target repo's own specs directory).
+
+```
+subagent(
+  prompt="You are a spec document reviewer. Verify this spec is complete and ready for implementation.
+
+    **Spec to review:** [SPEC_FILE_PATH]
+    **Spec type:** [master | sub]
+    **Master Spec, if this is a sub-Spec:** [MASTER_SPEC_FILE_PATH or N/A]
+
+    ## What to Check
+
+    | Category | What to Look For |
+    |----------|------------------|
+    | Frontmatter | Where the workspace uses OKF: parseable YAML frontmatter with `type: Design Spec`, `title`, `description`, `tags`, `status`, and `repos` (plural `tags`, never a singular `tag`). Where it does not: the header matches the surrounding specs instead |
+    | Completeness | TODOs, placeholders, "TBD", incomplete sections |
+    | Consistency | Internal contradictions, conflicting requirements |
+    | Clarity | Requirements ambiguous enough to cause someone to build the wrong thing |
+    | Scope | Master Specs decompose large work into sub-Specs; sub-Specs are independently implementable and do not try to implement the whole master Spec |
+    | YAGNI | Unrequested features, over-engineering |
+
+    ## Calibration
+
+    **Only flag issues that would cause real problems during implementation.**
+    A missing section, a contradiction, or a requirement so ambiguous it could be
+    interpreted two different ways — those are issues. Minor wording improvements,
+    stylistic preferences, and "sections less detailed than others" are not.
+
+    Approve unless there are serious gaps that would lead to a flawed implementation. Do not reject a master Spec merely because it covers multiple subsystems; reject it only if it lacks clear sub-Specs, ordering, boundaries, or shared contracts. Do not reject a sub-Spec merely because it does not implement the whole master Spec.
+
+    ## Output Format
+
+    ## Spec Review
+
+    **Status:** Approved | Issues Found
+
+    **Issues (if any):**
+    - [Section X]: [specific issue] - [why it matters for implementation]
+
+    **Recommendations (advisory, do not block approval):**
+    - [suggestions for improvement]
+```
+
+**Reviewer returns:** Status, Issues (if any), Recommendations

package/skills/code-review/SKILL.md

@@ -0,0 +1,90 @@
+---
+name: code-review
+description: Review the changes since a fixed point (commit, branch, tag, or merge-base) along two axes — Standards (does the code follow this repo's documented coding standards?) and Spec (does the code match what the originating issue/PRD asked for?). Runs both reviews as parallel `subagent` delegations and reports them side by side. Use when the user wants to review a branch, a PR, work-in-progress changes, or asks to "review since X".
+---
+
+# Code Review
+
+Two-axis review of the diff between `HEAD` and a fixed point the user supplies:
+
+- **Standards** — does the code conform to this repo's documented coding standards?
+- **Spec** — does the code faithfully implement the originating issue / PRD / spec?
+
+Both axes run as parallel `subagent` delegations so they don't pollute each other's context, then this skill aggregates their findings.
+
+## Process
+
+### 1. Pin the fixed point
+
+Whatever the user said is the fixed point — a commit SHA, branch name, tag, `main`, `HEAD~5`, etc. If they didn't specify one, ask for it.
+
+Capture the diff command once: `git diff <fixed-point>...HEAD` (three-dot, so the comparison is against the merge-base). Also note the list of commits via `git log <fixed-point>..HEAD --oneline`.
+
+Before going further, confirm the fixed point resolves (`git rev-parse <fixed-point>`) and the diff is non-empty. A bad ref or empty diff should fail here — not inside two parallel agents.
+
+### 2. Identify the spec source
+
+Look for the originating spec, in this order:
+
+1. Issue references in the commit messages (`#123`, `Closes #45`, GitLab `!67`, etc.)
+2. A path the user passed as an argument.
+3. A spec/PRD file under `docs/`, `specs/`, `.workspace-docs/`, or `.scratch/` matching the branch name or feature.
+4. If nothing is found, ask the user where the spec is. If they say there isn't one, the **Spec** agent will skip and report "no spec available".
+
+### 3. Identify the standards sources
+
+Anything in the repo that documents how code should be written, such as `CODING_STANDARDS.md`, `CONTRIBUTING.md`, `CLAUDE.md`, or `AGENTS.md`.
+
+On top of whatever the repo documents, the Standards axis always carries the **smell baseline** below — a fixed set of Fowler code smells (_Refactoring_, ch.3) that applies even when a repo documents nothing. Two rules bind it:
+
+- **The repo overrides.** A documented repo standard always wins; where it endorses something the baseline would flag, suppress the smell.
+- **Always a judgement call.** Each smell is a labelled heuristic ("possible Feature Envy"), never a hard violation — and, like any standard here, skip anything tooling already enforces.
+
+Each smell reads *what it is* → *how to fix*; match it against the diff:
+
+- **Mysterious Name** — a function, variable, or type whose name doesn't reveal what it does or holds. → rename it; if no honest name comes, the design's murky.
+- **Duplicated Code** — the same logic shape appears in more than one hunk or file in the change. → extract the shared shape, call it from both.
+- **Feature Envy** — a method that reaches into another object's data more than its own. → move the method onto the data it envies.
+- **Data Clumps** — the same few fields or params keep travelling together (a type wanting to be born). → bundle them into one type, pass that.
+- **Primitive Obsession** — a primitive or string standing in for a domain concept that deserves its own type. → give the concept its own small type.
+- **Repeated Switches** — the same `switch`/`if`-cascade on the same type recurs across the change. → replace with polymorphism, or one map both sites share.
+- **Shotgun Surgery** — one logical change forces scattered edits across many files in the diff. → gather what changes together into one module.
+- **Divergent Change** — one file or module is edited for several unrelated reasons. → split so each module changes for one reason.
+- **Speculative Generality** — abstraction, parameters, or hooks added for needs the spec doesn't have. → delete it; inline back until a real need shows.
+- **Message Chains** — long `a.b().c().d()` navigation the caller shouldn't depend on. → hide the walk behind one method on the first object.
+- **Middle Man** — a class or function that mostly just delegates onward. → cut it, call the real target direct.
+- **Refused Bequest** — a subclass or implementer that ignores or overrides most of what it inherits. → drop the inheritance, use composition.
+
+### 4. Spawn both sub-agents in parallel
+
+Send both `subagent` calls in a single message — each a fresh quality-tier child with a fully self-contained prompt; children see none of this conversation.
+
+**Standards sub-agent prompt** — include:
+
+- The full diff command and commit list.
+- The list of standards-source files you found in step 3, **plus the smell baseline from step 3** pasted in full — the sub-agent has no other access to it.
+- The brief: "Report — per file/hunk where relevant — (a) every place the diff violates a documented standard: cite the standard (file + the rule); and (b) any baseline smell you spot: name it and quote the hunk. Distinguish hard violations from judgement calls — documented-standard breaches can be hard, but baseline smells are always judgement calls, and a documented repo standard overrides the baseline. Skip anything tooling enforces. Under 400 words."
+
+**Spec sub-agent prompt** — include:
+
+- The diff command and commit list.
+- The path or fetched contents of the spec.
+- The brief: "Report: (a) requirements the spec asked for that are missing or partial; (b) behaviour in the diff that wasn't asked for (scope creep); (c) requirements that look implemented but where the implementation looks wrong. Quote the spec line for each finding. Under 400 words."
+
+If the spec is missing, skip the Spec agent and note this in the final report.
+
+### 5. Aggregate
+
+Present the two reports under `## Standards` and `## Spec` headings, verbatim or lightly cleaned. Do **not** merge or rerank findings — the two axes are deliberately separate.
+
+End with a one-line summary: total findings per axis, and the worst issue _within each axis_ (if any).
+
+## Handling review feedback
+
+When you receive feedback from a review:
+
+1. **Verify before implementing.** Check each finding against the codebase — does it break existing functionality? Is the reviewer missing context? Is the current implementation intentional?
+2. **Push back with reasoning** when a finding is wrong — reference working code, tests, or architectural decisions.
+3. **No performative agreement.** State the fix, not "Great point!" or "You're absolutely right!" — just fix it and show the result.
+4. **YAGNI check.** When a reviewer suggests "implementing properly", grep for actual usage. If unused, propose removal instead.
+5. **Fix in order:** blocking issues → simple fixes → complex fixes. Test each fix individually.

package/skills/dev/SKILL.md

@@ -0,0 +1,41 @@
+---
+name: dev
+description: "Node contract for the DSH execution backend: prompt requirements, report formats, and failure semantics for implementation and review nodes."
+---
+
+# Built-in development backend (node contracts)
+
+This skill defines the execution backend's two node types. Wave orchestration (worktrees, merging, cleanup, review-loop scheduling) belongs to `/exec`; this skill must not create, merge, or delete worktrees. Subagents have no independent working directory and cannot see the orchestration session: every node input must come with the prompt (absolute worktree path, Spec path, shared contracts, verification commands), with bash always using `workdir` and file tools always using absolute paths.
+
+## Implementation node (develop)
+
+One brand-new subagent (quality tier) handles exactly one sub-Spec, following `main-agent-driven-development` in prebuilt-worktree mode (in an `/exec` wave, skip its internal review step — the review loop is run by `/exec`, and nodes do not dispatch reviewers themselves).
+
+Report format (JSON code block at the end of the closing message):
+
+```js
+{
+  status: 'complete' | 'blocked',
+  commit: '<final commit SHA>',
+  verification: '<verification commands run this round and their results>',
+  summary: '<implementation summary for the reviewer and orchestrator>',
+  blocker: '<required when status=blocked>'
+}
+```
+
+## Review node (review-only)
+
+A brand-new read-only subagent (quality tier). The prompt supplies: absolute worktree path, diff range, Spec path, implementation summary, and verification already run. Four-state verdict format (JSON code block at the end of the closing message):
+
+```js
+{
+  status: 'APPROVED' | 'APPROVED_WITH_NOTES' | 'CHANGES_REQUIRED' | 'BLOCKED',
+  findings: ['<issue, with file and line number>']
+}
+```
+
+Serious correctness errors, Spec gaps, integration risks, security issues, or missing verification must yield `CHANGES_REQUIRED`. Do not edit, commit, or merge.
+
+## Failure semantics
+
+A subagent failure (error / empty return) = `node-failed`; `blocked`, timeouts, partial replies, or uncommitted results never count as complete. The caller decides whether to redispatch, or to continue via `send_message` only when unblocking the same sub-Spec. Never reuse a node for another sub-Spec.

package/skills/diagnosing-bugs/SKILL.md

@@ -0,0 +1,132 @@
+---
+name: diagnosing-bugs
+description: Diagnosis loop for hard bugs and performance regressions. Use when the user says "diagnose"/"debug this", or reports something broken/throwing/failing/slow.
+---
+
+# Diagnosing Bugs
+
+A discipline for hard bugs. Skip phases only when explicitly justified.
+
+## Phase 1 — Build a feedback loop
+
+**This is the skill.** Everything else is mechanical. If you have a **tight** pass/fail signal for the bug — one that goes red on _this_ bug — you will find the cause; bisection, hypothesis-testing, and instrumentation all just consume it. If you don't have one, no amount of staring at code will save you.
+
+Spend disproportionate effort here. **Be aggressive. Be creative. Refuse to give up.**
+
+### Ways to construct one — try them in roughly this order
+
+1. **Failing test** at whatever seam reaches the bug — unit, integration, e2e.
+2. **Curl / HTTP script** against a running dev server.
+3. **CLI invocation** with a fixture input, diffing stdout against a known-good snapshot.
+4. **Headless browser script** (Playwright / Puppeteer) — drives the UI, asserts on DOM/console/network.
+5. **Replay a captured trace.** Save a real network request / payload / event log to disk; replay it through the code path in isolation.
+6. **Throwaway harness.** Spin up a minimal subset of the system (one service, mocked deps) that exercises the bug code path with a single function call.
+7. **Property / fuzz loop.** If the bug is "sometimes wrong output", run 1000 random inputs and look for the failure mode.
+8. **Bisection harness.** If the bug appeared between two known states (commit, dataset, version), automate "boot at state X, check, repeat" so you can `git bisect run` it.
+9. **Differential loop.** Run the same input through old-version vs new-version (or two configs) and diff outputs.
+10. **HITL bash script.** Last resort. If a human must click, drive _them_ with `scripts/hitl-loop.template.sh` so the loop is still structured. Captured output feeds back to you.
+
+Build the right feedback loop, and the bug is 90% fixed.
+
+### Tighten the loop
+
+Treat the loop as a product. Once you have _a_ loop, **tighten** it:
+
+- Can I make it faster? (Cache setup, skip unrelated init, narrow the test scope.)
+- Can I make the signal sharper? (Assert on the specific symptom, not "didn't crash".)
+- Can I make it more deterministic? (Pin time, seed RNG, isolate filesystem, freeze network.)
+
+A 30-second flaky loop is barely better than no loop; a 2-second deterministic one is tight — a debugging superpower.
+
+### Non-deterministic bugs
+
+The goal is not a clean repro but a **higher reproduction rate**. Loop the trigger 100×, parallelise, add stress, narrow timing windows, inject sleeps. A 50%-flake bug is debuggable; 1% is not — keep raising the rate until it's debuggable.
+
+### When you genuinely cannot build a loop
+
+Stop and say so explicitly. List what you tried. Ask the user for: (a) access to whatever environment reproduces it, (b) a captured artifact (HAR file, log dump, core dump, screen recording with timestamps), or (c) permission to add temporary production instrumentation. Do **not** proceed to hypothesise without a loop.
+
+### Completion criterion — a tight loop that goes red
+
+Phase 1 is done when the loop is **tight** and **red-capable**: you can name **one command** — a script path, a test invocation, a curl — that you have **already run at least once** (paste the invocation and its output), and that is:
+
+- [ ] **Red-capable** — it drives the actual bug code path and asserts the **user's exact symptom**, so it can go red on this bug and green once fixed. Not "runs without erroring" — it must be able to _catch this specific bug_.
+- [ ] **Deterministic** — same verdict every run (flaky bugs: a pinned, high reproduction rate, per above).
+- [ ] **Fast** — seconds, not minutes.
+- [ ] **Agent-runnable** — you can run it unattended; a human in the loop only via `scripts/hitl-loop.template.sh`.
+
+If you catch yourself reading code to build a theory before this command exists, **stop — jumping straight to a hypothesis is the exact failure this skill prevents.** No red-capable command, no Phase 2.
+
+## Phase 2 — Reproduce + minimise
+
+Run the loop. Watch it go red — the bug appears.
+
+Confirm:
+
+- [ ] The loop produces the failure mode the **user** described — not a different failure that happens to be nearby. Wrong bug = wrong fix.
+- [ ] The failure is reproducible across multiple runs (or, for non-deterministic bugs, reproducible at a high enough rate to debug against).
+- [ ] You have captured the exact symptom (error message, wrong output, slow timing) so later phases can verify the fix actually addresses it.
+
+### Minimise
+
+Once it's red, shrink the repro to the **smallest scenario that still goes red**. Cut inputs, callers, config, data, and steps **one at a time**, re-running the loop after each cut — keep only what is load-bearing for the failure.
+
+Why bother: a minimal repro shrinks the hypothesis space in Phase 3 (fewer moving parts left to suspect) and becomes the clean regression test in Phase 5.
+
+Done when **every remaining element is load-bearing** — removing any one of them makes the loop go green.
+
+Do not proceed until you have reproduced **and** minimised.
+
+## Phase 3 — Hypothesise
+
+Generate **3–5 ranked hypotheses** before testing any of them. Single-hypothesis generation anchors on the first plausible idea.
+
+Each hypothesis must be **falsifiable**: state the prediction it makes.
+
+> Format: "If <X> is the cause, then <changing Y> will make the bug disappear / <changing Z> will make it worse."
+
+If you cannot state the prediction, the hypothesis is a vibe — discard or sharpen it.
+
+**Show the ranked list to the user before testing.** They often have domain knowledge that re-ranks instantly ("we just deployed a change to #3"), or know hypotheses they've already ruled out. Cheap checkpoint, big time saver. Don't block on it — proceed with your ranking if the user is AFK.
+
+## Phase 4 — Instrument
+
+Each probe must map to a specific prediction from Phase 3. **Change one variable at a time.**
+
+Tool preference:
+
+1. **Debugger / REPL inspection** if the env supports it. One breakpoint beats ten logs.
+2. **Targeted logs** at the boundaries that distinguish hypotheses.
+3. Never "log everything and grep".
+
+**Tag every debug log** with a unique prefix, e.g. `[DEBUG-a4f2]`. Cleanup at the end becomes a single grep. Untagged logs survive; tagged logs die.
+
+**Perf branch.** For performance regressions, logs are usually wrong. Instead: establish a baseline measurement (timing harness, `performance.now()`, profiler, query plan), then bisect. Measure first, fix second.
+
+## Phase 5 — Fix + regression test
+
+Write the regression test **before the fix** — but only if there is a **correct seam** for it.
+
+A correct seam is one where the test exercises the **real bug pattern** as it occurs at the call site. If the only available seam is too shallow (single-caller test when the bug needs multiple callers, unit test that can't replicate the chain that triggered the bug), a regression test there gives false confidence.
+
+**If no correct seam exists, that itself is the finding.** Note it. The codebase architecture is preventing the bug from being locked down. Flag this in the post-mortem.
+
+If a correct seam exists:
+
+1. Turn the minimised repro into a failing test at that seam.
+2. Watch it fail.
+3. Apply the fix.
+4. Watch it pass.
+5. Re-run the Phase 1 feedback loop against the original (un-minimised) scenario.
+
+## Phase 6 — Cleanup + post-mortem
+
+Required before declaring done:
+
+- [ ] Original repro no longer reproduces (re-run the Phase 1 loop)
+- [ ] Regression test passes (or absence of seam is documented)
+- [ ] All `[DEBUG-...]` instrumentation removed (`grep` the prefix)
+- [ ] Throwaway prototypes deleted (or moved to a clearly-marked debug location)
+- [ ] The hypothesis that turned out correct is stated in the commit / PR message — so the next debugger learns
+
+**Then ask: what would have prevented this bug?** If the answer involves architectural change (no good test seam, tangled callers, hidden coupling), flag it for the user as an architecture improvement opportunity. Make the recommendation **after** the fix is in, not before — you have more information now than when you started.

package/skills/diagnosing-bugs/scripts/hitl-loop.template.sh

@@ -0,0 +1,55 @@
+#!/usr/bin/env bash
+# HITL (Human-In-The-Loop) debugging script template.
+# Used when a human must interact to reproduce a bug.
+# Drives the human through structured steps and captures output.
+
+set -euo pipefail
+
+LOG_DIR="${DEBUG_LOG_DIR:-/tmp/debug-hitl}"
+mkdir -p "$LOG_DIR"
+
+TIMESTAMP=$(date +%Y%m%d-%H%M%S)
+LOG_FILE="$LOG_DIR/hitl-$TIMESTAMP.log"
+
+echo "[HITL] Starting debug session. Output: $LOG_FILE"
+echo "[HITL] Timestamp: $TIMESTAMP"
+echo ""
+
+step() {
+    local n=$1; shift
+    echo "" | tee -a "$LOG_FILE"
+    echo "=== Step $n: $* ===" | tee -a "$LOG_FILE"
+    echo "[HITL] Press Enter when ready..." | tee -a "$LOG_FILE"
+    read -r
+}
+
+capture() {
+    local label=$1; shift
+    echo "[HITL] Capturing: $label" | tee -a "$LOG_FILE"
+    echo "--- $label ---" >> "$LOG_FILE"
+    "$@" 2>&1 | tee -a "$LOG_FILE"
+    echo "--- end $label ---" >> "$LOG_FILE"
+}
+
+# --- Steps go here ---
+
+step 1 "Reproduce the issue"
+echo "Follow these steps to reproduce:" | tee -a "$LOG_FILE"
+echo "  1. <describe step>" | tee -a "$LOG_FILE"
+echo "  2. <describe step>" | tee -a "$LOG_FILE"
+echo "  3. Observe: <expected vs actual>" | tee -a "$LOG_FILE"
+echo ""
+echo "[HITL] Paste the output or error message, then press Enter:" | tee -a "$LOG_FILE"
+read -r user_output
+echo "User observed: $user_output" >> "$LOG_FILE"
+
+step 2 "Collect diagnostics"
+capture "git-status" git status --short
+capture "git-diff" git diff --stat
+capture "recent-logs" tail -50 /var/log/app.log 2>/dev/null || echo "(no log file)"
+
+step 3 "Check environment"
+capture "env" env | grep -v -i -E 'secret|password|token|key' || true
+
+echo "" | tee -a "$LOG_FILE"
+echo "[HITL] Session complete. Log: $LOG_FILE" | tee -a "$LOG_FILE"

package/skills/exec/SKILL.md

@@ -0,0 +1,78 @@
+---
+name: exec
+description: "Use when the user invokes /exec with an approved master Spec. Orchestrates per-Spec worktrees, wave-parallel subagent execution, merging, verification, and final review."
+---
+
+# Execute multi-Spec tasks
+
+Run approved sub-Specs in isolated worktrees under `.worktrees/` in the target repo. The main workspace is always the merge target; orchestration state lives only in the current session context.
+
+## Prerequisites
+
+- The master Spec indexes at least two sub-Specs.
+- Confirm a single target repo; the main workspace is on a named branch and its working tree is clean.
+- `.worktrees/` is covered by the target repo's `.gitignore`; if not, ask the user to add it first.
+
+## Execution
+
+1. Read the master Spec and all sub-Specs; confirm shared contracts, dependency DAG, and verification commands.
+2. Build the task list by dependency wave.
+3. Per wave: create a branch from the main workspace HEAD, create a worktree at `<repo>/.worktrees/exec-<task>/<subtask>`, then dispatch the whole wave of nodes. Create the next wave's worktrees only after every prior wave has merged.
+
+## Wave execution: subagent + wait_subagent
+
+The main agent orchestrates each wave; node contracts (prompt elements, report format, failure semantics) are in the `dev` skill.
+
+1. **Dispatch**: in a single message, call `subagent` once per sub-Spec in this wave (quality tier), and record "Spec → subagent id". Implementation-node prompt template:
+
+   ```
+   You work in the isolated worktree <worktree absolute path>: always run bash with workdir=<worktree>, and use absolute paths for file tools.
+   Follow the main-agent-driven-development skill in prebuilt-worktree mode (skip its internal review step; the review loop is run by /exec).
+   Implement only <sub-Spec path> and obey the shared contracts: <contracts>. Run verification: <verification command>.
+   After committing, report in the dev skill's implementation-node format. Do not merge or delete the worktree; if blocked, set status=blocked and fill in blocker.
+   ```
+
+2. **Collect**: pass every id in this wave to `wait_subagent` in one call; reports arrive with the settlement notice. A Spec with a missing report, `blocked`, or no commit is recorded as `node-failed` and does not affect the other Specs in the wave.
+3. **Review loop** (each completed Spec advances independently; batches may be dispatched in parallel):
+   - Dispatch a brand-new read-only reviewer (quality tier): `Read-only review of the full diff of worktree <worktree> against the baseline (always run bash with workdir=<worktree>). Spec: <path>. Implementation summary: <summary>. Verification already run: <verification>. List issues by severity, each with file and line number; judge with the dev skill's four-state format. Do not edit, commit, or merge.`
+   - `CHANGES_REQUIRED` → send the findings to the original implementation subagent with `send_message` (preserving its context), and require it to fix each real issue, explain false positives, rerun verification, commit, and report again; then `wait_subagent` and dispatch a brand-new reviewer.
+   - At most 5 rounds; if still failing, record `review-exhausted`.
+4. Only Specs judged `APPROVED` / `APPROVED_WITH_NOTES` proceed to merge.
+
+Key points:
+
+- Every review round uses a brand-new subagent; fixes reuse the original implementation subagent — never start another implementation node for the same Spec.
+- Report any node question as blocked for the main agent to handle; do not ask the user within a wave.
+- In PTC mode, a whole wave's dispatch and collection can be done in one `run_code`.
+
+## Merge
+
+For each completed node: confirm it is committed and verification passed → check the changed files for out-of-scope edits → merge into the main workspace → verify after merging → delete the worktree and sub-branch.
+
+Small, well-defined conflicts are resolved directly by the main agent. For complex conflicts, use a new fix worktree under `.worktrees/` and a development node. Never merge failed or blocked nodes.
+
+## Final review
+
+Once all sub-Specs are merged, run the full integration verification, then dispatch a brand-new read-only reviewer subagent (quality tier) to review the whole integrated result:
+
+```
+subagent(
+  prompt="Read-only review of the <base>..HEAD diff in <workspace> (always run bash with workdir=<workspace>).
+         Master Spec: <path> | all sub-Specs | shared contracts | changed files | implementation summary | verification results.
+         List issues by severity, each with file and line number.
+         Return APPROVED / APPROVED_WITH_NOTES / CHANGES_REQUIRED / BLOCKED. Do not edit, commit, or merge."
+)
+```
+
+Wait with `wait_subagent`. On `CHANGES_REQUIRED` there is no need to ask the user — the main agent classifies and fixes all real bugs directly, and briefly explains false positives and existing behavior in context; after fixing, verify again and dispatch a brand-new reviewer for re-review. If serious or blocking issues remain after a soft cap of 3 rounds, stop the fix loop and truthfully report the remaining issues to the user.
+
+## Wrap-up
+
+Run the full verification, check the Specs, report branches, commits, verification results, and open issues, and ask the user what to do next. Do not create a PR or delete branches without the user's choice.
+
+## KISS
+
+- One sub-Spec, one worktree, one development node.
+- The main agent holds repo topology (branches/worktrees/merges/cleanup) and in-wave scheduling; implementation and review go to subagents.
+- State lives only in session context; add no integration branch, scheduler scripts, or state files.
+- Completion notices arrive automatically; wait only when you need results to proceed. Never poll with `sleep`.

package/skills/handoff/SKILL.md

@@ -0,0 +1,23 @@
+---
+name: handoff
+description: Compress the current conversation into a handoff document for a fresh agent to continue from.
+argument-hint: "What will the next session be used for?"
+disable-model-invocation: true
+---
+
+Compress the current conversation into a handoff document, so a brand-new agent can pick up the work without re-reading the parent session.
+
+## Storage and reuse
+
+- **Rewrite if one exists**: if a handoff document is already in the session context (written earlier in this session, or injected when the session started), rewrite that file in full; do not create a new one.
+- **Otherwise create one**: when the workspace has `.workspace-docs/`, write to `.workspace-docs/notes/<repo-or-topic>/` — a handoff is essentially a note; otherwise write to the target repo's existing docs directory. Prefix the file name with the date and follow the naming style already used in that directory.
+- When writing under `.workspace-docs/`, new files carry an OKF header (`type: Note` plus `title`/`description`/`tags`/`status`/`repos`), and are not registered in `index.md`; commit/push follows that repo's existing discipline. Where the target repo has no such convention, use its existing doc format.
+- If neither location exists, fall back to the OS temp directory.
+
+## Content requirements
+
+- Include a "Suggested skills" section pointing the receiving agent at the skills it should invoke.
+- Do not restate content already on disk (spec, plan, ADR, issue, commit, diff); give paths or URLs only.
+- Record only objective facts and verification evidence; no self-justifying narrative.
+- Redact sensitive content such as API keys, passwords, and personal identity information.
+- When the user invokes it with an argument, that argument is the next session's focus; trim the document accordingly.

package/skills/main-agent-driven-development/SKILL.md

@@ -0,0 +1,64 @@
+---
+name: main-agent-driven-development
+description: "Use only when the user or an orchestration skill explicitly invokes /main-agent-driven-development to complete a well-bounded implementation task."
+---
+
+# Main-agent-driven development
+
+The current agent session implements a well-bounded Spec directly. The outer `/exec` orchestrator owns the worktree and merge lifecycle.
+
+## Worktree modes
+
+Choose exactly one:
+
+- **Prebuilt mode** — when the caller already provided an isolated worktree and owns its lifecycle, use it directly; do not create, merge, or delete worktrees.
+- **Standalone mode** — otherwise, identify the target repo, require the baseline to be on a named branch, record the starting SHA, and create a worktree under the repo's `.worktrees/`.
+
+All operations must happen inside the chosen worktree. After isolation, do not edit the original checkout.
+
+## Flow
+
+1. Read the assigned Spec and the relevant repo instructions.
+2. Confirm task boundaries, dependencies, acceptance criteria, and required verification. Ask questions only when a missing decision truly blocks implementation.
+3. Initialize the task list from the Spec.
+4. Project setup + baseline verification. Report first if the baseline fails; continue only when the failure is clearly unrelated and documented.
+5. Implement directly, limited to the Spec's scope. Follow the `tdd` skill (bundled in this package): write a failing test first, then the minimal implementation.
+6. After each logical step, run focused verification, self-review the diff, and commit when it is complete. Verification standard: run the command this round and confirm the output; never replace it with "it should pass".
+7. After implementation, run all required verification.
+8. When verification fails or review finds a bug, follow the `diagnosing-bugs` skill (bundled in this package): build a feedback loop to find the root cause first, then fix.
+9. Run the internal review loop (see below). Exception: when acting as an implementation node in an `/exec` wave, **skip this step** — the review loop is run by `/exec`, and the node only implements, verifies, commits, and reports.
+10. Commit all approved fixes and report to the caller.
+
+Keep it KISS. Prefer reusing existing patterns, small and complete changes, and only the targeted refactoring the Spec requires.
+
+## Internal review loop
+
+After full verification, dispatch exactly one brand-new read-only reviewer subagent (quality tier):
+
+```
+subagent(
+  prompt="Review <worktree-abs-path> from <base_sha> to HEAD.
+         Spec: <path>
+         Implementation summary: <brief>
+         Changed files: <list>
+         Verification already run: <commands and results>"
+)
+```
+
+Require file and line numbers, and one status: `APPROVED` / `APPROVED_WITH_NOTES` / `CHANGES_REQUIRED` / `BLOCKED`.
+
+Wait for the review with `wait_subagent`. Once results arrive, fix all necessary correctness errors, Spec gaps, security issues, integration risks, and verification gaps directly — no need to ask the user. After verifying and committing the fixes, dispatch a brand-new reviewer with `subagent` again. Repeat until `APPROVED` or only non-blocking suggestions remain.
+
+Never self-approve, and never reuse an old reviewer.
+
+## Completion contract
+
+Before reporting completion, all of the following must hold:
+
+- All assigned acceptance criteria are implemented
+- Required verification ran and passed this round (backed by command output)
+- No uncommitted implementation changes
+- Internal review passed with no required fixes
+- The final commit SHA is available
+
+Report blockers truthfully. Do not merge on your own; the caller owns integration and cleanup.

package/skills/tdd/SKILL.md

@@ -0,0 +1,34 @@
+---
+name: tdd
+description: Test-driven development. Use when the user wants to build features or fix bugs test-first, mentions "red-green-refactor", or wants integration tests.
+---
+
+# Test-Driven Development
+
+TDD is the red → green loop. This skill is the reference that makes that loop produce tests worth keeping: what a good test is, where tests go, the anti-patterns, and the rules of the loop. Every section applies on every cycle — consult them before and during the loop, not after.
+
+## What a good test is
+
+Tests verify behavior through public interfaces, not implementation details. Code can change entirely; tests shouldn't. A good test reads like a specification — "user can checkout with valid cart" tells you exactly what capability exists — and survives refactors because it doesn't care about internal structure.
+
+See [tests.md](tests.md) for examples and [mocking.md](mocking.md) for mocking guidelines.
+
+## Seams — where tests go
+
+A **seam** is the public boundary you test at: the interface where you observe behavior without reaching inside. Tests live at seams, never against internals.
+
+**Test only at pre-agreed seams.** Before writing any test, write down the seams under test and confirm them with the user. No test is written at an unconfirmed seam. You can't test everything — agreeing the seams up front is how testing effort lands on the critical paths and complex logic instead of every edge case.
+
+Ask: "What's the public interface, and which seams should we test?"
+
+## Anti-patterns
+
+- **Implementation-coupled** — mocks internal collaborators, tests private methods, or verifies through a side channel (querying the database instead of using the interface). The tell: the test breaks when you refactor but behavior hasn't changed.
+- **Tautological** — the assertion recomputes the expected value the way the code does (`expect(add(a, b)).toBe(a + b)`, a snapshot derived by hand the same way, a constant asserted equal to itself), so it passes by construction and can never disagree with the code. Expected values must come from an independent source of truth — a known-good literal, a worked example, the spec.
+- **Horizontal slicing** — writing all tests first, then all implementation. Bulk tests verify _imagined_ behavior: you test the _shape_ of things rather than user-facing behavior, the tests go insensitive to real changes, and you commit to test structure before understanding the implementation. Work in **vertical slices** instead — one test → one implementation → repeat, each test a **tracer bullet** that responds to what the last cycle taught you.
+
+## Rules of the loop
+
+- **Red before green.** Write the failing test first, then only enough code to pass it. Don't anticipate future tests or add speculative features.
+- **One slice at a time.** One seam, one test, one minimal implementation per cycle.
+- **Refactoring is not part of the loop.** It belongs to the review stage (see the `code-review` skill), not the red → green implementation cycle.

package/skills/tdd/mocking.md

@@ -0,0 +1,59 @@
+# When to Mock
+
+Mock at **system boundaries** only:
+
+- External APIs (payment, email, etc.)
+- Databases (sometimes - prefer test DB)
+- Time/randomness
+- File system (sometimes)
+
+Don't mock:
+
+- Your own classes/modules
+- Internal collaborators
+- Anything you control
+
+## Designing for Mockability
+
+At system boundaries, design interfaces that are easy to mock:
+
+**1. Use dependency injection**
+
+Pass external dependencies in rather than creating them internally:
+
+```typescript
+// Easy to mock
+function processPayment(order, paymentClient) {
+  return paymentClient.charge(order.total);
+}
+
+// Hard to mock
+function processPayment(order) {
+  const client = new StripeClient(process.env.STRIPE_KEY);
+  return client.charge(order.total);
+}
+```
+
+**2. Prefer SDK-style interfaces over generic fetchers**
+
+Create specific functions for each external operation instead of one generic function with conditional logic:
+
+```typescript
+// GOOD: Each function is independently mockable
+const api = {
+  getUser: (id) => fetch(`/users/${id}`),
+  getOrders: (userId) => fetch(`/users/${userId}/orders`),
+  createOrder: (data) => fetch('/orders', { method: 'POST', body: data }),
+};
+
+// BAD: Mocking requires conditional logic inside the mock
+const api = {
+  fetch: (endpoint, options) => fetch(endpoint, options),
+};
+```
+
+The SDK approach means:
+- Each mock returns one specific shape
+- No conditional logic in test setup
+- Easier to see which endpoints a test exercises
+- Type safety per endpoint