fusebase-flow

KO | EN

gitlite — search

#developer-tools #tensorflow #nextjs #machine-learning #ai #ruby #svg #http #claude-code #ui

(★ 9)

The framework client-facing teams use to build internal & client apps with AI. Two agents — a Product Owner that advises what to build, and an AI Developer that ships it. Built by FuseBase.

File Explorer

ZIP Download

- - ai-developer.md
  - app-architect.md
  - app-create-checker.md
  - product-owner.md
- - find-wasted-code.md
  - find-wasted-effort.md
  - fusebase-health.md
  - handoff.md
  - onboard.md
  - product-owner.md
  - token-waste-audit.md
- - quality-check-apps.js
  - run-lint-on-stop.sh
  - run-typecheck-apps.js
  - run-typecheck-on-stop.sh
- settings.json.example
- marketplace.json
- plugin.json
- - ai-developer.md
  - app-architect.md
  - app-create-checker.md
  - product-owner.md
- config.toml.example
- hooks.json.example
- plugin.json
- - fusebase-flow-always.mdc
  - fusebase-flow-implementation.mdc
  - fusebase-flow-security.mdc
  - fusebase-flow-specs.mdc
  - fusebase-flow-validation.mdc
- - fusebase-flow.instructions.md
  - security.instructions.md
  - validation.instructions.md
- - bug_report.md
  - config.yml
  - feature_request.md
- - fusebase-flow-maintainer.yml
  - fusebase-flow-measure-windows.yml
  - fusebase-flow-release.yml
  - fusebase-flow-verify.yml
- copilot-instructions.md
- PULL_REQUEST_TEMPLATE.md
- - AGENT.md
- - AGENT.md
- agent-mirror-manifest.txt
- cli-upstream-manifest.json
- cli-vendor-manifest.json
- hook-layer-manifest.json
- managed-content-manifest.json
- README.md
- skill-mirror-manifest.txt
- - two-agent-banner.svg
- - index.md
  - README.md
- - 2026-06-01-f1-f5-install-upgrade-review.md
  - 2026-06-01-overlay-refresh-trailing-blank.md
  - 2026-06-01-u10-flag-gated-cli-skills.md
  - 2026-06-01-u11-u12-hooksoff-skills-guard.md
  - 2026-06-01-u13-noncanonical-provider-mirrors.md
  - 2026-06-01-u14-wire-hooks-stop-mis-wire.md
  - 2026-06-01-u15-eslint-ignore-staging-clone.md
  - 2026-06-01-u9-legacy-project-values-seed.md
  - 2026-06-06-sync-version-strings-nested-docs-prune.md
  - 2026-06-10-audit-nit-sweep.md
  - 2026-06-10-flow-efficiency-repairs.md
  - 2026-06-10-flow-token-trim.md
  - 2026-06-10-fr-25-hardening.md
  - 2026-06-10-publish-roadmap-backlog.md
  - 2026-06-11-delegation-verification-discipline.md
  - 2026-06-11-handoff-paper-trail.md
  - 2026-06-11-v3181-nit-sweep.md
  - 2026-07-07-cli-0.25.16-guidance-shift.md
  - 2026-07-26-overlay-template-drift.md
  - 2026-07-27-rule-inventory-version-literal-noise.md
  - 2026-09-07-maintainer-process.md
  - 2026-09-07-release-completion.md
  - index.md
- - .gitkeep
- - 2026-05-29-cli-first-flow-second-recovery-implement.md
  - 2026-05-29-provider-skill-drift-guards-implement.md
  - 2026-06-06-comment-policy-fr22-write-time-delivery-deploy.md
  - 2026-06-06-comment-policy-fr22-write-time-delivery-implement.md
  - README.md
- - README.md
- - v2.1.0.md
  - v2.1.1.md
  - v2.2.0.md
  - v2.2.1.md
  - v2.3.0.md
  - v2.3.1.md
  - v2.3.2.md
  - v2.4.0.md
  - v2.4.1.md
  - v2.5.0.md
  - v2.6.0.md
  - v2.6.1.md
  - v2.7.0.md
  - v2.7.1.md
  - v2.8.0.md
  - v2.9.0.md
  - v3.1.md
  - v3.10.0.md
  - v3.11.0.md
  - v3.11.1.md
  - v3.12.0.md
  - v3.12.1.md
  - v3.13.0.md
  - v3.14.0.md
  - v3.14.1.md
  - v3.14.2.md
  - v3.15.0.md
  - v3.16.0.md
  - v3.16.1.md
  - v3.16.2.md
  - v3.16.3.md
  - v3.16.4.md
  - v3.17.0.md
  - v3.17.1.md
  - v3.18.0.md
  - v3.18.1.md
  - v3.19.0.md
  - v3.2.md
  - v3.20.0.md
  - v3.20.1.md
  - v3.21.0.md
  - v3.21.1.md
  - v3.22.0.md
  - v3.23.0.md
  - v3.23.1.md
  - v3.24.0.md
  - v3.25.0.md
  - v3.25.1.md
  - v3.26.0.md
  - v3.27.0.md
  - v3.28.0.md
  - v3.29.0.md
  - v3.3.md
  - v3.30.0.md
  - v3.30.1.md
  - v3.30.2.md
  - v3.30.3.md
  - v3.30.4.md
  - v3.30.5.md
  - v3.30.6.md
  - v3.30.7.md
  - v3.4.md
  - v3.5.1.md
  - v3.5.2.md
  - v3.5.md
  - v3.6.md
  - v3.7.md
  - v3.8.1.md
  - v3.8.2.md
  - v3.8.3.md
  - v3.8.4.md
  - v3.8.5.md
  - v3.8.6.md
  - v3.8.7.md
  - v3.8.md
  - v3.9.0.md
  - v4.10.0.md
  - v4.10.1.md
  - v4.11.0.md
  - v4.12.0.md
  - v4.13.0.md
  - v4.13.1.md
  - v4.14.0.md
  - v4.14.1.md
  - v4.15.0.md
  - v4.15.1.md
  - v4.15.2.md
  - v4.15.3.md
  - v4.16.0.md
  - v4.16.1.md
  - v4.16.2.md
  - v4.16.3.md
  - v4.16.4.md
  - v4.16.5.md
  - v4.16.6.md
  - v4.17.1.md
  - v4.2.0.md
  - v4.2.1.md
  - v4.2.2.md
  - v4.3.0.md
  - v4.3.1.md
  - v4.3.2.md
  - v4.4.0.md
  - v4.4.1.md
  - v4.5.0.md
  - v4.6.0.md
  - v4.6.1.md
  - v4.7.0.md
  - v4.7.1.md
  - v4.8.0.md
  - v4.9.0.md
  - v4.9.1.md
  - v4.9.2.md
  - v5.1.md
  - v5.2.md
- - README.md
- - .gitkeep
  - repo-context.md
- - handoff.md
- - .gitkeep
- ADVISORY-2026-08-20-missing-base-upgrade.md
- architecture-overview.md
- clean-room.md
- comment-policy.md
- compatibility.md
- constitution.md
- framework.md
- fusebase-cli-edition.md
- health-check-deferrals.md
- hook-coverage.md
- install-existing-project.md
- install-fusebase-cli-project.md
- maintainer-execution.md
- maintainer-testing.md
- north-star.md
- operator-discipline.md
- rail-mapping.md
- release-fingerprints.md
- source-map.md
- tradeoffs.md
- - SKILL.md
- - SKILL.md
- - SKILL.md
- - SKILL.md
- - SKILL.md
- - SKILL.md
- - SKILL.md
- - SKILL.md
- - SKILL.md
- - SKILL.md
- - SKILL.md
- - SKILL.md
- - SKILL.md
- - SKILL.md
- - SKILL.md
- - SKILL.md
- - SKILL.md
- - SKILL.md
- - SKILL.md
- - SKILL.md
- - SKILL.md
- - SKILL.md
- - SKILL.md
- - SKILL.md
- - SKILL.md
- - SKILL.md
- - SKILL.md
- - SKILL.md
- - SKILL.md
- - SKILL.md
- - SKILL.md
- - SKILL.md
- - SKILL.md
- - SKILL.md
- - commit-msg
  - pre-commit
  - pre-push
- - permission_request.py
  - post_tool_use.py
  - pre_compact.py
  - pre_tool_use.py
  - session_start.py
  - stop.py
  - user_prompt_submit.py
- - approve-local.sh
  - bootstrap-upgrade.sh
  - check-cli-flow-conflicts.sh
  - check-git-capture.sh
  - check-module-size.sh
  - check-vendored-rendered.sh
  - cleanup-flow-backups.sh
  - eslint-ignore-flow-paths.sh
  - find-wasted-code.py
  - find-wasted-effort.py
  - fusebase-flow-health-check.sh
  - install-codex-prompts.sh
  - install-git-hooks.sh
  - lane-assessment.py
  - lane-router.sh
  - mirror-agents.sh
  - mirror-skills.sh
  - po-investigate.sh
  - post-fusebase-update.sh
  - preflight.sh
  - print-release-fingerprints.sh
  - recover-missing-base.sh
  - refresh-cli-vendor.sh
  - rule-inventory.sh
  - run-handler.sh
  - run-validators.sh
  - stamp-cli-provenance.sh
  - stamp-hook-manifest.sh
  - stamp-managed-content-manifest.sh
  - sync-version-strings.sh
  - token-waste-audit.py
  - upgrade-engine.sh
  - upgrade.sh
  - verify-gate.sh
  - verify-hook-manifest.sh
  - verify-managed-content-manifest.sh
  - verify-tag-target.sh
  - write-bootstrap-approval.sh
- - __init__.py
  - approval_artifact.py
  - audit_logger.py
  - command_policy.py
  - command_rules.py
  - denial_message.py
  - git_push_binding.py
  - git_utils.py
  - module_size.py
  - path_policy.py
  - policy_loader.py
  - secret_scanner.py
  - staged_secret_scan.py
- - benchmark-flow-consumers.py
  - benchmark-stop-transcript.py
  - cli-flow-recovery-classify.sh
  - cli-flow-recovery-direct.sh
  - cli-flow-recovery-e2e.sh
  - cli-flow-recovery-engine.sh
  - cli-flow-recovery-fixture.sh
  - cli-flow-recovery-preflight.sh
  - health-check-heartbeat.sh
  - lane-workflow-fixture.py
  - run-tests.sh
  - run_hook_tests.py
  - test-approval-binding.sh
  - test-approval-receipt-durability.sh
  - test-approval-schema3.sh
  - test-approval-writer.sh
  - test-artifact-manifest.py
  - test-baseline-merge.sh
  - test-boot-size.sh
  - test-bootstrap-baseline-hop.sh
  - test-bootstrap-exception.sh
  - test-budget-literals.sh
  - test-cli-0259-compat.sh
  - test-cli-flow-recovery-selectors.sh
  - test-cli-flow-recovery.sh
  - test-cli-vendor-refresh.sh
  - test-cli-version-gate.sh
  - test-codex-plugin-surface.sh
  - test-codex-prompt-parity.sh
  - test-command-policy-denial-message.sh
  - test-command-policy.sh
  - test-ff-only.sh
  - test-fingerprint-row-per-tag.sh
  - test-flow-consumer-benchmark.sh
  - test-fr22-delivery-guarantee.sh
  - test-git-capture-guard.sh
  - test-git-hooks-smoke.sh
  - test-health-check-timeout.sh
  - test-history-extraction.sh
  - test-hook-install-rc.sh
  - test-hook-manifest.sh
  - test-hook-wiring-intent.sh
  - test-hop-log-truthfulness.sh
  - test-install-fusebase-cli-project-doc.sh
  - test-job-probe-honesty.sh
  - test-lane-router.sh
  - test-lane-workflow.sh
  - test-liveness-bounded-run.sh
  - test-minimal-path-fixture.sh
  - test-missing-base-detection.sh
  - test-module-size.sh
  - test-msys-tree-cleanup.sh
  - test-newline-preserve.sh
  - test-plugin-parity-scope.sh
  - test-po-investigate.sh
  - test-po-verifiable-boot.sh
  - test-policy-state-preserve.sh
  - test-pre-commit-git-context-contract.sh
  - test-pre-commit-git-context-mutation.sh
  - test-pre-commit-interpreter-contract.sh
  - test-pre-commit-interpreter-mutation.sh
  - test-pre-commit-python3-version-contract.sh
  - test-pre-commit-python3-version-mutation.sh
  - test-prohibition-residency.sh
  - test-recover-missing-base.sh
  - test-recovery-eol-equivalence.py
  - test-recovery-final-verification.py
  - test-recovery-hint-honesty.sh
  - test-recovery-noop.py
  - test-recovery-owned-bootstrap.py
  - test-release-evidence-authority.sh
  - test-release-tag-binding.sh
  - test-return-budget.sh
  - test-rule-inventory.sh
  - test-run-preconditions.sh
  - test-run-tests-signal-reap.sh
  - test-secret-scan-staged.sh
  - test-stamp-eol-guard.sh
  - test-startup-context.sh
  - test-supersede-primitive.sh
  - test-sync-allowlist.sh
  - test-token-waste-classify.sh
  - test-trusted-enforcer.sh
  - test-upgrade-classify-eol.sh
  - test-upgrade-conflict-classification.sh
  - test-upgrade-delivers-or-refuses.sh
  - test-upgrade-preboundary-consumed-tree.sh
  - test-upgrade-repair-managed.sh
  - test-upgrade-source-boundary.sh
  - test-upgrade-truthful-base.sh
  - test-validation-instructions.sh
  - test-validator-evidence.sh
  - test-vendored-rendered.sh
  - test-wasted-effort-windowing.sh
  - test-wire-hooks-add-beside.sh
  - test-ws5-upgrade-bounded.sh
- flow_hook_event.schema.json
- README.md
- requirements.txt
- approval-policy.yml
- command-policy.yml
- comment-policy.yml
- gate-contracts.yml
- module-size-baseline.txt
- module-size.yml
- protected-paths.yml
- ratchet-governance.yml
- required-artifacts.yml
- secret-patterns.yml
- - .gitkeep
- - .gitkeep
- .gitkeep
- - architect-response-checklist.md
  - deploy-report-checklist.md
  - gate-report-checklist.md
- architect-response.md
- audience.md
- backlog-ticket-README.md
- business-logic-index.md
- business-logic.md
- change-note.md
- clarify-conversation.md
- decisions.md
- deploy-report.md
- gate-report.md
- handoff-deploy.md
- handoff-folder-README.md
- handoff-implement.md
- handoff.md
- north-star.md
- problem-catalog-entry.md
- product.md
- skill-template.md
- smoke-test-playwright.md
- spec.md
- tasks.md
- verification-gate.md
- architect-escalation.md
- eight-phase-flow.md
- git-discipline.md
- greenlight-deploy.md
- greenlight-implement.md
- knowledge-curation.md
- lightweight-lane.md
- live-user-verification.md
- session-initiation.md
- setup.md
- smoke-verification.md
- verification-gate.md
- violation-recovery.md
.gitattributes
.gitignore
.python-version
AGENTS.md
CHANGELOG.md
CLAUDE.md
CODE_OF_CONDUCT.md
CONTRIBUTING.md
FLOW_RULES.md
FLOW_RULES_HISTORY.md
GEMINI.md
install.sh
LICENSE
PUBLISHING.md
README.md
ROADMAP.md
SECURITY.md
VERSION

# Use via CDN

jsDelivr

jsDelivr serves any public GitHub repository as a CDN with zero setup. Pick a version and a file to get a ready-to-paste link and snippet.

Version

File

Link

Example

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

**The framework client-facing teams use to build internal and client-facing apps with AI.**

**🌐 Read this in:** 🇪🇸 [Español](docs/translations/es/README.md) · 🇫🇷 [Français](docs/translations/fr/README.md) · 🇩🇪 [Deutsch](docs/translations/de/README.md) · 🇧🇷 [Português](docs/translations/pt-BR/README.md) · 🇯🇵 [日本語](docs/translations/ja/README.md) · 🇨🇳 [简体中文](docs/translations/zh-Hans/README.md)

![FuseBase Flow — you design and decide with the Product Owner agent, which hands off to the AI Developer agent that implements, runs the verification gate, and deploys](https://raw.githubusercontent.com/fusebase-dev/fusebase-flow/main/docs/assets/two-agent-banner.svg)

[![Version](https://img.shields.io/badge/version-4.7.1-blue.svg)](https://raw.githubusercontent.com/fusebase-dev/fusebase-flow/main/VERSION)
[![License: MIT](https://img.shields.io/badge/license-MIT-green.svg)](https://raw.githubusercontent.com/fusebase-dev/fusebase-flow/main/LICENSE)
[![CI](https://github.com/fusebase-dev/fusebase-flow/actions/workflows/fusebase-flow-verify.yml/badge.svg)](https://github.com/fusebase-dev/fusebase-flow/actions/workflows/fusebase-flow-verify.yml)
[![Use this template](https://img.shields.io/badge/GitHub-Use_this_template-brightgreen.svg?logo=github)](https://github.com/fusebase-dev/fusebase-flow/generate)
[![Built by FuseBase](https://img.shields.io/badge/built_by-FuseBase-0A66C2.svg)](https://thefusebase.com)
[![Discussions](https://img.shields.io/badge/community-Discussions-5865F2.svg?logo=github)](https://github.com/fusebase-dev/fusebase-flow/discussions)

A development framework for client-facing businesses and teams, FuseBase Flow covers what breaks during real app development for internal and external collaboration — drift, context rot, scope creep, unreliable hand-offs — so two AI agents (a Product Owner and an AI Developer) can ship reliably.

It shapes your existing AI agent through **repo files** — no SaaS, no daemon, no proprietary runtime. Works in Claude Code, Codex, Cursor, Copilot, and Gemini.

## Built by FuseBase

FuseBase Flow is built and maintained by **FuseBase** (Nimbus Web Inc.) — a US company building client-facing collaboration software since **2014 (11 years)**. It's the framework FuseBase itself uses to ship apps, backed by a proven product track record:

- 🏆 **Product Hunt** — Product of the Day, Week, Month & Year (team collaboration)
- 🥇 **3× top-selling deal on AppSumo**
- ⭐ **~600 five-star reviews**

FuseBase Flow isn't an experiment — it's the workflow a real product company runs on.

## Built with FuseBase Flow

Real client-facing apps — a help-desk, a rental marketplace, an adoption-analytics dashboard, a training portal, a client-interview workspace, and more — **built with FuseBase Flow on FuseBase Apps, by the community in a few days.**

<table>
 <tr>
 <td align="center" width="25%"><a href="https://ai-dev.thefusebase.com/"><img src="docs/assets/showcase/ticketing-support.png" alt="Asset support ticketing app built with FuseBase Flow" width="100%"></a> Help-desk ticketing</td>
 <td align="center" width="25%"><a href="https://ai-dev.thefusebase.com/"><img src="docs/assets/showcase/help-desk.png" alt="Support desk and knowledge-base portal built with FuseBase Flow" width="100%"></a> Support desk &amp; KB</td>
 <td align="center" width="25%"><a href="https://ai-dev.thefusebase.com/"><img src="docs/assets/showcase/adoption-dashboard.png" alt="Customer adoption analytics dashboard built with FuseBase Flow" width="100%"></a> Analytics dashboard</td>
 <td align="center" width="25%"><a href="https://ai-dev.thefusebase.com/"><img src="docs/assets/showcase/rental-marketplace.png" alt="Room rental marketplace built with FuseBase Flow" width="100%"></a> Rental marketplace</td>
 </tr>
 <tr>
 <td align="center" width="25%"><a href="https://ai-dev.thefusebase.com/"><img src="docs/assets/showcase/training-course.png" alt="Training and course app built with FuseBase Flow" width="100%"></a> Learning &amp; training</td>
 <td align="center" width="25%"><a href="https://ai-dev.thefusebase.com/"><img src="docs/assets/showcase/interview-workspace.png" alt="Client interview workspace built with FuseBase Flow" width="100%"></a> Interview workspace</td>
 <td align="center" width="25%"><a href="https://ai-dev.thefusebase.com/"><img src="docs/assets/showcase/content-agency-site.png" alt="Content agency marketing site built with FuseBase Flow" width="100%"></a> Marketing site</td>
 <td align="center" width="25%"><a href="https://ai-dev.thefusebase.com/"><img src="docs/assets/showcase/language-learning-game.jpg" alt="Gamified language-learning app built with FuseBase Flow" width="100%"></a> Language-learning game</td>
 </tr>
</table>

🔎 **[Explore the full gallery → ai-dev.thefusebase.com](https://ai-dev.thefusebase.com/)** · Built something with FuseBase Flow? Share it in **[Show and tell](https://github.com/fusebase-dev/fusebase-flow/discussions)** — standout projects get featured here.

## Who it's for

- **Agencies, consultancies, and client-facing teams** building apps for both their own internal operations and their clients.
- Teams who want to **productize their expertise** — turn the knowledge only you have into apps and systems you deliver, internally and to clients.
- Anyone who's hit the wall where one AI chat gets clogged, the model drifts, and a half-built app stops being trustworthy.

## Why a framework (and why two agents)

Building real apps with an AI agent breaks in predictable ways: one chat fills up and the model **drifts**; context rot makes later edits contradict earlier ones; a single mega-prompt smuggles in **scope creep**; and work handed between sessions loses its thread. FuseBase Flow closes those gaps with a disciplined loop run by **two agents** — a consultant and a builder, not a sprawling fleet. The simplicity is the point.

| Agent | Role |
|---|---|
| **Product Owner** | Your single point of contact. Consults on *what* to build and *how to build it right*, then breaks the work into phases and slices. Owns Specify -> Clarify -> Plan -> Decisions -> Tasks -> Review -> deploy hand-off. |
| **AI Developer** | The builder. Executes each slice one task = one commit, stops at a verification gate, and deploys only on approval -- in a separate session so the main context stays clean. |

```mermaid
flowchart LR
 Client([Client / team request]) --> S[📋 Specify]
 S --> C[❓ Clarify] --> P[🗺️ Plan] --> D[🔒 Decisions] --> T[✅ Tasks / slices]
 T --> V[🚦 Verify gate]
 V -->|handoff| I[⚙️ Implement one task = one commit]
 I --> R[🔍 Review] --> H[📦 Deploy handoff] --> X[🚀 Deploy] --> Done([Shipped])
 style Client fill:#fef9c3,stroke:#a16207
 style S fill:#dbeafe,stroke:#1d4ed8
 style V fill:#fff3e0,stroke:#f57c00
 style I fill:#dcfce7,stroke:#15803d
 style X fill:#dcfce7,stroke:#15803d
```

*Product Owner (blue) is the single point of contact -- consults, advises, and breaks work into phases and slices. AI Developer (green) builds and deploys. The full eight-phase procedure lives at [`workflows/eight-phase-flow.md`](workflows/eight-phase-flow.md).*

## How it stays reliable

- **No drift** -- the Product Owner (advise) and AI Developer (build) split the work so neither chat clogs and the model stays on target.
- **Phases -> slices** -- complex work is decomposed Jira-style into reviewable slices, never one risky mega-prompt.
- **Durable hand-offs** -- work survives session resets with full context, so a fresh chat picks up without fatigue.
- **Many small apps, not one monster** -- a product is composed of focused apps, so one failure can't sink the whole system.
- **Ceremony scales with risk (FR-21)** -- a small, reversible change takes the **Lightweight lane** (one change-note, one build→verify→deploy pass, a plain "ship it" go-ahead) instead of the full spec→decisions→tasks→gate chain; risky/uncertain work takes the full lane. The safety floor -- live proof, an explicit deploy go-ahead, protected-path check, rollback -- is kept either way.

## Commands & capabilities

Seven slash commands are the only things you invoke directly — everything else is a **skill** that activates automatically when its trigger matches. The tables below are the use-case view; for the phase-mapped trigger view of every skill, see [§ Skill catalog](#skill-catalog).

### Slash commands

| Command | What it does | Real-world use case |
|---|---|---|
| **/product-owner** | Starts a Product Owner session — your single point of contact who advises *what* to build and *how*, reads your North Star, and breaks work into phases/slices. It opens with a verifiable activation boot: the PO echoes its operating-rules checklist and a `PO-ACTIVATED` marker, and a Stop-hook warns if a session skips it. | "Let's build a booking system" → the PO scopes it, asks the right questions, and slices it into reviewable work. |
| **/onboard** | The PO interviews you about vision, audience, and domain, then writes the project artifacts (`docs/north-star.md`, audience, project values) that steer all future work. | First time using Flow on your repo — capture your product vision once so every later task is aimed at it. |
| **/handoff** | Writes the live session state to `docs/tmp/handoff.md` (16-section template) so a fresh chat resumes exactly where you left off. | A long debugging session is getting heavy → `/handoff`, open a new chat, continue without losing the thread. |
| **/fusebase-health** | Read-only health check — reports drift between the FuseBase CLI layer and the Flow layer, and offers recovery for Flow-owned drift. | After a `fusebase update` you're unsure if Flow still works → confirms what (if anything) drifted and offers to fix it. |
| **/token-waste-audit** | Parses this project's transcripts and lists token-waste *candidates* (big reads, re-reads, polling, `large-output`, `repeat-output`) mapped to FR-26. | A session felt expensive → see where the tokens actually went and what to do differently next time. |
| **/find-wasted-effort** | Audits Flow *artifacts on disk* (gate reports, handoffs, approvals, git log) for ceremony that bought no safety outcome. Read-only; findings are review candidates. | You suspect the process has overhead that isn't earning its keep → spot ceremony to trim (nothing auto-removed). |
| **/find-wasted-code** | Statically scans the *repo source* (docs, skills, commands, hooks, settings) for friction footguns — dead-end tool calls, broken links, missing helpers, footgun configs, plus a silent-push-through baseline — and writes a tracked report to `docs/wasted-code/report.md`. Manual-trigger only; read-only; findings are review candidates. | Before a release you want to catch the papercuts that make an agent or teammate silently dead-end → get a low-false-positive list of what's broken. |

These are native Claude Code slash commands. On **Codex, Cursor, Copilot, and Gemini** the same commands work via the `AGENTS.md` command-equivalents table — invoke the named skill, or type the command as text. Codex users who want native `/prompts:<cmd>` can additionally run the per-machine opt-in `bash hooks/local/install-codex-prompts.sh` (user-global, namespaced, Codex-deprecated in favor of skills).

### What the skills do for you

**Always on (every session)**

| Skill | What it does | Real-world use case |
|---|---|---|
| **communication** | Mode A for chat (clear, concrete, skimmable) + Mode B for internal artifacts (dense, tabular, front-loaded). | Every answer is structured and scannable; every internal doc is compact, not padded prose. |
| **role-discipline** | Enforces the PO-vs-AI-Developer boundaries and the exact refusal wording when a rule would be broken. | The PO won't quietly start writing app code; asked to skip a gate, it refuses with a clear reason. |

**Ticket lifecycle (Specify → Deploy)**

| Skill | What it does | Real-world use case |
|---|---|---|
| **requirements-specification** | Drafts the spec, clarifying questions, and acceptance criteria at the start of a ticket. | "Build a feature" → it writes the spec and asks the few questions that actually matter before any code. |
| **design-discovery-ideation** | Generates divergent options / UI & product directions *before* a decision is locked. | Unsure how a dashboard should work → get 3 distinct directions to choose from instead of committing blind. |
| **implementation-planning** | Turns the locked spec into decisions, tasks, a verification gate, and an implementer handoff. | Spec is ready → work is broken into one-task-one-commit slices with a clear gate to stop at. |
| **task-delegation** | Decides when to split work across parallel sub-agents — only when the split saves more than its context cost. | A migration touches 20 independent files → safely fan it out instead of one slow serial pass. |
| **validation-and-qa** | The verification gate: lint, typecheck, tests, and reproduce-before-fix discipline. | A bug fix must first *reproduce* the bug, then prove the fix with a test, before it's called done. |
| **smoke-testing** | Proves the *operator-visible outcome* on the deployed surface — not just "tests passed." | After deploy, it actually exercises the feature to confirm it works for a real user. |
| **code-review** | Reviews the diff against spec/decisions for correctness bugs, scope creep, maintainability, rollback. | Before merge, an independent pass checks the change does what was specified — and nothing extra. |
| **security-permissions-review** | Focused review when changes touch auth, secrets, deploy config, or customer-visible behavior. | A change adds an API key + a public endpoint → it flags the sensitive surfaces and what needs sign-off. |
| **release-deploy-reporting** | Drafts the deploy handoff, captures deploy hash + probes + smoke, flips spec DRAFT→DONE. | "Ship it" → produces the deploy plan and the post-deploy evidence record. |

**Review, anti-drift & debugging**

| Skill | What it does | Real-world use case |
|---|---|---|
| **zoom-out** (FR-20) | Forces a root-cause-vs-patch check before applying a fix. | A bug keeps recurring → "are we fixing the cause or the symptom?" before patching it a third time. |
| **phase-audit** | A fresh sub-agent independently audits *all* slices of a multi-slice phase before sign-off. | A big phase shipped across 8 slices → every slice gets checked against the spec before you call it done. |
| **git-history-diagnostic** | Regression archaeology — locates the exact commit that introduced a break. | "It worked last week, broken now" → bisects history to the causing commit instead of guessing. |
| **repo-onboarding-context-map** | Builds a durable map of an unfamiliar repo (where things live, how it fits together). | Dropped into a large new codebase → get the lay of the land before editing anything. |

**Quality & discipline (the always-on rule carriers)**

| Skill | What it does | Real-world use case |
|---|---|---|
| **lightweight-lane** (FR-21) | Classifies Full vs Lightweight; small/reversible changes get a change-note + one build→verify→deploy pass. | A one-line constant bump skips heavy ceremony but is still verified and recorded. |
| **comment-policy** (FR-22) | Write-time comment policy — tripwires + retrieval pointers, not restating the code. | Comments capture the non-obvious "why" and point to the spec, instead of narrating obvious lines. |
| **documentation-budget** (FR-23) | Classifies whether a doc is needed and at which tier *before* writing it. | Stops a redundant "design doc" from being created just because a template exists. |
| **module-size-discipline** (FR-25) | Module-size ratchet — gated files stay under the ceiling (default 800 lines); over-ceiling files may only shrink. | A file creeping toward 800 lines triggers a clean extraction along a seam, not unchecked growth. |
| **token-economy** (FR-26) | Token-efficient execution + context-compression discipline (route-by-type, extract-before-reasoning, pointer-backed summaries); measured via `/token-waste-audit`. | The AI reads the slice it needs and references big results instead of re-pasting them. |
| **liveness-discipline** (FR-27) | Never launch long/silent background work bare — bound it with a timeout/watchdog (`bounded-run.sh`), finish it in-turn, or return `BLOCKED-AT-<gate>` so a hung job can't leave the agent idling silently. | A background re-verify probe stalls against a cold-start proxy → it times out with a visible line instead of the agent sitting idle until you ask "is it done?". |
| **find-wasted-effort** | Ceremony audit — process-per-outcome; reads Flow artifacts for steps that bought no safety (the sibling of `/token-waste-audit` on a different axis). | Surfaces gate stops or handoffs that never prevented anything, so you can trim ceremony deliberately. |
| **find-wasted-code** | Static friction-footgun audit — code-per-friction; scans repo source for dead-end tool calls, broken links, missing helpers, footgun configs, and a silent-push-through baseline (`/find-wasted-code`, manual-trigger, tracked report). | Surfaces the papercuts that silently dead-end an agent or teammate, with a conservative low-false-positive contract. |
| **app-quality-patterns** | Cross-project behavioral quality patterns (URL reflects view state, delete-cascade policy, empty/loading/error states…) that become spec ACs. | Building a list view → "show empty/loading/error states" and "URL reflects filters" are baked in as acceptance criteria. |

**Project setup & product (dormant until you `/onboard`)**

| Skill | What it does | Real-world use case |
|---|---|---|
| **project-onboarding** | The `/onboard` discovery interview that writes your project artifacts. | Captures your vision/audience once so the whole framework is tuned to your project. |
| **north-star** | Steers every task to `docs/north-star.md` and flags drift away from it. | A proposed feature that contradicts your stated vision gets flagged before it's built. |
| **client-vs-internal** | Steers surfaces — simple/guided/trust-first for clients, robust/power-features for internal. | A client-facing screen gets a guided design; the internal admin tool gets bulk controls. |
| **product-docs-first** | Designs per-app product docs before any code is written. | Before building, the product doc that planning builds from is written and agreed. |
| **business-logic-guardian** | Treats documented business logic as a guard layer during fixes. | A "quick fix" that would silently break a documented billing rule gets caught. |
| **product-apps-decomposition** | Decides one big app vs several focused apps. | A sprawling "CRM" request → split into focused apps so one failure can't sink the whole system. |

**Health, continuity & meta**

| Skill | What it does | Real-world use case |
|---|---|---|
| **fusebase-flow-health-check** | The read-only engine behind `/fusebase-health` — layer-by-layer drift verdicts + offered recovery. | Confirms whether CLI and Flow files conflict after an update, and fixes Flow-owned drift on confirmation. |
| **handoff** | The engine behind `/handoff` — reconstructs goal/decisions/failures/next-step into the restart template. | A complex migration spans sessions → the next chat resumes from the exact point, fatigue-free. |
| **skill-authoring** | Create/update reusable skills (clean-room classified; includes domain-expert mode). | A waste or quality pattern recurs across audits → capture it as a new skill rule the right way. |

## What it costs

FuseBase Flow runs natively in your IDE through the FuseBase CLI. There are **no per-token platform fees** -- you pay only for the AI subscription you already have (Claude Code, Codex, Cursor, Gemini, or Copilot).

## Coming from ad-hoc agent prompting?

If today you open Claude Code / Codex / Cursor and just say *"build me X"*, you already have everything FuseBase Flow needs -- it doesn't replace your agent, it **gives it a process**:

| Without FuseBase Flow | With FuseBase Flow |
|---|---|
| One giant prompt -> one giant diff you have to trust | Spec -> decisions -> tasks -> one-commit-per-task you can review |
| "It worked on my machine" | Verification gate + outcome-based smoke before deploy |
| Scope creep mid-session | Locked decisions; supersede discipline (FR-18) |
| Re-explaining context every session | Durable repo artifacts (`docs/specs/`, `docs/tmp/handoff/`) |
| Risky deploys | Deploy gated on an explicit approval artifact |

Nothing to uninstall from your agent -- drop the files in, attest once, keep working.

## Contents

- [Built by FuseBase](#built-by-fusebase)
- [Who it's for](#who-its-for)
- [Why a framework (and why two agents)](#why-a-framework-and-why-two-agents)
- [How it stays reliable](#how-it-stays-reliable)
- [What it costs](#what-it-costs)
- [Coming from ad-hoc agent prompting?](#coming-from-ad-hoc-agent-prompting)
- [What's in the box](#whats-in-the-box)
- [Quick start (GitHub template)](#quick-start-github-template)
- [Filing your first ticket](#filing-your-first-ticket)
- [Supported agents & IDEs](#supported-agents--ides)
- [Using sub-agents](#using-sub-agents)
- [Skill catalog](#skill-catalog)
- [Installing into an existing project](#installing-into-an-existing-project)
- [Health check & recovery](#health-check--recovery)
- [How enforcement works](#how-enforcement-works)
- [Default workflow modes](#default-workflow-modes)
- [Validating an installation](#validating-an-installation)
- [FAQ & troubleshooting](#faq--troubleshooting)
- [What's inside](#whats-inside)
- [Clean-room, license & publishing](#clean-room-license--publishing)

## What's in the box

FuseBase Flow has two layers. **Flow** is the lifecycle: specs, decisions, tasks, gates, reviews, deploy handoffs, and smoke discipline. The bundled **FuseBase Apps domain skills** are the build layer: app architecture, FuseBase CLI usage, dashboards, gate, secrets, routing, logs, and scaffold checks — so the agent can ship real apps, not just plan them.

See [`docs/fusebase-cli-edition.md`](docs/fusebase-cli-edition.md) for the layer boundary map and overlap table.

| Is | Isn't |
|---|---|
| Repo-local discipline (rules, skills, workflows, hooks, policies, templates) | A coding agent or chat product |
| A GitHub template you copy into projects | A SaaS or external service |
| Tool-portable across multiple AI coding surfaces | Tied to one vendor |
| Stdlib-first Python + bash + git | Requires heavy frameworks (FastAPI, daemons, servers) |
| Local-only hooks | Network webhooks |

## Quick start (GitHub template)

1. On GitHub, click **"Use this template"** → "Create a new repository".
2. Clone your new repo locally.
3. Open the repo in your IDE / agent of choice. The agent reads `AGENTS.md` first; from there it follows `FLOW_RULES.md`.
4. (Optional) Run the convenience installer:

```bash
   bash install.sh
   ```

This installs git fallback hooks, runs preflight, and offers to mirror canonical skills into the provider folders. It does NOT install heavy dependencies and does NOT require any external service.

5. Install the runtime dependency for hook handlers:

```bash
   pip install -r hooks/requirements.txt
   ```

(Only PyYAML; ~100 KB.)

### Or install as a Claude Code plugin

Prefer one command? Add the marketplace and install — skills, commands, and sub-agents load namespaced:

```
/plugin marketplace add fusebase-dev/fusebase-flow
/plugin install fusebase-flow@fusebase-flow
```

### Optimize it for your project (optional)

Out of the box FuseBase Flow runs generically. To steer it toward *your* team's vision, run onboarding — the Product Owner interviews you, then writes the project artifacts (North Star, audience, per-app product docs) that the rest of the skills read:

```
/onboard          # Product Owner discovery interview → writes docs/north-star.md, etc.
/product-owner    # start a Product Owner session for a ticket
```

Skipping is fine — nothing is created unless you provide it, and the framework behaves exactly like a generic install until you opt in.

## Filing your first ticket

1. Tell the agent: *"Let's ship `<feature description>`."*
2. The agent invokes the `requirements-specification` skill, drafts `docs/specs/<slug>/spec.md`, and runs clarify questions.
3. After clarify resolves, the agent invokes `implementation-planning` to produce `decisions.md`, `tasks.md`, `verification-gate.md`, plus a saved handoff at `docs/tmp/handoff/<YYYY-MM-DD>-<slug>-implement.md`.
4. Open a fresh agent session, paste the handoff, and the AI Developer executes the task chain — stopping at the verification gate.
5. Paste the gate report back to the originating session. Run `code-review`; `security-permissions-review` runs only when the diff touches a sensitive surface (auth/secrets/env/deploy config/external messages/production data), else the review records `security: N/A — no sensitive surface`.
6. If clean, the operator says *"prepare deploy"* — the `release-deploy-reporting` skill drafts the deploy handoff, you paste it into the AI Developer session, deploy runs, probes and outcome-based smoke verify.

The full eight-phase lifecycle lives at [`workflows/eight-phase-flow.md`](workflows/eight-phase-flow.md).

**Docs layout.** Your own ticket artifacts are created on demand — nothing to scaffold. (The template tree does carry FuseBase Flow's OWN dev history under `docs/specs/`, `docs/changes/`, `docs/release-notes/`, `docs/backlog/` — upstream framework records, not your project's; the existing-repo copy commands below copy only the live framework docs, never the dev history.) Expected paths once you start: `docs/specs/<slug>/` (spec · decisions · tasks · verification-gate), `docs/tmp/handoff/` (cross-session handoffs), `docs/changes/` (Lightweight-lane ledger, opt-in), `docs/backlog/` (parked tickets). Run `/onboard` first if you want project artifacts (`docs/north-star.md`, project values) before ticket #1.

## Supported agents & IDEs

**Get started — find your tool, do the one step.** (After *Use this template* → clone → open the repo in your tool of choice.)

| Your AI tool | Then do this |
|---|---|
| **Claude Code** | Auto-reads `CLAUDE.md`. Say *"Let's ship `<feature>`."* — or tailor it first with `/onboard`, or install as a plugin: `/plugin marketplace add fusebase-dev/fusebase-flow` |
| **Codex** | Say *"Read `AGENTS.md` and follow `FLOW_RULES.md`,"* then *"Let's ship `<feature>`."* |
| **Cursor** | Rules auto-load from `.cursor/rules/`. Say *"Let's ship `<feature>`."* |
| **GitHub Copilot / VS Code** | `.github/copilot-instructions.md` auto-loads. Say *"Let's ship `<feature>`."* |
| **Gemini** | Reads `GEMINI.md` + `AGENTS.md`. Say *"Let's ship `<feature>`."* |

Compatibility files per tool:

- **Anthropic Claude Code** — `CLAUDE.md`, `.claude/skills/`, `.claude/settings.json.example`
- **OpenAI / ChatGPT Codex** — `AGENTS.md`, `.agents/skills/`, `.codex/config.toml.example`, `.codex/hooks.json.example`, `.codex-plugin/plugin.json`
- **Cursor** — `.cursor/rules/*.mdc`, `AGENTS.md`
- **GitHub Copilot / VS Code** — `.github/copilot-instructions.md`, `.github/instructions/*.instructions.md`, `AGENTS.md`
- **Gemini / Antigravity-style IDE agents** — `GEMINI.md`, `AGENTS.md`
- **Generic local repo workflows** — `AGENTS.md` + root-level framework dirs (`flow-skills/`, `workflows/`, `policies/`, `templates/`, `hooks/`) + git fallback hooks + local scripts

`.claude/skills/` and `.agents/skills/` include both canonical Flow skill mirrors and FuseBase Apps domain skills. The audit mirror manifest tracks the Flow mirrors only.

The full surface support breakdown lives at [`docs/compatibility.md`](docs/compatibility.md).

## Using sub-agents

Two role-shaped sub-agents cover the full eight-phase lifecycle. They are **opt-in** — the framework remains fully usable via the skill-and-workflow pattern alone — but they make role boundaries explicit and harder to drift across.

| Sub-agent | Owns | Skills it invokes |
|---|---|---|
| **Product Owner** | Specify, Clarify, Plan, design discovery/ideation, Decisions, Tasks, draft-verification-gate, smoke contract definition, clean-room skill classification, post-implement code-review (+ security-permissions-review when the diff matches its trigger list), deploy-handoff drafting, spec DRAFT→DONE flip, **plus Architect responsibilities inline on escalation** (>10 files / cross-cutting refactor / platform blocker / blocked migration) | `requirements-specification`, `design-discovery-ideation`, `implementation-planning`, `smoke-testing`, `task-delegation`, `skill-authoring`, `code-review`, `security-permissions-review`, `release-deploy-reporting` |
| **AI Developer** | Run gate, Implement T-chain (one task = one commit; stops at gate), implement approved framework skill changes, Run deploy command (gated on approval artifact, captures hash, runs probes and smoke evidence) | `validation-and-qa`, `smoke-testing`, `task-delegation`, `skill-authoring`, `repo-onboarding-context-map` |

Both sub-agents always load the mandatory `communication` and `role-discipline` skills.

FuseBase Flow also ships FuseBase Apps app-agents (`app-architect`, `app-create-checker`) as domain assets. They support FuseBase Apps architecture and scaffold validation; they do not replace the Flow Product Owner or AI Developer role agents.

### Invoking from Claude Code

```
> Use the product-owner sub-agent. Let's ship pagination.
```

```
> Use the ai-developer sub-agent. Run docs/tmp/handoff/2026-05-09-pagination-implement.md.
```

Claude Code auto-discovers `.claude/agents/<name>.md`.

### Invoking from Codex

Codex discovers skills from `.agents/skills/` and, when installed as a plugin, from `.codex-plugin/plugin.json`. Use the `product-owner` skill or search `/product` / `/skills` to activate Product Owner:

```
> Use the product-owner skill. Let's ship pagination.
```

The direct agent-file fallback still works when the skill surface is unavailable:

```
> Read .codex/agents/product-owner.md and operate as Product Owner per its instructions.
> Let's ship pagination.
```

```
> Read .codex/agents/ai-developer.md and operate as AI Developer per its instructions.
> Run docs/tmp/handoff/2026-05-09-pagination-implement.md.
```

### Updating sub-agent definitions

Edit the canonical at `agents/<name>/AGENT.md`, then regenerate provider mirrors:

```bash
bash hooks/local/mirror-agents.sh
```

Preflight will warn on drift if the mirrors and canonical fall out of sync. Full release notes for the v2.1.0 sub-agents launch live at [`docs/release-notes/v2.1.0.md`](docs/release-notes/v2.1.0.md).

## Skill catalog

Skills are on-demand expertise the agent loads when a task matches the skill's description. **34 canonical Flow skills** govern the lifecycle and project-optimization; **22 FuseBase Apps domain skills** supply the app-building knowledge. You usually describe the work and let the matcher load the right one; Codex can also expose the `product-owner` bridge when you search `/product` or `/skills`.

### Flow lifecycle skills (33)

| Phase | Skill | What it does |
|---|---|---|
| _always_ | `communication` ★ | Mode A chat output + Mode B artifact writing |
| _always_ | `role-discipline` ★ | Enforces role boundaries + FR refusal phrasing |
| Specify / Clarify | `requirements-specification` | Drafts the spec + clarify questions + acceptance criteria |
| Clarify / Plan | `design-discovery-ideation` | Divergent options & UI/product directions before lock |
| Plan / Decisions / Tasks | `implementation-planning` | Produces decisions, tasks, verification-gate, handoff |
| Tasks / Implement | `task-delegation` | Safe parallel/subagent slicing of independent tasks |
| Verify / Implement | `validation-and-qa` | Gate report: lint, typecheck, tests, repro-before-fix |
| Implement / Deploy | `smoke-testing` | Proves the operator-visible outcome on the deployed surface |
| Review | `code-review` | Diff vs spec/decisions, maintainability, scope, rollback |
| Review | `security-permissions-review` | Auth, secrets, deploy-config, customer-visible changes |
| Deploy | `release-deploy-reporting` | Deploy handoff, hash + probes + smoke, DRAFT→DONE flip |
| Onboarding | `repo-onboarding-context-map` | Durable context map for a new/unfamiliar repo |
| Meta | `skill-authoring` | Create/update reusable skills (clean-room classified; incl. domain-expert mode) |
| Code-writing | `comment-policy` | FR-22 write-time carrier — tripwire + retrieval-pointer comment policy |
| Health | `fusebase-flow-health-check` | Read-only overlay drift diagnosis + offered recovery |
| Anti-drift | `zoom-out` | FR-20 — root-cause-vs-patch check before a fix |
| Review | `phase-audit` | Independent sub-agent audit of all slices of a phase |
| Debug | `git-history-diagnostic` | Regression archaeology — locate the causing commit |
| Role activation | `product-owner` | Codex-visible bridge for `/product-owner` and Product Owner session activation; reuses the canonical Product Owner role agent instead of duplicating it |
| Project setup | `project-onboarding` | `/onboard` discovery interview → writes project artifacts |
| Project focus | `north-star` | Steers work to `docs/north-star.md` (no-op if absent) |
| Audience | `client-vs-internal` | Simple-for-client / robust-for-internal (no-op if absent unless the operator explicitly requests it) |
| Product | `product-docs-first` | Design per-app product docs before code (no-op if absent) |
| Guard | `business-logic-guardian` | Protect documented business logic during fixes (no-op if absent) |
| Architecture | `product-apps-decomposition` | Product → focused apps (generic + steers to product doc) |
| Lane / speed | `lightweight-lane` | FR-21 — classify Full vs Lightweight; small/reversible changes use a change-note + one build→verify→deploy pass instead of the full chain |
| Docs budget | `documentation-budget` | FR-23 — tier-classify (0-4) before any AI-consumed artifact; canonical ownership + pointers over duplication |
| Continuity | `handoff` | Writes active session state to `docs/tmp/handoff.md` (16-section template); operator-triggered (`/handoff`, `Mode: restart`); autonomous runs may update it as `Mode: run-ledger` (announced in chat) |
| Structure | `module-size-discipline` | FR-25 — module-size ratchet; gated source ≤ ceiling (default 800), over-ceiling files shrink-only; extraction on a responsibility seam is in-scope |
| Quality | `app-quality-patterns` | Cross-project behavioral quality patterns (QP-xx: URL reflects view state, delete cascade policy, empty/loading/error states…) — become spec ACs by ID; Verify lines are copy-ready smoke recipes |
| Economy | `token-economy` | FR-26 — token-efficient execution (scoped reads, no re-reads of unchanged files, two-strike retry rule, targeted edits) with per-rule quality guards; measured via `/token-waste-audit` — plus **context-compression discipline** for large context/output (route-by-type, extract-before-reasoning, pointer-backed summaries, reopen-original-before-deciding); `/token-waste-audit` now flags `large-output` + `repeat-output` candidates across built-in **and MCP** tools |
| Liveness | `liveness-discipline` | FR-27 — never launch long/silent background work bare; ≥1 liveness guarantee before launch (bound via `hooks/local/lib/bounded-run.sh`, complete in-turn, or return `BLOCKED-AT-<gate>` + a record-then-read pointer) so a hung job reaches completion-or-death instead of a silent idle; diagnose a suspected hang by activity/mtime not 0-byte existence; **no blocking gate, no verification hook** (a hang is undetectable by construction — enforcement = bounded-run tooling + present-by-construction delivery) |
| Ceremony audit | `find-wasted-effort` | A2 — process-per-outcome ceremony audit (`/find-wasted-effort`); reads Flow artifacts on disk for ceremony that bought no safety outcome; read-only, findings are review candidates (never auto-prune); sibling of `/token-waste-audit` on a different axis |
| Code audit | `find-wasted-code` | Static friction-footgun audit (`/find-wasted-code`, manual-trigger only via `disable-model-invocation`); scans repo source for dead-end tool calls, broken links, missing helpers, footgun configs + a silent-push-through baseline; conservative confirmed-only-when-provable contract; tracked report at `docs/wasted-code/report.md`; sibling of the two audits on the code-per-friction axis |

★ = mandatory, loaded every session. The last 9 (zoom-out … product-apps-decomposition) shipped in v3.3–v3.5; `lightweight-lane` v3.7, `comment-policy` v3.11, `documentation-budget` v3.12, `handoff` v3.14, `module-size-discipline` v3.16, `app-quality-patterns` v3.19, `token-economy` v3.20, `find-wasted-effort` v3.22, `liveness-discipline` v3.28, `find-wasted-code` v4.5. The project-* / north-star / client-vs-internal / product-* / guard skills are **artifact-gated by default** — dormant until onboarding creates their `docs/` artifact (client-vs-internal also activates on an explicit operator posture-check request). `product-owner` is an activation bridge, not an alternate role definition.

### FuseBase CLI provider skills (22)

<details>
<summary>App build · runtime · data · ops domain skills</summary>

| Group | Skills |
|---|---|
| **Build & structure** | `fusebase-cli`, `app-dev-practices`, `app-routing`, `app-ui-design` |
| **Backend & infra** | `app-backend`, `app-secrets`, `app-sidecar`, `managed-integrations` |
| **Data & dashboards** | `fusebase-dashboards`, `fusebase-gate`, `file-upload`, `fusebase-portal-specific-apps` |
| **Auth & errors** | `handling-authentication-errors`, `invite-with-password` |
| **Debug & ops** | `dev-debug-logs`, `remote-logs`, `api-exploration`, `mcp-gate-debug`, `app-api-contract-testing`, `app-e2e-tests` |
| **Docs & git** | `app-business-docs`, `git-workflow` |

</details>

### Which one do I use?

| Situation | Reach for |
|---|---|
| Starting a new ticket | `requirements-specification` (or the **Product Owner** sub-agent) |
| Plan is set, time to build | the **AI Developer** sub-agent + `validation-and-qa` |
| "Is this diff safe?" | `code-review` (+ `security-permissions-review` when the diff matches its trigger list — auth/secrets/deploy-config/etc.) |
| "Did the deploy actually work?" | `smoke-testing` |
| "Did `fusebase update` break Flow?" | `fusebase-flow-health-check` (or `/fusebase-health`) |

## Installing into an existing project

Do not blindly copy this repository over an existing project.

If the target repo already contains `AGENTS.md`, `CLAUDE.md`, `.gitignore`, `.claude/settings.json`, `.mcp.json`, `.cursor/mcp.json`, `.agents/skills/`, `.claude/skills/`, `.codex-plugin/plugin.json`, `fusebase.json`, or `skills-lock.json`, use the FuseBase CLI / MCP-safe install path:

- append to `AGENTS.md`
- append to `CLAUDE.md`
- append to `.gitignore`
- add skills into existing skill folders only when no name collision exists
- never replace MCP configuration
- never replace active Claude settings or hooks
- review `.claude/settings.json.example` before merging lifecycle hooks

See [`docs/install-fusebase-cli-project.md`](docs/install-fusebase-cli-project.md). The general existing-repo guide lives at [`docs/install-existing-project.md`](docs/install-existing-project.md).

<details>
<summary>Copy-into-existing-repo commands</summary>

```bash
# From the existing repo's root, copy the framework + the always-on baseline:
SRC=/path/to/fusebase-flow

cp -R $SRC/flow-skills ./
cp -R $SRC/workflows ./
cp -R $SRC/hooks ./
cp -R $SRC/policies ./
cp -R $SRC/templates ./
cp -R $SRC/audit ./
cp -R $SRC/state ./

# Live framework docs only:
mkdir -p docs && cp $SRC/docs/*.md docs/
cp -R $SRC/docs/translations docs/   # optional: translated READMEs
# upstream dev history (docs/specs, docs/changes, docs/release-notes, docs/backlog,
# docs/handoff, docs/assets …) is deliberately NOT copied

cp $SRC/AGENTS.md ./
cp $SRC/CLAUDE.md ./
cp $SRC/GEMINI.md ./
cp $SRC/FLOW_RULES.md ./
cp $SRC/FLOW_RULES_HISTORY.md ./
cp $SRC/VERSION ./
cp $SRC/install.sh ./
cp $SRC/.gitattributes ./
cp $SRC/.gitignore ./
cp $SRC/.python-version ./
cp -R $SRC/.github ./

# Copy only the provider/IDE compatibility surfaces you use:
cp -R $SRC/.claude ./       # Anthropic Claude Code
cp -R $SRC/.agents ./       # OpenAI / ChatGPT Codex
cp -R $SRC/.codex ./        # OpenAI / ChatGPT Codex
cp -R $SRC/.cursor ./       # Cursor

# Then run the installer:
bash install.sh
```

</details>

## Health check & recovery

When FuseBase Flow is installed on top of the FuseBase CLI, the two share a repo. Flow's recovery model is **CLI-first, Flow-second**: **Flow never overwrites FuseBase CLI-owned files or instructions.** The health engine classifies every drift by ownership layer and recovers only what Flow owns.

| Layer | Examples | Who restores it |
|---|---|---|
| **CLI-owned** | CLI provider skills, `.claude/hooks/**`, MCP config, `fusebase.json`, `skills-lock.json`, existing CLI instructions | FuseBase CLI refresh/update — Flow **diagnoses only**, never writes |
| **Flow-owned** | Flow skill/agent mirrors, `AGENTS.md`/`CLAUDE.md` overlay blocks, health-check skill + `/fusebase-health` command, Flow-owned hook assets | Flow recovery script |
| **Shared** | `.claude/settings.json` | **Merged**, never replaced |

An ownership manifest backs this split, and a read-only conflict reporter surfaces the per-layer verdict.

| Need | Command |
|---|---|
| Check health + layer verdict (read-only) | `bash hooks/local/fusebase-flow-health-check.sh` or `/fusebase-health` (Claude Code) or *"is FuseBase Flow healthy?"* (any agent) |
| Detailed CLI/Flow ownership & conflict report + drift advisory (read-only) | `bash hooks/local/check-cli-flow-conflicts.sh` |
| Re-stamp CLI vendor provenance (after a `fusebase update` or an intentional CLI asset change) | `bash hooks/local/stamp-cli-provenance.sh` |
| Recover Flow-owned + shared surfaces | `bash hooks/local/post-fusebase-update.sh` or reply `yes` when the skill offers recovery in chat |
| (Re)wire Flow lifecycle hooks into `.claude/settings.json` (opt-in) | `bash hooks/local/post-fusebase-update.sh --wire-hooks` |
| Restore CLI-owned drift | Run the current **FuseBase CLI refresh/update first**, then `post-fusebase-update.sh` for the Flow layer |
| **Upgrade Flow content** (skills/rules/agents) to latest upstream | **From an install ≤ 4.6.1 the only supported route is `bash hooks/local/bootstrap-upgrade.sh -- --auto-yes`** — your installed engine predates the classifier and cannot deliver 4.7.0 correctly (why: [Upgrading an installed overlay](#upgrading-an-installed-overlay-v360)). Already on 4.7.0+: `bash hooks/local/upgrade.sh` (refresh `.fusebase-flow-source/` first; `--dry-run` to preview) |
| ~~Upgrade only the engine + recovery scripts~~ | `upgrade-engine.sh` is a deprecated shim (v3.18.0) — it forwards to `bash hooks/local/upgrade.sh` |
| Re-sync embedded `vX.Y.Z` strings to the `VERSION` file | `bash hooks/local/sync-version-strings.sh` |
| Avoid drift on routine updates | `fusebase update --skip-skills` (preserves FuseBase Flow overlay) |

<details>
<summary>What the health check verifies, verdicts, deferrals & recovery flow</summary>

### What the health check verifies

12 inventory checks per run:

- VERSION file
- AGENTS.md overlay block (`## FuseBase Flow — workflow lifecycle overlay`, appended inside the CLI-preserved custom wrapper)
- CLAUDE.md overlay block (`## FuseBase Flow — additional rules (overlay)`)
- `.claude/settings.json` lifecycle events (auto-discovered count)
- `.claude/skills/` Flow mirror count (auto-discovered set; CLI provider skills may also be present)
- `.claude/agents/` Flow agent mirror count (auto-discovered set; CLI app agents may also be present)
- Health-check skill self-presence
- Recovery script presence + executable
- Overlay templates folder presence
- `preflight.sh` clean
- `hooks/tests/run-tests.sh` passing
- Windows `shell:true` patch on `.claude/hooks/run-typecheck-apps.js` (CVE-2024-27980 mitigation)
- CLI vendor provenance manifest (`audit/cli-vendor-manifest.json`) present + parseable (advisory)

Plus active approval artifacts in `state/approvals/` are surfaced informationally so artifact-attributable test failures don't trigger false BROKEN verdicts.

### CLI vendor provenance & drift advisory (v3.2.0+)

FuseBase Flow vendors a frozen copy of FuseBase CLI-owned assets (22 provider skills + `references/`, 2 app-agents, 4 quality hooks; FuseBase CLI 0.29.8). Re-vendoring goes through `bash hooks/local/refresh-cli-vendor.sh --source <cli-tree> --cli-version <x.y.z>`, which takes upstream content while preserving Flow-authored `CUSTOM:SKILL` blocks byte-for-byte (a plain `cp -r` destroys them) and records each file's sha256 **computed from the source CLI tree** in `audit/cli-upstream-manifest.json`. `bash hooks/local/stamp-cli-provenance.sh` then writes `audit/cli-vendor-manifest.json` (a committed document of record) with `source_cli_version` **derived** from that upstream record rather than asserted, plus per-file `upstream_sha256` / `matches_upstream`, so "matches upstream" is distinguishable from "matches whatever we shipped". A tree that has never been re-vendored keeps the `"unknown"` sentinel and stays advisory-only.

`check-cli-flow-conflicts.sh` then hashes each **present** CLI asset against that manifest and surfaces two **advisory** findings (informational only — they never change the verdict or exit code):

| Advisory | Meaning | What to do |
|---|---|---|
| `CLI_SNAPSHOT_STALE` | a present CLI asset's sha256 differs from the bundled snapshot (newer or locally modified) — distinct from `MISSING`, which still escalates to `CLI_LAYER_DRIFT` | expected after `fusebase update`; if intentional, re-stamp with `stamp-cli-provenance.sh` |
| `CLI_CUSTOM_AT_RISK` | a CLI-owned skill carries a `CUSTOM:SKILL` block a future CLI refresh may overwrite | back up the block before the next `fusebase update` |

This guards the **two-writer hazard** — `fusebase update` and the Flow snapshot both write the same provider paths. The documented install copy is non-clobbering for CLI-owned paths, and Flow recovery never writes them. See [docs/fusebase-cli-edition.md](docs/fusebase-cli-edition.md) § "Two-writer hazard".

The Claude Code Stop hooks shipped in `.claude/settings.json.example` mirror the FuseBase CLI 0.25.16 wired set: `run-lint-on-stop.sh`, `run-typecheck-on-stop.sh`, `quality-check-apps.js`, followed by Flow `stop.py`. The merge is **preserve-only** — it appends `stop.py` and keeps every existing CLI Stop hook, and never static-injects a hook from a name (an older-CLI project that still wires `run-typecheck-apps.js` keeps it; Flow simply stops re-adding it).

### Verdicts (ownership-layer model)

| Verdict | Exit | Meaning | Recovery posture |
|---|:---:|---|---|
| `HEALTHY` | 0 | CLI-owned, Flow-owned, and shared-merge surfaces all intact **and every critical check ran clean** | No action |
| `CLI_LAYER_DRIFT` | 1 | CLI-owned assets missing or structurally damaged | **Run FuseBase CLI refresh/update first**, then Flow recovery — Flow does not write CLI-owned files |
| `FLOW_LAYER_DRIFT` | 1 | Flow-owned mirrors or overlay files missing/drifted | Flow recovery offered |
| `SHARED_MERGE_DRIFT` | 1 | Shared files missing Flow overlay/merge additions | Flow recovery offered (merge, not replace) |
| `BROKEN` | 2 | A completed critical check failed, or a sub-script crashed (rc≠0, no parsable result) | Inspect the broken item first; no recovery |
| `EXCEPTION_IN_EFFECT` | 3 | Drift covered by active approval/deferral artifacts in `state/approvals/` | Surface the artifact; no automatic recovery |
| `PARTIAL_UNVERIFIED` | 4 | A critical check (preflight, hook tests, conflict reporter) was skipped/timed-out/unavailable; nothing that ran proves drift or breakage | **Not full health, not a failure** — re-run with more time, raise the relevant `FFHC_*_TIMEOUT` knob, or run the named check directly |

**Bounded execution + `--fast` / `--no-upstream` (v3.24.0+).** The slow verdict-affecting ops (preflight, hook tests, conflict reporter, upstream `git fetch`) are time-bounded so a network-impaired or large-repo host can't make the read-only diagnostic appear to hang. A timed-out/skipped **critical** check ⇒ `PARTIAL_UNVERIFIED` (exit 4) — never a false `HEALTHY`. The upstream comparison is **optional**: its fetch timing out is a "upstream not verified" note only, never exit 4. Flags: `--no-upstream` (full local verdict, exit 0 OK) and `--fast` (skips the slow hook tests for a quick verdict — keeps preflight — but is explicitly partial: **exit 4, never 0**). Timeouts are env-overridable: `FFHC_FETCH_TIMEOUT` (15s), `FFHC_PREFLIGHT_TIMEOUT` (30s), `FFHC_CONFLICT_TIMEOUT` (30s), `FFHC_TESTS_TIMEOUT` (60s); worst-case bounded full run ≈ 155s. With neither `timeout` nor `gtimeout` present, bounded ops are skipped ⇒ `PARTIAL_UNVERIFIED` (or opt into unbounded with `FFHC_ALLOW_UNBOUNDED=1`). **Any caller keying off the exit code must treat 4 as partial/unverified — not healthy, not a hard failure.**

**Flag-gated CLI skills are absent-by-design, not drift (v3.8.2+).** The FuseBase CLI gates some provider skills behind config flags (`portal-specific-apps`, `managed-integrations`, `git-init`/`git-debug-commits`, `app-business-docs`, `mcp-gate-debug`) and removes the skill when the flag is off. The health check treats such an **absent flag-gated skill as a benign INFO** (not `CLI_LAYER_DRIFT`) — the only correct remediation is `fusebase config set-flag <flag>` if you actually want the feature, never `fusebase update`. An absent skill whose flag is provably **on** is still genuine drift; non-flag-gated absences are unaffected.

**Flow lifecycle hooks off = benign, not drift (v3.8.3+).** Hook wiring is opt-in (v3.6.0+). A `.claude/settings.json` that exists (CLI hooks present) but doesn't wire Flow's `stop.py` now reads as a benign INFO ("hooks not wired — opt-in"), not `SHARED_MERGE_DRIFT`. Wire them with `post-fusebase-update.sh --wire-hooks` if you want them; a Flow merge that *clobbered* existing CLI Stop hooks is still flagged.

> ℹ️ **Canonical skills live in `flow-skills/` (v3.9.0+), not root `skills/`.** Earlier versions used root `skills/`, which collided with the FuseBase CLI's `⚠️ The ./skills folder is obsolete and should be deleted` warning. As of v3.9.0 Flow's canonical source is the Flow-namespaced `flow-skills/` — the CLI never touches it, so that warning is now safe to follow. `mirror-skills.sh`, `upgrade.sh`, and the health mirror-count all build on `flow-skills/`; `upgrade.sh` auto-migrates an existing install (moves `skills/` → `flow-skills/`, retires the old dir with a backup). The health check flags an empty/absent `flow-skills/` (while Flow mirrors exist) with restore steps (`upgrade.sh` / `bootstrap-upgrade.sh` / `git checkout -- flow-skills/`).

Recovery (`post-fusebase-update.sh`) restores **only** Flow-owned assets and shared Flow additions — Flow skill/agent mirrors, `AGENTS.md`/`CLAUDE.md` overlay blocks, the `fusebase-flow-health-check` skill, and `.claude/commands/fusebase-health.md`. It never touches `.claude/hooks/**`, CLI provider skills, MCP config, `fusebase.json`, `skills-lock.json`, or active `.codex/config.toml`. **Hook wiring is opt-in, and the opt-in is remembered** (opt-in since v3.6.0; automatic restoration since v4.15.0): recovery touches `.claude/settings.json` only where an earlier `--wire-hooks` recorded an ENABLED wiring intent for the `claude_settings` surface (`state/audit/flow-hook-wiring-intent.json`). Such a tree gets its Flow lifecycle events restored automatically and the run reports which events it added. With no marker, recovery leaves the file alone — pass `--wire-hooks` to opt in, or `--forget-hook-wiring` to record an opt-out. The CLI's own Stop hooks are preserved either way.

### Deferral artifacts (v2.4.0+)

When an install brief or operator deliberately omits parts of the canonical FuseBase Flow setup (e.g. lifecycle hooks not wired, Windows patch not applied per protected-paths discipline), file a **deferral artifact** at `state/approvals/health_check_deferral-<slug>-<YYYYMMDD>.json` listing the check_ids being deferred. Engine reclassifies matching drift items from `LOCAL_DRIFT` → `LOCAL_DEFERRED` (⊘ symbol in the report) and verdict drops to `EXCEPTION_IN_EFFECT` (exit 3).

See [docs/health-check-deferrals.md](docs/health-check-deferrals.md) for the artifact schema, the canonical check_id taxonomy, examples, and operator workflow for adding/removing deferrals.

### Recovery flow (the diagnose-then-offer pattern)

The skill is read-only during diagnosis. When drift is detected and recoverable, the skill **offers** recovery in chat:

```
Run recovery now? It will:
  • Restore AGENTS.md overlay block in the CLI-preserved custom wrapper (if missing)
  • Re-apply Windows shell:true patch (if missing)
  • Re-mirror FuseBase Flow skills + sub-agents (no-op if already present)
  (Lifecycle-hook wiring into .claude/settings.json is opt-in — run
   post-fusebase-update.sh --wire-hooks separately.)

Reply `yes` / `run it` / `fix it` / `proceed` to execute.
Reply anything else to halt and decide later.
```

On affirmative reply → recovery executes + re-check + report new verdict. On any non-affirmative reply (silence, `no`, a question) → halt. Operator authority preserved (PO.5 from `role-discipline` skill); friction reduced — no terminal context-switch needed for most cases.

The recovery script is **idempotent** — safe to run multiple times. Only re-applies pieces that are actually missing.

### Upgrading an installed overlay (v3.6.0+)

There are three upgrade tools, by scope:

- **`bash hooks/local/upgrade.sh`** — the in-place **content** upgrade. Use this when a newer Flow ships new/changed skills, rules, agents, workflows, policies, templates, **or hooks**. It refreshes the canonical content (incl. the `hooks/` layer — so the hook handlers and the upgrade tooling itself stay current) from `.fusebase-flow-source/`, re-mirrors it, syncs the derived attestation strings (version + FR-range + skill count), refreshes drifted AGENTS.md/CLAUDE.md overlay blocks **carrying your `FLOW:PRESERVE` region forward** (it never clobbers your `### Project-specific values`), then bumps `VERSION` **last**. `--dry-run` previews the plan; backups are written with a `.pre-upgrade-<ts>` suffix and are removed — once you have validated the upgrade — with `bash hooks/local/cleanup-flow-backups.sh --all` (or by naming exact targets). That tool's destructive authority is exact managed-stem membership plus an exact `.pre-upgrade-<YYYYMMDDTHHMMSSZ>` suffix, so it refuses absolute paths, `..`, globs, symlinks, non-members and anything resolving outside the repo root. It does **not** copy framework dev-docs into your `docs/` — pass `--with-framework-docs` to stage them under `docs/_fusebase-flow/`.
- **`bash hooks/local/bootstrap-upgrade.sh`** — the **first hop for a pre-3.6.0 install** that has no `upgrade.sh` yet. It stages an upstream copy at `.fusebase-flow-source/`, copies the engine scripts into `hooks/local/`, then hands off to `upgrade.sh` (passes through flags after `--`). For an install so old it lacks even this script, run the equivalent one-liner:
 ```bash
 git clone --depth 1 https://github.com/fusebase-dev/fusebase-flow.git .fusebase-flow-source \
 && cp .fusebase-flow-source/hooks/local/{upgrade,upgrade-engine,sync-version-strings,post-fusebase-update,mirror-skills,mirror-agents,preflight}.sh hooks/local/ \
 && bash hooks/local/upgrade.sh --dry-run
 ```
- **`bash hooks/local/upgrade-engine.sh`** — **deprecated shim (v3.18.0):** forwards to `upgrade.sh`, which covers the engine + recovery scripts and everything else.

All accept `.fusebase-flow-source/` as either a git clone (enables HEAD/diff reporting) or a plain directory copy (the documented install end-state, which drops `.git`); a plain dir falls back to VERSION-file comparison instead of erroring.

> ⚠️ **Upgrading FROM ≤3.20.0: prefer the bootstrap path.** Engines before v3.20.1 overwrite their own running script while refreshing `hooks/` and can abort mid-upgrade with a `syntax error` (offset-dependent; deterministic on some hops). Two safe options: run `bash hooks/local/bootstrap-upgrade.sh -- --auto-yes` (stages the new engine *first*, so the self-overwrite is byte-identical and harmless — works on any 3.8.0+ install, not just pre-3.6.0), or simply **re-run `upgrade.sh` after the abort** — the refreshed engine completes the remaining steps idempotently. v3.20.1+ engines parse the whole file before executing (`main()` wrapper) and are immune.

> ⚠️ **Upgrading FROM a pre-v3.25 install: use the bootstrap path.** Run `bash hooks/local/bootstrap-upgrade.sh -- --auto-yes` for the v3.25.x hop. v3.25.0 added a baseline merge-preserve step (it keeps your project's own over-ceiling `policies/module-size-baseline.txt` rows instead of letting the wholesale `policies/` refresh clobber them), but **that merge logic ships inside the version you're upgrading TO** — your *installed* old `upgrade.sh` has no merge code, and even running a freshly-copied `upgrade.sh` directly fails if its sourced lib (`hooks/local/lib/`) hasn't been staged first. The bootstrap path stages the new engine **and** `hooks/local/lib/` before handoff, so the merge actually runs on the adoption hop. If a baseline was clobbered (you'll see a loud `module-size baseline was NOT merge-preserved` warning, or `check-module-size --all` starts failing), it is recoverable: `cp policies/module-size-baseline.txt.pre-upgrade-<ts> policies/module-size-baseline.txt` (the `.pre-upgrade-<ts>` backup), then re-run via the bootstrap path.

> ⚠️ **Upgrading FROM ≤4.6.1 to 4.7.0+: the bootstrap path is the only supported route — running your installed `upgrade.sh` is unsupported.** Run `bash hooks/local/bootstrap-upgrade.sh -- --auto-yes`.
>
> **This is not theoretical.** A prerelease consumer ran their installed 4.5 engine instead, and the two HIGH bugs they then filed — a new top-level file never installed, and a hand-edited `policies/` entry silently reverted — were both **artifacts of the stale engine**, not of 4.7.0: 4.7.0 drives the managed set from a manifest and classifies every managed path per file. Full write-up: `docs/release-notes/v4.7.0.md` § "three reported findings need no code". 4.7.0 replaces the whole-directory `cp -R` refresh with a **three-way classifier**: it compares what upstream shipped you last time (the *base*, `audit/managed-content-manifest.json`) against your tree and the incoming tree, so it can tell **your** edits from **upstream's** and stops silently overwriting local hardening. Two reasons the bootstrap path is required rather than merely preferred: (1) the classifier ships *inside* the version you are upgrading to, and the old engine would copy upstream over `hooks/**` — including the new engine — before any classification ran; (2) an install from ≤4.6.1 has **no base manifest**, and without one every managed path classifies `unknown-base`, which K9 *preserves* — the upgrade would report success while installing nothing. The bootstrap path fixes both: it stages the new engine first, then **synthesizes the base** from the upstream tag matching your installed `VERSION` (e.g. `v4.6.1`), which is byte-identical to what your last install/upgrade actually wrote. If that tag cannot be resolved (a forked or unreleased `VERSION`), the run continues with `unknown-base` — everything is **preserved and reported**, never overwritten, but little is refreshed; record a base yourself with `bash hooks/local/stamp-managed-content-manifest.sh` and re-run. Paths where **both** you and upstream changed the same file are `changed-by-both`: `--auto-yes` **aborts** on them without writing anything, names each one, and tells you the resume command. `bash hooks/local/preflight.sh` warns when the base is missing or stale.

> ⚠️ **`.fusebase-flow-source/` + ESLint (v3.8.6+).** The staging clone holds CLI-owned **CommonJS** hooks, and ESLint **flat config does not read `.gitignore`** — so if your `fusebase deploy` runs lint, it lints the clone and fails (`@typescript-eslint/no-require-imports`) even with zero app errors. The clone is **transient**: remove it after an upgrade through the sanctioned entry point (`bash hooks/local/cleanup-flow-backups.sh .fusebase-flow-source` — re-created next upgrade; a raw `rm -rf` is denied by `policies/command-policy.yml` under FR-06), or add `".fusebase-flow-source/**"` to your `eslint.config` `ignores` next to `".claude/**"`. One-shot helper: `bash hooks/local/eslint-ignore-flow-paths.sh` (idempotent; backs up your config).

**Canonical → mirror order (why VERSION is bumped last).** Provider folders (`.claude/skills`, `.agents/skills`, `.claude/agents`, `.codex/agents`) are *generated* from the canonical `flow-skills/` and `agents/` trees. The upgrade always: **(1)** refresh canonical content (incl. `hooks/`, preserving `hooks/local/*.local.*`) → **(2)** re-mirror to providers → **(3)** sync derived attestation strings (version + `FR-01..FR-NN` + `(NN canonical skills total)`) → **(4)** refresh drifted AGENTS.md/CLAUDE.md overlay blocks (operator `FLOW:PRESERVE` region carried forward) → **(5)** bump `VERSION`. Bumping `VERSION` last guarantees the version number can never advertise content that hasn't actually landed. Edit canonical files, never the mirrors; `preflight.sh` warns on drift.

Hook wiring is a deliberately separate, opt-in step (`post-fusebase-update.sh --wire-hooks`). `upgrade.sh` never edits `.claude/settings.json` itself, but since v4.15.0 the recovery step it runs restores the Flow lifecycle events on a tree that already recorded an ENABLED wiring intent — the upgrade summary reports that outcome, naming the events it added.

### Auto-discovery for upstream upgrades

The engine and the merger auto-discover the canonical sets of skills, agents, lifecycle events, and handler commands from the upstream `.fusebase-flow-source/` clone at runtime. This means:

- **Patch / minor upstream releases** (new skill, new agent, renamed handler, new matcher) → **zero maintenance** to the health check + recovery system.
- **Major upstream releases** (heading marker rename, fundamental restructuring) → manual edits to heading-marker references in 4 files. Documented in the upgrade procedure section of the canonical skill.

### Files involved

```
flow-skills/fusebase-flow-health-check/SKILL.md          ← canonical skill (description-matched)
.claude/skills/fusebase-flow-health-check/SKILL.md  ← Claude Code mirror
.agents/skills/fusebase-flow-health-check/SKILL.md  ← Codex mirror
.claude/commands/fusebase-health.md                 ← /fusebase-health slash command
hooks/local/fusebase-flow-health-check.sh           ← engine (read-only diagnostic)
hooks/local/post-fusebase-update.sh                 ← recovery script (8 idempotent steps; --wire-hooks / --refresh-overlays)
hooks/local/fusebase-flow-overlays/                 ← overlay templates + canonical skill + slash command source
  ├── agents-md-overlay.md                          ← custom-block-wrapped block to append to AGENTS.md
  ├── claude-md-overlay.md                          ← block to append to CLAUDE.md
  ├── settings-json-merge.py                        ← Python merger (no jq)
  ├── flow-skills/fusebase-flow-health-check/SKILL.md    ← skill template (recovery copies into mirrors)
  └── commands/fusebase-health.md                   ← slash command template
```

</details>

## How enforcement works

| Layer | What it does | Where |
|---|---|---|
| **Always-on rules** | 27 baseline rules (FR-01..FR-27) every session attests to | `FLOW_RULES.md` |
| **Workflows** | Step-by-step procedures (eight-phase, greenlight-implement, greenlight-deploy, etc.) | `workflows/` |
| **Skills** | On-demand expertise loaded when triggered by description match | `flow-skills/` (canonical) + provider mirrors |
| **Sub-agents** | Role-shaped specialists (Product Owner, AI Developer) with tight tool surfaces and self-attestation | `agents/` (canonical) + `.claude/agents/`, `.codex/agents/` mirrors |
| **Policies** | Machine-readable rule data (deny lists, secret patterns, approval rules) | `policies/` |
| **Hooks** | Deterministic enforcement at lifecycle events (Python; stdin → stdout) | `hooks/handlers/` |
| **Git fallback** | Always-on safety net for any IDE without native hooks | `hooks/git/{pre-commit,commit-msg}` |
| **Local scripts** | Local helpers (preflight, install-git-hooks, mirror-skills, approve-local) — run by the agent, or the operator | `hooks/local/` |

Hooks read a unified JSON event from stdin (schema at `hooks/flow_hook_event.schema.json`) and emit a JSON decision. They are **local guardrails**, not a complete security boundary; combine with git hooks and operator vigilance.

## Default workflow modes

- **Solo / local default:** direct-to-main with pre-task git checkpoint, one-task-one-commit, lint+typecheck per commit, and verification gate before deploy.
- **Team / shared mode:** feature branches + PR review. Switch via `policies/approval-policy.yml: workflow_mode: branch_pr` (or in a local override at `approval-policy.local.yml`).

The flow rules are identical in both modes; only the git surface changes.

## Validating an installation

```bash
bash hooks/local/preflight.sh    # structure + YAML + frontmatter + mirror drift + action-name consistency
bash hooks/tests/run-tests.sh    # 19 deterministic handler fixtures + 8 module-size gate scenarios
```

Both must pass cleanly:

```
[preflight] preflight finished — errors: 0, warnings: 0
[run-tests] 24/24 PASS
```

CI does **not** run on ordinary pushes or PRs — `.github/workflows/fusebase-flow-verify.yml` is the
maintainer/release suite (dual-platform, exact SHA) and runs only on `workflow_dispatch` or when the
release workflow calls it for a tagged SHA. You inherit no runner cost for ordinary work.

## FAQ & troubleshooting

<details>
<summary>Does Flow replace my coding agent?</summary>

No. Flow is repo-local files (rules, skills, workflows, hooks). Your existing agent (Claude Code, Codex, Cursor, Copilot, Gemini) reads them and follows the process. There is no separate runtime, daemon, or SaaS.
</details>

<details>
<summary>Do I have to use the sub-agents?</summary>

No. The Product Owner / AI Developer sub-agents are **opt-in**. The framework is fully usable through the skill-and-workflow pattern alone. The sub-agents just make role boundaries explicit and harder to drift across.
</details>

<details>
<summary>Do I need the Python hooks?</summary>

They're optional guardrails. Nothing runs until you copy `.claude/settings.json.example` → `.claude/settings.json`. The git fallback hooks (`hooks/git/`) provide a safety net even with Claude Code hooks off. Dependencies: **Python 3.11+** (also used by preflight, slash commands, and `po-investigate`) plus PyYAML (~100 KB). On a machine without Python, the lifecycle hooks **self-disable with a single warning** rather than erroring on every event — they route through `hooks/local/run-handler.sh`, which auto-detects `python3`/`py`/`python` (override with `FUSEBASE_FLOW_PYTHON`).
</details>

<details>
<summary>`fusebase update` changed my files — is Flow broken?</summary>

Probably not. Run the read-only health check — it reports a **layer verdict** so you know who restores what:

```bash
bash hooks/local/fusebase-flow-health-check.sh    # or /fusebase-health in Claude Code
```

- **`FLOW_LAYER_DRIFT` / `SHARED_MERGE_DRIFT`** → Flow recovers it idempotently: `bash hooks/local/post-fusebase-update.sh`
- **`CLI_LAYER_DRIFT`** → CLI-owned files. Run the **FuseBase CLI refresh/update first**, then the Flow recovery. Flow never overwrites CLI-owned files.

Avoid drift next time with `fusebase update --skip-skills`. See [Health check & recovery](#health-check--recovery).
</details>

<details>
<summary>Preflight or tests fail after I edited a skill</summary>

Skill files are mirrored across provider folders and tracked by a SHA-256 manifest. Edit the **canonical** under `flow-skills/` (or `agents/`), then re-mirror:

```bash
bash hooks/local/mirror-skills.sh
bash hooks/local/mirror-agents.sh
bash hooks/local/preflight.sh # should report errors: 0, warnings: 0
```
</details>

<details>
<summary>Solo vs team workflow?</summary>

Default is **solo / direct-to-main** with per-task commits and a verification gate. Switch to **feature branches + PR** by setting `workflow_mode: branch_pr` in `policies/approval-policy.yml` (or `approval-policy.local.yml`). The flow rules are identical in both modes.
</details>

<details>
<summary>How do I uninstall / back out?</summary>

Flow is just files. Remove the framework dirs (`flow-skills/ workflows/ hooks/ policies/ templates/ audit/ state/`), the adapter files (`AGENTS.md CLAUDE.md GEMINI.md FLOW_RULES.md FLOW_RULES_HISTORY.md VERSION`), and the provider surfaces you added (`.claude/ .agents/ .codex/ .cursor/ .github/`). To disable just the hooks, delete `.claude/settings.json`; if you installed the git fallback hooks, delete the copied `pre-commit` and `commit-msg` files from `.git/hooks/`. Your agent and code are untouched.
</details>

## What's inside

<details>
<summary>Full repository tree</summary>

```
fusebase-flow/
├── README.md                       ← (this file)
├── PUBLISHING.md                   ← history-hygiene before public publishing
├── LICENSE                         ← MIT
├── install.sh                      ← optional convenience installer
├── AGENTS.md                       ← portable always-on baseline
├── CLAUDE.md                       ← Anthropic Claude Code adapter
├── GEMINI.md                       ← Gemini-style IDE adapter
├── FLOW_RULES.md                   ← FR-01..FR-27 always-on rules
├── FLOW_RULES_HISTORY.md           ← dated amendment log (never a session read)
├── VERSION                         ← (current release)
├── .gitattributes                  ← LF line endings for shell/python/yaml/md
├── .python-version                 ← 3.12 (recommended)
├── flow-skills/                         ← 34 canonical skills (2 mandatory + 32 on-demand, incl. product-owner bridge + find-wasted-code (v4.5) + liveness-discipline (v3.28) + find-wasted-effort (v3.22) + token-economy (v3.20) + app-quality-patterns (v3.19) + module-size-discipline (v3.16) + handoff (v3.14) + documentation-budget (v3.12) + comment-policy (v3.11) + lightweight-lane (v3.7) + the v3.3–v3.5 additions: zoom-out, phase-audit, git-history-diagnostic, project-onboarding, north-star, client-vs-internal, product-docs-first, business-logic-guardian, product-apps-decomposition)
├── agents/                         ← 2 canonical sub-agents (product-owner, ai-developer)
├── workflows/                      ← 13 procedures (incl. lightweight-lane)
├── policies/                       ← 9 YAML policies (incl. module-size ratchet + ratchet-governance)
├── templates/                      ← 22 substrates (incl. change-note, business-logic-index, handoff)
├── hooks/
│   ├── README.md
│   ├── flow_hook_event.schema.json
│   ├── handlers/                   ← 8 Python lifecycle handlers
│   ├── shared/                     ← 7 shared utilities (incl. module_size.py)
│   ├── git/                        ← pre-commit + commit-msg
│   ├── local/                      ← preflight / verify-gate / approve-local / mirror-skills / mirror-agents / po-investigate
│   │                                  / install-git-hooks / fusebase-flow-health-check / post-fusebase-update / upgrade / upgrade-engine / sync-version-strings
│   ├── local/fusebase-flow-overlays/  ← AGENTS.md + CLAUDE.md overlay templates,
│   │                                     settings-json-merge.py, health-check skill + slash command templates
│   ├── tests/                      ← run-tests.sh + 19 fixtures + module-size scenarios
│   └── requirements.txt            ← pyyaml (only non-stdlib dep)
├── audit/
│   ├── README.md                   ← what does (and does not) live here
│   ├── skill-mirror-manifest.txt   ← sha256 manifest used by preflight + CI
│   └── agent-mirror-manifest.txt   ← sha256 manifest for sub-agent mirrors
├── state/                          ← runtime state (gitignored contents)
├── docs/                           ← public reference docs + per-project artifacts
├── .agents/skills/                 ← Codex skill surface (34 Flow mirrors + 22 CLI provider skills)
├── .claude/skills/                 ← Claude Code skill surface (34 Flow mirrors + 22 CLI provider skills)
├── .claude/agents/                 ← Claude Code agent surface (2 Flow role agents + 2 CLI app agents)
├── .claude/commands/               ← Anthropic Claude Code slash commands (incl. /fusebase-health)
├── .claude/settings.json.example   ← Claude Code hook wiring
├── .codex/agents/                  ← Codex agent surface (2 Flow role agents + 2 CLI app agents)
├── .codex-plugin/plugin.json       ← Codex plugin metadata pointing at the Codex skill surface
├── .codex/{config.toml,hooks.json}.example ← Codex hook wiring + project trust note
├── .cursor/rules/                  ← Cursor rules (always + scoped)
└── .github/
    ├── copilot-instructions.md     ← repo-wide Copilot / VS Code instructions
    ├── instructions/               ← scoped Copilot / VS Code instructions
    └── workflows/fusebase-flow-verify.yml ← CI: preflight + tests + mirror drift + public-surface allowlist
```

</details>

## Clean-room, license & publishing

- **Clean-room** — Canonical Flow files are clean-room original. The bundled FuseBase Apps domain skills are provider-scoped assets; see [`docs/clean-room.md`](docs/clean-room.md) and [`docs/fusebase-cli-edition.md`](docs/fusebase-cli-edition.md).
- **License** — MIT. See [`LICENSE`](LICENSE).
- **Publishing** — Before making this repo public, follow the history-hygiene step in [`PUBLISHING.md`](PUBLISHING.md).

### Public reference docs

Public-facing reference material lives in [`docs/`](docs/):

- [`ROADMAP.md`](ROADMAP.md) — what's likely next, parked backlog tickets, and explicit non-goals
- [`docs/compatibility.md`](docs/compatibility.md) — provider / IDE support detail
- [`docs/hook-coverage.md`](docs/hook-coverage.md) — hook × provider coverage
- [`docs/rail-mapping.md`](docs/rail-mapping.md) — FR-01..FR-27 → enforcement surfaces
- [`docs/clean-room.md`](docs/clean-room.md) — clean-room license attestation
- [`docs/source-map.md`](docs/source-map.md) — generic pattern attribution

### Audit folder

[`audit/`](audit/) is intentionally minimal in the public template:

- `README.md` — what does (and does not) live here
- `skill-mirror-manifest.txt` — SHA-256 manifest used by `preflight.sh` and CI to detect drift

Build-time phase reports, packaging reports, and per-run test output do **not** ship in the template. Generated runtime reports (install report, hook test report) are written to `state/audit/` (gitignored). CI runs upload that directory as the `fusebase-flow-audit` workflow artifact.

fusebase-flow

File Explorer

# Use via CDN

Was this content helpful?

Recent Feedback

Download README