For floop contributors. If you're a user, see docs/integrations/ for setup guides.
You have persistent memory via floop. Learned behaviors are loaded via MCP and, where supported, auto-injected via hooks.
When corrected, IMMEDIATELY capture it:
mcp__floop__floop_learn(right="what to do instead")
# With optional context about what went wrong:
mcp__floop__floop_learn(right="what to do instead", wrong="what you did (optional)")
# With explicit tags (optional, for pack filtering):
mcp__floop__floop_learn(right="what to do instead", tags=["topic", "category"])
Do NOT wait for permission. Capture learnings proactively. The hooks will also auto-detect corrections, but explicit capture is more reliable.
For non-Claude agents, see docs/integrations/agent-prompt-template.md.
Available MCP tools:
floop_active- See currently active behaviors for this contextfloop_learn- Capture a correction (USE PROACTIVELY)floop_feedback- Signal whether a behavior was helpful (confirmed) or contradicted (overridden)floop_list- List all stored behaviorsfloop_deduplicate- Merge duplicate behaviors
In Codex environments, treat these as required pseudo-hooks:
- Task start: Call
floop_activewith currentfileandtask. - Context change (file/task/mode shift): Re-call
floop_active. - Correction received: Immediately call
floop_learn(no permission needed). - Behavior outcome: Call
floop_feedbackwithconfirmedoroverridden.
If MCP is unavailable, use CLI fallback immediately:
floop active --file <path> --task <task> --json
floop learn --right "what to do instead" --wrong "what happened" --file <path>
floop list --jsonfloop is a CLI tool that enables AI agents to learn from corrections and maintain consistent behavior across sessions.
Tech stack: Go 1.25+, Cobra CLI, YAML, Beads (issue tracking)
docs/GO_GUIDELINES.md- Go coding standards (read before writing code)
Use floop MCP tools proactively. Capture corrections as they happen - don't wait for permission.
go build ./cmd/floop # Build CLI
go install ./cmd/floop # Install globally
go test ./... # Run all tests
go test -v -cover ./... # Verbose with coverage
go fmt ./... # Format code- Run
bv --robot-triageto find available tasks - Read the task with
bd show <id> - Claim it:
bd update <id> --claim - Check dependencies - some tasks block others
- Read GO_GUIDELINES.md first - follow the patterns
- Write tests - all packages need
*_test.gofiles - Test coverage - test both success and error paths
- Format code - run
go fmt ./...before committing
- Make small, incremental commits
- Use conventional commit format:
feat:new featuresfix:bug fixesdocs:documentationtest:test additionschore:maintenance
- Run quality gates (if code changed):
go test ./...— Run testsgo fmt ./...— Format code- If
cmd/floop/changed: verifydocs/CLI_REFERENCE.mdis current
- Close the issue:
bd close <id> --reason "..." - Commit Dolt changes:
bd dolt commit - Commit changes on a feature branch
- Push and create a PR — never commit directly to main
- Wait for review before merging
cmd/floop/— CLI entry pointinternal/— All application packages. Runls internal/for current list.docs/— Documentation (GO_GUIDELINES.md,FLOOP_USAGE.md,integrations/).floop/— Learned behaviors (JSONL + manifest tracked; DB + audit.jsonl gitignored).beads/— Issue tracking (Dolt backend, server at~/.dolt-data/beads)
func newXxxCmd() *cobra.Command {
cmd := &cobra.Command{
Use: "xxx",
Short: "One line description",
RunE: func(cmd *cobra.Command, args []string) error {
jsonOut, _ := cmd.Flags().GetBool("json")
// Implementation
if jsonOut {
json.NewEncoder(os.Stdout).Encode(result)
}
return nil
},
}
return cmd
}result, err := doSomething()
if err != nil {
return fmt.Errorf("context for what failed: %w", err)
}func TestFunction(t *testing.T) {
tests := []struct {
name string
input Type
want Type
wantErr bool
}{
{"valid case", input, expected, false},
{"error case", badInput, nil, true},
}
for _, tt := range tests {
t.Run(tt.name, func(t *testing.T) {
// test implementation
})
}
}Use floop_learn to capture corrections immediately. This builds the dataset for the learning loop.
Check bd ready for current tasks.
For graph-aware issue triage, use bv with --robot-* flags. See docs/BV_SIDECAR.md for full documentation.
Quick start:
bv --robot-triage # Get ranked recommendations
bv --robot-next # Get single top pickCRITICAL: Use ONLY --robot-* flags. Bare bv launches an interactive TUI that blocks your session.
IMPORTANT: This project uses bd (beads) for ALL issue tracking. Do NOT use markdown TODOs, task lists, or other tracking methods.
- Dependency-aware: Track blockers and relationships between issues
- Git-friendly: Dolt-powered version control with native sync
- Agent-optimized: JSON output, ready work detection, discovered-from links
- Prevents duplicate tracking systems and confusion
Check for ready work:
bd ready --jsonCreate new issues:
bd create "Issue title" --description="Detailed context" -t bug|feature|task -p 0-4 --json
bd create "Issue title" --description="What this issue is about" -p 1 --deps discovered-from:bd-123 --jsonClaim and update:
bd update <id> --claim --json
bd update bd-42 --priority 1 --jsonComplete work:
bd close bd-42 --reason "Completed" --jsonbug- Something brokenfeature- New functionalitytask- Work item (tests, docs, refactoring)epic- Large feature with subtaskschore- Maintenance (dependencies, tooling)
0- Critical (security, data loss, broken builds)1- High (major features, important bugs)2- Medium (default, nice-to-have)3- Low (polish, optimization)4- Backlog (future ideas)
- Check ready work:
bd readyshows unblocked issues - Claim your task atomically:
bd update <id> --claim - Work on it: Implement, test, document
- Discover new work? Create linked issue:
bd create "Found bug" --description="Details about what was found" -p 1 --deps discovered-from:<parent-id>
- Complete:
bd close <id> --reason "Done"
bd automatically syncs via Dolt:
- Each write auto-commits to Dolt history
- Use
bd dolt push/bd dolt pullfor remote sync - No manual export/import needed!
- ✅ Use bd for ALL task tracking
- ✅ Always use
--jsonflag for programmatic use - ✅ Link discovered work with
discovered-fromdependencies - ✅ Check
bd readybefore asking "what should I work on?" - ❌ Do NOT create markdown TODO lists
- ❌ Do NOT use external issue trackers
- ❌ Do NOT duplicate tracking systems
For more details, see README.md and docs/QUICKSTART.md.
When ending a work session, you MUST complete ALL steps below. Work is NOT complete until git push succeeds.
MANDATORY WORKFLOW:
- File issues for remaining work - Create issues for anything that needs follow-up
- Run quality gates (if code changed) - Tests, linters, builds
- Update issue status - Close finished work, update in-progress items
- Commit Dolt changes -
bd dolt commit - Commit and push on a branch - Never commit directly to main:
git checkout -b chore/session-cleanup # or use existing feature branch git add <specific files> git commit -m "chore: sync beads state" bd dolt push git push -u origin HEAD git status # MUST show "up to date with origin"
- Create PR -
gh pr createand present to user for review - Clean up - Clear stashes, prune remote branches
- Verify - All changes committed AND pushed
- Hand off - Provide context for next session
CRITICAL RULES:
- NEVER commit directly to main — always use a feature branch + PR
- NEVER merge PRs without user review — present PRs and wait for approval
- Work is NOT complete until
git pushsucceeds - NEVER stop before pushing - that leaves work stranded locally
- NEVER say "ready to push when you are" - YOU must push
- If push fails, resolve and retry until it succeeds
For graph-aware issue triage, use bv with --robot-* flags. See docs/BV_SIDECAR.md for full documentation.
Quick start:
bv --robot-triage # Get ranked recommendations
bv --robot-next # Get single top pickCRITICAL: Use ONLY --robot-* flags. Bare bv launches an interactive TUI that blocks your session.
IMPORTANT: This project uses bd (beads) for ALL issue tracking. Do NOT use markdown TODOs, task lists, or other tracking methods.
- Dependency-aware: Track blockers and relationships between issues
- Git-friendly: Dolt-powered version control with native sync
- Agent-optimized: JSON output, ready work detection, discovered-from links
- Prevents duplicate tracking systems and confusion
Check for ready work:
bd ready --jsonCreate new issues:
bd create "Issue title" --description="Detailed context" -t bug|feature|task -p 0-4 --json
bd create "Issue title" --description="What this issue is about" -p 1 --deps discovered-from:bd-123 --jsonClaim and update:
bd update <id> --claim --json
bd update bd-42 --priority 1 --jsonComplete work:
bd close bd-42 --reason "Completed" --jsonbug- Something brokenfeature- New functionalitytask- Work item (tests, docs, refactoring)epic- Large feature with subtaskschore- Maintenance (dependencies, tooling)
0- Critical (security, data loss, broken builds)1- High (major features, important bugs)2- Medium (default, nice-to-have)3- Low (polish, optimization)4- Backlog (future ideas)
- Check ready work:
bd readyshows unblocked issues - Claim your task atomically:
bd update <id> --claim - Work on it: Implement, test, document
- Discover new work? Create linked issue:
bd create "Found bug" --description="Details about what was found" -p 1 --deps discovered-from:<parent-id>
- Complete:
bd close <id> --reason "Done"
bd automatically syncs via Dolt:
- Each write auto-commits to Dolt history
- Use
bd dolt push/bd dolt pullfor remote sync - No manual export/import needed!
- ✅ Use bd for ALL task tracking
- ✅ Always use
--jsonflag for programmatic use - ✅ Link discovered work with
discovered-fromdependencies - ✅ Check
bd readybefore asking "what should I work on?" - ❌ Do NOT create markdown TODO lists
- ❌ Do NOT use external issue trackers
- ❌ Do NOT duplicate tracking systems
For more details, see README.md and docs/QUICKSTART.md.
When ending a work session, you MUST complete ALL steps below. Work is NOT complete until git push succeeds.
MANDATORY WORKFLOW:
- File issues for remaining work - Create issues for anything that needs follow-up
- Run quality gates (if code changed) - Tests, linters, builds
- Update issue status - Close finished work, update in-progress items
- PUSH TO REMOTE - This is MANDATORY:
git pull --rebase bd dolt push git push git status # MUST show "up to date with origin" - Clean up - Clear stashes, prune remote branches
- Verify - All changes committed AND pushed
- Hand off - Provide context for next session
CRITICAL RULES:
- Work is NOT complete until
git pushsucceeds - NEVER stop before pushing - that leaves work stranded locally
- NEVER say "ready to push when you are" - YOU must push
- If push fails, resolve and retry until it succeeds