devflow-kit 1.8.3 → 2.0.0

package/src/assets/commands/_partials/_factory.mds

@@ -0,0 +1,216 @@
+@define factory_shape():
+### Ticket-factory pipeline shape (generalized)
+
+This is the standard shape for converting an initiative or spec into a reviewed, amended, self-consistent set of tickets plus a tracking issue. It generalises the `l3-ticket-factory` reference (`draft → [2-lens review in parallel] → revise → whole-set critic → per-ticket amend → tracking-issue`).
+
+The candidate ticket slate is **proposed by the model** (you, reading the initiative/spec), then **user-editable** before the pipeline runs. Never hardcode ticket identities — let the user confirm the slate first.
+
+---
+
+#### Stage 1 — Draft (one agent per ticket, parallelisable)
+
+Spawn one Design agent or Synthesize agent per candidate ticket:
+
+```js
+// Parallel per-ticket drafters — each is fully independent at draft time
+const drafts = await parallel(candidates.map(c => () =>
+  agent(`Draft ticket for: ${c.title}\nInitiative: ${initiative}\n${constraints}`, {
+    agentType: "Design",
+    schema: DRAFT_SCHEMA
+  })
+));
+```
+
+DRAFT_SCHEMA (in fenced block — braces are raw):
+
+```json
+{
+  "type": "object",
+  "required": ["title", "summary", "wave", "dependsOn", "scope", "acceptanceCriteria", "openQuestions"],
+  "properties": {
+    "title":             { "type": "string" },
+    "summary":           { "type": "string" },
+    "wave":              { "type": "number" },
+    "dependsOn":         { "type": "array", "items": { "type": "string" } },
+    "scope":             { "type": "object",
+                           "properties": { "in": { "type": "array", "items": { "type": "string" } },
+                                           "out": { "type": "array", "items": { "type": "string" } } } },
+    "acceptanceCriteria":{ "type": "array", "items": { "type": "string" } },
+    "openQuestions":     { "type": "array", "items": { "type": "string" } }
+  }
+}
+```
+
+---
+
+#### Stage 2 — Two-lens review (parallel per ticket)
+
+For each draft, run TWO independent Review agents **in parallel** — one per lens:
+
+**Lens A — Planner-readiness (cold read):** Could a planner build from this ticket alone, with no other context? Hunt: missing information; untestable or missing negative acceptance criteria; ambiguous constraints; scope holes (things the feature obviously needs that neither In nor Out mentions); undefined terms a cold reader cannot resolve. Severity: critical = planner would be blocked or misled; major = planner would guess; minor = polish.
+
+**Lens B — Accuracy / scope-discipline audit:** Every claim is sourced from the initiative or spec. No smuggled anti-features (scope items the initiative explicitly excludes). Constraints are honored. Dependency placeholders are consistent with the candidate slate. Severity: critical = invented fact / anti-feature / leak; major = unsourced claim or stance contradiction; minor = citation polish.
+
+```js
+// Two Review agents per ticket, parallel across both lens and all tickets
+const reviews = await parallel(drafts.map((draft, i) => () =>
+  parallel([
+    () => agent(`Planner-readiness cold read of ticket: ${JSON.stringify(draft)}`, {
+      agentType: "Review",
+      schema: REVIEW_SCHEMA
+    }),
+    () => agent(`Accuracy/scope-discipline audit of ticket: ${JSON.stringify(draft)}`, {
+      agentType: "Review",
+      schema: REVIEW_SCHEMA
+    }),
+  ])
+));
+```
+
+REVIEW_SCHEMA (in fenced block — braces are raw):
+
+```json
+{
+  "type": "object",
+  "required": ["verdict", "findings"],
+  "properties": {
+    "verdict":  { "type": "string", "enum": ["ready", "needs-work"] },
+    "findings": { "type": "array", "items": {
+      "type": "object",
+      "required": ["severity", "issue", "suggestion"],
+      "properties": {
+        "severity":   { "type": "string", "enum": ["critical", "major", "minor"] },
+        "issue":      { "type": "string" },
+        "suggestion": { "type": "string" }
+      }
+    }}
+  }
+}
+```
+
+---
+
+#### Stage 3 — Revise (one agent per ticket, per review findings)
+
+For each ticket, spawn one Synthesize agent or Design agent to apply review findings:
+
+```js
+// Sequential per ticket (shared file state); parallelisable across tickets only if separate files
+const revised = await parallel(drafts.map((draft, i) => () =>
+  agent(`Revise ticket per review findings. Fix all critical + major findings; apply minor only where they clarify.
+Ticket: ${JSON.stringify(draft)}
+Reviews: ${JSON.stringify(reviews[i])}
+Rules: if a finding asks for information that does not exist in the source initiative, add it to Open Questions — never invent. If a finding contradicts the stated initiative scope, the initiative wins; note the decline.`, {
+    agentType: "Synthesize",
+    schema: REVISE_SCHEMA
+  })
+));
+```
+
+REVISE_SCHEMA (in fenced block — braces are raw):
+
+```json
+{
+  "type": "object",
+  "required": ["title", "changesMade", "remainingConcerns"],
+  "properties": {
+    "title":            { "type": "string" },
+    "changesMade":      { "type": "array", "items": { "type": "string" } },
+    "remainingConcerns":{ "type": "array", "items": { "type": "string" } }
+  }
+}
+```
+
+---
+
+#### Stage 4 — Whole-set cross-critic (single agent, sees all revised tickets)
+
+One Design agent reviews the FULL revised set for set-level issues — not individual prose quality:
+
+1. **Coverage:** does the union of tickets cover every item the initiative mandates? Anything the initiative mandates that no ticket owns?
+2. **Overlaps / contradictions:** same responsibility claimed by two tickets; contradictory constraints between tickets; inconsistent terminology for the same concept.
+3. **Dependency graph:** placeholders used consistently; wave assignment matches stated dependencies; anything that should be a dependency but isn't declared.
+4. **Acceptance-criteria coherence:** no criterion in one ticket contradicts a criterion in another.
+
+```js
+const critic = await agent(`Whole-set completeness & coherence audit.
+Revised tickets: ${JSON.stringify(revised)}
+Initiative: ${initiative}
+Audit: coverage · overlaps/contradictions · dependency graph · acceptance-criteria coherence.
+Return: setVerdict + perTicketAmendments + trackingGuidance.`, {
+  agentType: "Design",
+  schema: CRITIC_SCHEMA
+});
+```
+
+CRITIC_SCHEMA (in fenced block — braces are raw):
+
+```json
+{
+  "type": "object",
+  "required": ["setVerdict", "perTicketAmendments", "trackingGuidance"],
+  "properties": {
+    "setVerdict": { "type": "string" },
+    "perTicketAmendments": { "type": "array", "items": {
+      "type": "object",
+      "required": ["title", "amendments"],
+      "properties": {
+        "title":      { "type": "string" },
+        "amendments": { "type": "array", "items": { "type": "string" } }
+      }
+    }},
+    "trackingGuidance": { "type": "string" }
+  }
+}
+```
+
+---
+
+#### Stage 5 — Per-ticket amend (parallel, only tickets with amendments)
+
+Apply cross-set amendments to the tickets that need them:
+
+```js
+const toAmend = (critic.perTicketAmendments || []).filter(a => a.amendments.length > 0);
+if (toAmend.length) {
+  await parallel(toAmend.map(a => () =>
+    agent(`Apply cross-set amendments to ticket "${a.title}":
+Amendments: ${JSON.stringify(a.amendments)}
+Rules: same as revise — never invent; unresolvable items go to Open Questions; initiative scope wins over any amendment that contradicts it.`, {
+      agentType: "Synthesize"
+    })
+  ));
+}
+```
+
+---
+
+#### Stage 6 — Assemble tracking issue
+
+One Synthesize agent writes the tracking-issue document from the final ticket set + critic guidance:
+
+```js
+const tracker = await agent(`Write a tracking-issue document for the initiative.
+Guidance from cross-set critic: ${JSON.stringify(critic.trackingGuidance)}
+Final tickets: ${JSON.stringify(revised)}
+Structure: initiative context (1–2 paragraphs) + wave-structured execution checklist + ticket index (one line per ticket, user-facing) + explicitly-excluded items (decisions, not oversights) + invariants that bind every ticket.
+Output: write to the artifact path and return { path, title }.`, {
+  agentType: "Synthesize",
+  schema: { type: "object", required: ["path", "title"],
+    properties: { path: { type: "string" }, title: { type: "string" } } }
+});
+```
+
+---
+
+#### Usage notes for commands that import this partial
+
+- The `candidates` array is **what the model proposed + user confirmed** — never hardcoded.
+- The `initiative` variable is the raw user input (a description, a spec doc path, or inline text) — read it and distill before passing to agents.
+- The `constraints` variable is optional: any cross-cutting rules (naming discipline, scope filters, authority order) the user supplied.
+- Emit artifact files using the `ticket_body_template()` shape (from `_ticket_template.mds`) for each ticket — write inside agents, since the script body has no filesystem access.
+- Tracking-issue doc goes to `.devflow/docs/tickets/\{slug\}/\{ts\}/tracking-issue.md` (agents do the writing).
+- For large initiatives (more than ~8 tickets), chunk the `parallel(map())` fan-outs into batches (e.g. `for` loop over slices, `await`-ing each batch) so agent concurrency stays bounded and provider rate limits are respected.
+@end
+
+@export factory_shape

package/src/assets/commands/_partials/_knowledge.mds

@@ -0,0 +1,95 @@
+@define knowledge_load():
+### Load Feature Knowledge
+
+Resolve the worktree root using the `devflow:worktree-support` algorithm (use WORKTREE_PATH if provided, otherwise cwd). All paths below are relative to `\{worktree\}`.
+
+**Step 1 — Read the index cache:**
+
+Attempt to read `\{worktree\}/.devflow/features/index.md`. Each line follows the format:
+
+```
+- **{slug}** — {areas} — {Use-when description}
+```
+
+If `index.md` exists and contains at least one entry line, use it for relevance matching.
+
+**Step 2 — Fallback: glob frontmatter (if `index.md` is absent or empty):**
+
+Glob `\{worktree\}/.devflow/features/*/KNOWLEDGE.md`. For each file found, read only its YAML frontmatter block (between the opening and closing `---` delimiters). The frontmatter fields `name`, `description`, and `directories` are the authoritative relevance surface — `index.md` is only a cache.
+
+**Step 3 — Pick relevant KBs:**
+
+Match the current task area and description against each index line (or frontmatter `description` + `directories` on fallback). Select entries whose documented area overlaps the current task. This is a relevance judgment — prefer specificity over breadth.
+
+**Step 4 — Read selected KBs:**
+
+For each selected entry, read `\{worktree\}/.devflow/features/\{slug\}/KNOWLEDGE.md` in full. When the KB content contradicts the current code you observe, **trust the code** — the code is the freshness mechanism; the KB may lag behind.
+
+**Step 5 — Set FEATURE_KNOWLEDGE:**
+
+Concatenate the selected KNOWLEDGE.md files under slug headers:
+
+```
+--- Feature knowledge: {slug} ---
+{full KNOWLEDGE.md content}
+```
+
+If no KBs exist, no KBs are relevant, or `.devflow/features/` is absent, set `FEATURE_KNOWLEDGE` to `(none)`.
+
+**No subprocess, no git calls, no `.cjs` script.** This entire step is direct file reads — 1 index read (or N frontmatter reads on fallback), bounded by KB count.
+@end
+
+@export knowledge_load
+
+@define knowledge_writeback():
+### Feature Knowledge Write-Back (Conditional)
+
+Resolve the worktree root using the `devflow:worktree-support` algorithm (use WORKTREE_PATH if provided, otherwise cwd). All paths below are relative to `\{worktree\}`.
+
+**Step 1 — Check the opt-out gate:**
+
+Read `\{worktree\}/.devflow/config.json`. If the `knowledge` field is `false`, skip write-back entirely — the user has disabled it.
+
+If `.devflow/config.json` does not exist, proceed (default is enabled).
+
+**Step 2 — Evaluate whether write-back is warranted:**
+
+Only proceed if **at least one** of these is true:
+- This workflow changed files in a directory that is documented by an existing feature knowledge base (a documented area changed).
+- This workflow surfaced durable, cross-cutting knowledge about a codebase area that would help future agents working in the same area — patterns, anti-patterns, integration points, gotchas not visible from a single file read.
+
+**Never spawn unconditionally.** If neither condition is met, skip write-back silently.
+
+**Step 3 — Spawn the Knowledge agent:**
+
+Spawn `Agent(subagent_type="Knowledge")` with the following context:
+
+```
+"WORKTREE_PATH: {worktree root}
+FEATURE_SLUG: {slug derived from primary changed directory, kebab-case}
+FEATURE_NAME: {human-readable name}
+DIRECTORIES: {list of primary directories touched by this workflow}
+FILES_CHANGED: {list of files changed}
+DECISIONS_CONTEXT: {DECISIONS_CONTEXT if available, else (none)}
+
+Load the devflow:feature-knowledge skill and follow its authoring process.
+
+Write the knowledge base to:
+  {worktree}/.devflow/features/{slug}/KNOWLEDGE.md
+
+Then update the index cache by performing a read-modify-write on:
+  {worktree}/.devflow/features/index.md
+
+Index line format: `- **{slug}** — {areas} — {Use-when description}`
+
+If the line for this slug already exists in index.md, replace it. If it does not exist, append it. If index.md does not exist, create it with just this line.
+
+The frontmatter in KNOWLEDGE.md is the source of truth — index.md is only a cache. Write the two files directly — no intermediate result JSON files, no external scripts.
+
+After writing, commit the two files to the current worktree branch yourself by running git via your Bash tool (do not use a script). Stage ONLY .devflow/features/index.md and .devflow/features/{slug}/KNOWLEDGE.md, then commit just those paths with a docs(knowledge): message. Do NOT push, do NOT force, do NOT stage anything else. Follow your Commit Protocol — it is non-blocking, so if any git step fails, report KB_COMMIT and finish normally."
+```
+
+**Failure handling**: Non-blocking. If the Knowledge agent fails, log the failure and continue — the workflow outcome is not affected by write-back success.
+@end
+
+@export knowledge_writeback

package/src/assets/commands/_partials/_plan_contract.mds

@@ -0,0 +1,51 @@
+@define acceptance_criteria_contract():
+### Acceptance criteria + test plan contract
+
+This is the shared shape produced by `/devflow:dynamic-plan`'s plan-challenge step (§5.1) and consumed by `/devflow:dynamic-build`'s Gate 2 (§7.2). Single source of truth — no drift between planning and build.
+
+#### What the plan-challenge step MUST produce (per ticket)
+
+A structured document (written as part of the per-ticket plan) containing:
+
+**Acceptance criteria (numbered, for the Evaluate agent)**
+
+Criteria must cover:
+- Functionality: what the feature does, including all stated use cases
+- API contracts: exact signatures, return types, error codes, preconditions, postconditions
+- Performance: explicit thresholds (e.g., "p99 latency < 200ms under 100 RPS") or a stated "no perf requirement"
+
+Each criterion is either:
+- POSITIVE: "The system MUST do X when Y" — the implementation must demonstrate this
+- NEGATIVE: "The system MUST NOT do Z" — the implementation must not exhibit this behavior
+
+At least one negative criterion is required per ticket (e.g., "must not break existing behavior X", "must not expose Y to unauthenticated callers", "must not regress test suite Z").
+
+**Test plan (structured, for the Test agent)**
+
+For each acceptance criterion:
+- Test scenario: a concrete, runnable scenario description
+- Setup: preconditions and test data needed
+- Expected outcome: the specific observable result that confirms the criterion
+- Verification method: unit test / integration test / manual step / load test
+
+The test plan must be executable by the Test agent without further clarification — it is a complete specification, not notes.
+
+#### Consumption by Gate 2
+
+The Evaluate agent panel receives: the per-ticket plan + the numbered acceptance criteria (positive and negative).
+
+The Test agent receives: the test plan (all scenarios and expected outcomes).
+
+If either document is absent (no plan from `/devflow:dynamic-plan`, or criteria not written), the corresponding Gate 2 agent is skipped silently — build proceeds Gate-1-only. Never fabricate criteria.
+
+#### Quality bar
+
+A criterion is NOT acceptable if it is:
+- Vague: "the feature should work correctly" — no observable outcome
+- Implementation-coupled: "the function must call X" — tests behavior, not implementation
+- Untestable: no concrete way to verify pass/fail
+
+Challenge every criterion against these three disqualifiers before accepting the plan.
+@end
+
+@export acceptance_criteria_contract

package/src/assets/commands/_partials/_preamble.mds

@@ -0,0 +1,82 @@
+@define authoring_preamble():
+## Your task: author a Claude Code dynamic Workflow and run it
+
+You (the main model) will construct a Claude Code dynamic Workflow script inline and execute it using the `Workflow` tool. You do NOT write a static file — you author the script body right here, then pass it to the Workflow tool.
+
+### Workflow runtime contract
+
+A workflow script MUST begin with a pure-literal export:
+
+```js
+export const meta = {
+  name: "devflow-dynamic-...",   // flat hyphenated namespace — always prefix devflow-dynamic-
+  description: "...",
+  phases: ["..."]
+};
+```
+
+The script body uses ONLY these hooks — nothing else:
+
+```js
+agent(prompt, opts)      // spawn a sub-agent; opts.agentType resolves devflow installed agents
+parallel(thunks)         // barrier — awaits all; concurrency capped ~min(16, cores-2)
+pipeline(items, ...fns)  // stream items through stages (no barrier between stages)
+phase(name, fn)          // named phase boundary for resume / progress
+log(msg)                 // structured log
+workflow(fn)             // nest one level
+```
+
+Globals available in the script body: `args`, `budget`, `workflow()`.
+
+**The script body has NO filesystem / Node.js / `gh` CLI access.** All file reading, issue fetching, git operations, and shell commands happen INSIDE the agents the script spawns — never in the script body itself. There is no `fs`, no `exec`, no `fetch` in scope.
+
+### Agent reuse via agentType
+
+Spawn devflow agents with:
+
+```js
+agent("your prompt here", { agentType: "Code" })
+```
+
+Valid `agentType` values: Code, Validate, Simplify, Scrutinize, Evaluate, Test, Review, Git, Synthesize, Knowledge, Design.
+
+**OMIT `opts.model` whenever `agentType` is set.** The agent frontmatter carries its own model tier (Code→sonnet, Validate→haiku, Review→opus, etc.) and that tier is honored automatically. Passing `opts.model` overrides it — always a mistake.
+
+Do not write logic that depends on an agent enumerating its own skills. Skills are loaded (confirmed by spike F5) but agents do not reliably self-report them.
+
+### Pre-flight self-check — MANDATORY before the first live `Workflow` call
+
+Two distinct LLM-authored-script bugs have crashed whole runs in the field: `TypeError: pipeline() expects an array as the first argument` and `undefined is not an object (evaluating 'SEAL.num')`. Before you invoke the `Workflow` tool, audit the script you just authored against this checklist — it targets exactly those crash classes:
+
+- **`meta` is a pure literal** — `name` and `description` present; NO variables, function calls, spreads, or template interpolation anywhere inside `meta`.
+- **Every `pipeline(x, …)` / `parallel(x)` first argument is a real array** — never a function, object, or possibly-undefined value. If it derives from a prior agent result, coerce it: `parallel((maybeList || []).map(...))`.
+- **No reference to a possibly-undefined field** — guard every cross-result field access with optional chaining (e.g. `result?.findings`, `seal?.num`). This is the `SEAL.num` crash class: an agent returned a shape without `num`, so `SEAL.num` threw.
+- **`.filter(Boolean)` before mapping over `agent()` / `parallel()` results** — an agent can return `null` (skipped, or died after retries); strip nulls before `.map` or field access. filter(Boolean) is crash-safety only; it must never convert missing required coverage into success.
+- **`phase()` titles match the phases declared in `meta`** — every `phase("…")` call has a matching declared phase, and vice-versa.
+
+Then run a cheap syntax gate: write the authored script to a fresh, run-unique scratch file `/tmp/df-wf-check-<meta.name>-<epoch-seconds>.js` (a NEW filename every run — never reuse a prior run's path, as rewriting an existing file trips write guards), run `node --check` on that file, and only then pass the script text to the `Workflow` tool as usual. `node --check` catches SYNTAX errors only — it does NOT catch the runtime type errors above, so the checklist is the real safeguard.
+
+### Budget scaling
+
+The `budget` global governs depth. Scale Review agent roster and verification votes to `budget`. A low-budget run uses a leaner roster and fewer verification votes; a high-budget run expands both. Never hardcode a roster size — let budget guide it.
+
+### DECISIONS_CONTEXT — obtain BEFORE authoring
+
+Before you author the workflow script, read `.devflow/learning/index.md` for the current worktree. If the file is absent or empty, set `DECISIONS_CONTEXT` to `(none)`; otherwise use the file content as `DECISIONS_CONTEXT`.
+
+The script body cannot perform this read — you (the main model) do it before authoring. Then inject the relevant DECISIONS_CONTEXT into agent prompts using the `devflow:apply-decisions` consumption algorithm (scan index → Read relevant entries → cite verbatim IDs in agent prompts). Only agents that need architectural context (Code agent, Evaluate agent, Review agent, Scrutinize agent) need DECISIONS_CONTEXT injected; lightweight agents (Validate agent, Simplify agent) do not.
+
+### Handoff convention for sequential Code agents within a ticket
+
+When a ticket requires multiple sequential Code agent phases, each Code agent writes `.devflow/docs/handoff-\{branch_slug\}.md` (branch-scoped to prevent concurrent session clobber). The next Code agent reads it via HANDOFF_FILE input. PRIOR_PHASE_SUMMARY is the compact in-context form; the handoff file is the durable form that survives context compaction. Always read the handoff file directly — code is authoritative, summaries are supplementary.
+
+### IRON RULE (ADR-008: LLM-vs-plumbing)
+
+**Author ZERO deterministic feature code.** No parsers, no schedulers, no topological-sort, no dependency-graph helpers, no confidence formulas. ALL issue reading, dependency reasoning, and scheduling decisions are LLM judgment at runtime, performed by the workflow's agents. The recipe is instructions. The workflow script Claude authors IS the runtime logic — keep it free of hand-coded feature algorithms.
+
+### SAFETY BANNER
+
+**NEVER merge to main or master** — the workflow merges to an integration branch only. The user merges to main themselves after reviewing. This rule is absolute and must appear as an `engine_invariants()` note in every workflow that touches git.
+@end
+
+@export authoring_preamble

package/src/assets/commands/_partials/_publication.mds

@@ -0,0 +1,7 @@
+@define publication_gate():
+**Resolve `REVIEW_PUBLICATION` per worktree:** Read the current worktree's `.devflow/config.json` (a single, direct file read — multi-worktree repos may have different publication settings per worktree root). If the file exists and `reviewPublication` is one of `auto`, `full`, or `off`, set `REVIEW_PUBLICATION` to that value; otherwise set `REVIEW_PUBLICATION = "auto"`.
+
+Note: `auto` is NOT fail-open — under `auto`, the Git agent probes the repository visibility and treats any error or unrecognised value as PUBLIC (mode STUB).
+@end
+
+@export publication_gate

package/src/assets/commands/_partials/_roster.mds

@@ -0,0 +1,31 @@
+@define agent_roster():
+### Confirmed agent roster
+
+The following agentType values are valid. Model tiers are shown for reference — OMIT `opts.model` in all `agent()` calls; each agent's frontmatter carries its own tier.
+
+| agentType | Model tier | Role |
+|-----------|-----------|------|
+| Code | sonnet | Writes all code and all fixes — the ONLY agent that writes code |
+| Validate | haiku | Build / typecheck / lint / test — fast correctness gate |
+| Simplify | sonnet | Reduces complexity, removes duplication, improves readability |
+| Scrutinize | opus | 9-pillar self-review — deep structural analysis |
+| Evaluate | opus | Plan-fidelity / alignment — "was the plan implemented correctly?" |
+| Test | sonnet | Scenario-based acceptance tests against acceptance criteria |
+| Review | opus | Focus-parameterized code review — spawn ONE agent() per focus area |
+| Git | haiku | Git operations — branches, commits, merges, worktree management |
+| Synthesize | haiku | Summarizes and aggregates multi-agent outputs |
+| Knowledge | sonnet | Codebase exploration — feature knowledge base creation/update |
+| Design | opus | Architecture and design — plans, gap analysis, design review |
+@end
+
+@define agent_caveats():
+### Agent caveats
+
+- **A Code agent writes every fix** — no other agent type writes code. Finding-verification uses adversarial Review agent-style passes (§6.3 of design doc). Risk-assessment and tech-debt routing live in the post-code pipeline + escalation doctrine.
+- **Always omit `opts.model` with `agentType`.** Each agent honors its own frontmatter model tier; overriding it defeats the per-agent specialization.
+- **Review agents are focus-parameterized.** Each focus is a SEPARATE `agent()` call with `agentType: "Review"` and the focus baked into the prompt. Do NOT batch multiple focuses into one Review agent call — that defeats parallel specialization.
+- **Do not depend on agents enumerating their own skills.** Skills are loaded (spike F5 confirmed) but self-reporting is imperfect. Write agent prompts that give the agent full context directly.
+@end
+
+@export agent_roster
+@export agent_caveats

package/src/assets/commands/_partials/_ticket_template.mds

@@ -0,0 +1,59 @@
+@define ticket_body_template():
+### Ticket body template
+
+Each ticket in a wave MUST use this structure. The wave scheduler agents read these fields to reason about dependencies and order. The build engine agents read acceptance criteria to drive Gate 2.
+
+---
+
+**Wave:** N
+**Depends on:** #issue-number, #issue-number (or "none")
+
+---
+
+## Summary
+
+One paragraph: what this ticket implements and why it exists in this wave.
+
+## Scope
+
+**In scope:**
+- Explicit list of what this ticket covers
+- Named deliverables (files, functions, APIs, schemas)
+
+**Out of scope (anti-features — do NOT implement):**
+- Explicit list of what this ticket deliberately excludes
+- Related things that belong to other tickets
+- Future work that must NOT be anticipated
+
+Anti-features are load-bearing: they prevent scope creep and tell the Code agent what NOT to build. At least one is required per ticket.
+
+## Invariants
+
+System properties that MUST remain true after this ticket is merged:
+- Backward compatibility guarantees (if any)
+- Data integrity constraints
+- Performance contracts inherited from prior work
+
+## Acceptance criteria
+
+Numbered, for the Evaluate and Test agents. See `acceptance_criteria_contract()` for the quality bar.
+
+1. POSITIVE: The system MUST...
+2. POSITIVE: The API MUST return...
+3. NEGATIVE: The system MUST NOT...
+4. NEGATIVE: Existing behavior X MUST NOT regress...
+
+(Minimum: at least one negative criterion)
+
+## Open questions
+
+Questions that must be answered before implementation begins. If none, write "None".
+
+When used with `/devflow:dynamic-plan`, open questions are collected into `DECISIONS-NEEDED.md` for user review at the plan→build boundary (the human gate, §11). Preference-profile-settled questions are auto-resolved and do not appear here.
+
+---
+
+**Note for wave scheduler:** The `Depends on:` field lists GitHub issue numbers this ticket must wait for. The `Wave: N` label is a human-readable hint; actual ordering is determined by reading the `Depends on` relationships. An agent reads all wave issues and reasons about the ready set — no topological sort algorithm is used.
+@end
+
+@export ticket_body_template