devflow-kit 3.14.0 → 3.16.0

package/src/assets/commands/dynamic-plan.mds

@@ -1,289 +0,0 @@
----
-description: Parallel wave planning — challenge each ticket plan, write acceptance criteria and test plans, resolve decisions from the preference profile, output DECISIONS-NEEDED.md
-argument-hint: "[tickets-dir | issue-list]"
-output-dir: dist/commands
----
-@import { authoring_preamble, authoring_decisions } from "./_partials/_preamble.mds"
-@import { docs_root } from "./_partials/_docs_root.mds"
-@import { agent_roster, agent_caveats } from "./_partials/_roster.mds"
-@import { acceptance_criteria_contract } from "./_partials/_plan_contract.mds"
-@import { issue_ref_grammar, issue_capture_contract } from "./_partials/_tracker.mds"
-@import "./_partials/_settings.mds" as settings
-{{authoring_preamble()}}
-
-<!-- curation:on -->
-### Settings line
-
-{{settings.settings_resolve()}}
-
-Run this call with the start directory as `{root}` in the same turn as the `resolve-root.cjs` call and the profile read: none needs the output of another.
-
-<!-- curation:end -->
-{{authoring_decisions()}}
----
-
-## dynamic-plan — author and run a parallel planning + plan-challenge workflow
-
-Author and run a dynamic Workflow that plans and challenges every ticket in parallel, audits the plans against each other, and auto-resolves the decisions the preference profile settles.
-
-{{agent_roster()}}
-
-{{agent_caveats()}}
-
----
-
-**Requires:** ticket files directory or tracker issue list; optional `~/.devflow/preference-profile.md`
-**Produces:** per-ticket plan files + `DECISIONS-NEEDED.md` at `{worktree}/.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. **Tracker paths:** a list of issue references or URLs is read through the Git agent, which resolves the configured tracker and its access itself and reports `TRACEABILITY: DEGRADED ({reason})` when it cannot read an issue — then fall back to reading ticket `.md` files from a local path. No tracker CLI is checked here.
-3. **No-remote path:** if the repo has no remote, read ticket files from the provided local path; the Git agent reports DEGRADED for any issue it cannot reach.
-
----
-
-### Pre-authoring setup
-
-{{docs_root()}}
-
-Pass `{worktree}` to the workflow as its `root` argument, and its `slug` argument: the `{slug}` of the ticket directory (`tickets/{slug}/{ts}/`) when that is the ticket source, otherwise `wave`.
-
-<!-- curation:on -->
-**1. Apply decisions context**
-
-Apply the `devflow:apply-decisions` algorithm to the DECISIONS_CONTEXT loaded by the decisions step above: scan the index, Read relevant entries, note verbatim ADR/PF IDs to inject into Design agent prompts.
-
-<!-- curation:end -->
-**2. Read the preference profile**
-
-Run this in the same turn as the `resolve-root.cjs` call:
-```bash
-cat ~/.devflow/preference-profile.md 2>/dev/null || echo "(no preference profile)"
-```
-
-If present, note its contents as `PREFERENCE_PROFILE`. 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**
-
-What follows the command is bound once, here. Every later step names it `COMMAND_INPUT` and never restates it:
-
-<command-input>
-$ARGUMENTS
-</command-input>
-
-Determine the ticket source from `COMMAND_INPUT` (in priority order):
-- A directory of ticket `.md` files (from `/devflow:dynamic-tickets` output)
-- A list of candidate issue references or issue URLs
-- Inline ticket descriptions passed as args
-
-{{issue_ref_grammar()}}
-
-Note the tickets and their key constraints; the agents read them in full.
-
-{{issue_capture_contract()}}
-
----
-
-### AskUserQuestion at the command boundary, never inside the workflow
-
-A workflow cannot pause mid-run. It only writes `DECISIONS-NEEDED.md`; you read the file and ask after the workflow returns.
-
-After the workflow completes:
-1. **Check each plan's test plan.** For every path in `planPaths`, copy that plan's `## Test Plan` section — the heading and its TP lines, up to the next `## ` heading — byte for byte into a new file in a `mktemp -d` folder with the Write tool, never through an interpolated shell string, and run the check below on it. Batch the plans: one `mktemp -d` call, one turn of parallel Writes, one file per plan, and one Bash call runs every check, each behind an `echo "file=<that file>"` line:
-
-```bash
-node "$HOME/.devflow/scripts/verify-evidence.cjs" check tp <that file>; echo "exit=$?"
-```
-
-   Check the section, never the whole plan file. `exit=0` passes. Any other result names that plan `test plan malformed (<code>)` in your summary, `<code>` being the code the script printed on stderr; a plan with no `## Test Plan` section copies as an empty file, which the script refuses. Nothing is repaired: `/devflow:dynamic-build` passes no test plan from that plan.
-2. Read the `decisionsNeededPath` the workflow returned, in the same turn as the checks — never the flat `{worktree}/.devflow/docs/design/DECISIONS-NEEDED.md`.
-3. First surface the **Auto-Resolved Decisions** section (decision → resolution → source) for audit, then ask all open **Decisions Needed** in one batched `AskUserQuestion`, never one at a time.
-4. The user's answers feed into their own plan edits or a follow-up `/devflow:dynamic-plan` run.
-
----
-
-### 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";
-<!-- curation:on -->
-const DECISIONS_CONTEXT = args.decisionsContext || "";   // injected before authoring
-<!-- curation:end -->
-const PREFERENCE_PROFILE = args.preferenceProfile || "";  // injected before authoring
-const TP_CONTRACT = args.tpContract || "";  // the "Test-plan line (TP)" contract below — its paragraph and four bullets — passed verbatim as tpContract when invoking the workflow, never pasted into this script (it holds backticks)
-const slug = args.slug || "wave";
-const now = new Date(), two = (n) => String(n).padStart(2, '0');
-const ts = `${now.getFullYear()}-${two(now.getMonth() + 1)}-${two(now.getDate())}_${two(now.getHours())}${two(now.getMinutes())}`;
-const ROOT = args.root;  // {worktree} from Pre-authoring setup: the checkout's toplevel, never cwd
-const OUTDIR = `${ROOT}/.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 tracker issues, use the Git agent's fetch-issue or fetch-issues-batch operation.
-Return: array of ticket objects with all fields.`, { agentType: "Git" })
-);
-
-// Phase 2: Plan all tickets in parallel — one 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)}
-<!-- curation:on -->
-Decisions context (apply devflow:apply-decisions; a plan file can be posted to the tracker, so state each decision in words, never by ID): ${DECISIONS_CONTEXT}
-<!-- curation:end -->
-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: "Architect" })
-  ))
-);
-
-// Phase 3: Plan-challenge — one adversarial challenger per ticket (parallel)
-// Keep the challenge intent below verbatim; never paraphrase it.
-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])}
-
-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. The test plan for the Test agent as TP lines, numbered from TP-1, at least one per criterion, each in exactly the shape of the test-plan line contract below. Map each scenario onto its line:
-   - the scenario, in plain words, is the line's scenario text — never a path, a reference, a mention or markup;
-   - the number of the criterion it covers is its (AC-m);
-   - its verification method is its method: a test committed to the suite is ci; a command run and read (a load test, a script) is local; a step performed and observed is manual;
-   - the paths it exercises, from the plan's affected files, are its files: globs.
-   Setup and expected outcome never go in a line: give them per TP in testScenarios.
-4. A list of genuine design decisions that require user input (not settled by the plan or the preference profile).
-
-Test-plan line contract:
-${TP_CONTRACT}
-
-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 TP-line strings, TP-1 first), testScenarios (array of {tp, setup, outcome}), 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)}
-<!-- curation:on -->
-Decisions context: ${DECISIONS_CONTEXT}
-<!-- curation:end -->
-
-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.
-
-<!-- curation:on -->
-For each conflict found: state which two tickets are involved, describe the conflict precisely, and propose a resolution aligned with the decisions ledger.
-<!-- curation:off -->
-For each conflict found: state which two tickets are involved, describe the conflict precisely, and propose a resolution.
-<!-- curation:end -->
-
-Return: { conflicts (array of {tickets, conflictDescription, proposedResolution}), planAmendments (array of {ticketTitle, amendment}) }.`, { agentType: "Design" })
-);
-
-// Phase 5: Preference-profile auto-resolution
-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) || [])}
-
-For each open decision:
-- If the preference profile 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, {ticket-slug} being the ticket's file name without .md when it came from a ticket directory, otherwise the ticket title run through title.toLowerCase().replace(/[^a-z0-9]+/g, '-') with nothing trimmed, containing:
-- ## Implementation Plan
-- The plan body (incorporate cross-plan amendments)
-- ## Acceptance Criteria (numbered, positive + negative)
-- ## Test Plan — the challenger's testPlan lines, verbatim, one per line, and nothing else: no prose, no blank line between them, no setup or outcome
-- ## Test Scenarios — one line per TP, in TP order: TP-n: its setup, then its expected outcome, from testScenarios
-<!-- curation:on -->
-- ## Auto-Resolved Decisions (if any — list each as: decision → resolution → source, naming a recorded decision in words, never by ID)
-<!-- curation:off -->
-- ## Auto-Resolved Decisions (if any — list each as: decision → resolution → source)
-<!-- curation:end -->
-
-Then write ${OUTDIR}/DECISIONS-NEEDED.md:
-<!-- curation:on -->
-- ## 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."
-<!-- curation:off -->
-- ## Auto-Resolved Decisions — list each silently-resolved decision as: decision → resolution → source (preference profile), so auto-resolution is auditable and reversible. If none, write "None."
-<!-- curation:end -->
-- ## 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.
-<!-- curation:on -->
-- If no decisions needed, write: "No open decisions — all settled by preference profile or existing ADRs."
-<!-- curation:off -->
-- If no decisions needed, write: "No open decisions — all settled by the preference profile."
-<!-- curation:end -->
-
-Return: { planPaths (array), decisionsNeededPath (string), decisionsNeededCount (number) }.`, { agentType: "Synthesize" })
-);
-```
-
----
-
-Phase 3 must produce the acceptance criteria and test plan shape that `/devflow:dynamic-build`'s Gate 2 consumes:
-
-{{acceptance_criteria_contract()}}
-
----
-
-### Output schema
-
-The workflow returns:
-
-```json
-{
-  "planPaths": ["string — path to each per-ticket plan file; its ## Test Plan holds TP lines only, its ## Test Scenarios their setup and outcome"],
-  "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: check each plan's test plan, then read `DECISIONS-NEEDED.md` and ask, as the list above says. 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`."

package/src/assets/commands/dynamic-profile.mds

@@ -1,103 +0,0 @@
----
-description: Decision-preference profile distiller — mine past session transcripts of all projects into ~/.devflow/preference-profile.md
-argument-hint: "[--dry-run]"
-output-dir: dist/commands
----
-## dynamic-profile — distill a decision-preference profile from past sessions
-
-This command spawns one Knowledge 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`. `/devflow:dynamic-plan` reads the profile to pre-resolve design decisions that match established taste, so only new decisions reach the user.
-
-**This is one plain Agent spawn, not a Workflow.** The agent does the reading and writing directly.
-
----
-
-**Requires:** read access to `{claude_dir}/projects/*/` session transcripts and `{claude_dir}/rules/`
-**Produces:** `~/.devflow/preference-profile.md` — plain-prose decision-preference profile
-
----
-
-### Claude Code's directory
-
-`{claude_dir}` is Claude Code's directory, resolved once, the way the installer resolves it: `CLAUDE_CONFIG_DIR` when that is set to an absolute path, else `$HOME/.claude`. Run
-
-```bash
-d="${CLAUDE_CONFIG_DIR:-}"; case "$d" in /*) ;; *) d="$HOME/.claude" ;; esac; printf '%s\n' "$d"
-```
-
-and use its one-line output. Pass it to the agent below as `CLAUDE_DIR`.
-
----
-
-### Privacy note
-
-This command mines session transcripts across **all projects** on this machine — `{claude_dir}/projects/*/*.jsonl`, `{claude_dir}/history.jsonl`, and feedback memories. Planning prompts then carry the profile, so one project's decisions may influence planning in another. The user reviews and edits the profile before use. It is never committed to any repo.
-
----
-
-### When --dry-run is passed
-
-Print what the agent would do (a summary of which paths under the resolved `{claude_dir}` it would search, what it would write) and STOP — do not spawn the agent.
-
----
-
-### Agent task
-
-The task for the one Knowledge agent:
-
-```
-You are distilling a decision-preference profile from past session history.
-
-CLAUDE_DIR: {claude_dir} — Claude Code's directory, already resolved; every path below is under it.
-
-BOUNDED READING — MANDATORY: transcripts are gigabytes; never full-read them.
-1. Run: rg -l "AskUserQuestion" "{claude_dir}/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_dir}/history.jsonl if it exists (rg "AskUserQuestion" ... similarly).
-4. Read all files in {claude_dir}/rules/ (small — read fully).
-5. Read all *.md files in {claude_dir}/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 }.
-```
-
-Spawn it with the Agent tool: `Agent(subagent_type="Knowledge")`, with the task above as the prompt.
-
----
-
-### 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.
-```