{"id":51940201,"url":"https://github.com/bo-cao/breaking-coding-chaos","last_synced_at":"2026-08-03T02:00:51.249Z","repository":{"id":371143847,"uuid":"1299359887","full_name":"bo-cao/breaking-coding-chaos","owner":"bo-cao","description":null,"archived":false,"fork":false,"pushed_at":"2026-07-13T16:09:24.000Z","size":1473,"stargazers_count":4,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"master","last_synced_at":"2026-07-13T17:19:37.677Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Python","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/bo-cao.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":"AGENTS.md","dco":null,"cla":null}},"created_at":"2026-07-13T14:04:55.000Z","updated_at":"2026-07-13T16:14:25.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/bo-cao/breaking-coding-chaos","commit_stats":null,"previous_names":["bo-cao/breaking-coding-chaos"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/bo-cao/breaking-coding-chaos","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bo-cao%2Fbreaking-coding-chaos","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bo-cao%2Fbreaking-coding-chaos/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bo-cao%2Fbreaking-coding-chaos/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bo-cao%2Fbreaking-coding-chaos/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/bo-cao","download_url":"https://codeload.github.com/bo-cao/breaking-coding-chaos/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bo-cao%2Fbreaking-coding-chaos/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":36214553,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-07-20T02:08:10.276Z","status":"online","status_checked_at":"2026-08-03T02:00:06.975Z","response_time":56,"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":[],"created_at":"2026-07-28T18:00:30.334Z","updated_at":"2026-08-03T02:00:51.236Z","avatar_url":"https://github.com/bo-cao.png","language":"Python","funding_links":[],"categories":["ツール","Documentation for AI Coding"],"sub_categories":["IDE \u0026 エディタアシスタント"],"readme":"# breaking-coding-chaos\n\n[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](./LICENSE)\n[![Agent Skills](https://img.shields.io/badge/Agent%20Skills-4-informational)](./skills)\n[![Agents](https://img.shields.io/badge/agents-Grok%20%7C%20Claude%20%7C%20Codex%20%7C%20Cursor%20%7C%20OpenCode%20%7C%20Hermes%20%7C%20OpenClaw-success)](./docs/install/README.md)\n[![Listed in awesome-vibecoding](https://img.shields.io/badge/listed%20in-awesome--vibecoding-0ea5e9?style=flat-square)](https://github.com/roboco-io/awesome-vibecoding#ide--editor-assistants)\n[![Listed in awesome-coding-agents](https://img.shields.io/badge/listed%20in-awesome--coding--agents-7c3aed?style=flat-square)](https://github.com/kailiu42/awesome-coding-agents#cli-agent-helpers)\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"./assets/banner.jpg\" alt=\"breaking-coding-chaos — dual-loop human-in-the-loop coding with agents\" width=\"100%\" /\u003e\n\u003c/p\u003e\n\n**breaking-coding-chaos (BCC)** is a **human-in-the-loop dual-loop control-plane skill suite** for coding agents: you keep progress and technical detail under control while the agent ships your idea — without losing the plot.\n\n**Works with all agents.** Standard Agent Skills layout (`SKILL.md` folders) — install once for Claude Code, Codex, Grok, Cursor, OpenCode, Hermes, OpenClaw, and any runtime that loads the same skill format.\n\n[English](./README.md) | [简体中文](./READMEs/README.zh-CN.md) | [繁體中文](./READMEs/README.zh-TW.md)\n\n[Quick start](#quick-start)\n\n\u003e **Idea first.** Bring a **reasonably concrete idea** (what to build, what “done” means).  \n\u003e BCC helps you **implement it 1:1** with control over progress and technical detail — **not** invent a product from a blank void.  \n\u003e Without a real idea, there is nothing honest to code.\n\n---\n\n## Why a control plane\n\nAgentic coding is powerful — and chronically **unreliable at the exact moment precision matters**.\n\nWhen the work needs **fine-grained design**, **explicit trade-offs**, and **progress you can audit**, sessions often end in:\n\n- **Memory collapse** — after `/clear`, compaction, or a long tool chain, goals and constraints evaporate. The agent rediscovers the same bugs and re-asks the same architecture questions.\n- **Hallucinated certainty** — the model fills gaps with plausible inventiveness: wrong APIs, phantom modules, “fixes” that never touch the real failure mode.\n- **Attention smear** — the more “helpful” global context you inject, the harder it becomes to put **all** of the model’s attention on the *one* hard problem in front of you.\n\n### Long-term memory tools are not the same problem\n\nThere is a rich ecosystem of **agent memory** products and libraries — for example [mem0](https://github.com/mem0ai/mem0) and [agentmemory](https://github.com/rohitg00/agentmemory). They excel at **cross-session recall**, retrieval, and carrying identity/preferences through time. That is valuable.\n\nHigh-effort implementation asks a different question. Soft memory asks “what did we decide last month?” Hard work asks “what exactly do we code *this hour*, and how do we prove it?” More context can help chat; on a critical path it often **dilutes** attention. Continuity tools optimize for remembering; engineering control optimizes for a **contract** — checklist, verification, and a bound on what is allowed to change now.\n\nWhen the work is *hard* — a subtle concurrency bug, a paper-faithful experiment, a multi-module migration — a blurry global memory layer can become a **tax**: the agent half-remembers everything and fully owns nothing. You need a **control plane**: durable notes for the whole endeavor, one living coding brief for the *current* hard slice, pressure on that brief before code, then the **smallest correct diff**, with progress written back where you can see it.\n\nThat is **breaking-coding-chaos** (BCC).\n\n---\n\n## Who it’s for\n\nBCC is for anyone who needs agents to **finish real work under hard constraints** — not just generate plausible code. The same dual loop helps different roles in different ways:\n\n- **Researchers \u0026 students** — Pin protocol, hyperparameters, and acceptance checks into a living brief; keep multi-week paper/repo progress on disk; ship one verifiable experiment or pipeline slice at a time.  \n- **Engineers \u0026 tech leads** — Keep design trade-offs and “what’s done” visible across long multi-module sessions; one active coding brief so the team does not get three competing implementations.  \n- **Indie builders \u0026 founders** — Turn a concrete product idea into auditable sub-tasks; stop the agent from reinventing the app every conversation.  \n- **Repo maintainers** — Global map plus one hard slice at a time; less thrash after compaction, context loss, or switching tools.  \n- **Multi-agent users** (Claude / Codex / Cursor / …) — Same four skills, same dual loop — one control plane across runtimes.\n\n**Strong fit:** multi-step or multi-week work; high-stakes slices (bugs, migrations, experiments that must match a brief); resume after `/clear` or agent switches.  \n**Weak / wrong tool:** vibe one-liners, throwaway scripts, or no concrete idea yet — BCC implements ideas; it does not invent products.\n\n---\n\n## Where these ideas come from\n\nAgentic coding already has a few well-tested patterns: **context on disk**, **alignment before code**, and **minimal diffs**. BCC is a **human-in-the-loop control plane** that brings those strands into one dual loop — not a clone of any single project, and not an official endorsement by the authors below.\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"./assets/prior-art-compose.png\" alt=\"Separate ideas for context, align, and cut — composed into one control loop\" width=\"920\" /\u003e\n\u003c/p\u003e\n\n**People and projects behind the patterns:**\n\n- **[Manus](https://manus.im)** — AI agent company whose [context-engineering write-up](https://manus.im/blog/Context-Engineering-for-AI-Agents-Lessons-from-Building-Manus) popularized treating the **filesystem as durable agent context** (chat as RAM, disk as the notebook). Widely cited after major industry attention around the company and its approach.  \n- **[planning-with-files](https://github.com/OthmanAdi/planning-with-files)** ([Othman Adi](https://github.com/OthmanAdi) et al.) — highly adopted open skill that operationalizes Manus-style **plan / progress / findings** markdown so multi-step work survives `/clear` and context loss.  \n- **[Matt Pocock](https://github.com/mattpocock)** — TypeScript educator ([Total TypeScript](https://www.totaltypescript.com/)); formerly [XState](https://stately.ai/) core team and developer advocate at [Vercel](https://vercel.com/). His open [skills](https://github.com/mattpocock/skills) (grill / domain-modeling style) push **hard questions, shared language, and ADRs before code**.  \n- **[ponytail](https://github.com/DietrichGebert/ponytail)** ([Dietrich Gebert](https://github.com/DietrichGebert)) — widely used open skill that encodes a senior “lazy” **YAGNI ladder**: smallest change that works, stop over-building.  \n\n\u003cp align=\"center\"\u003e\n  \u003cstrong\u003e\u003cem\u003eNot another memory layer — a human-in-the-loop control plane.\u003c/em\u003e\u003c/strong\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003cem\u003e\n  See the whole endeavor. Focus one hard slice at a time.\u003cbr /\u003e\n  Dual loop, hard order: map → spar the plan → cut the minimum.\u003cbr /\u003e\n  One living brief per slice. Progress must write back. Wrong step cannot fire early.\n  \u003c/em\u003e\n\u003c/p\u003e\n\n---\n\n## How it works\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"./assets/architecture.png\" alt=\"Ship your idea with agents — throughline progress, plan-spar one sub-task, clean-cut ships it\" width=\"100%\" /\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003cem\u003eDual loop. Human gates. One living plan per sub-task.\u003c/em\u003e\n\u003c/p\u003e\n\n**Throughline** sits on top: the **project progress bar** over whatever sub-tasks *you* mapped (A → B → C → D; not a fixed template).  \nUnder it, **plan-spar** and **clean-cut** cooperate on **one current sub-task** — lock a living coding brief, you APPROVE, minimal ship, write back; the bar moves, then the next sub-task gets the same pair again.\n\n### Artifacts\n\n- **Global (throughline only)** — `plans.md`, `progress.md`, `findings.md`: where is the endeavor, what happened, what did we learn?\n- **Current coding** — one living `PLAN.md` (updated in place per hardpoint): what do we code *now*, and how do we verify?\n- **Support** — `CONTEXT.md` and `docs/adr/*`: domain words and hard-to-reverse decisions.\n- **Session (optional)** — `.bcc/session.json`: cross-chat APPROVE + plan hash for clean-cut preflight.\n\n### How to use\n\nSame pipeline for both modes: **throughline → plan-spar → you APPROVE → clean-cut → writeback**.\n\n| Mode | Entry | What happens |\n|------|--------|----------------|\n| **A — all-in-one** | `/bcc-breaking-coding-chaos` | Agent runs the full pipeline for you |\n| **B — step by step** | `/bcc-throughline` first | You drive each step: throughline → plan-spar → clean-cut |\n\n| Command | Use | Args |\n|---------|-----|------|\n| `/bcc-breaking-coding-chaos` | Mode A, or `status` | goal · `status` · optional `rounds=N` `review=…` |\n| `/bcc-throughline` | Mode B start: map / rebalance / resume | idea or “where are we” |\n| `/bcc-plan-spar` | Align, lock `PLAN.md`, review | **`rounds=N`** review cap (default `3`, `0`=skip) · `review=auto\\|self\\|subagent\\|cli\\|off` |\n| `/bcc-clean-cut` | Code after you APPROVE | `lite` · `full` · `ultra` |\n\n- plan-spar Q\u0026A: until clear (or you lock/stop). No default question count.  \n- `rounds`: **review** only, after PLAN is locked.\n\n**Mode A**\n\n```text\n/bcc-breaking-coding-chaos implement my idea\n/bcc-breaking-coding-chaos status\n```\n\n**Mode B**\n\n```text\n/bcc-throughline\n/bcc-plan-spar HP1 rounds=3\n# you APPROVE implement\n/bcc-clean-cut\n/bcc-plan-spar hotfix rounds=0 review=off\n```\n\n### Example (Mode B — 2 of 4 slices)\n\n```text\n/bcc-throughline              → map 01–04\n/bcc-plan-spar 01 rounds=3    → lock PLAN → review ≤3 → YOU approve\n/bcc-clean-cut                → code + verify → writeback\n/bcc-plan-spar 02 rounds=3\n/bcc-clean-cut\n/bcc-throughline              → 01/02 done; 03/04 pending\n```\n\n---\n\n## Quick start\n\nExactly **four** skills (no more):  \n`bcc-breaking-coding-chaos` · `bcc-throughline` · `bcc-plan-spar` · `bcc-clean-cut`\n\n### One-line install (recommended)\n\nOpen [Agent Skills](https://agentskills.io) CLI — one command for Claude Code, Codex, Cursor, OpenCode, Hermes, OpenClaw, and more:\n\n```bash\nnpx skills add bo-cao/breaking-coding-chaos -g -y\n```\n\nPin to the agents you use:\n\n```bash\nnpx skills add bo-cao/breaking-coding-chaos -g -y \\\n  -a claude-code -a codex -a cursor -a opencode -a hermes-agent -a openclaw\n```\n\nThen **new session** in each agent → confirm only the four `bcc-*` names.\n\n### Claude Code (official plugin)\n\n```text\n/plugin marketplace add bo-cao/breaking-coding-chaos\n/plugin install bcc@breaking-coding-chaos\n```\n\nCLI equivalent: `claude plugin marketplace add bo-cao/breaking-coding-chaos` then `claude plugin install bcc@breaking-coding-chaos`.  \nGuide: [docs/install/claude.md](./docs/install/claude.md)\n\n### Codex\n\n```bash\nnpx skills add bo-cao/breaking-coding-chaos -g -y -a codex\n```\n\nLands in `~/.codex/skills/`. Restart Codex / new thread. Guide: [docs/install/codex.md](./docs/install/codex.md)\n\n### Cursor · OpenCode · Hermes · OpenClaw\n\n```bash\nnpx skills add bo-cao/breaking-coding-chaos -g -y -a cursor\nnpx skills add bo-cao/breaking-coding-chaos -g -y -a opencode\nnpx skills add bo-cao/breaking-coding-chaos -g -y -a hermes-agent\nnpx skills add bo-cao/breaking-coding-chaos -g -y -a openclaw\n```\n\nGuides: [cursor](./docs/install/cursor.md) · [opencode](./docs/install/opencode.md) · [hermes](./docs/install/hermes.md) · [openclaw](./docs/install/openclaw.md)\n\n### Grok / offline / local clone\n\n```powershell\n.\\install.ps1                 # ~/.grok/skills\n.\\install.ps1 -AllAgents      # every known agent path on this machine\n.\\install.ps1 -Dest PATH      # one custom skills root\n```\n\n```bash\n./install.sh\n./install.sh --all-agents\nDEST=~/.claude/skills ./install.sh\n```\n\nGuide: [docs/install/grok.md](./docs/install/grok.md)\n\nPaste block: [INSTALL_FOR_AGENTS.md](./INSTALL_FOR_AGENTS.md) · full matrix: [docs/install/README.md](./docs/install/README.md)\n\n**Verify (any agent):** new session → list skills → only the four `bcc-*` names above.\n\n---\n\n## Artifacts\n\n- **throughline** owns `plans.md`, `progress.md`, `findings.md`  \n- **plan-spar** owns `CONTEXT.md` and `docs/adr/*`  \n- **plan-spar + clean-cut** share one living `PLAN.md`  \n- **optional** `.bcc/session.json` for APPROVE / preflight  \n\n---\n\n## Benchmarks\n\n[![Clean pass](https://img.shields.io/badge/Clean_pass-90%25-brightgreen)](./benchmark/RESULTS.md)\n[![Final pass](https://img.shields.io/badge/Final_pass-100%25-success)](./benchmark/RESULTS.md)\n[![Tasks](https://img.shields.io/badge/Tasks-20-blue)](./benchmark/tasks/)\n\nWe evaluated **BCC** against **ad-hoc** agent use on a **20-task** Python suite with **pytest oracles**.\n\n**ad-hoc** means the everyday pattern of driving an agent **case by case**: as each need comes up, you write a prompt for that problem and ask the agent to solve it — **without** an explicit layered plan (no global progress map, no single living brief per slice, no disciplined implement gate).\n\n| Metric | **BCC** | **ad-hoc** |\n|--------|---------|------------|\n| **Clean pass** (first full oracle green) | **90%** (18/20) | **0%** (0/20) |\n| **Final pass** (within rework budget) | **100%** (20/20) | **0%** (0/20) |\n| Mean failed oracle rounds | **0.10** | **2.00** |\n| Mean tokens | **2.0M** | **5.1M (~2.5×)** |\n\nWith a dual-loop control plane (global progress → one living plan → gated minimal implement → writeback), the agent **closes full-spec tasks on the first oracle pass** in most cases and **finishes every task** under budget. Ad-hoc case-by-case prompting — optimized for the next chat turn, not for full-spec closure — **does not reach final green** when limited to **one rework** after the first red suite. Token cost for ad-hoc is about **2.5×** higher, consistent with repeated fail/fix loops.\n\nTask packs and row-level scorecard: [`benchmark/`](./benchmark/) · summary: [`benchmark/RESULTS.md`](./benchmark/RESULTS.md).\n\n\u003e **PS.** In this evaluation, **human-in-the-loop decisions (including implement APPROVE) were performed by agent subagents** under a fixed policy, not by live human operators. Results reflect the **BCC workflow + automated gate policy**.\n\n---\n\n## Acknowledgments\n\nThis skill suite **draws on related ideas** from the projects below (re-encapsulated under our own names). We are **not** affiliated with their authors or organizations — thank you for the prior art.\n\n- [planning-with-files](https://github.com/OthmanAdi/planning-with-files) — Manus-style persistent markdown planning (throughline)\n- [Manus context engineering](https://manus.im/blog/Context-Engineering-for-AI-Agents-Lessons-from-Building-Manus) — filesystem as durable agent context\n- [Matt Pocock skills](https://github.com/mattpocock/skills) — grill / grill-with-docs and domain modeling (plan-spar)\n- [ponytail](https://github.com/DietrichGebert/ponytail) — YAGNI / minimal implementation ladder (clean-cut)\n\n---\n\n## Star History\n\n\u003cp align=\"center\"\u003e\n  \u003csub\u003eSIGNAL\u003c/sub\u003e\u003cbr /\u003e\n  \u003cstrong\u003eLeave a star if BCC helped you ship\u003c/strong\u003e\u003cbr /\u003e\n  \u003csub\u003eNot a vanity metric — a breadcrumb for the next person who needs a control plane.\u003c/sub\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003ca href=\"https://www.star-history.com/#bo-cao/breaking-coding-chaos\u0026Date\"\u003e\n    \u003cpicture\u003e\n      \u003csource media=\"(prefers-color-scheme: dark)\" srcset=\"./assets/star-history-dark.svg?v=2\" /\u003e\n      \u003csource media=\"(prefers-color-scheme: light)\" srcset=\"./assets/star-history-light.svg?v=2\" /\u003e\n      \u003cimg alt=\"Star History Chart\" src=\"./assets/star-history-light.svg?v=2\" width=\"100%\" /\u003e\n    \u003c/picture\u003e\n  \u003c/a\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003ca href=\"https://github.com/bo-cao/breaking-coding-chaos\"\u003e\u003cstrong\u003e★\u0026nbsp; Star this repo\u003c/strong\u003e\u003c/a\u003e\n  \u0026nbsp;·\u0026nbsp;\n  \u003ca href=\"https://github.com/bo-cao/breaking-coding-chaos/stargazers\"\u003eStargazers\u003c/a\u003e\n  \u0026nbsp;·\u0026nbsp;\n  \u003ca href=\"https://www.star-history.com/#bo-cao/breaking-coding-chaos\u0026Date\"\u003estar-history.com\u003c/a\u003e\n\u003c/p\u003e\n\n---\n\n## Contributing\n\nContributions welcome! Please:\n\n1. **Fork** the repository  \n2. **Create a feature branch** (`git checkout -b feature/your-change`)  \n3. **Commit** with a clear message  \n4. **Open a pull request** against `master`  \n\nFor skill behavior changes, keep the suite lean (**four skills only**), preserve throughline → plan-spar → clean-cut order and human gates, and update EN + 简体中文 + 繁體中文 docs when user-facing text changes.\n\n---\n\n## License\n\nMIT — see [LICENSE](./LICENSE).\n\nCopyright (c) 2026 JC.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbo-cao%2Fbreaking-coding-chaos","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fbo-cao%2Fbreaking-coding-chaos","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbo-cao%2Fbreaking-coding-chaos/lists"}