| name | flow-setup |
| description | Use when initializing Flow in a repo, configuring .agents, installing or checking Beads bd, setting local-only sync policy, or creating first project context files. |
Flow Setup
Use this lifecycle skill for project initialization, installation checks, setup validation, and first context files.
Beads mode: Skip every bd invocation when the SessionStart hook reports Beads Backend: Missing (None) or Disabled via plugin config (useBeads=false). Treat spec.md markers as fallback source of truth and skip /flow:sync. Never halt for missing Beads. See ../flow/references/discipline.md.
Workflow
- Detect project root, existing
.agents/ state, Beads availability, and repo-native commands.
- If Beads is missing, offer official Beads (
bd) installation or no-Beads degraded mode.
- Initialize Flow context files from templates and prefer local-only Beads settings.
- Store setup decisions in Beads notes when a backend exists.
- Re-run setup validation before handing off to planning.
Guardrails
- Prefer
.git/info/exclude for local-only ignores.
- Do not edit
.gitignore unless the user wants shared repository policy.
- Do not run
bd dolt push, bd export, or auto-stage unless policy explicitly allows it.
- Keep setup idempotent; preserve existing user context files and merge rather than overwrite.
Validation
- Confirm
.agents/ root, workflow.md, patterns.md, knowledge/index.md, and Beads config existence when setup is expected.
- Confirm Beads config defaults are local-only: no git ops, no auto export, and no auto git add.
- Run repository validation commands documented in
.agents/workflow.md or hook context.
References Index
Example
User: "Use Flow to set up this repo."
Action: detect the repo root, initialize .agents/, configure local-only Beads, capture setup notes, validate files, then hand off to flow-planning for the first flow.
