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.
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.
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.
There is a rich ecosystem of agent memory products and libraries — for example mem0 and 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).
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.
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.
People and projects behind the patterns:
- Manus — AI agent company whose context-engineering write-up 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 (Othman Adi et al.) — highly adopted open skill that operationalizes Manus-style plan / progress / findings markdown so multi-step work survives
/clearand context loss. - Matt Pocock — TypeScript educator (Total TypeScript); formerly XState core team and developer advocate at Vercel. His open skills (grill / domain-modeling style) push hard questions, shared language, and ADRs before code.
- ponytail (Dietrich Gebert) — 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.
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.
- 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.mdanddocs/adr/*: domain words and hard-to-reverse decisions. - Session (optional) —
.bcc/session.json: cross-chat APPROVE + plan hash for clean-cut preflight.
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
/bcc-breaking-coding-chaos implement my idea
/bcc-breaking-coding-chaos status
Mode B
/bcc-throughline
/bcc-plan-spar HP1 rounds=3
# you APPROVE implement
/bcc-clean-cut
/bcc-plan-spar hotfix rounds=0 review=off
/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
Exactly four skills (no more):
bcc-breaking-coding-chaos · bcc-throughline · bcc-plan-spar · bcc-clean-cut
Open Agent Skills CLI — one command for Claude Code, Codex, Cursor, OpenCode, Hermes, OpenClaw, and more:
npx skills add bo-cao/breaking-coding-chaos -g -yPin to the agents you use:
npx skills add bo-cao/breaking-coding-chaos -g -y \
-a claude-code -a codex -a cursor -a opencode -a hermes-agent -a openclawThen new session in each agent → confirm only the four bcc-* names.
/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
npx skills add bo-cao/breaking-coding-chaos -g -y -a codexLands in ~/.codex/skills/. Restart Codex / new thread. Guide: docs/install/codex.md
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 openclawGuides: cursor · opencode · hermes · openclaw
.\install.ps1 # ~/.grok/skills
.\install.ps1 -AllAgents # every known agent path on this machine
.\install.ps1 -Dest PATH # one custom skills root./install.sh
./install.sh --all-agents
DEST=~/.claude/skills ./install.shGuide: docs/install/grok.md
Paste block: INSTALL_FOR_AGENTS.md · full matrix: docs/install/README.md
Verify (any agent): new session → list skills → only the four bcc-* names above.
- throughline owns
plans.md,progress.md,findings.md - plan-spar owns
CONTEXT.mdanddocs/adr/* - plan-spar + clean-cut share one living
PLAN.md - optional
.bcc/session.jsonfor APPROVE / preflight
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/ · summary: 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.
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 — Manus-style persistent markdown planning (throughline)
- Manus context engineering — filesystem as durable agent context
- Matt Pocock skills — grill / grill-with-docs and domain modeling (plan-spar)
- ponytail — YAGNI / minimal implementation ladder (clean-cut)
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 this repo · Stargazers · star-history.com
Contributions welcome! Please:
- Fork the repository
- Create a feature branch (
git checkout -b feature/your-change) - Commit with a clear message
- 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.
MIT — see LICENSE.
Copyright (c) 2026 JC.