{"id":50373651,"url":"https://github.com/barturba/complexity-burndown-swarm","last_synced_at":"2026-05-30T08:30:20.890Z","repository":{"id":358191397,"uuid":"1240420924","full_name":"barturba/complexity-burndown-swarm","owner":"barturba","description":"SQLite-coordinated local AI swarm for Ruby cyclomatic-complexity burn-downs","archived":false,"fork":false,"pushed_at":"2026-05-16T05:51:50.000Z","size":17,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-05-16T07:36:11.443Z","etag":null,"topics":["ai-agents","codex","complexity","ruby","sqlite"],"latest_commit_sha":null,"homepage":"https://bartas.co","language":"Ruby","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/barturba.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-05-16T05:39:06.000Z","updated_at":"2026-05-16T06:07:08.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/barturba/complexity-burndown-swarm","commit_stats":null,"previous_names":["barturba/complexity-burndown-swarm"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/barturba/complexity-burndown-swarm","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/barturba%2Fcomplexity-burndown-swarm","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/barturba%2Fcomplexity-burndown-swarm/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/barturba%2Fcomplexity-burndown-swarm/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/barturba%2Fcomplexity-burndown-swarm/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/barturba","download_url":"https://codeload.github.com/barturba/complexity-burndown-swarm/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/barturba%2Fcomplexity-burndown-swarm/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33686018,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-05-30T02:00:06.278Z","response_time":92,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ai-agents","codex","complexity","ruby","sqlite"],"created_at":"2026-05-30T08:30:20.120Z","updated_at":"2026-05-30T08:30:20.868Z","avatar_url":"https://github.com/barturba.png","language":"Ruby","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Complexity Burndown Swarm\n\nA tiny local coordinator for burning down cyclomatic complexity with multiple AI coding agents.\n\nThis is not a feature-building framework. It is deliberately narrow: scan a target repo for complex Ruby methods, put the methods into SQLite-backed batches, let isolated worktree agents claim one batch at a time, and merge completed branches back through a single lock.\n\nIt was extracted from a real Rails cleanup run and scrubbed for public use. The repo contains no live queue database, process IDs, logs, private project paths, generated reports, or application code.\n\n## What It Is Good For\n\n- Mechanical refactors where the success metric is objective.\n- Reducing `Metrics/CyclomaticComplexity` in Ruby/Rails repos.\n- Running several low-reasoning agents safely because each gets a narrow file/method list.\n- Keeping merge state explicit instead of trusting agents to coordinate in chat.\n\n## What It Is Bad For\n\n- Product features.\n- UX/copy decisions.\n- Anything where agents need to invent the acceptance criteria.\n\n## Architecture\n\nThe swarm has four parts:\n\n- `bin/burndown`: SQLite coordinator. It scans complexity, creates batches, claims work, records completion, writes a Markdown status file, and serializes merges with a lock.\n- `bin/burndown-worktrees`: creates or reuses target-repo worktrees such as `agent-A`, `agent-B`, `agent-C`, and `agent-D`.\n- `bin/burndown-tmux`: opens a 2x2 tmux session in those worktrees.\n- AI agents: each agent reads `bin/burndown prompt \u003cagent\u003e`, edits only the listed methods, runs focused checks, commits, and records completion.\n\nThe default worker set is `A B C D`. That is usually enough. More workers increase merge pressure faster than they increase useful throughput.\n\n## Requirements\n\n- Ruby\n- `sqlite3` Ruby gem\n- Git\n- Bundler and RuboCop available in the target repo\n- tmux, optional\n- Codex or another coding agent, optional\n\nInstall the SQLite gem if your system Ruby does not already have it:\n\n```bash\ngem install sqlite3\n```\n\n## Quick Start\n\nClone this repo next to the target repo:\n\n```bash\ngit clone https://github.com/barturba/complexity-burndown-swarm.git\ncd target-rails-repo\n```\n\nInitialize state and worktrees:\n\n```bash\n../complexity-burndown-swarm/bin/burndown init\n../complexity-burndown-swarm/bin/burndown refresh\n../complexity-burndown-swarm/bin/burndown backfill 2 6\n../complexity-burndown-swarm/bin/burndown-worktrees init\n../complexity-burndown-swarm/bin/burndown-tmux\n```\n\nIn an agent pane:\n\n```bash\n../complexity-burndown-swarm/bin/burndown prompt A\n```\n\nGive that prompt to the coding agent running in the `agent-A` worktree.\n\n## Typical Agent Loop\n\nEach worker should do exactly this:\n\n1. Claim one batch: `bin/burndown claim A`.\n2. Merge latest `main` into its worktree branch.\n3. Edit only the files and methods listed in the batch.\n4. Reduce methods below the next useful threshold.\n5. Run `git diff --check`, touched-file RuboCop, and one focused test when obvious.\n6. Commit.\n7. Record completion: `bin/burndown complete A \u003cbatch_id\u003e \u003ccommit_sha\u003e '\u003cchecks\u003e'`.\n8. Run `bin/burndown self-merge A \u003cbatch_id\u003e` only if the merge is clean and obvious.\n9. If the merge conflicts or looks non-trivial, abort and mark conflict: `bin/burndown conflict A \u003cbatch_id\u003e '\u003cfiles/reason\u003e'`.\n\nDo not let workers resolve broad conflicts casually. Conflict resolution is where mechanical cleanup becomes accidental product work.\n\n## Commands\n\n```bash\nbin/burndown init\nbin/burndown refresh\nbin/burndown backfill [target_open=2] [batch_size=6]\nbin/burndown claim \u003cagent\u003e\nbin/burndown complete \u003cagent\u003e \u003cbatch_id\u003e \u003ccommit_sha\u003e '\u003cchecks\u003e'\nbin/burndown self-merge \u003cagent\u003e \u003cbatch_id\u003e\nbin/burndown conflict \u003cagent\u003e \u003cbatch_id\u003e '\u003cnotes\u003e'\nbin/burndown status\nbin/burndown prompt \u003cagent\u003e\nbin/burndown write-md\n```\n\nWorktree helpers:\n\n```bash\nbin/burndown-worktrees init\nbin/burndown-worktrees status\nbin/burndown-worktrees path A\nbin/burndown-worktrees sync\nbin/burndown-tmux\n```\n\n## Configuration\n\nEnvironment variables:\n\n- `BURNDOWN_TARGET_REPO`: target repo path. Defaults to the current directory.\n- `BURNDOWN_STATE_DIR`: state directory. Defaults to `.burndown-swarm` in the target repo.\n- `BURNDOWN_AGENTS`: space-separated worker labels. Defaults to `A B C D`.\n- `BURNDOWN_BRANCH_PREFIX`: branch prefix. Defaults to `agent`.\n- `BURNDOWN_TARGET_MIN_CC`: minimum complexity to queue. Defaults to `5`.\n- `BURNDOWN_WORKTREES_DIR`: parent directory for worktrees. Defaults to a sibling `\u003crepo\u003e-burndown-worktrees` directory.\n- `BURNDOWN_TMUX_SESSION`: tmux session name. Defaults to `burndown-swarm`.\n\nExample:\n\n```bash\nBURNDOWN_AGENTS=\"A B\" BURNDOWN_TARGET_MIN_CC=8 bin/burndown backfill 1 4\n```\n\n## State Files\n\nBy default, generated state lives under the target repo in `.burndown-swarm/`:\n\n- `coordination.sqlite3`\n- `current-complexity.tsv`\n- `BURNDOWN_COORDINATION.md`\n\nThese files are local operating state. Do not commit them to your application repo.\n\n## Safety Rules\n\n- Keep `main` clean before merging completed branches.\n- Merge one worker branch at a time.\n- Prefer smaller batches over bigger batches.\n- Do not create new complex helper methods to hide old complex methods.\n- Do not run this against uncommitted user work unless you intend to manage that work manually.\n- Treat failing focused tests as a stop signal, not noise.\n\n## Why SQLite\n\nMarkdown is readable but weak as a lock. SQLite gives the swarm atomic claims, a merge lock, durable completion state, and a cheap audit trail. The Markdown file is generated from SQLite for human scanning.\n\n## Sanitization Note\n\nThis public repo intentionally excludes:\n\n- real queue databases\n- process IDs\n- tmux pane IDs\n- generated complexity reports from private code\n- private file paths\n- private prompts\n- commit history from the source project\n\nOnly the generic workflow and scripts are included.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbarturba%2Fcomplexity-burndown-swarm","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fbarturba%2Fcomplexity-burndown-swarm","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbarturba%2Fcomplexity-burndown-swarm/lists"}