@kontourai/flow-agents 0.1.1

package/kits/catalog.json

@@ -0,0 +1,11 @@
+{
+  "schema_version": "1.0",
+  "kits": [
+    {
+      "id": "builder",
+      "name": "Builder Kit",
+      "path": "kits/builder",
+      "description": "Flow-backed shaping, planning, build, verification, merge readiness, pull request readiness, and learning workflows."
+    }
+  ]
+}

package/package.json

@@ -0,0 +1,130 @@
+{
+  "name": "@kontourai/flow-agents",
+  "version": "0.1.1",
+  "description": "Flow Agents — a Kontour product that applies Flow and Veritas discipline inside the agent tools you already use: Claude Code, Codex, Kiro, and GitHub Actions.",
+  "keywords": [
+    "agents",
+    "ai-agents",
+    "workflow",
+    "skills",
+    "claude-code",
+    "codex",
+    "kiro",
+    "evidence",
+    "process-transparency"
+  ],
+  "license": "Apache-2.0",
+  "publishConfig": {
+    "access": "public"
+  },
+  "type": "module",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/kontourai/flow-agents.git"
+  },
+  "engines": {
+    "node": ">=22"
+  },
+  "bin": {
+    "flow-agents": "build/src/cli.js",
+    "flow-agents-build-bundles": "build/src/cli.js",
+    "flow-agents-console-learning-projection": "build/src/cli.js",
+    "flow-agents-context-map": "build/src/cli.js",
+    "flow-agents-effective-backlog-settings": "build/src/cli.js",
+    "flow-agents-filter-installed-packs": "build/src/cli.js",
+    "flow-agents-flow-kit": "build/src/cli.js",
+    "flow-agents-fixture-retirement-audit": "build/src/cli.js",
+    "flow-agents-promote-workflow-artifact": "build/src/cli.js",
+    "flow-agents-publish-change": "build/src/cli.js",
+    "flow-agents-pull-work-provider": "build/src/cli.js",
+    "flow-agents-runtime-adapter": "build/src/cli.js",
+    "flow-agents-telemetry-doctor": "build/src/cli.js",
+    "flow-agents-usage-feedback": "build/src/cli.js",
+    "flow-agents-veritas-governance": "build/src/cli.js",
+    "flow-agents-validate-artifacts": "build/src/cli/validate-workflow-artifacts.js",
+    "flow-agents-validate-hook-influence": "build/src/cli.js",
+    "flow-agents-validate-source": "build/src/cli.js",
+    "flow-agents-workflow-artifact-cleanup-audit": "build/src/cli.js",
+    "flow-agents-workflow-sidecar": "build/src/cli/workflow-sidecar.js"
+  },
+  "files": [
+    ".github/",
+    ".githooks/",
+    "AGENTS.md",
+    "CHANGELOG.md",
+    "CODE_OF_CONDUCT.md",
+    "CONTEXT.md",
+    "CONTRIBUTING.md",
+    "SECURITY.md",
+    "agent-cards/",
+    "agents/",
+    "build/",
+    "console.telemetry.json",
+    "context/",
+    "docs/",
+    "evals/",
+    "install.sh",
+    "integrations/",
+    "kits/",
+    "packaging/",
+    "powers/",
+    "prompts/",
+    "schemas/",
+    "scripts/",
+    "skills/",
+    "src/",
+    "tsconfig.json",
+    "veritas.claims.json",
+    "!evals/cases/dev/node_modules/",
+    "!evals/results/",
+    "!**/.DS_Store",
+    "!**/.flow-agents/",
+    "!**/.surface/",
+    "!**/.telemetry/",
+    "!**/.veritas/",
+    "!**/node_modules/"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "validate:source": "npm run build --silent && node build/src/cli.js validate-source",
+    "validate:artifacts": "npm run build --silent && node build/src/cli/validate-workflow-artifacts.js",
+    "context-map": "npm run build --silent && node build/src/cli.js context-map",
+    "context-map:check": "npm run build --silent && node build/src/cli.js context-map --check",
+    "build:bundles": "npm run build --silent && node build/src/cli.js build-bundles",
+    "filter:packs": "npm run build --silent && node build/src/cli.js filter-installed-packs",
+    "validate:package": "npm run build --silent && node build/src/cli.js validate-package",
+    "workflow:sidecar": "npm run build --silent && node build/src/cli/workflow-sidecar.js",
+    "workflow:validate-artifacts": "npm run build --silent && node build/src/cli/validate-workflow-artifacts.js",
+    "flow-kit": "npm run build --silent && node build/src/cli.js flow-kit",
+    "effective-backlog-settings": "npm run build --silent && node build/src/cli.js effective-backlog-settings",
+    "pull-work-provider": "npm run build --silent && node build/src/cli.js pull-work-provider",
+    "publish-change": "npm run build --silent && node build/src/cli.js publish-change",
+    "promote-workflow-artifact": "npm run build --silent && node build/src/cli.js promote-workflow-artifact",
+    "usage-feedback": "npm run build --silent && node build/src/cli.js usage-feedback",
+    "runtime-adapter": "npm run build --silent && node build/src/cli.js runtime-adapter",
+    "telemetry-doctor": "npm run build --silent && node build/src/cli.js telemetry-doctor",
+    "veritas-governance": "npm run build --silent && node build/src/cli.js veritas-governance",
+    "validate:hook-influence": "npm run build --silent && node build/src/cli.js validate-hook-influence",
+    "workflow-artifact-cleanup-audit": "npm run build --silent && node build/src/cli.js workflow-artifact-cleanup-audit",
+    "fixture:retirement-audit": "npm run build --silent && node build/src/cli.js fixture-retirement-audit",
+    "setup:repo-hooks": "bash scripts/setup-repo-hooks.sh",
+    "validate:repo-hooks": "bash evals/static/test_repo_hooks.sh",
+    "eval": "bash evals/run.sh",
+    "eval:static": "bash evals/run.sh static",
+    "eval:integration": "bash evals/run.sh integration",
+    "eval:acceptance": "bash evals/run.sh acceptance",
+    "eval:llm": "bash evals/run.sh llm",
+    "eval:llm:codex": "bash evals/run.sh llm dev --runtime codex",
+    "eval:llm:claude": "bash evals/run.sh llm dev --runtime claude --judge-runtime codex",
+    "promptfoo": "PROMPTFOO_CONFIG_DIR=.promptfoo PROMPTFOO_DISABLE_WAL_MODE=true PROMPTFOO_DISABLE_TELEMETRY=true promptfoo",
+    "promptfoo:view": "PROMPTFOO_CONFIG_DIR=.promptfoo PROMPTFOO_DISABLE_WAL_MODE=true PROMPTFOO_DISABLE_TELEMETRY=true promptfoo view",
+    "check:content-boundary": "node scripts/check-content-boundary.cjs",
+    "prepack": "npm run build --silent && npm run validate:source --"
+  },
+  "devDependencies": {
+    "@types/node": "^22.19.19",
+    "promptfoo": "^0.121.15",
+    "typescript": "^6.0.3"
+  }
+}

package/packaging/README.md

@@ -0,0 +1,60 @@
+# Universal Packaging
+
+This directory defines the cross-harness packaging layer for Flow Agents.
+
+## Canonical Source
+
+The repo root stays canonical:
+
+- `agents/` contains source Kiro-style agent specs: the `dev` workflow surface plus specialist `tool-*` agents.
+- `agent-cards/` contains discovery metadata for routable orchestrators.
+- `skills/`, `context/`, `powers/`, `prompts/`, `scripts/`, and `evals/` remain shared content.
+- `src/` contains TypeScript CLI, runtime adapter, packaging, validation, context-map, and repository tooling source that compiles to `build/src/`.
+- `packaging/manifest.json` describes target-specific copy rules, profile definitions, substitutions, and model/provider mappings.
+- Generated bundles live under `dist/`, are intentionally untracked, and can be recreated at any time.
+
+For the full source/generated/runtime inventory, see [Repository Structure](../docs/repository-structure.md).
+
+## Targets
+
+- `dist/kiro/` keeps native Kiro JSON agents and rewrites path-bound config through the install token.
+- `dist/claude-code/` exports `.claude/agents/*.md` and `.claude/skills/*/SKILL.md`.
+- `dist/codex/` exports `.codex/agents/*.toml`, `.codex/skills/*/SKILL.md`, and profile config for `kdev` and its Bedrock variant.
+
+All targets also receive shared canonical directories where supported: `context/`, `powers/`, `prompts/`, `scripts/`, and `evals/`.
+
+`docs/` and `evals/` are intentionally included in generated bundles today. `docs/` gives installed agents durable local reference material, and `evals/` provides install-time and runtime smoke tests for the exported bundle. If bundle size becomes a product constraint, prune these through `packaging/manifest.json` and update install tests rather than deleting generated output by hand.
+
+## Generated And Runtime Boundaries
+
+`dist/` is a generated export surface, not the source of truth. Installed runtime directories such as `.codex/` and `.claude/` are also not source. They are created from the generated target bundle and installer scripts. If generated or installed hook config is wrong, fix the canonical source, rebuild `dist/`, and reinstall the runtime config.
+
+Runtime workflow state under `.flow-agents/<slug>/` is local working memory. Packaging should copy canonical workflow contracts and skills, but it should not publish local task artifacts as product source. Durable outcomes must be promoted into docs, source, schemas, or provider records before merge.
+
+## Validation And Build
+
+Run the source validator before rebuilding:
+
+```bash
+npm run validate:source --
+```
+
+Rebuild every target bundle:
+
+```bash
+npm run build:bundles --
+```
+
+Run static package checks after rebuilding:
+
+```bash
+bash evals/run.sh static
+```
+
+For telemetry and shell integration coverage:
+
+```bash
+bash evals/run.sh integration
+```
+
+The builder is stdlib-only so the package stays dependency-free.

package/packaging/manifest.json

@@ -0,0 +1,173 @@
+{
+  "canonical_copy_dirs": [
+    "agent-cards",
+    "context",
+    "docs",
+    "evals",
+    "kits",
+    "packaging",
+    "powers",
+    "prompts",
+    "scripts",
+    "schemas",
+    "skills"
+  ],
+  "root_copy_files": [
+    "console.telemetry.json"
+  ],
+  "optional_copy_dirs": [],
+  "source_root_aliases": [
+    "~/.flow-agents",
+    "$HOME/.flow-agents"
+  ],
+  "kiro": {
+    "path_token": "__KIRO_PACKAGE_ROOT__",
+    "install_default": "~/.flow-agents"
+  },
+  "claude_code": {
+    "task_dir": ".flow-agents",
+    "permissions": {
+      "defaultMode": "auto"
+    },
+    "skipDangerousModePermissionPrompt": true
+  },
+  "codex": {
+    "task_dir": ".flow-agents",
+    "settings": {
+      "approvals_reviewer": "auto_review"
+    },
+    "tui": {
+      "status_line": [
+        "model-with-reasoning",
+        "project-name",
+        "git-branch",
+        "task-progress",
+        "context-remaining",
+        "run-state"
+      ]
+    },
+    "features": {
+      "multi_agent": true,
+      "js_repl": true,
+      "hooks": true,
+      "apps": false,
+      "plugins": false
+    },
+    "excluded_agents": [
+      "dev"
+    ],
+    "profiles": {
+      "kdev": {
+        "model": "gpt-5.5",
+        "model_reasoning_effort": "medium",
+        "approval_policy": "on-request",
+        "sandbox_mode": "workspace-write",
+        "web_search": "cached",
+        "developer_instructions": "You are operating in Flow Agents dev mode. You write and modify code, validate it works, and deliver clean results. You own the code; specialist tool-* subagents provide bounded context, review, verification, or parallel implementation support. Use deliver for feature work, fix-bug for bug fixes, plan-work for planning, execute-plan for approved plans, review-work for critique, verify-work for evidence collection, search-first for unfamiliar external APIs, and context-budget when context grows. When a workflow skill or shared contract names a delegate, that delegate is a required gate, not an optional optimization: plan-work must delegate to tool-planner, execute-plan to tool-worker, review-work to tool-code-reviewer and conditionally tool-security-reviewer, verify-work to tool-verifier, and browser/UI verification to tool-playwright when those agents are available. Attempt required delegation even in read-only or partially blocked environments; if blocked, report the blocked gate as NOT_VERIFIED or incomplete with evidence instead of replacing it with a local summary. In progress and final reports, name exact delegate ids such as tool-planner, tool-worker, tool-code-reviewer, tool-security-reviewer, tool-verifier, and tool-playwright so text-only evals remain auditable when telemetry is unavailable. In Codex, required specialist delegation must pass the role through the spawn tool, for example agent_type=tool-worker; do not spawn unnamed/default subagents for Flow Agents worker, planner, reviewer, verifier, or Playwright gates."
+      },
+      "kdev-br": {
+        "model_provider": "amazon-bedrock",
+        "model": "amazon.nova-pro-v1:0",
+        "model_reasoning_effort": "medium",
+        "approval_policy": "on-request",
+        "sandbox_mode": "workspace-write",
+        "web_search": "cached",
+        "developer_instructions": "You are operating in Flow Agents dev mode on Amazon Bedrock. You write and modify code, validate it works, and deliver clean results. You own the code; specialist tool-* subagents provide bounded context, review, verification, or parallel implementation support. Use deliver for feature work, fix-bug for bug fixes, plan-work for planning, execute-plan for approved plans, review-work for critique, verify-work for evidence collection, search-first for unfamiliar external APIs, and context-budget when context grows. When a workflow skill or shared contract names a delegate, that delegate is a required gate, not an optional optimization: plan-work must delegate to tool-planner, execute-plan to tool-worker, review-work to tool-code-reviewer and conditionally tool-security-reviewer, verify-work to tool-verifier, and browser/UI verification to tool-playwright when those agents are available. Attempt required delegation even in read-only or partially blocked environments; if blocked, report the blocked gate as NOT_VERIFIED or incomplete with evidence instead of replacing it with a local summary. In progress and final reports, name exact delegate ids such as tool-planner, tool-worker, tool-code-reviewer, tool-security-reviewer, tool-verifier, and tool-playwright so text-only evals remain auditable when telemetry is unavailable. In Codex, required specialist delegation must pass the role through the spawn tool, for example agent_type=tool-worker; do not spawn unnamed/default subagents for Flow Agents worker, planner, reviewer, verifier, or Playwright gates."
+      }
+    },
+    "model_providers": {
+      "amazon-bedrock": {
+        "aws": {
+          "region": "us-east-1"
+        }
+      }
+    }
+  },
+  "tool_name_map": {
+    "read": "Read",
+    "imageRead": "Read",
+    "code": "Edit",
+    "write": "Write",
+    "shell": "Bash",
+    "ls": "Bash",
+    "grep": "Grep",
+    "glob": "Glob",
+    "subagent": "Task",
+    "web_fetch": "WebFetch",
+    "web_search": "WebSearch"
+  },
+  "claude_model_map": {
+    "claude-opus": "opus",
+    "claude-sonnet": "sonnet",
+    "default": "sonnet"
+  },
+  "codex_model_map": {
+    "claude-opus": "gpt-5.5",
+    "claude-sonnet": "gpt-5.5",
+    "kimi-k2.5": "gpt-5.3-codex-spark",
+    "agi-nova-beta-1m": "gpt-5.4-mini",
+    "default": "gpt-5.4-mini"
+  },
+  "codex_reasoning_map": {
+    "claude-opus": "high",
+    "claude-sonnet": "low",
+    "kimi-k2.5": "low",
+    "agi-nova-beta-1m": "medium",
+    "default": "medium"
+  },
+  "target_substitutions": {
+    "common": [],
+    "claude_code": [
+      {
+        "from": "Claude Code",
+        "to": "Claude Code"
+      },
+      {
+        "from": "todo tool",
+        "to": "todo tool"
+      },
+      {
+        "from": "delegate to a specialist agent",
+        "to": "delegate to a specialist agent"
+      },
+      {
+        "from": "run shell commands",
+        "to": "run shell commands"
+      },
+      {
+        "from": "read files",
+        "to": "read files"
+      },
+      {
+        "from": "write files",
+        "to": "write files"
+      }
+    ],
+    "codex": [
+      {
+        "from": "Claude Code",
+        "to": "Codex"
+      },
+      {
+        "from": "todo tool",
+        "to": "todo tool"
+      },
+      {
+        "from": "delegate to a specialist agent",
+        "to": "delegate to a native subagent"
+      },
+      {
+        "from": "run shell commands",
+        "to": "run shell commands"
+      },
+      {
+        "from": "read files",
+        "to": "read files"
+      },
+      {
+        "from": "write files",
+        "to": "write files"
+      }
+    ]
+  }
+}

package/packaging/packs.json

@@ -0,0 +1,69 @@
+{
+  "schema_version": "1.0",
+  "packs": [
+    {
+      "name": "core",
+      "default": true,
+      "description": "Small default surface for reliable coding and workflow execution.",
+      "skills": [
+        "search-first",
+        "plan-work",
+        "execute-plan",
+        "review-work",
+        "verify-work",
+        "evidence-gate",
+        "feedback-loop",
+        "knowledge-capture",
+        "browser-test"
+      ],
+      "agents": [
+        "tool-planner",
+        "tool-worker",
+        "tool-verifier",
+        "tool-code-reviewer",
+        "tool-playwright"
+      ],
+      "powers": [
+        "playwright"
+      ]
+    },
+    {
+      "name": "development",
+      "default": false,
+      "description": "Development workflow depth for backlog, release, dependency, GitHub, TDD, and frontend work.",
+      "skills": [
+        "builder-shape",
+        "idea-to-backlog",
+        "pull-work",
+        "design-probe",
+        "pickup-probe",
+        "deliver",
+        "fix-bug",
+        "tdd-workflow",
+        "release-readiness",
+        "learning-review",
+        "dependency-update",
+        "eval-rebuild",
+        "explore",
+        "github-cli",
+        "frontend-design",
+        "agentic-engineering",
+        "context-budget"
+      ],
+      "agents": [
+        "dev",
+        "tool-dependencies-updater",
+        "tool-security-reviewer",
+        "tool-explore-config",
+        "tool-explore-deps",
+        "tool-explore-entry",
+        "tool-explore-patterns",
+        "tool-explore-structure",
+        "tool-explore-tests"
+      ],
+      "powers": [
+        "dependency-checker"
+      ]
+    }
+  ]
+}

package/powers/dependency-checker/POWER.md

@@ -0,0 +1,20 @@
+---
+name: "dependency-checker"
+displayName: "Dependency Version Checker"
+description: "Check latest versions, identify outdated packages, and find security advisories across npm, PyPI, Cargo, Maven, Go, NuGet, Ruby, PHP, Swift, Dart, Docker, Helm, Terraform, and GitHub Actions"
+keywords: ["dependencies", "outdated", "update", "upgrade", "version", "security", "advisory", "cve", "vulnerability", "npm", "pypi", "cargo", "maven", "package"]
+---
+
+# Dependency Version Checker
+
+Check package versions and security advisories across all major ecosystems.
+
+## Available Tools
+- `package-version-check` — Batch version lookups across ecosystems
+- `package-registry` — GitHub Security Advisory search
+
+## Workflow
+1. Scan project for dependency manifests (package.json, requirements.txt, Cargo.toml, etc.)
+2. Use `package-version-check` tools to batch-check versions by ecosystem
+3. Use `package-registry` to search GitHub Security Advisories for outdated packages
+4. Report grouped by risk: CRITICAL (CVEs), MAJOR (breaking), MINOR (safe updates)

package/powers/dependency-checker/mcp.json

@@ -0,0 +1,20 @@
+{
+  "mcpServers": {
+    "package-registry": {
+      "args": [
+        "package-registry-mcp"
+      ],
+      "command": "npx"
+    },
+    "package-version-check": {
+      "args": [
+        "package-version-check-mcp",
+        "--mode=stdio"
+      ],
+      "command": "uvx",
+      "env": {
+        "GITHUB_PAT": "${GITHUB_TOKEN}"
+      }
+    }
+  }
+}

package/powers/playwright/POWER.md

@@ -0,0 +1,25 @@
+---
+name: "playwright"
+displayName: "Playwright Browser"
+description: "Browser automation and testing via Playwright - load pages, test navigation, check accessibility via structured snapshots, evaluate scripts, fill forms, take screenshots"
+keywords: ["playwright", "browser", "accessibility", "dom", "screenshot", "debug", "frontend", "testing", "automation", "web"]
+---
+
+# Playwright Browser
+
+Provides browser automation and testing through Microsoft's Playwright MCP server. Uses structured accessibility snapshots instead of pixel-based approaches for efficient, LLM-friendly browser interaction.
+
+## Available Tools
+- All tools from the `playwright` MCP server (navigate, click, type, snapshot, screenshot, etc.)
+
+## When to Use
+- Loading and navigating real web pages
+- Testing frontend accessibility via structured accessibility snapshots (ARIA roles, tab order)
+- Evaluating JavaScript in a live browser context
+- Taking screenshots for visual verification
+- Filling forms, clicking buttons, testing user flows
+- Generating and validating Playwright test code
+
+## NOT For
+- General web search or fetching page content for research
+- Scraping data from websites

package/powers/playwright/mcp.json

@@ -0,0 +1,12 @@
+{
+  "mcpServers": {
+    "playwright": {
+      "args": [
+        "@playwright/mcp@latest",
+        "--headless",
+        "--isolated"
+      ],
+      "command": "npx"
+    }
+  }
+}

package/prompts/code-audit.md

@@ -0,0 +1,123 @@
+---
+name: code-audit
+description: "Iterative codebase audit. First run: broad sweep. Subsequent runs: deep dive into specific dimensions or files."
+---
+
+# Codebase Audit — {depth:broad} | Focus: {focus:all}
+
+Audit this repository at the requested depth and focus. Every finding must reference specific files and line ranges.
+
+## Depth Modes
+
+**broad** (default) — Scan the full codebase across all dimensions. Produce a summary-level report with the top findings per dimension. Don't read every file — sample key files, entry points, and the largest/most-changed modules. Goal: identify WHERE the problems are so subsequent deep dives are targeted.
+
+**deep** — Exhaustive analysis of the specified focus area. Read every relevant file. Trace call chains, map dependencies, and propose specific refactors with before/after sketches. If focus is "all", pick the highest-severity dimension from a prior broad scan and go deep on that.
+
+## Focus Areas
+
+When focus is not "all", restrict analysis to the specified dimension:
+
+- **dry** — Duplicated logic, repeated patterns, copy-pasted code, magic values that should be constants
+- **abstractions** — SRP violations, missing interfaces, tight coupling, business logic in wrong layers, god objects
+- **testability** — Hardcoded dependencies, side effects, missing DI, logic buried in framework code, test organization
+- **errors** — Swallowed exceptions, missing error handling on I/O/network, inconsistent error formats, missing retries/timeouts
+- **naming** — Misleading names, overgrown files, dead code, TODO/FIXME/HACK markers, structural inconsistencies
+- **security** — Hardcoded secrets, missing input validation, overly permissive access, sensitive data in logs
+- **dependencies** — Outdated/unused deps, missing lock files, build script complexity
+
+## Scope Narrowing
+
+{scope?}
+
+If a scope is provided above (file paths, directories, or module names), restrict the audit to those areas only. Otherwise audit the full repository.
+
+## Phase 1: Orient
+
+Before analyzing, understand the codebase:
+
+1. Map directory structure, tech stack, frameworks, languages
+2. Identify entry points (main files, API routes, CLI commands, exports)
+3. Read key config files (package.json, pyproject.toml, Cargo.toml, Dockerfile, etc.)
+4. Understand testing setup (frameworks, coverage, test locations)
+5. Check for linting/formatting config
+
+**If depth is deep**: Also read the specific files in the focus area thoroughly. Trace imports and call chains. Understand how the focused code interacts with the rest of the system.
+
+Summarize your understanding before proceeding.
+
+## Phase 2: Analyze
+
+### Broad Mode
+
+For each applicable dimension, scan for the most significant issues. Limit to 3-5 findings per dimension. For each:
+
+```
+### [Finding Title] — Severity: HIGH | MEDIUM | LOW
+
+**Files:** `path/to/file.ext` (lines X-Y)
+**Problem:** What's wrong and why it matters.
+**Recommendation:** One-line concrete fix direction.
+```
+
+### Deep Mode
+
+For the focused dimension, provide exhaustive analysis:
+
+```
+### [Finding Title] — Severity: HIGH | MEDIUM | LOW
+
+**Files:** `path/to/file.ext` (lines X-Y), `path/to/other.ext` (lines A-B)
+
+**Problem:** Detailed explanation — what's wrong, why it happened, what breaks or degrades because of it.
+
+**Current pattern:**
+[Show the actual problematic code or describe the pattern concretely]
+
+**Proposed refactor:**
+[Show the target structure — new files, interfaces, function signatures. Not full implementations, but enough to be unambiguous about the design.]
+
+**Migration path:** Steps to get from current to proposed without breaking things.
+
+**Effort:** S / M / L
+**Risk:** What could go wrong during the refactor.
+```
+
+## Phase 3: Report
+
+### Broad Mode Report
+
+1. **Heatmap** — Which dimensions have the most/worst findings? Rank them.
+2. **Top 5 highest-impact changes** — Best ROI refactors across all dimensions.
+3. **Recommended deep dive order** — Which focus area to audit next and why.
+4. **What's done well** — Patterns worth preserving.
+
+### Deep Mode Report
+
+1. **All findings** for the focused dimension, ordered by severity then effort.
+2. **Dependency graph** — How do the findings relate? Which refactors unlock others?
+3. **Suggested implementation order** — Sequence the fixes to minimize risk and maximize incremental value.
+4. **What's done well** in this dimension — patterns to extend, not just problems to fix.
+
+## Severity Guide
+
+- **HIGH** — Actively causes bugs, security issues, or makes the codebase significantly harder to maintain
+- **MEDIUM** — Creates friction, slows development, or will become a problem as the codebase grows
+- **LOW** — Cleanup opportunity, style improvement, or minor inconsistency
+
+## Rules
+
+- Be specific. "This function is too long" is useless. "This function handles parsing, validation, and persistence — split into three" is useful.
+- Don't nitpick formatting if a formatter/linter is configured — focus on logic and design.
+- Don't suggest adding tests — focus on making code testable. The user will decide when to write tests.
+- Respect the existing tech stack. Don't suggest rewrites in different languages/frameworks.
+- In broad mode, prioritize breadth over depth. In deep mode, prioritize thoroughness.
+- If you've seen a prior broad audit in this conversation, reference those findings and go deeper — don't repeat the surface-level observations.
+- If the codebase is small, say so and keep the audit proportional.
+
+## Iterative Usage
+
+Typical progression:
+1. `@code-audit` — broad sweep, identify hotspots
+2. `@code-audit deep abstractions` — deep dive into worst dimension
+3. `@code-audit deep testability src/agents/` — targeted deep dive on specific code
+4. Repeat until satisfied