Flow

Context-Driven Development toolkit for AI agents — spec-first planning, TDD workflow, and Beads integration.

Install

npx -y skills add cofin/flow --skill flow

Assembled from the repository path, not quoted from the project. Check it against their README if it does not work.

One thing to look at

14 stars14 stars. Stars are a popularity signal and not a quality one, but at this level it is likely that nobody has read this closely except its author, and you would be relying on your own review.

What its author says it does

Copied from the file, not written here

Use when a repository has .agents, when the user asks for Flow lifecycle routing, Beads-backed task memory, spec-first planning, TDD implementation, sync/status, review, finish, archive, or /flow:* help.

SKILL.md

3.0 KB, as published. Nobody here has run it

Flow Router

Flow coordinates Context-Driven Development in .agents/ repositories. Keep this skill small: use it to identify the active lifecycle phase, enforce the Beads-first invariants, and load the matching lifecycle skill.

Flow is a skill, not a CLI. There is no flow executable. Never run flow, flow sync, flow prd, etc. as shell commands. Invoke this skill (or the matching lifecycle skill), or use the /flow:* slash commands where the harness supports them.

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 references/discipline.md.

Workflow

Check hook-provided Flow context first; otherwise detect .agents/, Beads (bd), git branch, and repo-native commands.
Route the request:
- Setup, validation, install, context initialization: use flow-setup.
- PRD, research, plan, refine, revise, task creation: use flow-planning.
- Implement, claim ready tasks, TDD, commit, task close: use flow-execution.
- Sync, status, refresh, cleanup, context drift: use flow-sync-status.
- Review, finish, archive, revert, docs, phase completion: use flow-completion.
Record durable discoveries and task state in Beads. Markdown files are synchronized views.
Prefer repo-native commands from .agents/workflow.md or hook context for validation.

Guardrails

Never edit task markers ([ ], [~], [x], [!], [-]) manually in spec.md.
Do not run bd export, auto-stage, bd dolt push, or git operations through Beads unless .agents/beads.json allows it or the user asks.
Store Flow specs and planning artifacts under .agents/specs/<flow_id>/.
Make minimal targeted changes and record findings with bd note <id> "..." when work exceeds a quick fix.

Validation

For planning: verify the plan is decision-complete before presenting it.
For implementation: verify red-green-refactor evidence, full relevant tests, and Beads task closure before claiming completion.
For sync/status: read backend state first and report drift instead of guessing.
For this repository: run make validate-skills and make validate-codex-manifest after skill or command changes.

References Index

Example

User: "Use Flow to implement the current spec."

Action: load flow-execution, claim a ready Beads task, add investigation notes, follow TDD, close the task with evidence, then sync according to policy.