This edition layers Fusebase Flow lifecycle discipline on top of the Fusebase Apps CLI domain assets. Flow owns the ticket lifecycle, role boundaries, verification gates, deploy reporting, and smoke discipline. The CLI assets own app/runtime guidance for Fusebase Apps, MCP, dashboards, gate, routing, secrets, logs, and scaffold quality.
| Area | Owner | Path |
|---|---|---|
| Flow lifecycle skills | Flow canonical | flow-skills/, mirrored to .claude/skills/ and .agents/skills/ |
| CLI domain skills | CLI provider assets | .claude/skills/<cli-skill>/ and .agents/skills/<cli-skill>/ |
| Flow agents | Flow canonical | agents/, mirrored to .claude/agents/ and .codex/agents/ |
| CLI app agents | CLI provider assets | .claude/agents/app-architect.md, .claude/agents/app-create-checker.md, copied to .codex/agents/ |
| CLI quality hooks | CLI provider assets | .claude/hooks/* |
| Flow hooks | Flow canonical | hooks/handlers/*, hooks/git/*, .claude/settings.json.example |
- Flow governs specs, clarifies, decisions, tasks, verification gates, implementation handoffs, review, deploy handoffs, smoke contracts, and DONE flips.
- CLI skills govern Fusebase Apps implementation/runtime/MCP/SDK/domain behavior.
- If runtime app guidance conflicts with generic Flow guidance, follow the CLI/project-specific runtime rule and keep the Flow lifecycle artifact intact.
- Do not copy CLI provider skills into
flow-skills/; they are edition/provider assets, not canonical Flow framework skills. - Do not add CLI provider skills to
audit/skill-mirror-manifest.txt; the manifest tracks canonical Flow mirror drift only. - If a CLI skill becomes a reusable Flow framework pattern, route it through
flow-skills/skill-authoring/SKILL.mdas a clean-room upstream proposal.
The vendored CLI-owned assets live at provider paths that are written by two independent tools:
| Writer | What it writes | When |
|---|---|---|
fusebase update (live FuseBase CLI bundle) |
.claude/skills/<cli-skill>/, .claude/hooks/*, .claude/agents/app-*.md (0.25.16 copyAgentsAndSkills writes only AGENTS.md + .claude/{skills,agents,hooks,settings.json}; ide-setup writes only .codex/config.toml) |
whenever the project syncs the current CLI bundle |
| Fusebase Flow snapshot | a frozen copy of those same assets, shipped inside this edition template — including .agents/skills/<cli-skill>/ and .codex/agents/app-*.md, which the live CLI does not write |
at install / template-copy time |
Because both writers target the same paths, a blind recursive overwrite (cp -R
without -n, or PowerShell Copy-Item -Force) of .claude/ or .agents/
during install clobbers the live CLI-owned assets with the frozen Flow
snapshot. This is the strongest concrete data-loss vector in the edition, and
it directly violates the edition rule that Flow must never restore CLI-owned
assets from its bundled copy.
CUSTOM:SKILL blocks are especially at risk: a <!-- CUSTOM:SKILL:BEGIN -->…END
customization a user added to a CLI-owned skill is silently lost on a blind
overwrite or a fusebase update.
Managed-app caveat — a third AGENTS.md writer surface with no update-survival.
fusebase init --managed appends an unmarked AGENTS.managed.md block to
AGENTS.md. Because that block carries no CUSTOM:SKILL markers, fusebase update / product update overwrites AGENTS.md and destroys it — the
custom-block capture/restore never sees it; only re-running fusebase init --managed re-appends it. Recovery is CLI-side. Before the recovery system
rewrites AGENTS.md, post-fusebase-update.sh --refresh-overlays writes a
.pre-refresh-<ts> backup first.
- Install copy is non-clobbering.
docs/install-existing-project.mdanddocs/install-fusebase-cli-project.mdcopy CLI-owned provider paths only-if-absent (cp -Rn/Copy-Itemwithout-Force); Flow-owned framework folders copy normally. See those docs for the exact commands. - Recovery never writes CLI-owned paths.
mirror-skills.shwrites only the 34 canonical Flow skills;post-fusebase-update.shexcludes.claude/hooks/**, CLI provider skills, MCP/fusebase.json/skills-lock.json, and active.codex/config.toml; the ownership map marks all 20 CLI provider skillsflow_write_mode:"never". - Drift is visible.
audit/cli-vendor-manifest.jsonrecords a per-file sha256 of every vendored CLI-owned asset (regenerated byhooks/local/stamp-cli-provenance.sh).check-cli-flow-conflicts.shhashes present assets against it and reportsCLI_SNAPSHOT_STALE(a present asset differs from the snapshot — newer or locally modified) andCLI_CUSTOM_AT_RISK(a CLI skill carries aCUSTOM:SKILLblock). Both are advisory only; restoration of CLI content always stays with the CLI.
After any install or fusebase update, run
bash hooks/local/check-cli-flow-conflicts.sh to confirm nothing was clobbered.
| Flow activity | Supporting CLI asset |
|---|---|
| New/update app architecture | app-architect, app-dev-practices, fusebase-cli |
| UI direction or implementation | app-ui-design |
| Backend/API behavior | app-backend, api-exploration |
| Dashboard data and views | fusebase-dashboards |
| Gate, orgs, users, tokens, permissions | fusebase-gate |
| Secrets and authentication errors | app-secrets, handling-authentication-errors |
| File upload | file-upload |
| Routing | app-routing |
| Sidecars | app-sidecar |
| Local or deployed debugging | dev-debug-logs, remote-logs |
| Git/deploy traceability | git-workflow, fusebase-cli |
| Scaffold verification | app-create-checker |
| MCP gate debugging | mcp-gate-debug |
| Managed integrations | managed-integrations |
| Portal-specific apps | fusebase-portal-specific-apps |
| Business docs for apps | app-business-docs |
| Flow skill | Overlapping CLI asset | Why it overlaps | Boundary |
|---|---|---|---|
requirements-specification |
app-architect, app-business-docs |
All shape app intent and requirements | Flow writes spec and ACs; CLI assets inform app-domain constraints |
design-discovery-ideation |
app-ui-design |
Both guide UI/product direction | Flow frames options before lock; CLI asset provides Fusebase Apps UI conventions |
implementation-planning |
app-dev-practices, fusebase-cli, git-workflow |
All affect implementation sequence | Flow writes decisions/tasks/gate; CLI assets inform commands and runtime approach |
validation-and-qa |
app-create-checker, dev-debug-logs, remote-logs |
All verify behavior | Flow decides gate sufficiency; CLI assets provide app-specific probes and diagnostics |
security-permissions-review |
app-secrets, handling-authentication-errors, fusebase-gate, fusebase-dashboards |
All touch auth, tokens, secrets, data access | Flow owns approval/blocker review; CLI assets define app-specific security surfaces |
smoke-testing |
remote-logs, dev-debug-logs, fusebase-cli |
Smoke needs deployed app diagnostics | Flow owns outcome-first smoke discipline; CLI assets identify ground-truth surfaces |
release-deploy-reporting |
fusebase-cli, git-workflow, remote-logs |
Deploy handoff needs CLI/deploy evidence | Flow owns deploy report shape; CLI assets provide commands and runtime evidence |
repo-onboarding-context-map |
fusebase-cli, app-dev-practices |
Both orient agents to app repos | Flow writes durable context map; CLI assets supply Fusebase Apps project conventions |
code-review |
app-backend, app-ui-design, app-routing, file-upload, app-sidecar |
Reviews need domain standards | Flow reviews against spec/decisions/tasks; CLI skills supply implementation-specific review criteria |
app-quality-patterns |
app-ui-design, app-routing, fusebase-dashboards |
Both shape feature behavior/UI | QP owns WHAT must be true (behavioral ACs + smoke recipes); CLI assets own HOW on the FuseBase stack |
| Role | Uses CLI assets how |
|---|---|
| Product Owner | May use app-architect and domain skills as supporting input while drafting specs, decisions, tasks, gates, and smoke contracts. PO still does not write production code or lock decisions without operator approval. |
| AI Developer | Uses relevant CLI skills during implementation, debugging, validation, and deploy evidence collection. AI Developer still follows one task = one commit and stops at the gate. |
| Deploy phase | Uses fusebase-cli, remote-logs, dev-debug-logs, and git-workflow for deploy probes and diagnostics. Deploy phase still cannot mark DONE. |
| App checker | app-create-checker is supporting validation evidence, not a replacement for Flow verification-gate and smoke evidence. |
.claude/settings.json.example intentionally merges two hook families:
| Hook family | Purpose |
|---|---|
| Flow lifecycle hooks | Enforce session, prompt, tool-use, stop, and compact discipline from hooks/handlers/*. |
| CLI Stop hooks | The FuseBase CLI 0.25.16 wired Stop set — run-lint-on-stop.sh, run-typecheck-on-stop.sh, quality-check-apps.js — runs app lint, typecheck, and quality checks from .claude/hooks/* before completion on Claude Code. Flow appends stop.py preserve-only (never removing an existing CLI hook). |
Keep the merge additive. Do not overwrite an active downstream .claude/settings.json; append or merge after inspection.