Data

Tools

Indexes

Applications

Experiments

Awesome

An open API service indexing awesome lists of open source software.

https://github.com/bo-cao/breaking-coding-chaos


https://github.com/bo-cao/breaking-coding-chaos

Last synced: about 19 hours ago
JSON representation

Awesome Lists containing this project

README 

          
# breaking-coding-chaos



[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](./LICENSE)

[![Agent Skills](https://img.shields.io/badge/Agent%20Skills-4-informational)](./skills)

[![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)

[![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)

[![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)





  breaking-coding-chaos — dual-loop human-in-the-loop coding with agents




**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.



**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.



[English](./README.md) | [简体中文](./READMEs/README.zh-CN.md) | [繁體中文](./READMEs/README.zh-TW.md)



[Quick start](#quick-start)



> **Idea first.** Bring a **reasonably concrete idea** (what to build, what “done” means).  

> BCC helps you **implement it 1:1** with control over progress and technical detail — **not** invent a product from a blank void.  

> Without a real idea, there is nothing honest to code.



---



## Why a control plane



Agentic coding is powerful — and chronically **unreliable at the exact moment precision matters**.



When the work needs **fine-grained design**, **explicit trade-offs**, and **progress you can audit**, sessions often end in:



- **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.

- **Hallucinated certainty** — the model fills gaps with plausible inventiveness: wrong APIs, phantom modules, “fixes” that never touch the real failure mode.

- **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.



### Long-term memory tools are not the same problem



There 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.



High-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.



When 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.



That is **breaking-coding-chaos** (BCC).



---



## Who it’s for



BCC 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:



- **Researchers & 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.  

- **Engineers & 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.  

- **Indie builders & founders** — Turn a concrete product idea into auditable sub-tasks; stop the agent from reinventing the app every conversation.  

- **Repo maintainers** — Global map plus one hard slice at a time; less thrash after compaction, context loss, or switching tools.  

- **Multi-agent users** (Claude / Codex / Cursor / …) — Same four skills, same dual loop — one control plane across runtimes.



**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.  

**Weak / wrong tool:** vibe one-liners, throwaway scripts, or no concrete idea yet — BCC implements ideas; it does not invent products.



---



## Where these ideas come from



Agentic 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.





  Separate ideas for context, align, and cut — composed into one control loop




**People and projects behind the patterns:**



- **[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.  

- **[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.  

- **[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**.  

- **[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.  





  Not another memory layer — a human-in-the-loop control plane.






  

  See the whole endeavor. Focus one hard slice at a time.


  Dual loop, hard order: map → spar the plan → cut the minimum.


  One living brief per slice. Progress must write back. Wrong step cannot fire early.

  




---



## How it works





  Ship your idea with agents — throughline progress, plan-spar one sub-task, clean-cut ships it






  Dual loop. Human gates. One living plan per sub-task.




**Throughline** sits on top: the **project progress bar** over whatever sub-tasks *you* mapped (A → B → C → D; not a fixed template).  

Under 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.



### Artifacts



- **Global (throughline only)** — `plans.md`, `progress.md`, `findings.md`: where is the endeavor, what happened, what did we learn?

- **Current coding** — one living `PLAN.md` (updated in place per hardpoint): what do we code *now*, and how do we verify?

- **Support** — `CONTEXT.md` and `docs/adr/*`: domain words and hard-to-reverse decisions.

- **Session (optional)** — `.bcc/session.json`: cross-chat APPROVE + plan hash for clean-cut preflight.



### How to use



Same pipeline for both modes: **throughline → plan-spar → you APPROVE → clean-cut → writeback**.



| Mode | Entry | What happens |

|------|--------|----------------|

| **A — all-in-one** | `/bcc-breaking-coding-chaos` | Agent runs the full pipeline for you |

| **B — step by step** | `/bcc-throughline` first | You drive each step: throughline → plan-spar → clean-cut |



| Command | Use | Args |

|---------|-----|------|

| `/bcc-breaking-coding-chaos` | Mode A, or `status` | goal · `status` · optional `rounds=N` `review=…` |

| `/bcc-throughline` | Mode B start: map / rebalance / resume | idea or “where are we” |

| `/bcc-plan-spar` | Align, lock `PLAN.md`, review | **`rounds=N`** review cap (default `3`, `0`=skip) · `review=auto\|self\|subagent\|cli\|off` |

| `/bcc-clean-cut` | Code after you APPROVE | `lite` · `full` · `ultra` |



- plan-spar Q&A: until clear (or you lock/stop). No default question count.  

- `rounds`: **review** only, after PLAN is locked.



**Mode A**



```text

/bcc-breaking-coding-chaos implement my idea

/bcc-breaking-coding-chaos status

```



**Mode B**



```text

/bcc-throughline

/bcc-plan-spar HP1 rounds=3

# you APPROVE implement

/bcc-clean-cut

/bcc-plan-spar hotfix rounds=0 review=off

```



### Example (Mode B — 2 of 4 slices)



```text

/bcc-throughline              → map 01–04

/bcc-plan-spar 01 rounds=3    → lock PLAN → review ≤3 → YOU approve

/bcc-clean-cut                → code + verify → writeback

/bcc-plan-spar 02 rounds=3

/bcc-clean-cut

/bcc-throughline              → 01/02 done; 03/04 pending

```



---



## Quick start



Exactly **four** skills (no more):  

`bcc-breaking-coding-chaos` · `bcc-throughline` · `bcc-plan-spar` · `bcc-clean-cut`



### One-line install (recommended)



Open [Agent Skills](https://agentskills.io) CLI — one command for Claude Code, Codex, Cursor, OpenCode, Hermes, OpenClaw, and more:



```bash

npx skills add bo-cao/breaking-coding-chaos -g -y

```



Pin to the agents you use:



```bash

npx skills add bo-cao/breaking-coding-chaos -g -y \

  -a claude-code -a codex -a cursor -a opencode -a hermes-agent -a openclaw

```



Then **new session** in each agent → confirm only the four `bcc-*` names.



### Claude Code (official plugin)



```text

/plugin marketplace add bo-cao/breaking-coding-chaos

/plugin install bcc@breaking-coding-chaos

```



CLI equivalent: `claude plugin marketplace add bo-cao/breaking-coding-chaos` then `claude plugin install bcc@breaking-coding-chaos`.  

Guide: [docs/install/claude.md](./docs/install/claude.md)



### Codex



```bash

npx skills add bo-cao/breaking-coding-chaos -g -y -a codex

```



Lands in `~/.codex/skills/`. Restart Codex / new thread. Guide: [docs/install/codex.md](./docs/install/codex.md)



### Cursor · OpenCode · Hermes · OpenClaw



```bash

npx skills add bo-cao/breaking-coding-chaos -g -y -a cursor

npx skills add bo-cao/breaking-coding-chaos -g -y -a opencode

npx skills add bo-cao/breaking-coding-chaos -g -y -a hermes-agent

npx skills add bo-cao/breaking-coding-chaos -g -y -a openclaw

```



Guides: [cursor](./docs/install/cursor.md) · [opencode](./docs/install/opencode.md) · [hermes](./docs/install/hermes.md) · [openclaw](./docs/install/openclaw.md)



### Grok / offline / local clone



```powershell

.\install.ps1                 # ~/.grok/skills

.\install.ps1 -AllAgents      # every known agent path on this machine

.\install.ps1 -Dest PATH      # one custom skills root

```



```bash

./install.sh

./install.sh --all-agents

DEST=~/.claude/skills ./install.sh

```



Guide: [docs/install/grok.md](./docs/install/grok.md)



Paste block: [INSTALL_FOR_AGENTS.md](./INSTALL_FOR_AGENTS.md) · full matrix: [docs/install/README.md](./docs/install/README.md)



**Verify (any agent):** new session → list skills → only the four `bcc-*` names above.



---



## Artifacts



- **throughline** owns `plans.md`, `progress.md`, `findings.md`  

- **plan-spar** owns `CONTEXT.md` and `docs/adr/*`  

- **plan-spar + clean-cut** share one living `PLAN.md`  

- **optional** `.bcc/session.json` for APPROVE / preflight  



---



## Benchmarks



[![Clean pass](https://img.shields.io/badge/Clean_pass-90%25-brightgreen)](./benchmark/RESULTS.md)

[![Final pass](https://img.shields.io/badge/Final_pass-100%25-success)](./benchmark/RESULTS.md)

[![Tasks](https://img.shields.io/badge/Tasks-20-blue)](./benchmark/tasks/)



We evaluated **BCC** against **ad-hoc** agent use on a **20-task** Python suite with **pytest oracles**.



**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).



| Metric | **BCC** | **ad-hoc** |

|--------|---------|------------|

| **Clean pass** (first full oracle green) | **90%** (18/20) | **0%** (0/20) |

| **Final pass** (within rework budget) | **100%** (20/20) | **0%** (0/20) |

| Mean failed oracle rounds | **0.10** | **2.00** |

| Mean tokens | **2.0M** | **5.1M (~2.5×)** |



With 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.



Task packs and row-level scorecard: [`benchmark/`](./benchmark/) · summary: [`benchmark/RESULTS.md`](./benchmark/RESULTS.md).



> **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**.



---



## Acknowledgments



This 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.



- [planning-with-files](https://github.com/OthmanAdi/planning-with-files) — Manus-style persistent markdown planning (throughline)

- [Manus context engineering](https://manus.im/blog/Context-Engineering-for-AI-Agents-Lessons-from-Building-Manus) — filesystem as durable agent context

- [Matt Pocock skills](https://github.com/mattpocock/skills) — grill / grill-with-docs and domain modeling (plan-spar)

- [ponytail](https://github.com/DietrichGebert/ponytail) — YAGNI / minimal implementation ladder (clean-cut)



---



## Star History





  SIGNAL


  Leave a star if BCC helped you ship


  Not a vanity metric — a breadcrumb for the next person who needs a control plane.






  

    

      

      

      Star History Chart

    

  






  ★  Star this repo

   · 

  Stargazers

   · 

  star-history.com




---



## Contributing



Contributions welcome! Please:



1. **Fork** the repository  

2. **Create a feature branch** (`git checkout -b feature/your-change`)  

3. **Commit** with a clear message  

4. **Open a pull request** against `master`  



For 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.



---



## License



MIT — see [LICENSE](./LICENSE).



Copyright (c) 2026 JC.