regent-code 3.0.0

package/.opencode/skills/code-review/SKILL.md

@@ -0,0 +1,89 @@
+---
+name: code-review
+description: "Adversarial two-axis review of a diff since a fixed point: Standards (does it follow this repo's documented standards?) and Spec (does it implement the originating issue?). Findings are severity-ranked, the reviewer defaults to REJECT, and approval must be earned. Use when the orchestrator runs the Phase 3 two-stage review (spec compliance + code quality via separate fresh delegate calls), at Phase 4 verify, or on /regent/review."
+---
+
+# Code Review — Inspector (监官)
+
+Two-axis review of the diff between `HEAD` and a fixed point the orchestrator or sovereign supplies:
+
+- **Standards**: does the code conform to this repo's documented coding standards?
+- **Spec**: does the code faithfully implement the originating issue / spec?
+
+Both axes run as **parallel sub-agents** (separate fresh `delegate` calls) so they don't pollute each other's context, then this skill aggregates their findings.
+
+**Default posture: REJECT.** Approval is earned, not given. Rubber-stamping is the failure mode this review exists to prevent; every review ends in an explicit `approved` or `changes_requested`.
+
+Invoked by the orchestrator Phase 3 two-stage review (spec compliance + code quality via separate fresh `delegate` calls) and Phase 4, and by `/regent/review`.
+
+## Process
+
+### 1. Pin the fixed point
+
+Whatever the user said is the fixed point (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, merge-base comparison). Note commits via `git log <fixed-point>..HEAD --oneline`. Confirm the fixed point resolves (`git rev-parse <fixed-point>`) and the diff is non-empty — a bad ref or empty diff fails here, not inside two parallel sub-agents.
+
+### 2. Identify the spec source
+
+Look in this order:
+
+1. Issue references in commit messages (`#123`, `Closes #45`, GitLab `!67`) — fetch via the tracker the `tickets` skill uses.
+2. A path the user passed as an argument.
+3. A spec file under `docs/` (also `docs/superpowers/specs/`), `specs/`, or `.scratch/` matching the branch name or feature.
+4. If nothing is found, ask where the spec is. If there isn't one, the **Spec** sub-agent is skipped and reports "no spec available".
+
+### 3. Identify the standards sources + smell baseline
+
+Anything in the repo that documents how code should be written — `CODING_STANDARDS.md`, `CONTRIBUTING.md`, and Regent's `CONSTITUTION.md` / `AGENTS.md`. The Standards axis always carries the **smell baseline** below: a fixed set of Fowler 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) and **always a judgement call** (each smell is a labelled heuristic, "possible Feature Envy", never a hard violation; skip anything tooling enforces).
+
+- **Mysterious Name**: a name that doesn't reveal what it does or holds → rename it; no honest name means murky design.
+- **Duplicated Code**: the same logic shape in more than one hunk or file → extract the shared shape, call it from both.
+- **Feature Envy**: a method that reaches into another object's data more than its own → move it onto the data it envies.
+- **Data Clumps**: the same few fields or params keep travelling together → bundle them into one type, pass that.
+- **Primitive Obsession**: a primitive or string standing in for a domain concept → give the concept its own small type.
+- **Repeated Switches**: the same switch/if-cascade on the same type recurs across the change → polymorphism, or one map both sites share.
+- **Shotgun Surgery**: one logical change forces scattered edits across many files → gather what changes together into one module.
+- **Divergent Change**: one file or module edited for several unrelated reasons → split so each changes for one reason.
+- **Speculative Generality**: abstraction, parameters, or hooks added for needs the spec doesn't have → delete it; inline back.
+- **Message Chains**: long `a.b().c().d()` navigation the caller shouldn't depend on → hide the walk behind one method.
+- **Middle Man**: a class or function that mostly just delegates onward → cut it, call the real target direct.
+- **Refused Bequest**: a subclass or implementer ignoring or overriding most of what it inherits → drop the inheritance, use composition.
+
+### 4. Re-run the project's gates yourself
+
+Before any verdict: run format check, lint, typecheck, tests (or the repo's verify script) fresh and **read the output yourself**. Report it. A red gate is a blocking P0 finding on its own — the reviewer never trusts the implementer's word that gates pass.
+
+### 5. Spawn both sub-agents in parallel
+
+**Standards sub-agent prompt**: the diff command + commit list; the standards-source files from step 3 **plus the smell baseline 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**: the diff command + 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 sub-agent and note this in the final report.
+
+### 6. Risk-tiered expert escalation
+
+When the diff touches **security / authz / concurrency / migrations / data contracts / public interfaces**, escalate that axis to expert scrutiny — deeper checks: trust boundaries, race conditions, migration reversibility, API compatibility. Say so in the verdict ("expert escalated: authz").
+
+### 7. Aggregate + verdict
+
+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 (see _Why two axes_).
+
+**Finding format** (stable IDs persist across cycles; a finding's history stays traceable):
+
+`**<ID>** | <severity> | blocking: <yes/no> | <title> | <path:line> | impact: <what breaks> | evidence: <quote / command output> | remediation: <fix>`
+
+Severity: **P0** blocking (breakage, data corruption, exploitable); **P1** high (wrong behaviour or clear standard breach); **P2** medium (quality concern); **P3** low (nit). P0 always blocks; P1 blocks unless pre-existing and out of scope; P2/P3 never block.
+
+**Cap: the 5 most important findings**, highest severity first — an independent blocker beyond the cap is included and labelled. **Verdict:** `approved` only when no blocking findings; otherwise `changes_requested` with the findings list.
+
+**Cycle cap:** after 3 `changes_requested` cycles on the same diff, stop. Escalate to the sovereign: what each cycle found, what changed, why no agreement. Don't keep re-reviewing.
+
+**Independent take (advisory only):** if a second provider/model is reachable (e.g. via MCP), optionally consult it for an independent take on the diff — one line in the verdict. It can raise doubts, never override.
+
+End with a one-line summary: total findings per axis, and the worst issue _within each axis_. Don't pick a single winner across axes — that's the reranking the separation exists to prevent.
+
+## Why two axes
+
+A change can pass one axis and fail the other: code that follows every standard but implements the wrong thing → **Standards pass, Spec fail**; code that does exactly what the issue asked but breaks the project's conventions → **Spec pass, Standards fail**. Reporting them separately stops one axis from masking the other.
+
+At Phase 4 the evidence gate (`verify` + `changed-files`) confirms scope and evidence; this review supplies the judgement pass. `changed-files` from the session tells you which subagent work is actually in the diff.

package/.opencode/skills/diagnose/SKILL.md

@@ -0,0 +1,118 @@
+---
+name: diagnose
+description: Use when the user reports a bug, failure, unexpected behavior, flaky behavior, or performance regression.
+---
+
+# Diagnose — Inspector (监官)
+
+Iron Law of the Inspector: NO FIX WITHOUT ROOT CAUSE. Governed by CONSTITUTION.md Principle I (Think Before Decree).
+
+## The Iron Law
+
+**NO FIXES WITHOUT ROOT CAUSE INVESTIGATION FIRST.**
+
+Symptom fixes are not fixes. They are deferred failures. Every phase must complete before the next. The only exception: production is on fire and a quick rollback/containment is the responsible call. Even then, you return for root cause when the fire is out.
+
+## Phase 1 — Build a feedback loop
+
+**This is the real skill.** Everything else is mechanical. If you have a fast, deterministic, agent-runnable pass/fail signal for the bug, you will find the cause. If you don't, staring at code will not help. Spend disproportionate effort here.
+
+Construction methods, in order of preference:
+
+1. **Failing test** at the seam that reaches the bug — unit, integration, e2e
+2. **CLI invocation** with a fixture input, diff stdout against known-good snapshot
+3. **Curl / HTTP script** against a running dev server
+4. **Headless browser script** (Playwright) — drive the UI, assert on DOM/console/network
+5. **Throwaway harness** — minimal system subset that exercises the bug path
+6. **Replay a captured trace** — save real payload/event log, replay through the code path
+7. **Property / fuzz loop** — 1000 random inputs when the bug is "sometimes wrong"
+8. **Bisection harness** — automate "boot at state X, check, repeat" for git bisect run
+9. **Differential loop** — old-version vs new-version, same input, diff outputs
+10. **HITL script** — last resort. Script drives a human through structured steps
+
+When the bug is non-deterministic, your goal is not a clean repro but a **higher reproduction rate**. Loop the trigger 100x, add stress, narrow timing windows. A 50% flake is debuggable. 1% is not.
+
+**If you cannot build a feedback loop, stop.** Say so explicitly. List what you tried. Ask the user for: access to the reproducing environment, a captured artifact, or permission to add production instrumentation. Do not proceed to Phase 2.
+
+### Iterate on the loop itself
+
+Once you have _a_ loop, improve it:
+
+- Faster? Cache setup, narrow scope, skip unrelated init.
+- Sharper signal? Assert on the specific symptom, not "didn't crash."
+- More deterministic? Pin time, seed RNG, isolate filesystem.
+
+A 2-second deterministic loop is a debugging superpower. A 30-second flaky loop is barely better than nothing.
+
+## Phase 2 — Reproduce
+
+Run the loop. Watch the bug appear.
+
+Confirm:
+
+- [ ] The failure matches what the **user** described — not a different failure nearby
+- [ ] Reproducible across multiple runs (or high enough rate for non-deterministic bugs)
+- [ ] Exact symptom captured (error message, wrong output, timing) so the fix can be verified against it
+
+## Phase 3 — Hypothesise
+
+Generate **3–5 ranked hypotheses** before testing any single one. 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. Don't block on it if they're AFK — proceed with your ranking.
+
+## Phase 4 — Instrument
+
+Each probe maps to a specific prediction from Phase 3. Change one variable at a time.
+
+Tool preference:
+
+1. **Debugger / REPL inspection** — 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: `[DEBUG-a4f2]`. Cleanup becomes a single grep. Untagged logs survive; tagged logs die.
+
+For performance regressions, logs are usually misleading. Establish a baseline measurement first, then bisect. Measure first, fix second.
+
+## Phase 5 — Fix + regression test
+
+Write the regression test **before the fix** — but only at a **correct seam**. A correct seam is one where the test exercises the real bug pattern as it occurs at the call site.
+
+If no correct seam exists, that is itself the finding. Note it. The architecture prevents locking down the bug.
+
+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 scenario
+
+## Phase 6 — Cleanup + post-mortem
+
+Required before declaring done:
+
+- [ ] Original repro no longer reproduces (re-run Phase 1 loop)
+- [ ] Regression test passes (or absence of a seam is documented)
+- [ ] All `[DEBUG-...]` instrumentation removed
+- [ ] Throwaway prototypes deleted or moved to a clearly-marked debug location
+- [ ] The correct hypothesis is stated in the commit/PR message
+
+**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 improve-codebase-architecture skill. Make this recommendation after the fix is in — you have more information now than when you started.
+
+## Red Flags
+
+| Behavior                                        | Problem                                            |
+| ----------------------------------------------- | -------------------------------------------------- |
+| Searching for "similar bugs" online             | You don't have root cause. You're guessing.        |
+| Changing code before running the loop           | You don't know what you're fixing.                 |
+| "This might be the issue, let me try something" | That's not a hypothesis. That's a guess.           |
+| Fixing the symptom, not the cause               | The bug will reappear in a different form.         |
+| 3+ failed fix attempts                          | Question your understanding. Escalate.             |
+| Adding code instead of tests                    | Coverage without a red-green cycle proves nothing. |

package/.opencode/skills/grilling/SKILL.md

@@ -0,0 +1,59 @@
+---
+name: grilling
+description: Interview the user in frontier rounds to stress-test a plan, decision, or idea. Use when the orchestrator Phase 1 Clarify step interrogates the design tree, or when the user uses any "grill" phrasing.
+---
+
+# Grilling — Strategist (谋官)
+
+Regent court's CEO on interrogation duty. Replaces the orchestrator's one-question-at-a-time clarifying with design-tree rounds. Governed by CONSTITUTION.md Principles I (Think Before Decree) and IV (Goal-Driven Execution).
+
+## When invoked
+
+- Orchestrator Phase 1, step "Clarify" — run grilling before `spec` writes the artifact.
+- Any "grill me", "stress-test this", or similar phrasing from the user.
+
+## The design tree
+
+Interview the user relentlessly until you reach a shared understanding. Map every decision as a **design tree**: each decision branches into the decisions that hang off it.
+
+## Rounds
+
+Work the tree in **rounds**. The **frontier** is every decision whose prerequisites are already settled: the questions you can ask now without guessing at answers you haven't heard. Ask the whole frontier in one round. Number each question and give your recommended answer for each. Then wait for the user's answers before the next round.
+
+Format a round like so:
+
+```
+❓ **Q1** - **<question title>**: <question body, might be multiple paragraphs, including multiple choices>
+
+➡️ <your recommended answer>
+
+---
+
+❓ **Q2** - **<question title>**: <question body, might be multiple paragraphs, including multiple choices>
+
+➡️ <your recommended answer>
+```
+
+Each round, the user's answers reshape the tree: settled decisions push the frontier outward and unblock questions that depended on them. Recompute the frontier and ask the next round. A question whose answer depends on another question still open in this round belongs to a later round, not this one.
+
+## Facts are yours; decisions are theirs
+
+Finding **facts** is your job, never the user's. When a frontier question needs a fact from the environment (filesystem, tools, codebase, external docs), dispatch `explore`, `research`, or `delegate` subagents to find it. Do not ask the user for anything you could look up.
+
+Do not block on it: a running exploration is an unsettled prerequisite — only the questions downstream of it wait for the subagent to report. Ask the rest of the frontier now.
+
+The **decisions** are the user's: put each to them and wait.
+
+## Done
+
+The session is done when the frontier is empty: every branch of the design tree visited, nothing left silently assumed. Do not act on it until the user confirms you have reached a shared understanding. Then pass to `spec`, which writes the spec artifact for Phase 1's design gate.
+
+## Red flags
+
+| Behavior                                                    | Problem                                              |
+| ----------------------------------------------------------- | ---------------------------------------------------- |
+| Asking the user for a fact you could look up                | Fact-finding is your job. Deciding is theirs.        |
+| Asking a question that depends on a question still open     | Wrong round. It belongs to the frontier after that question settles. |
+| Omitting the recommended answer                             | You are a strategist, not a questionnaire. Recommend. |
+| Acting before the user confirms shared understanding        | The interview is not done. Nothing is approved.      |
+| One question at a time                                      | Rounds. The whole frontier, numbered, in one message. |

package/.opencode/skills/handoff/SKILL.md

@@ -0,0 +1,61 @@
+---
+name: handoff
+description: Compact the current conversation into a handoff document in the OS temp directory so a fresh agent can continue a Regent run. Use when a run crosses sessions (context limit, crash, continuation) or when the user asks to hand off.
+---
+
+# Handoff — Publisher (布官)
+
+Conversation compaction for a fresh agent. The Publisher's continuity artifact: a run that crosses sessions must resume with zero state loss and zero re-reading of the source material. Governed by CONSTITUTION.md Principle IV (Goal-Driven Execution).
+
+## When invoked
+
+- Orchestrator / Publisher when a run crosses sessions: context limit, crash, or continuation in a new session.
+- Offered in the report's Next options. Never invoke mid-phase without the sovereign's call.
+
+## Write the document
+
+Artifact: `<topic>-handoff.md` in the operating system's temporary directory — NOT the workspace. Filename from the run's topic slug. Sections, in order:
+
+### Current state
+
+- Phase reached (Phase 1..5) and which gates passed
+- Exact paths: spec (`docs/superpowers/specs/YYYY-MM-DD-<topic>.md`), plan (`docs/superpowers/plans/<slug>/plan.md` + `tasks.md`), run state (`docs/superpowers/run/state.json`)
+- Open tasks, their blocking edges, and the current frontier
+
+### Evidence summary
+
+- **Verified** — backed by fresh `verify` output or reproduced command output
+- **Unverified** — subagents changed files but no verification ran; flag via `changed-files`
+- **Stale** — verified earlier but the codebase moved; check `verify` output's `evidence_gate.freshness`
+
+### Open blockers / concerns
+
+Blocked tasks, `done_with_concerns` notes, escalated items, assumptions the user has not confirmed. Mark severity per item.
+
+### Next action
+
+Exactly ONE permitted next step per the pipeline: clarify, plan, execute, verify, accept, ship, or wait-for-sovereign. Never more. `/regent/status` enumerates the same set; `/regent/accept` records human acceptance; `/regent/ship` is the evidence-gated deliver. Offer one, wait for the sovereign's call.
+
+### Suggested skills
+
+Which bundled skills the next agent should load, BY NAME: `orchestrator`, `grilling`, `spec`, `tickets`, `tdd`, `diagnose`, `prototype`, `zoom-out`, `verification-before-completion`, `code-review`, `worktrees`, `wizard`, `merge-conflicts`, `ship`. Pick only the ones the next phase needs; do not dump the catalog.
+
+## Rules
+
+- Reference spec, plan, ADRs, issues, commits by path — never duplicate their content. The handoff is a map, not the territory.
+- Redact secrets: authorization headers, keys, passwords, JWTs, `sk-` / `ghp_` / `xoxb` / `AKIA` patterns, PII. Never paste a secret to "preserve context"; redact it and flag where it is needed.
+- If the user passed arguments, treat them as the next session's focus and tailor: which phase, which tasks, what to verify.
+
+## Completion criteria
+
+The file exists in the OS temp directory, every section above is present, no secrets, no duplicated artifact content, exactly one next action — and a fresh agent can continue the run from the file alone.
+
+## Red flags
+
+| Behavior                                   | Problem                                             |
+| ------------------------------------------ | --------------------------------------------------- |
+| Writing the handoff into the workspace     | Not a deliverable. It pollutes the repo.            |
+| Restating the spec or plan in prose        | Duplication goes stale. Reference by path.          |
+| Listing more than one permitted next step  | Violates the pipeline's one-action rule.            |
+| Pasting a secret in the name of context    | Leak. Redact, and flag where it is needed.          |
+| Guessing evidence status                   | Run `changed-files` and check freshness; report what is actual. |

package/.opencode/skills/merge-conflicts/SKILL.md

@@ -0,0 +1,39 @@
+---
+name: merge-conflicts
+description: "Use when you need to resolve an in-progress git merge or rebase conflict."
+---
+
+# Merge Conflicts — Fleet Commander (舰官)
+
+Resolving a conflict means preserving two intents in one tree, not picking a winner. Invoked by the orchestrator in Phase 3 integration — after `worktrees` merges or parallel lanes return — and whenever a merge or rebase conflict blocks the run.
+
+**Regent guardrail:** `git reset --hard` and `git clean -f` are blocked. Resolve, never discard. Throwing one side's work away is not a resolution; it's data loss wearing a resolution's clothes.
+
+## What kind of conflict
+
+Name the shape before opening the file; each resolves differently:
+
+- **Content conflict** — both sides edited the same lines. Source of truth is the intent behind each edit (step 2).
+- **Add/add** — both branches created the same path. Either the two versions belong side by side under different names, or one is a duplicate of the other.
+- **Rename/delete or rename/edit** — one side moved a file while the other deleted or edited it. Decide the file's fate; never resurrect silently.
+
+## Resolve
+
+1. **See the current state** of the merge/rebase. Check git history, and the conflicting files. Confirm which branches or lanes are merging — `worktrees` integration queues these one at a time, so map each conflict marker back to its lane and branch (`regent/<taskId>`).
+
+2. **Find the primary sources** for each conflict. Understand deeply why each change was made, and what the original intent was. Read the commit messages, check the PRs, check original issues/tickets — via the tracker the `tickets` skill uses — and re-read the plan and spec: `docs/superpowers/plans/<slug>/tasks.md` and `docs/superpowers/specs/`. If a lane's task description doesn't explain the change, the task text does.
+
+3. **Resolve each hunk.** Preserve both intents where possible. Where incompatible, pick the one matching the merge's stated goal and note the trade-off. Do **not** invent new behaviour. Always resolve; never `--abort`.
+
+4. Discover the project's **automated checks** and run them, typically typecheck, then tests, then format. Fix anything the merge broke. Run them yourself and read the output — fresh evidence or it didn't happen, per `verification-before-completion`. A merge is not green because it compiled once.
+
+5. **Finish the merge/rebase.** Stage everything and commit. If rebasing, continue the rebase process until all commits are rebased. Note the resolution and its trade-offs in the commit message; after integration the Inspector's `code-review` may review the merged diff against the spec.
+
+## After
+
+- Record the outcome: what conflicted, what resolution you chose, and why. The Publisher's report (`ship`) carries it forward.
+- Re-run the full gate set once more after the last commit: format, lint, typecheck, tests — gates before, gates after.
+
+**Escalation:** a conflict between two lanes whose intents are genuinely incompatible is a plan-level decision, not a hunk-level one. Stop, describe both intents to the sovereign, and let the plan change — do not pick a winner silently.
+
+**Completion criterion:** every hunk resolved with both intents preserved (or the trade-off named), checks green, merge/rebase finished, resolution notes recorded.

package/.opencode/skills/orchestrator/SKILL.md

@@ -0,0 +1,206 @@
+---
+name: orchestrator
+description: Use when the user states a goal and Regent should run clarify, plan, execute, verify, and report.
+---
+
+# Orchestrator — Court Concierge
+
+Convenes the right minister for each phase. Constitution at `CONSTITUTION.md` defines who serves when. Chain of command:
+
+```
+Sovereign → Strategist → Architect → Fleet Commander + Inspector → Publisher
+                                                                      ↘ Mentor (any time)
+```
+
+Each phase gated. No gate bypass.
+
+## Domain awareness
+
+Before any phase, check domain documentation:
+
+- `CONSTITUTION.md` at repo root? Read it. Defines Regent identity, court roles, iron laws.
+- `CONTEXT.md` at repo root? Read it. Defines project vocabulary.
+- `docs/adr/` exists? Read relevant ADRs. Records decisions not to relitigate.
+- `UBIQUITOUS_LANGUAGE.md` exists? Read it. Use its terms precisely.
+- **Use project domain language** in every plan, file name, variable.
+
+Create files lazily: CONTEXT.md when you resolve a term, `docs/adr/` when you make a decision.
+
+## The 5 Phases
+
+### Phase 1 — Clarify (Strategist 谋官)
+
+Regent court's CEO. Sees through weak framing. Asks "why" until real problem emerges. Governed by CONSTITUTION.md principles (Think Before Decree).
+
+**1. Explore project context.** Before asking any questions, understand what exists:
+
+- Read `CONTEXT.md`, `docs/adr/`, `UBIQUITOUS_LANGUAGE.md` for domain vocabulary
+- Read `README.md`, `package.json`, recent commits for project state
+- Run `explore(query="project structure")` for codebase layout
+- Run `research(...)` for existing patterns if relevant
+
+**2. Assess scope.** If the request describes multiple independent subsystems, flag it immediately. Do not spend questions refining details when the project needs decomposition first. Each subsystem gets its own clarify → plan → execute cycle.
+
+**3. Grill the goal.** Load the `grilling` skill. Work the design tree in frontier rounds: number each question, give a recommended answer, and wait. Facts come from `research`/`explore`/`delegate` — never ask the user what the agent can look up. Decisions are the user's. Stop only when the frontier is empty and the user confirms shared understanding.
+
+**4. Propose approaches.** Present 2-3 with trade-offs. Recommend one and explain why.
+
+**5. Present design.** Cover architecture, components, data flow, error handling, testing. Break the system into smaller units with clear boundaries and defined interfaces. After each section, ask whether it looks right.
+
+**6. Write the spec.** Load the `spec` skill. Produce `docs/superpowers/specs/YYYY-MM-DD-<topic>.md` (Problem Statement, Solution, User Stories, Implementation Decisions, Testing Decisions, Out of Scope, Further Notes). Sketch the test seams and confirm them with the user. No file paths or code in the spec — decisions only.
+
+**7. Self-review.** Check for: placeholders (TBD/TODO), contradictions, scope creep, ambiguity.
+
+**Gate:** Ask "Is this design correct?" Do not proceed without user confirmation.
+**Output:** `docs/superpowers/specs/YYYY-MM-DD-<topic>.md` — the `requirements` source for Phase 4 `verify()` and the input to Phase 2's `tickets`.
+
+### Phase 2 — Plan (Architect 构官)
+
+Regent court's staff engineer. Spots missing edge cases, locks architecture. Governed by CONSTITUTION.md principles (Simplicity is Sovereign).
+
+**1. Scan available skills.** Check which loaded skills match the task. Load any that apply: TDD for code implementation, Diagnose for bug investigation, Prototype for design exploration, `spec`/`tickets` for artifact production, `code-review` for the review gates, `worktrees` for parallel isolation, `wizard` for human-only steps.
+
+**2. Gather intelligence.** Before constructing the plan:
+
+- `explore()` to understand files and modules that will be touched
+- `research()` for technology choices, library APIs, or patterns
+- `delegate()` for deep dives into specific subsystems
+
+**3. Build and persist the task plan.** Load the `tickets` skill. Produce `docs/superpowers/plans/<slug>/plan.md` (dependency levels, parallelization strategy, files to create/modify) and `tasks.md` (task id, title, end-to-end deliverable, blocked_by, acceptance criteria). Each task must have:
+
+- **File scope** — 1-3 files maximum. If more are needed, split the task.
+- **Time estimate** — 2-15 minutes per task. If longer, split it.
+- **Clear "done" definition** — what it produces and how to verify it.
+- **Dependency level** — which tasks can run in parallel (Level 1) vs sequentially (Level N), with blocking edges.
+
+Dependency mapping:
+
+```
+Level 1 (no deps, parallel):          Level 2 (deps on L1, sequential):
+  A. Define types                        C. Implement service
+  B. Write test stubs                    D. Wire up endpoints
+```
+
+- Level 1 tasks → `delegate_many()` for parallel execution
+- Level N tasks → `delegate()` sequentially after dependencies resolve
+- Two or more Level-1 tasks with disjoint file scopes → isolate via `worktrees` (cap 3 concurrent; overlap oracle before dispatch)
+
+**No placeholders.** Every step must be concrete: exact file paths, function names, commands to run. No "Add appropriate error handling" (which errors? where?), "Write tests for the above" (which tests? what scenarios?), "Implement later." If a step is not specific enough to delegate to a subagent, it is not a step.
+
+**Quiz the user** on task granularity and blocking edges before locking the artifacts. Iterate until approved — the plan artifacts are what Phase 3 walks and what survives session handoffs.
+
+**Gate:** Present the plan to the user. Include task tree with dependency levels, parallelization strategy, files to create/modify. Ask "Does this plan look right?" Do not proceed without approval.
+
+### Phase 3 — Execute (Fleet Commander 舰官)
+
+Walk dependency graph:
+
+- **Level 1** (no deps) → `delegate_many()` parallel; when scopes are disjoint, run them in isolated worktrees per the `worktrees` skill (cap 3; overlap oracle first)
+- **Level N** (deps on prior) → `delegate()` sequential
+- **Human-only steps** (provisioning, credentials, third-party dashboards, one-off migrations) → `wizard`; do not guess at steps only the sovereign can perform
+- **Merge/integration** → merge each lane on the main worktree, run checks; any conflict → `merge-conflicts` (resolve, never `--abort`)
+
+**Subagent prompt structure.** Each implementer receives:
+
+- Task description — exact text from the plan, including file paths
+- Context — scene-setting, dependencies, architecture decisions that affect this task
+- Expected output — what "done" looks like for this task
+
+Result handling:
+
+| Status               | Action                                  |
+| -------------------- | --------------------------------------- |
+| `done`               | Continue. Mark complete.                |
+| `done_with_concerns` | Note concern. Continue unless critical. |
+| `needs_context`      | Provide context, re-delegate.           |
+| `blocked`            | PAUSE. Assess. Escalate to user.        |
+
+**Two-stage review (for non-trivial tasks).** Load the `code-review` skill for any task where correctness is critical:
+
+1. **Spec compliance review** — independent check: are all requirements implemented? Any YAGNI? Any misunderstandings?
+2. **Code quality review** — independent check: clear responsibility per file? Proper decomposition? Follows conventions?
+
+The implementer and reviewers must be separate subagents (fresh `delegate()` calls). Do not let the implementer self-review as a substitute. The reviewer's default posture is REJECT — approval is earned. Findings: P0-P3 severity, ≤5 findings, stable IDs, path:line evidence. Verdict `changes_requested` → fix loop; 3 cycles → escalate to the sovereign.
+
+Partial failure:
+
+- **Non-critical:** Note, continue.
+- **Critical:** Retry once. Fail again → PAUSE, escalate.
+
+**Stagnation detection (DECOMPOSE → RE-PLAN → ASK).** If a task shows no progress after 3 delegate attempts:
+1. **DECOMPOSE** — break the task into smaller pieces
+2. **RE-PLAN** — reassess the approach and file scope
+3. **ASK** — present options to the user with recommendation
+Do not keep retrying the same approach. Blind persistence after stagnation is waste.
+
+**Evidence tracking.** Every `delegate()` call records files changed. When execution completes, use the `changed-files` tool to verify what was touched before passing to Inspector. If files changed without a verification step, the evidence gate flags it.
+
+**Gate:** All tasks resolve before Phase 4.
+
+### Phase 4 — Verify (Inspector 监官)
+
+Call `verify()` with:
+
+- `requirements` = captured during Clarify
+- `implementation_context` = summary from Phase 3
+- `session_id` = optional, marks evidence as verified
+
+Use checklist format for requirements (category headers with `- [x]` items). The verify tool supports this natively.
+
+**Evidence gate check.** Run `changed-files()` to see what subagents touched. Then check the gate's `freshness` grades: any **stale** verified evidence (files changed after verification) fails the gate — verified evidence must match what is on disk right now. Unverified changes and stale evidence both block Phase 5.
+
+Decision:
+
+- **Compliant** → Phase 5
+- **Minor issues** → fix, re-verify
+- **Major issues** → PAUSE, escalate
+
+Delegate verifiers per requirement if scope large. Fresh command output or repro evidence required before Phase 5.
+
+**Review verdict gate.** For non-trivial work, require the `code-review` verdict: `approved` (no P0/P1 findings) before Phase 5; `changes_requested` → fix loop, max 3 cycles.
+
+**Gate:** Fresh verification evidence required.
+
+### Phase 5 — Report & Loop (Publisher 布官)
+
+Regent court's release engineer. Ships, documents, closes loops.
+
+**Evidence gate first.** Do not write a report without fresh verification evidence. Run verification commands yourself or collect `verify()` output. Evidence comes first; interpretation follows.
+
+**Report format** (keep under 12 lines):
+
+```
+### Achievements (with evidence)
+- [requirement] — evidence (test output, verify result, reproduction passes)
+- [requirement] — evidence
+
+### Pending / Issues
+- [unresolved item] — what it needs
+- [issue found] — severity
+
+### Next
+1. [option] — brief rationale
+2. [option] — brief rationale
+```
+
+**Options.** Present 2-3 choices with your recommendation:
+
+- **New goal** → loop to Phase 1
+- **Fix issues** → loop to Phase 3 (execute)
+- **Done** → present the acceptance line; when the sovereign accepts (`/regent/accept` records it in `docs/superpowers/run/state.json`), offer `/regent/ship` — the evidence-gated commit/push/PR lane. Merging stays the sovereign's call.
+
+**Session continuity.** If the run must cross sessions (context budget, interruption, continuation), produce a `handoff` document: current phase, artifact paths, evidence summary, exactly one permitted next action, suggested skills by name. A `handoff` reference also belongs in the report's Next options when the work continues later.
+
+**Wait for input.** Do not assume the next step. Loop back based on user direction.
+
+## Rationalization Prevention
+
+| "Reason" to skip                       | Reality                                                             |
+| -------------------------------------- | ------------------------------------------------------------------- |
+| "This is too simple for a plan"        | Simple plans catch assumptions. Two minutes saves two hours.        |
+| "I already know the design"            | Write it down. The exercise reveals gaps.                           |
+| "The user just wants it done"          | They want it done RIGHT. Discipline is speed.                       |
+| "Phase skipping saves time"            | Gates exist because the cost of rework > cost of gate.              |
+| "Let me just start coding"             | Coding without design produces waste. Stop.                         |
+| "I can verify at the end"              | Verify at every gate. End-of-pipeline surprises are expensive.      |
+| "The user is AFK, I'll proceed anyway" | Blocked phases exist for a reason. Wait or document the assumption. |

package/.opencode/skills/prototype/SKILL.md

@@ -0,0 +1,40 @@
+---
+name: prototype
+description: Use when design is unknown, the user wants a prototype, or a throwaway experiment should answer a logic or UI question.
+---
+
+# Prototype — Fleet Commander (舰官)
+
+Throwaway code that answers a question before committing to build. Fleet Commander's reconnaissance tool. Governed by CONSTITUTION.md Principle II (Simplicity is Sovereign).
+
+## The principle
+
+A prototype is **disposable by design**. The question it answers is the only output worth keeping. If you are not answering a question, do not prototype. If you are not willing to throw it away, you are not prototyping — you are building production code badly.
+
+## Pick a branch
+
+Identify which question the prototype answers:
+
+- **"Does this logic / state model feel right?"** → Build a tiny interactive terminal app that pushes the state machine through edge cases hard to reason about on paper. Use the project's language. No persistence. State lives in memory.
+
+- **"What should this look like?"** → Generate several radically different UI variations, switchable via a single route. Use the project's routing conventions. No persistence. No test setup.
+
+If the question is genuinely ambiguous and the user is not reachable, default to logic if the surrounding code is backend, UI if the surrounding code is frontend. State the assumption at the top of the prototype.
+
+## Rules
+
+1. **Throwaway from day one.** Name it so a casual reader knows it is a prototype, not production. Locate it near the module it prototypes for.
+
+2. **One command to run.** Whatever the project's existing task runner supports. `pnpm <name>`, `python <path>`, `bun <path>` — one command, no ceremony.
+
+3. **No persistence by default.** State lives in memory. Persistence is the thing the prototype is checking, not a dependency of the prototype.
+
+4. **Skip polish.** No tests, no error handling beyond what makes it runnable, no abstractions. The goal is learning, not quality.
+
+5. **Surface the state.** After every action, print or render the full relevant state. The user needs to see what changed.
+
+6. **Delete or absorb when done.** When the question is answered, either delete the prototype or fold the validated decision into real code. Do not leave it rotting.
+
+## When done
+
+Capture the answer in something durable: commit message, ADR, issue, or a `NOTES.md` next to the prototype. Include the question and the verdict. Then delete the prototype.