@kontourai/flow-agents 0.1.1

package/skills/evidence-gate/SKILL.md

@@ -0,0 +1,186 @@
+---
+name: "evidence-gate"
+description: "Evaluate whether completed work is trustworthy enough for human review, merge, or release. Use after implementation, verify-work, provider checks, CI, or remediation to map acceptance criteria to evidence, inspect scope integrity, classify failures, assess check health, and produce a confidence report."
+---
+
+# Evidence Gate
+
+Build confidence with falsifiable evidence, not process completion.
+
+Evidence Gate is not Release Readiness. It asks whether completed work has enough trustworthy evidence, scope integrity, and provider/runtime signal to publish the change, continue fixing, or ask for a human decision. Release Readiness comes later and decides whether a published branch/provider change should merge, release, deploy, hold, or roll back.
+
+## Contract
+
+- Review evidence after implementation and verification.
+- Do not fix code.
+- Do not mark unverified work as passing.
+- Treat `NOT_VERIFIED` as a first-class outcome.
+- Separate evidence provenance: human-authored, agent-authored, CI-generated, runtime-observed.
+- Do not approve release readiness.
+- After a clean local evidence verdict, require a publish-change gate before `release-readiness`: verified diff committed, branch pushed, provider change opened or updated by the active `ChangeProvider` or an explicit no-provider-change reason recorded, closing refs recorded, provider checks known, and evidence refs linked.
+- Provider-facing summaries, PR/change descriptions, issue comments, closure comments, and final acceptance comments that claim implementation behavior must include an `Acceptance Evidence` table with columns `AC id`, `Status`, `Command/Test Evidence`, `Source Evidence / Permalinks`, and `Gaps`.
+
+## Inputs
+
+- Work brief or selected GitHub issue.
+- Execution plan.
+- Verification report.
+- Provider change / branch / check run links when available.
+- Changed-file summary.
+- Active TODOs, issue links, and release/rollback notes.
+
+## Artifact Contract
+
+Write or update `.flow-agents/<slug>/<slug>--evidence-gate.md` with:
+
+- `intent`: issue/brief, acceptance criteria, non-goals, risk class
+- `evidence_manifest`: command/check name, source, timestamp, result, link/output pointer
+- `test_map`: acceptance criterion to evidence tier and gaps
+- `integrity_report`: scope drift, weakened tests/config, sensitive files
+- `ci_report`: checks, reruns, flakes, failures, skipped checks
+- `risk_assessment`: residual risks and required human review
+- `verdict`: PASS, FAIL, or NOT_VERIFIED
+- `next_step`: publish-change, release-readiness, verify-work, execute-plan, plan-work, CI remediation, or human decision
+
+Also write or update structured sidecars:
+
+- `state.json`: phase `evidence`, current status, and required next action
+- `acceptance.json`: final criterion statuses and goal-fit status
+- `evidence.json`: normalized checks, `standard_refs`, external evidence refs, not-verified gaps, and verdict
+- `handoff.json`: next step and blockers when verdict is not a clean pass
+
+Prefer `npm run workflow:sidecar --` for sidecar updates when available, then validate the artifact directory before reporting a clean pass.
+
+## Workflow
+
+### 1. Anchor To Intent
+
+Restate:
+
+- original problem
+- acceptance criteria
+- non-goals
+- expected risk class
+- authoritative artifacts
+
+If acceptance criteria changed after implementation began, flag scope drift unless the decision is documented.
+
+### 2. Build Test Map
+
+For each acceptance criterion, map evidence to one of:
+
+- existing automated test
+- new or modified automated test
+- browser/runtime check
+- static analysis
+- CI check
+- manual/human verification
+- `NOT_VERIFIED` with rationale
+
+Block clean pass if high-risk criteria have only indirect evidence.
+Every acceptance criterion must map to evidence or `NOT_VERIFIED`.
+For implementation-behavior claims, each criterion must map to both command/test proof and structured source evidence refs. Source refs require `kind: "source"`, `file`, `line_start`, `line_end`, and `excerpt`; include immutable GitHub blob permalinks pinned to a commit SHA in `url` when a pushed commit/provider URL exists. Local file/line refs are acceptable only as pre-publish fallback evidence.
+
+Use this table shape in evidence-gate summaries and provider/closure comments:
+
+| AC id | Status | Command/Test Evidence | Source Evidence / Permalinks | Gaps |
+| --- | --- | --- | --- | --- |
+
+Rows must preserve the original AC ids. If source evidence is missing for a behavior claim, the row must say `NOT_VERIFIED` or name an accepted gap; do not issue a clean pass from prose-only claims.
+
+### 3. Scope And Integrity Check
+
+Check for process gaming or accidental drift:
+
+- scope expanded beyond issue/brief
+- acceptance criteria changed after implementation
+- tests removed or weakened
+- verification config altered
+- CI config altered
+- required CI bypassed
+- sensitive files touched without review
+
+Sensitive areas include auth, security middleware, data migrations, CI config, deployment scripts, feature flags, test helpers, lint/type config, payment, crypto, and filesystem/network operations.
+
+### 4. CI And Flake Assessment
+
+Use `github-cli` / `gh` when available.
+
+Record:
+
+- check names
+- pass/fail/skipped
+- rerun count
+- flake suspicion
+- logs or artifact links
+- failure class
+- standard evidence refs when CI emits SARIF, JUnit, TAP, OpenTelemetry, Veritas, or another native proof format
+
+For Flow Agents source changes, prefer the GitHub Actions `Flow Agents CI / Builder Kit Baseline` provider check when present. Its local equivalent is `bash evals/ci/run-baseline.sh`, which writes `evals/results/ci-baseline/summary.md` and command logs. Treat skipped live GitHub mutation checks, LLM acceptance, or unavailable Veritas/governance evidence as explicit skip or `NOT_VERIFIED` entries based on the work's risk class; do not convert the baseline summary into proof that those live lanes ran.
+
+Treat passed-after-rerun as degraded confidence unless explained.
+
+### 5. Evidence Tiers
+
+Classify evidence:
+
+- Tier 0: claim only, no artifact.
+- Tier 1: local command output.
+- Tier 2: automated test tied to acceptance criterion.
+- Tier 3: CI-confirmed test on a clean environment.
+- Tier 4: runtime/browser/production-like verification with trace or log artifact.
+- Tier 5: post-deploy telemetry confirms expected behavior.
+
+Higher-risk work requires stronger tiers.
+
+When an evidence source already has a standard format, keep that format as the native artifact and reference it from `evidence.json`:
+
+- SARIF: static analysis, security, code review, and policy findings.
+- OpenTelemetry logs/traces: runtime behavior, tool/model calls, workflow telemetry, and post-deploy events.
+- JUnit/TAP: test results.
+- Veritas: optional evidence checks, repo standards, and authority settings. Flow Agents records the Veritas reference and verdict but does not own Veritas policy semantics.
+
+Use `context/contracts/governance-adapter-contract.md` before invoking Veritas or any similar governance provider. If the adapter is unavailable, record `NOT_VERIFIED` unless the user explicitly accepts skipping that governance evidence.
+
+### 6. Verdict
+
+Produce:
+
+- `PASS`: evidence satisfies risk and acceptance criteria.
+- `FAIL`: evidence shows the work is wrong or unsafe.
+- `NOT_VERIFIED`: evidence is missing, indirect, blocked, or inconclusive.
+
+For failures, classify:
+
+- implementation defect
+- bad plan
+- bad acceptance criteria
+- flaky infrastructure
+- missing environment
+- security concern
+- product ambiguity
+- scope drift
+
+Include required next evidence and whether to return to `plan-work`, `execute-plan`, `verify-work`, `remediate-ci`, or human decision.
+
+### 7. Publish Change Gate
+
+If the evidence verdict is otherwise `PASS` but the verified diff is not committed, pushed, and represented by a provider change record or an explicit no-provider-change reason, set `next_step` to `publish-change` instead of `release-readiness`.
+
+Use `git` and the active `ChangeProvider` adapter when available to:
+
+- confirm the working tree contains only the verified scope
+- commit the verified diff with a clear message
+- push the branch
+- open or update the provider change record linked to the issue/brief, closing refs, and evidence artifact, or record why no provider change is required
+- include or update the provider-facing `Acceptance Evidence` table, upgrading local source refs to immutable GitHub blob permalinks when the commit SHA and repository URL are known
+- collect provider check/CI links and statuses, or record why provider checks are unavailable
+- keep GitHub PRs as the first `ChangeProvider` adapter example: for GitHub, open or update a PR and collect PR checks
+
+If commit, push, provider change publication, or provider checks are blocked, keep the release path at `NOT_VERIFIED` or `HOLD` until the blocker is resolved or explicitly accepted by the user.
+
+## Gate
+
+Evidence passes only when acceptance criteria, scope integrity, CI/runtime evidence, and residual risk are sufficient for the risk class.
+
+After `PASS`, hand off to `publish-change` when the work is still local, or to `release-readiness` when the verified commit, pushed branch, provider change record or no-provider-change reason, provider checks, closing refs, structured evidence refs, and `Acceptance Evidence` table are available. After `FAIL` or `NOT_VERIFIED`, stop and name the missing work or evidence.

package/skills/execute-plan/SKILL.md

@@ -0,0 +1,110 @@
+---
+name: "execute-plan"
+description: "Parallel execution primitive — plan artifact path to implemented code via tool-worker (x4). Reads plan directly. Updates session file between waves."
+---
+
+# Execute
+
+Plan artifact in, implemented code out. Fans out to tool-worker subagents in parallel waves.
+
+## Agents
+
+| Agent | Role |
+|---|---|
+| tool-worker | Implementation per task spec (up to 4 parallel) |
+
+## Orchestrator Rule
+
+You do not write source files. You read the plan artifact, fan out tasks to tool-worker, and update the session file between waves.
+
+## Shared Contracts
+
+Follow:
+- `context/contracts/artifact-contract.md`
+- `context/contracts/execution-contract.md`
+- `context/contracts/planning-contract.md` for the plan artifact and Definition Of Done
+- `context/contracts/sandbox-policy.md`
+
+This skill owns orchestration between waves. The contracts own artifact continuity, worker task expectations, conflict handling, validation expectations, and completion rules.
+
+## Input
+
+- **Plan artifact path**: path to the `-plan.md` file in `.flow-agents/<slug>/`
+- **Session file path**: the session file to update with progress
+
+## Workflow
+
+1. Read the plan artifact directly
+2. Confirm the plan follows `context/contracts/planning-contract.md`, including `## Definition Of Done`. If missing, return to `plan-work` before implementation.
+3. Confirm the plan records an appropriate `sandbox_mode` using `context/contracts/sandbox-policy.md`. If missing, infer the smallest safe mode and record it before delegation.
+4. Confirm execution traceability before any worker starts:
+   - acceptance criteria have stable ids, preferably matching `acceptance.json`
+   - every wave/task lists the acceptance ids it supports
+   - the session/deliver file copies or links the criteria and includes a `Requirements Trace` or equivalent mapping
+   - each worker prompt includes the relevant acceptance ids and required evidence, not only a loose task title
+   - if traceability is missing, update the session file and/or send the plan back for refinement before delegation
+5. Set session file `status: executing` and use `npm run workflow:sidecar -- advance-state <artifact-dir> --status in_progress --phase execution --summary ... --next-action ...` when the repository provides it
+6. **Frontend design check:** If any tasks involve UI, CSS, layouts, components, or visual design, read the `frontend-design` skill and include its aesthetics guidelines in the tool-worker prompts for those tasks
+7. Fan out each wave to tool-worker subagents (up to 4 parallel):
+   - Delegate to the exact `tool-worker` role for every implementation worker. Do not spawn unnamed/default implementation agents.
+   ```
+   Each tool-worker gets:
+   - Task description from plan
+   - Files to create/modify
+   - Acceptance criteria
+   - Acceptance criterion ids and requirement ids this task supports
+   - Required evidence for those criteria
+   - Definition Of Done items that this task supports
+   - Sandbox mode, approval assumptions, rollback expectations, and escalation stop conditions
+   - Context from plan + prior wave results
+   - Plan artifact path (so it can read full context directly)
+   ```
+8. Between waves:
+   - Collect results from all tool-worker subagents
+   - Check for conflicts before next wave
+   - Feed completed wave context forward
+   - **Checkpoint**: update session file with completed tasks and next wave
+   - Record worker progress with `npm run workflow:sidecar -- record-agent-event --artifact-dir <artifact-dir> --agent-id <worker-id> --kind evidence --status active|done --summary ...`
+9. After all waves: set session file `status: executed` and update `state.json` / `handoff.json` with `advance-state`
+
+The orchestrator owns root `state.json` updates. Workers should receive the workflow artifact root explicitly and append agent events under that root instead of inferring the slug or rewriting shared sidecars.
+
+## Session File Updates
+
+Between each wave, append to the session file:
+
+```markdown
+## Execution Progress
+
+### Wave 1 (completed)
+- [x] Task A — done. Supports: AC1, AC2. Evidence: <test/check/artifact>. Modified files: `<path>`.
+- [x] Task B — done. Supports: AC3. Evidence: <test/check/artifact>. Modified files: `<path>`.
+
+### Wave 2 (in progress)
+- [ ] Task C. Supports: AC4, AC5. Required evidence: <test/check/artifact>.
+- [ ] Task D. Supports: AC6. Required evidence: <test/check/artifact>.
+
+## Requirements Trace
+
+- R1 <requirement>. Acceptance: AC1, AC2.
+- R2 <requirement>. Acceptance: AC3.
+
+## Modified Files / Scope
+
+- Record changed paths in the session/deliver artifact and worker event summaries after each wave.
+- Do not add ad hoc `modified_files` keys to `state.json` unless the sidecar schema explicitly supports them.
+- Verification and optional governance providers such as Veritas should consume this scope from the session/evidence artifacts or a dedicated evidence sidecar, not from invalid state fields.
+```
+
+This is the recovery point. If context is lost, a new session reads this and knows which waves are done.
+
+## Output
+
+- Implemented code in the working directory
+- Session file updated with execution progress and `status: executed`
+- Execution progress follows `context/contracts/execution-contract.md`
+- Structured state/handoff sidecars advanced when `npm run workflow:sidecar --` is available
+
+If `advance-state` or artifact validation is unavailable or blocked, record that exact blocker in the session file and do not mark execution as cleanly complete.
+
+{context?}

package/skills/explore/SKILL.md

@@ -0,0 +1,137 @@
+---
+name: "explore"
+description: "Parallel codebase exploration — fans out subagents to map structure, entry points, dependencies, patterns, config, and tests in one pass."
+---
+
+# Codebase Exploration
+
+Efficiently gather context about repositories by running parallel exploration tasks.
+
+## Harness Limit
+
+Some harnesses cap a single delegation batch at 4 subagents.
+- Respect the current harness limit.
+- If the limit is unknown, assume 4.
+- Never submit more than 4 subagents in one batch.
+- Use multiple waves when needed rather than overfilling the first fan-out.
+
+## Exploration Strategy
+
+Spawn MULTIPLE subagents IN PARALLEL to investigate different dimensions:
+
+### Wave 1A (parallel, up to 4 subagents)
+1. **Structure Scout** - Map directory structure, identify key folders (src, lib, tests, config)
+2. **Entry Point Finder** - Locate main files, CLI entry points, API routes, exports
+3. **Dependency Analyzer** - Parse package.json, requirements.txt, go.mod, Cargo.toml, pom.xml
+4. **Pattern Detective** - Identify architectural patterns, frameworks, coding conventions
+
+### Wave 1B (parallel, after Wave 1A if needed)
+5. **Config Inspector** - Find and summarize configuration files, env vars, build configs
+6. **Test Mapper** - Locate test files, understand testing strategy and coverage areas
+7. **Documentation Auditor** - Cross-reference all documentation against actual file system state:
+   - README agent tables vs actual `agents/*.agent-spec.json` files (ghost agents? missing agents?)
+   - README skill lists vs actual `skills/*/SKILL.md` files
+   - README dependency lists vs `Config` file declarations
+   - AGENTS.md shared sections consistency across packages (paths, naming examples, model references)
+   - All `.md` and `.json` files: grep for references to agents, skills, or paths that don't exist
+   - Agent spec `resources` paths: verify referenced context files exist
+   - Agent spec `model` fields: verify they follow conventions (orchestrators=opus, tools=haiku/sonnet)
+   - Typos and spelling errors in documentation files
+   - Empty directories or dead skill/SOP stubs
+
+### Wave 2 (after Wave 1A/1B — needs dependency list)
+7. **Tech Stack Researcher** - Research the identified tech stack using web search tools (`web_search`, `web_fetch`) and `tool-dependencies-updater` (audit-only — do NOT apply updates). Goals:
+   - Identify outdated or deprecated dependencies and how significant an upgrade would be (patch vs minor vs major, breaking changes)
+   - Discover new features in the current stack that the project could leverage
+   - Assess whether any part of the stack is irrelevant, superseded, or approaching EOL
+   - Surface project-specific context (migration guides, EOL announcements, known issues)
+
+## Execution Model
+
+```
+[User Request]
+      |
+      v
+[Wave 1A: Spawn first 4 dimensions in parallel]
+      |
+      v
+[Wave 1B: Spawn remaining dimensions in parallel if needed]
+      |
+      v
+[Aggregate Wave 1 findings]
+      |
+      v
+[Wave 2: Spawn Tech Stack Researcher with dependency list from Wave 1]
+  - tool-dependencies-updater: audit-only scan for outdated packages, version gaps, security advisories
+  - web search: research key frameworks/libraries for new features, deprecation, relevance
+      |
+      v
+[Final Synthesis]
+```
+
+## Subagent Prompts (use these as templates)
+
+Wave 1A:
+- "Explore the directory structure of this repo. List key folders and their purposes. Focus on: [specific area if provided]"
+- "Find all entry points in this codebase - main files, CLI commands, API routes, exported modules"
+- "Analyze dependencies - what frameworks, libraries, and tools does this project use?"
+- "Identify architectural patterns - is this MVC, microservices, monolith? What conventions are used?"
+
+Wave 1B:
+- "Find and summarize all configuration files - what can be configured and how?"
+- "Map the test structure - where are tests, what testing frameworks, what's the coverage strategy?"
+- "Audit all documentation for accuracy: (1) List every agent-spec.json file and cross-reference against README agent tables — flag any agents listed in docs but missing from disk or vice versa. (2) List every skills/*/SKILL.md and cross-reference against README skill lists. (3) Compare Config dependency declarations against README dependency sections. (4) Grep all .md and .json files for references to agent names and verify each referenced agent exists as an agent-spec.json. (5) Check AGENTS.md files across packages for inconsistent paths, naming examples, or model references. (6) Flag empty directories, typos, and dead stubs."
+
+Wave 2 (spawn these two in parallel):
+- tool-dependencies-updater: "Scan this project for all dependency manifests, check every dependency against the latest available version, run security advisory checks on outdated packages, and report findings grouped by risk level (critical/major/minor). Do NOT apply any updates — audit only."
+- web search: "Research the following tech stack: [list key frameworks/libraries from Wave 1]. For each, find: (1) latest stable version and what's new, (2) any deprecation or EOL announcements, (3) notable new features that could benefit this project, (4) whether any component has been superseded by a better alternative. Cite sources."
+
+## Output Format
+
+After all subagents complete, synthesize into:
+
+```
+## Codebase Overview
+[1-2 sentence summary]
+
+## Key Findings
+- **Tech Stack**: [languages, frameworks, tools]
+- **Architecture**: [pattern, structure]
+- **Entry Points**: [main files, commands]
+- **Configuration**: [key config files]
+- **Testing**: [strategy, frameworks]
+
+## Tech Stack Health
+- **Outdated (Critical)**: [packages with security vulnerabilities]
+- **Outdated (Major)**: [packages with major version bumps available — note breaking change risk]
+- **Outdated (Minor)**: [packages with minor/patch updates]
+- **New Features Available**: [notable new capabilities in current stack]
+- **Deprecation/EOL Warnings**: [anything approaching end of life]
+- **Upgrade Effort Summary**: [overall assessment — low/medium/high effort to get current]
+
+## Recommended Starting Points
+[Files to read first for understanding]
+
+## Potential Concerns
+[Any issues, outdated deps, missing tests, etc.]
+
+## Documentation Audit
+- **Ghost references**: [agents/skills/paths mentioned in docs but not on disk]
+- **Missing from docs**: [agents/skills that exist on disk but aren't documented]
+- **Stale content**: [outdated descriptions, wrong dependency lists, inconsistent AGENTS.md sections]
+- **Config mismatches**: [README deps vs Config file deps]
+- **Path inconsistencies**: [resource paths in agent specs that don't follow conventions]
+- **Empty/dead artifacts**: [empty directories, stub files with no content]
+- **Typos**: [spelling errors found in documentation]
+```
+
+## Key Principles
+
+- ALWAYS run explorations in PARALLEL within the current harness limit - this is the whole point
+- Never exceed 4 subagents in one batch unless the harness explicitly allows more
+- Wave 2 (Tech Stack Researcher) runs AFTER Wave 1A/1B completes because it needs the dependency list
+- tool-dependencies-updater is used in AUDIT-ONLY mode — never apply updates during explore
+- Be thorough but efficient - don't read entire files, scan for structure
+- Focus on what helps someone GET STARTED quickly
+- Flag anything unusual or concerning
+- If a specific area is requested, weight exploration toward that area

package/skills/feedback-loop/SKILL.md

@@ -0,0 +1,87 @@
+---
+name: "feedback-loop"
+description: "Verify implementation actually works. Visual changes → Playwright; integration changes → commands/tests. Run after completing builds."
+---
+
+# Feedback Loop
+
+Verify that what you claim to have built actually works. Don't just say "done" — prove it.
+
+## When to Use
+
+- After implementing changes, before declaring them complete
+- When the user asks you to verify or prove your work
+- As the final step of any implementation workflow
+- When you're uncertain whether your changes actually function correctly
+
+## Workflow
+
+### Step 1: IDENTIFY CHANGES
+
+Determine what was just built:
+- Check `git diff` for modified/added files
+- Review the active TODO list for context on what was implemented
+- Identify the nature of the change: what should be different now?
+
+### Step 2: CLASSIFY
+
+Determine the verification method:
+
+| Change Type | Method | Examples |
+|---|---|---|
+| **Visual** | Playwright via `tool-playwright` | UI components, pages, styles, layouts, forms, visual regressions |
+| **Integration** | Commands, tests, execution | APIs, CLIs, libraries, configs, build scripts, data processing |
+
+If changes span both, run both verification paths.
+
+### Step 3: VERIFY
+
+#### Visual Path (frontend/UI changes)
+Delegate to `tool-playwright`:
+1. Load the relevant URL (local dev server, preview, etc.)
+2. Take an accessibility snapshot to confirm elements exist and are structured correctly
+3. Take a screenshot for visual confirmation
+4. If interactive — click, type, navigate to exercise the changed behavior
+5. Compare against expected state: are the right elements present? Does the layout match intent?
+
+If the dev server isn't running, start it (or tell the user to) before proceeding.
+
+#### Integration Path (non-visual changes)
+Use the most direct verification available, in priority order:
+1. **Run existing tests** — if tests cover the changed code, run them
+2. **Execute the code** — run the CLI command, call the API endpoint, import the module
+3. **Check build** — compile/lint to confirm no syntax or type errors
+4. **Inspect output** — verify the output matches expected behavior
+
+Always capture actual output as evidence.
+
+### Step 4: REPORT
+
+State clearly:
+- **What was verified** — which changes, which method
+- **Evidence** — actual output, screenshots, test results, command output
+- **Verdict** — ✅ confirmed working, or ❌ found issues with specifics
+
+If verification fails, fix the issue and re-verify. Don't report failure without attempting a fix first.
+
+## Persistence Rule
+
+**Keep trying until the user says stop.** This is the core behavior of the feedback loop.
+
+- If a verification method fails (Playwright won't connect, tests error out, server won't start), **debug and retry**. Don't downgrade to a weaker method or declare "good enough."
+- If visual verification is required and Playwright is having issues, fix the Playwright issue. Don't fall back to "well the build passes so it's probably fine."
+- If integration tests fail, diagnose why, fix, and re-run. Don't report partial success.
+- Cycle: **verify → fail → diagnose → fix → verify again**. Repeat until either:
+  1. ✅ All verification methods pass with evidence, OR
+  2. 🛑 The user explicitly says to stop or skip a method
+
+Never self-exit the loop. Never decide on the AI's behalf that a failure is acceptable. The user breaks the loop, not the agent.
+
+## Key Principles
+
+- **Evidence over assertion.** Show output, not just "it works."
+- **Never settle.** If a verification method should work but isn't, that's a bug to fix — not a reason to skip it.
+- **Fix before reporting.** If verification reveals a bug you introduced, fix it and re-run.
+- **Match the medium.** UI changes need visual proof. Backend changes need execution proof.
+- **Be specific.** "Tests pass" is weak. "Ran `npm test` — 14 tests passed, 0 failed, output attached" is strong.
+- **Don't skip this.** The whole point is catching the gap between "I wrote the code" and "the code works."

package/skills/fix-bug/SKILL.md

@@ -0,0 +1,133 @@
+---
+name: "fix-bug"
+description: "Bug fix orchestrator — diagnose → plan-work → execute-plan → review-work → verify-work → loop. Diagnosis phase is unique to bugs, then chains the same primitives."
+---
+
+# Bug Fix
+
+Diagnose a bug, then chain the same plan → execute → verify loop. The diagnosis phase is what makes this different from deliver.
+
+## Agents
+
+Inherited from primitives + diagnosis:
+
+| Agent | Used by |
+|---|---|
+| tool-planner | diagnosis + plan-work |
+| tool-worker (x4) | execute-plan |
+| tool-code-reviewer | review-work |
+| tool-security-reviewer | review-work (conditional — security-sensitive changes) |
+| tool-verifier | verify-work |
+| tool-playwright | diagnosis (reproduce) + verify-work |
+
+## Orchestrator Rule
+
+You never use `read`, `glob`, `grep`, or `code` on source files. All codebase analysis goes through tool-planner. All review goes through review-work. All verification goes through tool-verifier or tool-playwright.
+
+## Input
+
+- **Bug report**: screenshot, error log, user description, or all three
+- **Directory**: working directory
+
+## Session File
+
+Filename: `<branch>--fix-bug-<slug>.md`
+
+```markdown
+# BUG: <one-liner>
+
+branch: <branch>
+worktree: <worktree>
+created: <date>
+status: diagnosing | planning | fixing | verifying | resolved
+type: fix-bug
+iteration: 0
+
+## Bug Report
+
+Source: screenshot | error log | user description
+<original report, pasted verbatim>
+
+## Diagnosis
+
+Root cause from tool-planner.
+
+## Plan
+
+(populated by plan-work)
+
+## Execution Progress
+
+(populated by execute-plan)
+
+## Verification Report
+
+(populated by verify-work)
+
+## History
+
+- iteration 1: partial — fix applied but regression in sidebar
+- iteration 2: pass — bug fixed, no regressions
+```
+
+## Workflow
+
+### 1. Create session file
+
+Paste the bug report verbatim. Set `status: diagnosing`.
+
+### 2. Diagnose (unique to bugs)
+
+1. **Reproduce** (if visual) — delegate to tool-playwright to confirm the bug is visible. Screenshot the broken state.
+2. **Find root cause** — delegate to tool-planner:
+   ```
+   Bug: <description>
+   Reproduction: <steps or screenshot evidence>
+   Directory: <working directory>
+   todo_file: <session file path>
+   Find the root cause and propose a fix plan.
+   ```
+3. Read the diagnosis from tool-planner's output
+4. Paste into session file `## Diagnosis`
+5. Present to user: "Here's what's broken and how I'd fix it. Agree?"
+6. On approval → proceed to plan
+
+### 3. Plan (plan-work)
+
+Invoke plan-work with: diagnosis + fix goal, directory, session file path.
+
+### 4. Execute (execute-plan)
+
+Invoke execute-plan with the plan artifact path and session file path.
+
+### 5. Review (review-work)
+
+Invoke `review-work` with the session file path. It must delegate to `tool-code-reviewer`, and to `tool-security-reviewer` when security triggers are present. CRITICAL/HIGH findings block and loop back to Execute unless explicitly accepted.
+
+### 6. Verify (verify-work)
+
+Invoke verify-work with the session file path. tool-verifier must verify:
+1. **Bug is fixed** — the specific issue from the report
+2. **No regressions** — build passes, existing tests pass, related functionality works
+
+### 7. Route on verdict
+
+- **All PASS** → resolve
+- **Any FAIL** → loop
+- **Any NOT_VERIFIED** → surface to user
+
+### 8. Loop (on failure)
+
+1. Summarize what failed
+2. Increment `iteration`
+3. Re-invoke plan-work with: original diagnosis + failure summary → updated fix plan
+4. Back to step 4
+
+### 9. Resolve
+
+1. Include verification report verbatim
+2. Show before/after evidence (screenshots if visual)
+3. `git diff --stat`
+4. Set `status: resolved`
+
+{context?}