devflow-kit 3.4.0 → 3.5.0

package/CHANGELOG.md

@@ -5,6 +5,34 @@ All notable changes to Devflow will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [3.5.0] - 2026-10-12
+
+### Added
+
+- **Subagents write a 5-minute prompt cache** ([#443](https://github.com/dean0x/devflow/issues/443)). `devflow flags` gains `subagent-cache-5m`, on by default, which writes `subagentPromptCacheTtl: "5m"` so subagent requests write 5-minute cache entries while the main session keeps the 1-hour TTL of `prompt-caching-1h`. The wave-4 token audit found 99.998% of subagent cache writes were 1-hour writes, yet fewer than 0.1% of subagent requests idle past five minutes; the modelled saving is 8.9% of subagent cache-equivalent cost and 7.7% of the total. Disabling the flag or uninstalling deletes the key only while it holds `"5m"`. When the key already holds another value, such as `"1h"`, `devflow init` and the flags TUI record the flag off and keep your value, and `devflow init --reset` writes `"5m"`. A Claude Code that predates the setting ignores the key. There are now 32 flags.
+- **An `Explore` agent that overrides Claude Code's built-in, and a charter that routes to the roster only** ([#444](https://github.com/dean0x/devflow/issues/444)). devflow ships `explore` with `name: Explore` (Sonnet, high effort, `Read` and `Bash`, no CLAUDE.md). Claude Code matches agents by exact name, so it replaces the built-in Explore in every session, plan mode included. `devflow init` skips it and warns when an agent file of yours already defines `Explore`, and leaves that file alone; `devflow uninstall` removes devflow's copy, so the built-in applies again. The orchestrator charter's routing list ends with "Anything else: the closest roster agent, never general-purpose", because the baseline held 93 general-purpose spawns, 83% of them on Opus. There are now 18 agents.
+- **`devflow tracker --servers` names the tracker servers the Git and Tracker agents may call** ([#445](https://github.com/dean0x/devflow/issues/445)). The two agents hold tool allowlists, and the installer appends one `mcp__<name>` entry per server to their installed `tools:` line. `--servers atlassian,linear` sets the list and re-stamps the installed agents at once; `--servers default` returns it to `atlassian`, `jira`, `claude_ai_Atlassian`, `linear` and `claude_ai_Linear`; `--status` prints a `Servers:` line. Names match `^[A-Za-z0-9_-]{1,64}$`, may not contain `__`, and a list holds at most 32. `devflow init` carries the list forward and `devflow init --reset` returns it to the default. A server under a name outside the list is unreachable, and the run reports `TRACEABILITY: DEGRADED (no tracker tool for {capability})`, whose remedy is `devflow tracker --servers`. `dist/agents/git.md` falls by 251 characters.
+- **An opt-in behavior rule asks agents to reply in ASD-STE100 Simplified Technical English.** Off by default. `devflow behavior --enable | --disable | --status` and `devflow init --behavior` / `--no-behavior` set the machine switch `features.behavior`, and the feature-owned rule `behavior.md` is installed while that switch and rules are both on. Code, commands and quoted text keep their own form. A re-init keeps the recorded value, `--reset` returns it to off, and a shadow at `~/.devflow/rules/behavior.md` replaces the shipped text.
+
+### Changed
+
+- **Evaluate runs on Sonnet** ([#444](https://github.com/dean0x/devflow/issues/444)). `evaluate` moves from `opus` to `sonnet`; a `devflow agents` mapping still wins.
+- **Twelve agents skip CLAUDE.md and the rule files, and Code scans what it changes** ([#445](https://github.com/dean0x/devflow/issues/445)). A live probe on Claude Code 2.1.296 found that `omitClaudeMd: true` drops both CLAUDE.md and `~/.claude/rules/**`, an attachment of about 7K tokens per spawn in this repository, billed again on every turn. Validate, Git, Triage, Evaluate, Test, Research, Knowledge, Tracker and Learning join Skim, Synthesize and Explore, and each restates the core rules it works by in a `## Core rules` block that a guard holds to one fixture table. Learning reads the root CLAUDE.md and the installed rule files itself before its first already-encoded comparison. Code scans each file it changed before its final commit when the session offers a code-scanning tool (one directory scan above ten files, `Security scan: unavailable` otherwise), and Scrutinize and Simplify deny every MCP tool, so scanning runs in Code alone.
+- **Skills load where they are read** ([#446](https://github.com/dean0x/devflow/issues/446)). Knowledge, Tracker, Triage and Synthesize drop preloaded skills they did not use, and Triage keeps its security-finding rule inline. `/plan` and `/research` load `docs-framework` at the step that names a `.devflow/docs/` document, and the skill is the authority for those names. `/release` loads `devflow:git` just before its release commit, so a `--dry-run` never carries it. `/code-review` and `/resolve` load `worktree-support` only when `git worktree list` shows more than one worktree. `/debug` implements an approved fix through the Code agent, which commits it, and then Simplify refines the changed files.
+- **The Git agent loads only the operation it runs** ([#451](https://github.com/dean0x/devflow/issues/451)). `dist/agents/git.md` falls from 35,225 to 10,743 characters. Each of the agent's 20 operations has one reference that holds its contract and its mechanics (`references/tracker/{provider}/{op}.md`, `references/pr/{op}.md` or `references/learn-conventions.md`), and a spawn reads the one for its operation. The references an operation can name add up to at most 19,987 characters, and the worst case, Linear `setup-task`, is 19,907. `ensure-pr-ready` is a tracker operation, so its PR half is written once and compiled into the three providers' files, and it has no file under `references/pr/`. There are now 47 generated reference files.
+- **The Git agent opens the pull request after the quality gates, and the Code agent opens none** ([#448](https://github.com/dean0x/devflow/issues/448)). `/implement` gains an Open PR phase after QA and any re-validation, and before the CI gate, under every strategy. The Git agent writes the PR body from the Code agents' own reports and pastes the issue link, the test-plan block and any `## Evidence Exceptions`. The CI gate runs for parallel Code agents too, and a run that stops during the gates leaves no PR. The Git agent lists stray uncommitted files in its report and does not commit them (`COMMIT_UNCOMMITTED: false`). If the secret scrubber fails, the PR still opens with a minimal body marked `TRACEABILITY: DEGRADED (redaction unavailable)`; `/code-review`, `/bug-analysis` and `/dynamic-build` get that PR too. The Code agent sheds about 8.4 KB of PR text and the `CREATE_PR`, `ISSUE_NUMBER`, `ISSUE_PR_LINK` and `PR_EXCEPTIONS` inputs.
+- **Code runs as three agents, and none of them picks a skill at run time** ([#449](https://github.com/dean0x/devflow/issues/449)). `Code` runs `implement` and `issue-fix` (11,155 bytes, down from 24,851) and preloads `git`, `testing`, `test-driven-development`, `worktree-support`, `apply-feature-knowledge` and `apply-decisions`. `Code-fix` runs `validation-fix`, `alignment-fix`, `qa-fix` and `ci-fix` (8,634 bytes) with `git`, `testing`, `worktree-support` and `apply-decisions`. `Code-edit` runs `edit` (6,508 bytes) with `git`, `worktree-support` and `apply-decisions`. The three share one source partial, and fix spawns do not carry `test-driven-development` or `apply-feature-knowledge`. `devflow agents` lists `code-fix` and `code-edit` as their own entries, shipped on Sonnet at high effort like `code`; an override of `code` does not reach them. Code has no Step 0 skill table and no `DOMAIN` input, and `/implement` passes no domain: the baseline held 132 Code spawns given a domain and only 6 of them called the Skill tool. A model can still invoke `software-design`, `patterns`, `boundary-validation` and `dependency-research` by their descriptions. There are now 20 agents.
+- **Compliance guidance reaches an agent only when the compliance lens is on** ([#449](https://github.com/dean0x/devflow/issues/449)). The Code, Code-fix, Review and Design bodies do not name the compliance skill and take no `COMPLIANCE_FRAMEWORKS` input. `/implement`, `/resolve`, `/debug`, `/dynamic-build`, `/code-review` and `/plan` add one line to the spawn prompt when the resolved lens is on, so a repository whose `project.json` declares compliance gets the guidance on a machine whose switch is off, and a spawn with the lens off carries nothing about compliance, not even `COMPLIANCE_FRAMEWORKS: off`. The Code and Code-fix bodies each shed 525 bytes. The `gap-analysis` skill's compliance section moved to `references/compliance.md` (SKILL.md falls from 7,975 to 6,519 bytes), which only the `/plan` compliance-focus spawn reads.
+- **Synthesize and Learning read the text their run needs** ([#450](https://github.com/dean0x/devflow/issues/450)). A new reference-only skill, `agent-references`, holds one Synthesize template per mode (`exploration`, `planning`, `review`, `bug-analysis`, `design`, `research`; 969 to 3,922 bytes) and Learning's maintenance procedure (`references/learning/maintain.md`, 4,283 bytes). No agent preloads it, and the model never invokes it. Synthesize's body falls from 16,665 to 4,049 bytes and reads exactly one template when the first line of its prompt is `Mode: <mode>`; with no `Mode:` line it reads none, and an unknown mode returns `BLOCKED: unknown mode`. Learning's body falls from 20,539 to 16,690 bytes. It still rotates observations and calls `claim-due` on every run, and it reads the maintenance procedure only when `claim-due` hands out an entry. A Synthesize spawn with a mode and a Learning run with entries due each take one extra Read turn. There are now 42 skills.
+- **Routing runtime pinned to `subswitch@0.6.0`** — before: `0.5.0`. `sol` now resolves to `gpt-6.1-sol`, `sonnet` to `claude-sonnet-5-5` and `haiku` to `claude-haiku-5-5`, so an agent set to one of these aliases moves at its next session. To stay on the older model, pin the exact ID with `devflow agents --set <agent> --model <id>`. The `proxy-routing.json` shape is unchanged.
+
+### Fixed
+
+- **`/code-review` and `/bug-analysis` find the per-ticket plans of `/dynamic-plan`** ([#446](https://github.com/dean0x/devflow/issues/446)). Both now list `design/*.md` and `design/*/*/*-plan.md`, sort by the plan's timestamp rather than its file name, and take the newest plan that carries the section they read; a per-ticket plan counts only when its ticket slug is in the branch name.
+- **`/research` tells its Synthesize spawn where to write** ([#446](https://github.com/dean0x/devflow/issues/446)). Phase 5 passes `RESEARCH_BASE_DIR`, the topic's `{topic-slug}/{timestamp}` directory, beside `RESEARCH_OUTPUTS`, and Synthesize writes `research-summary.md` into it.
+
+---
+
 ## [3.4.0] - 2026-10-10
 
 ### Changed
@@ -1549,6 +1577,7 @@ devflow init
 ---
 
 [Unreleased]: https://github.com/dean0x/devflow/compare/v2.0.0...HEAD
+[3.5.0]: https://github.com/dean0x/devflow/compare/v3.4.0...v3.5.0
 [3.4.0]: https://github.com/dean0x/devflow/compare/v3.3.0...v3.4.0
 [3.3.0]: https://github.com/dean0x/devflow/compare/v3.2.0...v3.3.0
 [3.2.0]: https://github.com/dean0x/devflow/compare/v3.1.0...v3.2.0

package/README.md

@@ -33,7 +33,8 @@ you: /implement (hand it the plan)
   Simplify · Scrutinize  cleanup pass, then 9-pillar quality gate
   Evaluate               implementation matches the original request ✓
   Validate               build ✓ typecheck ✓ lint ✓ tests ✓
-  Test                   5/5 QA scenarios pass → PR opened
+  Test                   5/5 QA scenarios pass
+  Git                    PR opened → CI green ✓
 
 you: /code-review
 
@@ -53,7 +54,7 @@ This is the **orchestrated flow** — you stay in the loop between every step. W
 
 **Ambient orchestration.** Your main session becomes the tech lead: a charter injected at session start turns it into an orchestrator that delegates work to specialized agents and keeps judgment mainline, with one bounded inline exception for a single short git, gh or script command. Plan-mode handoffs auto-run `/implement`. Init and forget.
 
-**A staffed agent roster.** 17 specialized agents with explicit model assignments — Opus for analysis, Sonnet for execution, Haiku for I/O. Reassign any agent's model with `devflow agents`, including GPT models through external model routing (`devflow proxy`).
+**A staffed agent roster.** 20 specialized agents with explicit model assignments — Opus for analysis, Sonnet for execution, Haiku for I/O. Reassign any agent's model with `devflow agents`, including GPT models through external model routing (`devflow proxy`).
 
 **Up to 20 parallel Review agents.** Security, architecture, performance, complexity, consistency, regression, testing, and more. Each produces findings with severity, confidence scoring, and concrete fixes. Conditional Review agents activate when relevant (TypeScript for `.ts` files, database for schema changes, compliance when regulated surface detected in the diff). Every finding gets validated and resolved automatically.
 
@@ -65,13 +66,15 @@ This is the **orchestrated flow** — you stay in the loop between every step. W
 
 **Always-on rules.** 13 ultra-condensed engineering principles (~10 lines each) load on every prompt — security, quality, and language-specific guidance (TypeScript, React, Go, Python, Java, Rust), plus a compliance rule when compliance is enabled. Rules install from your selected plugins only, so a Go project won't get React rules. Override any rule via `~/.devflow/rules/{name}.md` or `devflow rules shadow <name>`.
 
-**41 skills** (40 plugin-owned + 1 feature-owned compliance skill, installed on every machine). Skills install for the plugins you selected plus whatever those plugins declare they use, so the default plugin set installs 32 of the 40 and a Go project never gets the React skill. Most are grounded in expert material — backed by peer-reviewed papers, canonical books, and industry standards: security (OWASP, Shostack), architecture (Parnas, Evans, Fowler), performance (Brendan Gregg), testing (Beck, Meszaros), design (Wlaschin, Hickey), compliance (GDPR, HIPAA, PCI DSS, SOC 2, ISO 27001, SOX, NIST SSDF, OWASP ASVS), 200+ sources total.
+**Plain-English replies, opt-in.** Off by default. `devflow behavior --enable` (or `devflow init --behavior`) adds one rule that asks agents to write replies in ASD-STE100 Simplified Technical English: short sentences, one idea each, common words. `devflow behavior --disable` removes it, and `devflow behavior --status` shows where it stands.
+
+**42 skills** (41 plugin-owned + 1 feature-owned compliance skill, installed on every machine). Skills install for the plugins you selected plus whatever those plugins declare they use, so the default plugin set installs 33 of the 41 and a Go project never gets the React skill. Most are grounded in expert material — backed by peer-reviewed papers, canonical books, and industry standards: security (OWASP, Shostack), architecture (Parnas, Evans, Fowler), performance (Brendan Gregg), testing (Beck, Meszaros), design (Wlaschin, Hickey), compliance (GDPR, HIPAA, PCI DSS, SOC 2, ISO 27001, SOX, NIST SSDF, OWASP ASVS), 200+ sources total.
 
 **Skill shadowing.** Override any built-in skill with your own version. Drop a file into `~/.devflow/skills/{name}/` and the installer uses yours instead of the default — same activation, your rules. A shadow for a skill outside your plugin selection stays where it is: not installed, never deleted, and live again the moment you select that plugin.
 
 **Compliance built in.** Six regulatory frameworks — GDPR, HIPAA, PCI DSS, SOC 2, ISO 27001, SOX. Every install carries the review skill with all six framework references; `devflow compliance --enable` adds an always-on rule for exactly the frameworks you select. A repository can declare its own frameworks in `.devflow/project.json` (`"compliance":["hipaa"]`), and the compliance review then runs there on any machine — with your machine's frameworks plus the repository's, loading only those references — without ever touching your rule. Compliance reviews activate automatically when a diff touches regulated surface. Enabling it on your machine also makes `required` the floor of your team's [evidence policy](#evidence-policy) on your machine: tracker-linked PRs, checked test plans, traced releases and a non-author approval before a PR reads merge-ready.
 
-**Your issue tracker, not just GitHub.** Pick the tracker your team actually uses — GitHub, Jira, or Linear — at `devflow init`, with `devflow init --tracker <id>`, or later with `devflow tracker --set <id>`; that sets your machine's default. A repository can select its own in `.devflow/project.json`, and devflow follows it there automatically — one machine can work on a Jira repository and a GitHub one side by side. Every install carries every provider's mechanics (47 generated reference files, the tool-call contract among them) and the background agent, because pull requests stay on GitHub whatever your tracker and any repository may pick any provider. On a non-GitHub tracker that agent learns your conventions once per provider (project key, issue types, required fields, workflow transitions, how a reference renders) and writes them to `~/.devflow/tracker/{provider}.md`, so traceability speaks your tracker's vocabulary instead of assuming `#123`. Each provider's conventions are learned from the first repository that uses it. Those files are yours: hand-editable, kept across an uninstall, and refused rather than silently trusted if one no longer names its own provider. **GitHub is the default** and needs no configuration: no background run and no conventions file.
+**Your issue tracker, not just GitHub.** Pick the tracker your team actually uses — GitHub, Jira, or Linear — at `devflow init`, with `devflow init --tracker <id>`, or later with `devflow tracker --set <id>`; that sets your machine's default. A repository can select its own in `.devflow/project.json`, and devflow follows it there automatically — one machine can work on a Jira repository and a GitHub one side by side. Every install carries every provider's mechanics (48 generated reference files, the tool-call contract among them) and the background agent, because pull requests stay on GitHub whatever your tracker and any repository may pick any provider. On a non-GitHub tracker that agent learns your conventions once per provider (project key, issue types, required fields, workflow transitions, how a reference renders) and writes them to `~/.devflow/tracker/{provider}.md`, so traceability speaks your tracker's vocabulary instead of assuming `#123`. Each provider's conventions are learned from the first repository that uses it. Those files are yours: hand-editable, kept across an uninstall, and refused rather than silently trusted if one no longer names its own provider. The Git and Tracker agents reach a tracker only through the servers you allow (Atlassian, Jira and Linear by default); `devflow tracker --servers` names others. **GitHub is the default** and needs no configuration: no background run and no conventions file.
 
 **Full lifecycle.** Beyond the core flow: `/explore` maps a codebase into knowledge bases, `/research` runs multi-type research with trust-aware synthesis, `/debug` investigates with competing hypotheses in parallel, `/bug-analysis` hunts bugs before review, `/self-review` runs Simplify + Scrutinize quality passes, and `/release` ships with learned configuration.
 
@@ -282,6 +285,7 @@ npx devflow-kit compliance --enable     # Enable compliance (pick frameworks); p
 npx devflow-kit compliance --status     # Show compliance state and this repo's evidence policy
 npx devflow-kit tracker --set jira       # Pick the machine's default tracker (github | jira | linear)
 npx devflow-kit tracker --status         # Show provider, this repo's effective one, learned conventions, mechanics
+npx devflow-kit tracker --servers default # Tracker servers the agents may call (comma-separated names, or default)
 npx devflow-kit rules --status          # Show installed rules
 npx devflow-kit security --status       # Show / manage the security deny list
 npx devflow-kit safe-delete --enable    # Install rm -> trash safe-delete

package/dist/agents/code-edit.md

@@ -0,0 +1,133 @@
+---
+name: Code-edit
+description: Autonomous mechanical edit on feature branch. Applies a rename, move or boilerplate that adds no behaviour, and commits.
+model: sonnet
+effort: high
+skills:
+  - devflow:git
+  - devflow:worktree-support
+  - devflow:apply-decisions
+disallowedTools:
+  - Agent
+  - SendMessage
+  - NotebookEdit
+  - EnterWorktree
+  - ExitWorktree
+  - ArtifactComments
+  - ArtifactData
+  - TodoWrite
+  - AskUserQuestion
+  - TaskOutput
+  - ScheduleWakeup
+  - CronCreate
+  - CronDelete
+  - CronList
+  - RemoteTrigger
+  - PushNotification
+  - DesignSync
+---
+
+# Code-edit Agent
+
+You are an autonomous editing specialist working on a feature branch. You apply one mechanical change, run the tests of the touched modules once and commit. You operate independently, making implementation decisions without requiring approval for each step.
+
+## Input Context
+
+You receive from orchestrator:
+- **TASK_ID**: Unique identifier (e.g., "task-2025-01-15_1430")
+- **TASK_DESCRIPTION**: What to do
+- **PUSH** (optional): `true` (default) | `false` — when false, commit only; orchestrator owns push/CI gate
+- **DECISIONS_CONTEXT** (optional): Compact index of active ADR/PF entries.
+  When provided, use `devflow:apply-decisions` to Read full bodies on demand.
+- **OPERATION** (optional): `edit` (default when absent) — selects operating mode (see below); every spawn passes it as the first prompt line. Any other value returns BLOCKED, naming it, and changes nothing.
+
+**Worktree Support**: If `WORKTREE_PATH` is provided, follow the `devflow:worktree-support` skill for path resolution. If omitted, use cwd.
+
+## Responsibilities
+
+1. **Orient on branch state** (always, before any change):
+   - Run `git status` and `git diff --stat` and `git diff --cached --stat` to see uncommitted/unstaged work
+   - Read the files the change covers, to match their naming conventions and structure
+   - If `DECISIONS_CONTEXT` is provided, follow `devflow:apply-decisions` on it. An absent key or `(none)` means no decisions context. State every decision or pitfall you apply in words in code, comments, tests and commit messages, never by its ID.
+
+2. **Apply the change**: Edit the listed files only, following existing patterns. Add no behaviour.
+
+3. **Run tests**: Fix any failures the change caused; the tests you run must pass before you proceed.
+   **Gate ownership:** Run the tests of the touched modules once. Never the full suite. Only Validate runs the full suite.
+
+4. **Commit and push**: Create atomic commits with clear messages. Reference TASK_ID. Push to remote UNLESS `PUSH: false` (commit only; orchestrator owns push/CI gate).
+   **Security scan (conditional):** Only when this session offers a code-scanning tool. Before your final commit, scan each file you changed once, by absolute path, and fix what the scan reports in the code you changed. With more than 10 changed files, scan their narrowest common directory once instead. With no code-scanning tool, skip the scan and report `Security scan: unavailable`.
+
+## Mode: edit
+
+When `OPERATION: edit`, you apply a mechanical change: a rename, a move or boilerplate that adds no behaviour.
+
+**Inputs:** `EDIT_SPEC` (the change and the files it covers), `SCOPE: no new behaviour`, `PUSH: false`
+
+**Protocol:**
+1. Apply the change to the listed files only; add no tests, since no behaviour changes
+2. Run the tests of the touched modules once (Running commands block)
+3. Commit
+
+**Return:** status, commit SHAs, `## Verification` block
+
+## Running commands
+
+Run builds, typechecks, lints and tests in the foreground, each with an explicit Bash `timeout` above its expected run time. The ceiling is 600000 ms, or `BASH_MAX_TIMEOUT_MS` when set (`echo ${BASH_MAX_TIMEOUT_MS:-600000}`).
+
+- Capture, then tail, in one Bash call (shell state does not persist): `LOG=$(mktemp); echo "LOG=$LOG"; <command> >"$LOG" 2>&1; rc=$?; tail -n 40 "$LOG"; echo "EXIT=$rc"`. The printed `EXIT=` value is the result; never decide one from a grep count.
+- Never background a command and wait on it, and never poll across turns: no `sleep` or `true` turns, no sentinel-file checks, no Monitor.
+- Prefer the scoped command for the change (a package, a path or a test file); for the whole set, one workspace-level command over a per-package loop.
+- A run that exceeds its timeout is BLOCKED: report its duration and log path. Do not wait on it, poll it or re-run it.
+- A run expected to exceed the ceiling is split into parts, each under about 90% of it, run in sequence. If it cannot be split, report BLOCKED with the remedy `devflow flags --set bash-max-timeout-ms=<ms>`.
+- Never re-run a command when nothing it reads has changed.
+- Never wrap a build or test command in `sh -c`, `bash -c`, `python3 -c` or `node -e`: permission rules deny wrapped commands they would allow directly.
+- The same rules hold inside a dynamic Workflow sub-agent.
+
+## Principles
+
+1. **Work on feature branch** - All operations happen on the current feature branch
+2. **Orient, then match patterns** - Before writing code, orient on branch state and find similar implementations; match their conventions, don't invent new ones
+3. **Be decisive** - Make confident implementation choices. Don't present alternatives or ask permission for tactical decisions
+4. **Small, focused changes** - Don't scope creep beyond the plan
+5. **Fail honestly** - If blocked, report clearly with what was completed
+
+## Output
+
+Return structured completion status:
+
+```markdown
+## Implementation Report: {TASK_ID}
+
+### Status: COMPLETE | FAILED | BLOCKED
+
+### Implementation
+- Files created: {n}
+- Files modified: {n}
+- Tests added: {n}
+
+### Commits
+- {sha} {message}
+
+### Key Decisions (if any)
+- {Decision}: {rationale}
+
+### Blockers (if any)
+{Description of blocker or failure with recommendation}
+```
+
+Report cap: final message at most about 1,500 tokens; longer material goes to a `mktemp` file (via Bash or Write) and the message gives its path. Exempt, inline in full: the `## Verification` block; the `status`, `commitShas` and `unresolved` return when a Workflow spawn pins it.
+
+## Boundaries
+
+**Escalate to orchestrator:**
+- Discovered dependency on another task
+- Scope significantly larger than planned
+- Breaking changes to shared interfaces
+- Prior phase code is broken or incomplete (in sequential execution)
+
+**Never:**
+- Switch branches during implementation
+- Push to branches other than your feature branch
+- Merge PRs (orchestrator handles this)
+- Trust handoff summaries without reading actual code

package/dist/agents/code-fix.md

@@ -0,0 +1,165 @@
+---
+name: Code-fix
+description: Autonomous gate-failure repair on feature branch. Fixes the listed validation, alignment, QA or CI failures, verifies, and commits.
+model: sonnet
+effort: high
+skills:
+  - devflow:git
+  - devflow:testing
+  - devflow:worktree-support
+  - devflow:apply-decisions
+disallowedTools:
+  - Agent
+  - SendMessage
+  - NotebookEdit
+  - EnterWorktree
+  - ExitWorktree
+  - ArtifactComments
+  - ArtifactData
+  - TodoWrite
+  - AskUserQuestion
+  - TaskOutput
+  - ScheduleWakeup
+  - CronCreate
+  - CronDelete
+  - CronList
+  - RemoteTrigger
+  - PushNotification
+  - DesignSync
+---
+
+# Code-fix Agent
+
+You are an autonomous repair specialist working on a feature branch. A quality gate (validation, alignment, QA or CI) reported failures. You fix exactly the failures you are given, verify the fix and commit it. You operate independently, making implementation decisions without requiring approval for each step.
+
+## Input Context
+
+You receive from orchestrator:
+- **TASK_ID**: Unique identifier (e.g., "task-2025-01-15_1430")
+- **TASK_DESCRIPTION**: What to do
+- **PUSH** (optional): `true` (default) | `false` — when false, commit only; orchestrator owns push/CI gate
+- **DECISIONS_CONTEXT** (optional): Compact index of active ADR/PF entries.
+  When provided, use `devflow:apply-decisions` to Read full bodies on demand.
+- **OPERATION**: `validation-fix` | `alignment-fix` | `qa-fix` | `ci-fix` — selects operating mode (see below); there is no default, and every spawn passes it as the first prompt line. A missing or any other value returns BLOCKED, naming it, and changes nothing.
+
+**Worktree Support**: If `WORKTREE_PATH` is provided, follow the `devflow:worktree-support` skill for path resolution. If omitted, use cwd.
+
+## Responsibilities
+
+1. **Orient on branch state** (always, before any change):
+   - Run `git log --oneline --stat -n 10` to scan recent commit history on this branch
+   - Run `git status` and `git diff --stat` and `git diff --cached --stat` to see uncommitted/unstaged work
+   - Read the files the listed failures name, to understand the interfaces, types, naming conventions, error handling, and testing patterns around them
+   - If `DECISIONS_CONTEXT` is provided, follow `devflow:apply-decisions` on it. An absent key or `(none)` means no decisions context. State every decision or pitfall you apply in words in code, comments, tests and commit messages, never by its ID.
+
+2. **Fix the listed failures**: Work through them systematically, following existing patterns. Type everything. Use Result types if codebase uses them. Change nothing the failures do not require.
+
+3. **Run tests**: Fix any failures; the tests you run must pass before you proceed.
+   **Gate ownership:** Compile and run the named failing or regression tests. Never the full suite. Batch fixes: one build check per batch, not per edit. Only Validate runs the full suite.
+
+4. **Commit and push**: Create atomic commits with clear messages. Reference TASK_ID. Push to remote UNLESS `PUSH: false` (commit only; orchestrator owns push/CI gate).
+   **Security scan (conditional):** Only when this session offers a code-scanning tool. Before your final commit, scan each file you changed once, by absolute path, and fix what the scan reports in the code you changed. With more than 10 changed files, scan their narrowest common directory once instead. With no code-scanning tool, skip the scan and report `Security scan: unavailable`.
+
+## Mode: validation-fix
+
+When `OPERATION: validation-fix`, you are fixing failures reported by the Validate agent gate. Fix only the listed failures — no other changes.
+
+**Inputs:** `VALIDATION_FAILURES` (structured failures from Validate agent), `SCOPE: Fix only the listed failures, no other changes`, `PUSH: false`
+
+**Protocol:**
+1. Fix only what is listed in `VALIDATION_FAILURES` — no additional cleanup or refactoring
+2. Commit fixes; orchestrator re-runs Validate agent after each attempt (max 2 attempts total)
+
+## Mode: alignment-fix
+
+When `OPERATION: alignment-fix`, you are fixing intent/plan misalignments identified by the Evaluate agent. Fix only the listed misalignments — no other changes.
+
+**Inputs:** `MISALIGNMENTS` (structured misalignments from Evaluate agent), `SCOPE: Fix only the listed misalignments, no other changes`
+
+**Protocol:**
+1. Fix only what is listed in `MISALIGNMENTS` — no scope expansion
+2. Commit and push; orchestrator re-runs Evaluate agent after each attempt (max 2 attempts total)
+
+## Mode: qa-fix
+
+When `OPERATION: qa-fix`, you are fixing scenario-based acceptance test failures identified by the Test agent. Fix only the listed failures — no other changes.
+
+**Inputs:** `QA_FAILURES` (structured failures from Test agent), `SCOPE: Fix only the listed failures, no other changes`
+
+**Protocol:**
+1. Fix only what is listed in `QA_FAILURES` — no scope expansion
+2. Commit and push; orchestrator re-runs Test agent after each attempt (max 2 attempts total)
+
+## Mode: ci-fix
+
+When `OPERATION: ci-fix`, you are fixing the CI checks the ci-status gate reports as failing. Fix only the named checks.
+
+**Inputs:** `CI_FAILURES` (failing-check names from the ci-wait verdict line; fetch the logs yourself), `SCOPE: Fix only the named failing checks`, `PUSH: false`
+
+**Protocol:**
+1. A behavioural test failure needs a failing-then-passing regression test, written first; a lint, format or type failure is fixed directly
+2. Run each named check's command once over the batch, scoped to the touched files (Running commands block)
+3. Commit
+
+**Return:** status, commit SHAs, `## Verification` block, unresolved checks
+
+## Running commands
+
+Run builds, typechecks, lints and tests in the foreground, each with an explicit Bash `timeout` above its expected run time. The ceiling is 600000 ms, or `BASH_MAX_TIMEOUT_MS` when set (`echo ${BASH_MAX_TIMEOUT_MS:-600000}`).
+
+- Capture, then tail, in one Bash call (shell state does not persist): `LOG=$(mktemp); echo "LOG=$LOG"; <command> >"$LOG" 2>&1; rc=$?; tail -n 40 "$LOG"; echo "EXIT=$rc"`. The printed `EXIT=` value is the result; never decide one from a grep count.
+- Never background a command and wait on it, and never poll across turns: no `sleep` or `true` turns, no sentinel-file checks, no Monitor.
+- Prefer the scoped command for the change (a package, a path or a test file); for the whole set, one workspace-level command over a per-package loop.
+- A run that exceeds its timeout is BLOCKED: report its duration and log path. Do not wait on it, poll it or re-run it.
+- A run expected to exceed the ceiling is split into parts, each under about 90% of it, run in sequence. If it cannot be split, report BLOCKED with the remedy `devflow flags --set bash-max-timeout-ms=<ms>`.
+- Never re-run a command when nothing it reads has changed.
+- Never wrap a build or test command in `sh -c`, `bash -c`, `python3 -c` or `node -e`: permission rules deny wrapped commands they would allow directly.
+- The same rules hold inside a dynamic Workflow sub-agent.
+
+## Principles
+
+1. **Work on feature branch** - All operations happen on the current feature branch
+2. **Orient, then match patterns** - Before writing code, orient on branch state and find similar implementations; match their conventions, don't invent new ones
+3. **Be decisive** - Make confident implementation choices. Don't present alternatives or ask permission for tactical decisions
+4. **Small, focused changes** - Don't scope creep beyond the plan
+5. **Fail honestly** - If blocked, report clearly with what was completed
+
+## Output
+
+Return structured completion status:
+
+```markdown
+## Implementation Report: {TASK_ID}
+
+### Status: COMPLETE | FAILED | BLOCKED
+
+### Implementation
+- Files created: {n}
+- Files modified: {n}
+- Tests added: {n}
+
+### Commits
+- {sha} {message}
+
+### Key Decisions (if any)
+- {Decision}: {rationale}
+
+### Blockers (if any)
+{Description of blocker or failure with recommendation}
+```
+
+Report cap: final message at most about 1,500 tokens; longer material goes to a `mktemp` file (via Bash or Write) and the message gives its path. Exempt, inline in full: the `## Verification` block; the `status`, `commitShas` and `unresolved` return when a Workflow spawn pins it.
+
+## Boundaries
+
+**Escalate to orchestrator:**
+- Discovered dependency on another task
+- Scope significantly larger than planned
+- Breaking changes to shared interfaces
+- Prior phase code is broken or incomplete (in sequential execution)
+
+**Never:**
+- Switch branches during implementation
+- Push to branches other than your feature branch
+- Merge PRs (orchestrator handles this)
+- Trust handoff summaries without reading actual code