devflow-kit 1.8.3 → 2.0.1

package/dist/commands/dynamic-plan.md

@@ -0,0 +1,383 @@
+---
+description: Parallel wave planning — plan-challenge every ticket, produce acceptance criteria + test plans, auto-resolve decisions against the preference profile, output DECISIONS-NEEDED.md
+argument-hint: "[tickets-dir | issue-list]"
+---
+## 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.
+
+---
+
+## dynamic-plan — author and run a parallel planning + plan-challenge workflow
+
+This command instructs you to construct and run a Claude Code dynamic Workflow that plans all tickets in parallel, challenges each plan (gaps, edge cases, side-effects), produces well-structured acceptance criteria and a test plan for each ticket (consumed by `/devflow:dynamic-build`'s Gate 2), runs a cross-plan conflict critic, auto-resolves decisions matching the user's preference profile, and writes per-ticket plan files + one `DECISIONS-NEEDED.md`.
+
+### 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 |
+
+### 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.
+
+---
+
+**Requires:** ticket files directory or GitHub issue list; optional `~/.devflow/preference-profile.md`
+**Produces:** per-ticket plan files + `DECISIONS-NEEDED.md` at `.devflow/docs/design/{slug}/{ts}/`
+
+---
+
+### Preflight checks
+
+Before authoring, verify:
+
+1. **Workflow tool available:** if the `Workflow` tool is not in your available tools, STOP and tell the user: "The Workflow tool is not available in this session. dynamic-plan requires Claude Code's dynamic workflow runtime."
+2. **`agentType` support:** confirmed available (spike F5, 2026-06-11).
+3. **GitHub paths:** if the input is a list of GitHub issue URLs or numbers, `gh` CLI must be authenticated to read issue bodies. If not authenticated, fall back to reading ticket `.md` files from a local path.
+4. **No-remote path:** if the repo has no remote, skip GitHub-dependent steps and read ticket files from the provided local path.
+
+---
+
+### Pre-authoring setup
+
+**1. Apply decisions context**
+
+Apply the `devflow:apply-decisions` algorithm to the DECISIONS_CONTEXT loaded per the preamble above: scan the index, Read relevant entries, note verbatim ADR/PF IDs to inject into Design agent and Evaluate agent prompts.
+
+**2. Read the preference profile**
+
+Check whether `~/.devflow/preference-profile.md` exists:
+```bash
+cat ~/.devflow/preference-profile.md 2>/dev/null || echo "(no preference profile)"
+```
+
+If present, note its contents as `PREFERENCE_PROFILE`. This will be used to auto-resolve decisions that match established taste. If absent, proceed with a one-line note in the output: "No preference profile found — run `/devflow:dynamic-profile` to generate one."
+
+**3. Resolve ticket input**
+
+Determine the ticket source (in priority order):
+- A directory of ticket `.md` files (from `/devflow:dynamic-tickets` output)
+- A list of GitHub issue numbers/URLs
+- Inline ticket descriptions passed as args
+
+Read or note the tickets. The agents will read them in full; you need the list and any key constraints.
+
+---
+
+### CRITICAL (F4) — AskUserQuestion at the command boundary, NOT inside the workflow
+
+A workflow cannot pause mid-run. Open design decisions collected in `DECISIONS-NEEDED.md` are surfaced to the user via **AskUserQuestion AFTER the workflow returns** — at the command boundary. The workflow only WRITES the file; the command (you, the main model) reads it and asks.
+
+After the workflow completes:
+1. Read the `decisionsNeededPath` returned by the workflow (e.g. `.devflow/docs/design/<slug>/<ts>/DECISIONS-NEEDED.md`). Always use the OUTDIR-scoped path the workflow wrote — never the flat `.devflow/docs/design/DECISIONS-NEEDED.md`.
+2. First surface the **Auto-Resolved Decisions** section (decision → resolution → source) for audit, then surface ALL open **Decisions Needed** to the user in ONE batched `AskUserQuestion` (never one-at-a-time).
+3. The user's answers feed into their own plan edits or a follow-up `/devflow:dynamic-plan` run.
+
+State this explicitly in the workflow script as a comment: `// AskUserQuestion happens at the command boundary after this workflow returns — NOT here.`
+
+---
+
+### Planning + plan-challenge workflow structure
+
+Author a workflow script shaped like:
+
+```js
+export const meta = {
+  name: "devflow-dynamic-plan",
+  description: "Parallel planning + plan-challenge: per-ticket plans + acceptance criteria + DECISIONS-NEEDED.md",
+  phases: ["read-tickets", "plan-parallel", "plan-challenge", "cross-plan-critic", "preference-resolve", "write-artifacts"]
+};
+
+// AskUserQuestion happens at the command boundary after this workflow returns — NOT here.
+
+const ticketSource = args.ticketSource || args[0] || "see task description";
+const DECISIONS_CONTEXT = args.decisionsContext || "";   // injected before authoring
+const PREFERENCE_PROFILE = args.preferenceProfile || "";  // injected before authoring
+const slug = args.slug || "wave";
+const ts = new Date().toISOString().slice(0,16).replace(/[-:T]/g, (c) => c === 'T' ? '_' : c === ':' ? '' : c);
+const OUTDIR = `.devflow/docs/design/${slug}/${ts}`;
+
+// Phase 1: Read all tickets
+const tickets = await phase("read-tickets", () =>
+  agent(`Read all tickets from: ${ticketSource}
+For each ticket, extract: title, summary, wave, dependsOn, scope (in/out), acceptance criteria, open questions, and any existing implementation hints.
+If the source is a directory, read all .md files. If the source is GitHub issues, use gh issue view for each.
+Return: array of ticket objects with all fields.`, { agentType: "Git" })
+);
+
+// Phase 2: Plan all tickets in parallel — one Design agent per ticket
+const plans = await phase("plan-parallel", () =>
+  parallel((tickets || []).map(ticket => () =>
+    agent(`Write an implementation plan for this ticket.
+Ticket: ${JSON.stringify(ticket)}
+Decisions context (apply devflow:apply-decisions; cite ADR/PF IDs): ${DECISIONS_CONTEXT}
+The plan must cover: approach overview, affected files and modules, key design decisions, implementation sequence (what to build first), risks and mitigations, and any open questions you cannot resolve from the ticket alone.
+Write a thorough but tight plan — every section must earn its place for a Code agent who has no other context.
+Return: { ticketTitle, planMarkdown, openDecisions (array of genuine unknowns requiring user input) }.`, { agentType: "Design" })
+  ))
+);
+
+// Phase 3: Plan-challenge — one adversarial challenger per ticket (parallel)
+// Challenge verbatim intent (§5.1): hunt improvements, gaps, edge cases, side-effects, and produce acceptance criteria + test plan.
+const challenged = await phase("plan-challenge", () =>
+  parallel((plans || []).map((plan, i) => () =>
+    agent(`Challenge this implementation plan. Verbatim challenge intent:
+"Anything we can improve in this plan? Any gaps? Edge cases we did not address, changes or side-effects we did not consider? And make sure we have well-structured acceptance criteria and a test plan for our Evaluate and Test agents. We need to verify functionality, API contracts, performance. If there are any design decisions to be taken, loop me in."
+
+Plan under review: ${JSON.stringify(plan)}
+Ticket: ${JSON.stringify((tickets || [])[i])}
+Decisions context: ${DECISIONS_CONTEXT}
+
+Produce:
+1. List of improvements / gaps / edge cases / side-effects identified.
+2. Well-structured acceptance criteria (numbered, positive + negative, at least one negative per ticket). See the acceptance criteria contract below.
+3. A test plan for the Test agent: for each criterion, scenario + setup + expected outcome + verification method.
+4. A list of genuine design decisions that require user input (not settled by the plan, the preference profile, or existing ADRs).
+
+Acceptance criteria quality bar (apply strictly):
+- Vague criteria ("the feature should work correctly") are NOT acceptable — reject and rewrite.
+- Implementation-coupled criteria ("the function must call X") are NOT acceptable — test behavior, not implementation.
+- Untestable criteria are NOT acceptable.
+
+Return: { ticketTitle, improvements (array), acceptanceCriteria (array of numbered strings), testPlan (array of {scenario, setup, expectedOutcome, verificationMethod}), openDecisions (array) }.`, { agentType: "Evaluate" })
+  ))
+);
+
+// Phase 4: Cross-plan conflict critic — single Design agent sees all plans
+const crossCritic = await phase("cross-plan-critic", () =>
+  agent(`Cross-plan conflict audit.
+All ticket plans + challenged criteria: ${JSON.stringify(challenged)}
+Decisions context: ${DECISIONS_CONTEXT}
+
+Audit:
+1. API conflicts: two tickets defining the same API differently (different signatures, return types, error codes).
+2. Contradictory invariants: two tickets that cannot both be true simultaneously.
+3. Undeclared dependencies: ticket A's plan implicitly requires something ticket B provides, but no dependency is declared.
+4. Scope overlap: two tickets both claim ownership of the same module or behavior.
+
+For each conflict found: state which two tickets are involved, describe the conflict precisely, and propose a resolution aligned with the decisions ledger.
+
+Return: { conflicts (array of {tickets, conflictDescription, proposedResolution}), planAmendments (array of {ticketTitle, amendment}) }.`, { agentType: "Design" })
+);
+
+// Phase 5: Preference-profile auto-resolution
+// Read the profile and auto-resolve any open decisions that match established taste.
+// Decisions NOT settled by the profile accumulate in DECISIONS-NEEDED.md.
+const resolved = await phase("preference-resolve", () =>
+  agent(`Apply the preference profile to auto-resolve open design decisions.
+Preference profile: ${PREFERENCE_PROFILE || "(none — no profile found)"}
+Open decisions from plan-challenge: ${JSON.stringify((challenged || []).flatMap(c => c.openDecisions || []))}
+Cross-plan conflicts needing resolution: ${JSON.stringify((crossCritic && crossCritic.conflicts) || [])}
+Decisions context (ADRs/PFs already settled): ${DECISIONS_CONTEXT}
+
+For each open decision:
+- If the preference profile or an existing ADR/PF settles it clearly: auto-resolve and note the rationale.
+- If not settled: add to the DECISIONS-NEEDED list for the user.
+
+Return: { autoResolved (array of {decision, resolution, source}), decisionsNeeded (array of {decision, context, options}) }.`, { agentType: "Synthesize" })
+);
+
+// Phase 6: Write artifacts — per-ticket plan files + DECISIONS-NEEDED.md
+return phase("write-artifacts", () =>
+  agent(`Write all planning artifacts.
+Plans: ${JSON.stringify(plans)}
+Challenged plans (with acceptance criteria + test plans): ${JSON.stringify(challenged)}
+Cross-plan amendments: ${JSON.stringify(crossCritic && crossCritic.planAmendments)}
+Auto-resolved decisions: ${JSON.stringify(resolved && resolved.autoResolved)}
+Decisions needed: ${JSON.stringify(resolved && resolved.decisionsNeeded)}
+Output directory: ${OUTDIR}
+
+For each ticket, write ${OUTDIR}/{ticket-slug}-plan.md containing:
+- ## Implementation Plan
+- The plan body (incorporate cross-plan amendments)
+- ## Acceptance Criteria (numbered, positive + negative)
+- ## Test Plan (per-criterion scenarios)
+- ## Auto-Resolved Decisions (if any — list each as: decision → resolution → source)
+
+Then write ${OUTDIR}/DECISIONS-NEEDED.md:
+- ## Auto-Resolved Decisions — list each silently-resolved decision as: decision → resolution → source (preference profile / ADR-NNN), so auto-resolution is auditable and reversible. If none, write "None."
+- ## Decisions Needed
+- One section per open decision: what the decision is, why it matters, what options exist.
+- Include cross-plan conflicts that were not auto-resolved.
+- If no decisions needed, write: "No open decisions — all settled by preference profile or existing ADRs."
+
+Return: { planPaths (array), decisionsNeededPath (string), decisionsNeededCount (number) }.`, { agentType: "Synthesize" })
+);
+```
+
+---
+
+The plan-challenge step (Phase 3 above) MUST produce the acceptance criteria and test plan shape that `/devflow:dynamic-build`'s Gate 2 consumes:
+
+### 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.
+
+---
+
+### Artifact paths
+
+Per-ticket plans → `.devflow/docs/design/{slug}/{ts}/{ticket-slug}-plan.md`
+
+Decisions needed → `.devflow/docs/design/{slug}/{ts}/DECISIONS-NEEDED.md`
+
+Honor the `WORKTREE_PATH` prefix when provided.
+
+---
+
+### Output schema
+
+The workflow returns:
+
+```json
+{
+  "planPaths": ["string — path to each per-ticket plan file"],
+  "decisionsNeededPath": "string — path to DECISIONS-NEEDED.md",
+  "decisionsNeededCount": "number — how many decisions need user input",
+  "autoResolvedCount": "number — decisions auto-resolved by preference profile"
+}
+```
+
+After the workflow returns: read `DECISIONS-NEEDED.md`. First briefly surface the **Auto-Resolved Decisions** section (decision → resolution → source) so silently-settled calls are visible and reversible, then surface ALL open **Decisions Needed** in ONE batched `AskUserQuestion` (never one-at-a-time). Do not ask questions mid-workflow — this is F4. If no preference profile was found, note in your summary: "no preference profile found — N decisions were surfaced that a profile might have auto-resolved; consider `/devflow:dynamic-profile`."
+
+---
+
+### Maintenance note
+
+This recipe encodes the planning pipeline as of the authoring date (2026-06-12). The plan-challenge verbatim intent (§5.1) is load-bearing — do not paraphrase it when authoring the challenger agent prompt. The "Acceptance criteria + test plan contract" section above is the shared shape with `/devflow:dynamic-build` Gate 2; any change must be kept in sync. No tooling detects drift — by design (ADR-008 Iron Rule).

package/dist/commands/dynamic-profile.md

@@ -0,0 +1,206 @@
+---
+description: Decision-preference profile distiller — mine past session transcripts across all projects to write ~/.devflow/preference-profile.md
+argument-hint: "[--dry-run]"
+---
+## 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.
+
+---
+
+## dynamic-profile — distill a decision-preference profile from past sessions
+
+This command spawns an agent (or a small set of parallel readers + a Synthesize agent) that reads past session history across ALL projects on this machine, finds the `AskUserQuestion` moments and the user's chosen answers, and writes a plain-prose preference profile to `~/.devflow/preference-profile.md`.
+
+The profile is then consumed by `/devflow:dynamic-plan` to pre-resolve design decisions matching established taste, so only genuinely new decisions reach the user.
+
+**This is a plain Agent spawn — not a Workflow.** No `Workflow` tool required. The agent does the reading and writing directly.
+
+---
+
+**Requires:** read access to `~/.claude/projects/*/` session transcripts and `~/.claude/rules/`
+**Produces:** `~/.devflow/preference-profile.md` — plain-prose decision-preference profile
+
+---
+
+### Privacy note
+
+This command mines session transcripts across **all projects** on this machine — `~/.claude/projects/*/*.jsonl`, `~/.claude/history.jsonl`, and feedback memories. The resulting profile is then injected into planning prompts as context. This is a cross-project surface: patterns from one project's decisions may influence planning in another.
+
+Mitigation: the profile is plain prose that you review and edit before use. You can trim, redact, or rewrite any section. The profile is at `~/.devflow/preference-profile.md` — open it, read it, adjust it. It is never committed to any repo.
+
+---
+
+### Bounded reading — mandatory
+
+Session transcripts on a typical machine are gigabytes. **The agent MUST NOT full-read transcripts into context.** Instead:
+
+1. Use `rg` (ripgrep) or `grep` to search for `AskUserQuestion` occurrences across transcript files — extracting just the question text and the surrounding user response (a few lines each).
+2. Sample the results — take up to ~200 instances spread across projects and time; do not feed everything into context at once.
+3. Read `~/.claude/rules/` files (these are small) to supplement with explicitly stated preferences.
+4. Read existing feedback memory files (`~/.claude/projects/*/memory/*.md`) — these are small and already distilled.
+
+This grep-and-sample approach is both efficient and Iron-Rule-safe: the agent uses `rg`/`grep` as tools — no extractor or clustering logic is authored.
+
+---
+
+### When --dry-run is passed
+
+Print what the agent would do (a summary of which paths it would search, what it would write) and STOP — do not spawn the agent.
+
+---
+
+### Agent task
+
+Spawn a single Knowledge agent with this task:
+
+```
+You are distilling a decision-preference profile from past session history.
+
+BOUNDED READING — MANDATORY: transcripts are gigabytes; never full-read them.
+1. Run: rg -l "AskUserQuestion" ~/.claude/projects/ 2>/dev/null | head -50
+   to find transcript files that contain AskUserQuestion moments.
+2. For each found file, run: rg -A 5 "AskUserQuestion" <file> | head -200
+   to extract the question + nearby user response context. Sample broadly —
+   aim for ~150-200 instances spread across projects and time windows.
+3. Read ~/.claude/history.jsonl if it exists (rg "AskUserQuestion" ... similarly).
+4. Read all files in ~/.claude/rules/ (small — read fully).
+5. Read all *.md files in ~/.claude/projects/*/memory/ (small — read fully).
+
+From this evidence, identify the recurring patterns in how the user answers design
+questions. Look for preferences about:
+- Error handling style (Result types vs exceptions, etc.)
+- Fix-all-issues vs defer-and-tech-debt stance
+- Architectural tradeoffs (coupling vs performance, etc.)
+- Code review behavior (accept suggestions or push back)
+- Testing discipline
+- Security stance
+- Any other recurrent taste patterns with at least 3 examples
+
+Write ~/.devflow/preference-profile.md as plain prose:
+- ## Overview: 1 paragraph summary of the user's overall decision style
+- ## Preferences (one ## section per identified pattern):
+  - Pattern name
+  - Observed behavior (plain language, no quotes from transcripts)
+  - Confidence: high / medium / low (based on number of examples seen)
+  - Example context: describe a scenario where this preference applies
+- ## Uncertain / incomplete: patterns with only 1-2 examples, flagged for user review
+
+Keep the profile scannable and honest. Do not fabricate preferences with no evidence.
+If a section has low confidence, say so. The user will review and edit this file.
+
+After writing, return: { path: "~/.devflow/preference-profile.md", patternCount: N, lowConfidenceCount: N }.
+```
+
+Invoke the agent directly (not via a Workflow):
+
+```js
+// Spawn a single Knowledge agent — no Workflow tool needed
+const result = await agent(
+  `<the task above>`,
+  { agentType: "Knowledge" }
+);
+```
+
+After the agent completes, tell the user:
+- The profile was written to `~/.devflow/preference-profile.md`
+- How many patterns were found (and how many are low-confidence)
+- Prompt them to review and edit the file before running `/devflow:dynamic-plan`
+- Note: re-run this command any time to refresh the profile as new sessions accumulate
+
+---
+
+### Output
+
+After the agent returns, report:
+
+```
+Profile written to ~/.devflow/preference-profile.md
+Patterns found: {patternCount} ({lowConfidenceCount} low-confidence — review these)
+
+Next steps:
+1. Open ~/.devflow/preference-profile.md and review/edit the profile.
+2. Run /devflow:dynamic-plan — it will read the profile and auto-resolve decisions matching your taste.
+3. Re-run /devflow:dynamic-profile periodically to keep the profile fresh.
+```
+
+---
+
+### Maintenance note
+
+This command mines ALL projects' history on this machine. The bounded-reading discipline (grep/rg + sample — never full-read) is mandatory and must be preserved in every revision. The agent writes prose; no extraction or clustering algorithm is authored here. Per ADR-008 Iron Rule: the agent does the reading and summarizing — not a script we maintain.