debugging-patterns
DO NOT invoke directly - loaded by workflow agents via cc10x-router.Always loaded by: bug-investigator, integration-verifier.Provides system
Open source Repository Open in the app JSON README (API)
About
DO NOT invoke directly - loaded by workflow agents via cc10x-router.Always loaded by: bug-investigator, integration-verifier.Provides systematic debugging patterns: LOG FIRST approach, root cause inve
Details
- Kind
- Agent skills
- Topic
- Developer tools
- Publisher
- romiluz13
- Origin
- majiayu
- Category
- ferramentas
- Stars
- 19
- Forks
- 26
- Last push
- 2026-08-03T17:42:57Z
- Repository state
- ativo
- Language
- Python
- License
- MIT
- Added
- 2026-09-01 17:06:32
- Updated
- 2026-09-01 17:06:32
- Origin id
romiluz13/cc10x/plugins/cc10x/skills/debugging-patterns@main
README
<p align="center">
<img src="assets/logo.png" alt="CC10x — The Loop Engine for Claude Code. Orange stylized X with starburst and CC10x wordmark." width="280" />
</p>
<h1 align="center">cc10x — The Loop Engine for Claude Code</h1>
<p align="center">
<em>Stop chasing better models. Engineer the loop.</em>
</p>
<p align="center">
Same model. Same Claude Code. Different outcome.<br />
The agent forgets between turns. <strong>The harness remembers across runs.</strong><br />
cc10x writes every workflow to disk — intent, evidence, verdicts, failures — so resume, review, and verification read from the artifact, not from a context window that's already gone.
</p>
<p align="center">
<strong>1 router</strong> · <strong>11 specialist agents</strong> · <strong>20 skills</strong> · <strong>4 workflows</strong>
</p>
<p align="center">
Fail-closed gates · survives compaction · dispatch-by-reference · test honesty gates · anti-anchored review
</p>
<p align="center">
<strong>Explore interactively:</strong> <a href="cc10x-explorer.html">cc10x Explorer</a> · <a href="cc10x-architecture-explorer.html">Architecture Explorer</a>
</p>
**Current version:** 12.8.0
---
## Install
**Step 1 — Add the marketplace:**
```bash
/plugin marketplace add romiluz13/cc10x
```
**Step 2 — Install the plugin:**
```bash
/plugin install cc10x@cc10x
```
Then say **"set up cc10x for me"** in Claude Code and restart. Done.
---
## Quick Start Examples
### Build Something
```
"build a user authentication system"
→ Router detects BUILD intent
→ Stops to resolve missing requirements first
→ component-builder drives RED → GREEN → REFACTOR
→ code-reviewer + failure-hunter run in parallel
→ integration-verifier checks wiring, artifacts, and behavior
→ Workflow state and memory are updated
```
### Fix a Bug
```
"debug the payment processing error"
→ Router detects DEBUG intent
→ Loads prior failures and project memory
→ bug-investigator starts from logs and observed behavior
→ code-reviewer checks the fix path
→ integration-verifier confirms the bug is actually closed
→ Useful findings go back into memory
```
### Review Code
```
"review this PR for security issues"
→ Router detects REVIEW intent
→ code-reviewer uses repo and git context
→ Reports findings only when confidence clears the bar
→ Every finding includes file:line evidence
```
---
## Why cc10x
Ask Claude for something complex. It works for a while. Then it declares **"Done!"** — tests still red, refactor half-finished, and by message 40 it's contradicting itself because the context is gone.
**cc10x fixes the loop, not the prompt.** A better model running free loses to the same model, constrained and looped correctly. That's the whole bet.
| The pain you know | How cc10x handles it |
| --- | --- |
| "Done!" on red tests | `integration-verifier` is independent of the builder. Phase-exit gates block advancement on partial evidence. |
| Silent failures nobody asked about | `failure-hunter` runs in parallel with review — greps for swallowed errors and empty catches. |
| Context falls apart after compaction | Workflow state on disk with stable UUIDs. Memory files the router auto-heals. |
| Planning is just a chat | Three planning modes chosen by intent, with a fresh anti-anchored review by a reviewer who never saw the planner's rationale. |
| 12 slash commands to remember | One router. Every request hits `cc10x-router` first. |
| `.claude/` prompt spam on every fanout | State lives at `.cc10x/` — outside `.claude/`, so the harness's sensitive-file gate never fires. |
| Green tests that prove nothing | Test Honesty Gates grep for `getByTestId('…-mock')`, `as any`, `.find()` bypass, `setTimeout()` waits. A hit can't count as PASS on that test's strength alone. |
| Reviewer findings that sound right but aren't | Every finding at confidence ≥80 needs a verbatim `file:line` quote or it's auto-demoted. The verifier independently re-reads the line and drops hallucinated findings before they can gate. |
| Orchestrator context rotting with pasted history | Dispatch by reference, not by blob — the diff is written to disk, the prompt passes a path, never a body. (One real dispatch hit 42k chars, 99% pasted history. The scar became law.) |
---
## How It Works
**You describe the work. cc10x routes it, brings in the right specialists, and keeps the bar for "done" higher than a convincing paragraph.**
```
YOU
│
▼
┌────────────────────────┐
│ cc10x-router │ ◄── only entry point
│ detects intent │
└────────────┬───────────┘
│
┌──────────────┼──────────────┬─────────────┐
│ │ │ │
▼ ▼ ▼ ▼
BUILD DEBUG REVIEW PLAN
│ │ │ │
▼ ▼ ▼ ▼
component- bug- code- planner
builder investigator reviewer │
│ │ │ ▼
▼ ▼ (done) plan-gap-
[code-reviewer code-reviewer reviewer
∥ silent- │
failure- ▼
hunter] integration-
│ verifier
▼
integration-
verifier
┌──────────────────────────┐
│ STATE (every workflow) │
│ activeContext.md │
│ patterns.md │
│ progress.md │
│ {wf}.json + .events │
└──────────────────────────┘
```
---
## Claude Setup Instructions
This section is written for Claude Code to follow when the user says "set up cc10x for me".
**When user says "set up cc10x", "install cc10x", or similar:**
### Step 1: Check Existing Files
- Read `~/.claude/CLAUDE.md` (may not exist)
- Read `~/.claude/settings.json` (may not exist)
### Step 2: Update `~/.claude/CLAUDE.md`
**If file doesn't exist:** CREATE with the template below.
**If file exists:** PREPEND the cc10x section below, keep user's existing content.
> **Multi-project note:** The global `~/.claude/CLAUDE.md` activates cc10x in **every** project automatically — you do not need to reinstall or reconfigure per project. Only add the cc10x section to a project's `.claude/CLAUDE.md` if that project has its own conflicting CLAUDE.md already.
```markdown
# CC10x Orchestration (Always On)
IMPORTANT: ALWAYS invoke cc10x-router on ANY development task. First action, no exceptions.
IMPORTANT: Do only minimal orientation if needed, then invoke the router immediately.
IMPORTANT: Prefer retrieval-led reasoning over pre-training-led reasoning for orchestration decisions.
IMPORTANT: Never bypass the router. It is the system.
IMPORTANT: NEVER use Edit, Write, or Bash (for code changes) without first invoking cc10x-router.
**Skip CC10x ONLY when:**
- User EXPLICITLY says "don't use cc10x", "without cc10x", or "skip cc10x"
- No interpretation. No guessing. Only these exact opt-out phrases.
[CC10x]|entry: cc10x:cc10x-router
---
## Complementary Skills (Work Together with CC10x)
**Skills are additive, not exclusive.** CC10x provides orchestration. Domain skills provide expertise. Both work together.
**GATE:** Before writing code, check if task matches a skill below. If match, invoke it via `Skill(skill="...")`.
| When task involves... | Invoke |
|-----------------------|--------|
| *(Add user's installed skills here)* | |
```
### Step 3: Update `~/.claude/settings.json`
**If file doesn't exist:** CREATE with the template below.
**If file exists:** MERGE these permissions into the existing `permissions.allow` array (don't overwrite!):
```json
"Bash(mkdir -p .cc10x)",
"Bash(mkdir -p docs/plans)",
"Bash(mkdir -p docs/research)",
"Bash(mkdir -p docs/solutions)",
"Bash(git status)",
"Bash(git diff:*)",
"Bash(git log:*)",
"Bash(git branch:*)",
"Bash(git blame:*)",
"Bash(git ls-files:*)",
"Bash(git rev-parse:*)",
"Bash(python3:*)",
"Edit(.cc10x/*)",
"Write(.cc10x/*)"
```
> **Why the Edit/Write permissions?** The live cc10x memory namespace is `.cc10x/`. The permission examples use the `.cc10x/*` scope so the namespace works without re-prompting on every memory write.
> **Why `git rev-parse` and `python3`?** Every BUILD phase records its base SHA (`git rev-parse HEAD`), and the router produces review diff packages and phase briefs by running plugin tools via `python3`. Without these two, every phase prompts mid-workflow.
### Step 4: Set User Standards (Optional)
Ask the user:
> "Do you have coding standards or principles you want cc10x agents to always follow? (e.g. 'always use TypeScript strict mode', 'follow SOLID principles', 'never use `any`', 'prefer functional patterns')"
**If user provides standards**, write them to the project's memory:
```
Bash(command="mkdir -p .cc10x")
# Check if patterns.md already exists (Read returns error = doesn't exist)
Read(file_path=".cc10x/patterns.md")
# If it DOESN'T exist — create with standards already populated:
Write(file_path=".cc10x/patterns.md", content="# Project Patterns\n<!-- CC10X MEMORY CONTRACT: Do not rename headings. Used as Edit anchors. -->\n\n## User Standards\n- {standard 1}\n- {standard 2}\n\n## Common Gotchas\n\n## Project SKILL_HINTS\n\n## Last Updated\n{date}")
# If it DOES exist — append under User Standards:
Edit(file_path=".cc10x/patterns.md",
old_string="## User Standards",
new_string="## User Standards\n- {standard 1}\n- {standard 2}")
Read(file_path=".cc10x/patterns.md") # Verify
```
**If user skips:** No action. The memory file will be created on first workflow run with an empty `## User Standards` section for them to fill in later.
### Step 5: Scan Installed Skills & Add to Table
**Where to find installed skills:**
1. `~/.claude/settings.json` → check `enabledPlugins` object (plugins with value `true`)
2. `~/.claude/plugins/installed_plugins.json` → detailed plugin info
3. `~/.claude/skills/` → personal skills (all projects)
4. `.claude/skills/` → project-specific skills
**Skill naming in table:**
- **Plugin skills:** `plugin-name:skill-name` (e.g., `mongodb-agent-skills:mongodb-schema-design`)
- **Personal/project skills:** just the skill name (e.g., `react-best-practices`)
**Example:** If user has these:
```
# In enabledPlugins:
"mongodb-agent-skills@mongodb-agent-skills": true
# In ~/.claude/skills/:
react-best-practices/SKILL.md
```
**Add to the Complementary Skills table:**
```markdown
| When task involves... | Invoke |
|-----------------------|--------|
| MongoDB, schema, queries | `mongodb-agent-skills:mongodb-schema-design` |
| React, Next.js, UI | `react-best-practices` |
```
### Step 6: Confirm
>
> "cc10x is set up! Please restart Claude Code to activate."
---
## The 4 Workflows
| Intent | Trigger Words | What Happens |
| -------- | --------------- | -------------- |
| **BUILD** | build, implement, create, make, write, add | Clarify scope → TDD implementation → adversarial review → integration verification |
| **DEBUG** | debug, fix, error, bug, broken, troubleshoot | Reproduce from evidence → isolate cause → validate fix → prove no regression |
| **REVIEW** | review, audit, check, analyze, assess | High-signal review with confidence thresholds and file:line citations |
| **PLAN** | plan, design, architect, roadmap, strategy | Turn rough intent into an execution-ready plan with explicit decisions |
---
## Memory Persistence
cc10x survives context compaction. This is critical for long sessions.
```
.cc10x/
├── activeContext.md # What you're working on NOW
│ - Current task
│ - Active decisions (and WHY)
│ - Learnings this session
│
├── patterns.md # Project conventions
│ - Code patterns
│ - Common gotchas (bugs → fixes)
│ - Architectural decisions
│
└── progress.md # What's done, what's left
- Completed items (with evidence)
- Remaining tasks
- Blockers
```
The live namespace is `.cc10x/` (memory `.cc10x/*.md`, workflow state `.cc10x/workflows/*`). Two legacy residue locations are ignored by current router hydration if present: `.claude/cc10x/` (pre-10.1.20, before the workflow state moved out of `.claude/` to escape the harness sensitive-file gate) and the version-segmented `.cc10x/v10/` layout (v10.x, before the namespace was de-versioned in v11). cc10x does not migrate either; a fresh `.cc10x/` is created on first use.
**Iron Law:** Every workflow loads memory at START and updates at END.
---
## Optional MCP Integrations
cc10x works out of the box with no MCPs required. These are **optional** — they unlock specific features when installed in your own Claude Code MCP settings.
| MCP | Feature Unlocked | How to Install |
| ----- | ----------------- | ---------------- |
| **[octocode](https://github.com/nicepkg/octocode)** | GitHub research: find packages, search code across repos, read PR history. Triggered automatically when planner or bug-investigator needs external research. | Install via Claude Code MCP settings using the server name `octocode` |
| **[brightdata](https://github.com/nicepkg/mcp-brightdata)** | Web scraping for research tasks — used as fallback when web content is needed beyond GitHub. | Install via Claude Code MCP settings using the server name `brightdata` |
**Important:** CC10X no longer ships MCP server config inside the plugin. This avoids startup warnings for users who do not have Bright Data or Octocode credentials configured.
**Without these MCPs:** cc10x still works fully. The research agents degrade to built-in Claude Code tools and note the lower-confidence path in their outputs.
**With octocode installed:** When the router detects new/unfamiliar tech, 3+ failed debug attempts, or explicit research requests, it automatically calls octocode tools to search GitHub before invoking the planner or bug-investigator.
---
## Troubleshooting
### Claude Code keeps asking for permission to edit memory files
Add these two lines to `~/.claude/settings.json` under `permissions.allow`:
```json
"Edit(.cc10x/*)",
"Write(.cc10x/*)"
```
These permission examples cover the live `.cc10x/` namespace.
Or run **"Set up cc10x for me"** again — the setup wizard adds them automatically.
---
### cc10x asks for permission before writing plan/research docs
Working as intended. `.cc10x/` orchestration state is pre-permitted, but outward-facing project artifacts (`docs/plans/`, `docs/research/`, `docs/solutions/`) prompt for approval by design — trust-first friction, not missing configuration. Approve the write to continue.
---
### cc10x not activating in a specific project
The global `~/.claude/CLAUDE.md` activates cc10x in every project — you only need one install. If it's not activating in a specific project:
1. **Check if that project has its own `.claude/CLAUDE.md`** — open it and verify the cc10x section is present. If the project-level file exists but doesn't have the cc10x entry, add it there.
2. **Verify the entry format** — use `[CC10x]|entry: cc10x:cc10x-router` (plugin reference). A relative path like `./plugins/cc10x/...` only works in the cc10x repo itself, not in your projects.
3. **Restart Claude Code** — the plugin system requires a restart after any CLAUDE.md change.
---
### Ubuntu / Linux install error: EXDEV cross-device link
If you see:
```
Error: Failed to install: EXDEV: cross-device link not permitted
```
This is a Linux filesystem issue — `/tmp` and your home directory are on different filesystems, so the installer can't `rename()` across them. Fix:
```bash
# Set TMPDIR to a directory on the same filesystem as your home:
mkdir -p ~/.claude/tmp
TMPDIR=~/.claude/tmp claude
# Then install normally: /plugin install cc10x@cc10x
```
If that doesn't work, install manually:
```bash
# Clone directly into the plugins directory
git clone https://github.com/romiluz13/cc10x.git ~/.claude/plugins/cc10x
```
Then follow Step 2 in the setup guide above to add the cc10x entry to `~/.claude/CLAUDE.md`.
---
### "Unknown skill cc10x:cc10x-router"
The cc10x plugin is disabled. Run:
```
/plugins enable cc10x
```
Then retry your command.
---
## Architecture Deep Dive
Everything below the fold: how the loop actually works. For contributors and the curious — you do not need any of this to use cc10x.
<details>
<summary><strong>Runtime model, router kernel, agents, skills, hooks, diagrams, file layout</strong></summary>
### Runtime Model
#### 1. Router owns orchestration
`cc10x-router` is the only orchestration authority.
The router now uses a **kernel + mandatory reference** shape:
- universal orchestration law stays inline in `cc10x-router/SKILL.md`
- workflow-specific playbooks and appendix-heavy artifact/remediation law live in `cc10x-router/references/*.md`
- the kernel explicitly tells Claude which reference must be read before BUILD / DEBUG / REVIEW / PLAN branch logic continues
That keeps orchestration salient without turning the router into a context dump.
It decides:
- which workflow to run
- which subagent to invoke next
- when to pause for clarification or scope decisions
- when remediation is required
- when a workflow is allowed to advance
- when memory and workflow artifacts are finalized
Agents do not own workflow state. They return structured results. The router interprets them.
#### 2. Agents are narrow specialists
The shipped subagents are intentionally specialized:
- `planner`
- `plan-gap-reviewer`
- `component-builder`
- `bug-investigator`
- `code-reviewer`
- `failure-hunter`
- `integration-verifier`
- `researcher`
- `doc-syncer`
Each agent is optimized for one role. This keeps prompts sharper and makes workflow behavior easier to reason about.
#### 3. Skills are reusable local instructions
Skills are the reusable instruction layer that agents and the router depend on.
They provide:
- planning patterns
- TDD rules
- debugging patterns
- review rules
- research synthesis
- memory handling
- verification-before-completion discipline
#### 4. Workflow artifacts are the durable truth
cc10x writes proof-of-work workflow state under:
```text
.cc10x/workflows/{wf}.json
.cc10x/workflows/{wf}.events.jsonl
```
These artifacts track:
- workflow type and task ids
- intent/spec context
- agent results
- evidence and quality state
- remediation history
- lifecycle events
This is what makes resume, review, and debugging more reliable than relying on chat context alone.
#### 5. Hooks are guardrails, not a second orchestrator
cc10x ships a minimal Claude Code-native hook set:
- `PreToolUse`
- `SessionStart`
- `PostToolUse`
- `TaskCompleted`
Hooks do not replace the router. They provide lightweight enforcement and diagnostics:
- protected file and workflow write checks
- resume context hydration
- workflow artifact integrity audit
- task metadata validation
This follows the official Claude Code pattern: hooks are small guardrails around tool use, not a parallel control plane.
#### 6. MCP is optional acceleration only
cc10x does **not** ship MCP server config inside the plugin.
If the user already has Claude Code MCP servers named:
- `octocode`
- `brightdata`
then research gets better automatically.
If not, the plugin still works. Research falls back to built-in Claude Code tools and records degraded confidence where appropriate.
---
### BUILD flow, up close
```
┌──────────────────────────────────────────────────────────────────────────────┐
│ │
│ YOU: "build a user auth system" │
│ ┌────────────────────────────────────┐ │
│ ┌─────►│ component-builder │ │
│ │ │ + TDD enforcement │ │
│ ┌────────────────────┐ │ │ + code-generation skill │ │
│ │ │ │ └──────────────┬─────────────────────┘ │
│ │ cc10x-router │─────┤ │ │
│ │ (auto-detects │ │ ┌──────────────▼─────────────────────┐ │
│ │ BUILD intent) │ │ │ code-reviewer ∥ silent-failure │ │
│ │ │ │ │ (parallel execution) │ │
│ └────────────────────┘ │ └──────────────┬─────────────────────┘ │
│ │ │ │
│ │ ┌──────────────▼─────────────────────┐ │
│ └─────►│ integration-verifier │ │
│ │ + E2E validation │ │
│ └────────────────────────────────────┘ │
│ │
└──────────────────────────────────────────────────────────────────────────────┘
```
---
### Architecture
```
USER REQUEST
│
▼
┌─────────────────────────────────────────────────────────────────┐
│ cc10x-router (ONLY ENTRY POINT) │
│ Detects intent → Routes to workflow │
└─────────────────────────────────────────────────────────────────┘
│
├── BUILD ──► component-builder ──► [code-reviewer ∥ failure-hunter] ──► integration-verifier
│
├── DEBUG ──► bug-investigator ──► code-reviewer ──► integration-verifier
│
├── REVIEW ─► code-reviewer
│
└── PLAN ───► planner
MEMORY (.cc10x/)
├── activeContext.md ◄── Current focus, decisions, learnings
├── patterns.md ◄── Project conventions, common gotchas
└── progress.md ◄── Completed work, remaining tasks
WORKFLOW STATE (.cc10x/workflows/)
├── {wf}.json ◄── Durable workflow artifact
└── {wf}.events.jsonl ◄── Append-only workflow event log
```
---
### The 11 Agents
| Agent | Purpose | Key Behavior |
| ------- | --------- | -------------- |
| **component-builder** | Builds features | TDD: RED → GREEN → REFACTOR (no exceptions) |
| **bug-investigator** | Fixes bugs | LOG FIRST: Evidence before any fix |
| **code-reviewer** | Reviews code | Confidence ≥80%; 6-pass adversarial review (security, performance, quality, friction, plan validity, spec compliance) |
| **failure-hunter** | Hunts silent failures | Runs in parallel with code-reviewer; zero-tolerance for empty catches, log-only handlers, discarded errors |
| **integration-verifier** | E2E validation | Exit codes: PASS/FAIL with evidence |
| **doc-syncer** | Diff-driven documentation sync | Classifies doc impact; SKIPPED/PARTIAL/COMPLETE/FAIL contract gating Memory Update; honors `DIFF_DRIVEN_DOCS: skip` |
| **planner** | Creates plans | Saves to `docs/plans/` + updates memory |
| **plan-gap-reviewer** | Fresh plan challenge pass | Read-only anti-anchoring review before final plan handoff |
| **researcher** | Web + GitHub research (Bright Data / Octocode MCP accelerators, built-in fallbacks) | Saves findings to file |
| **triage-agent** | Triages incoming issues/PRs | Read-only; categorizes, verifies, checks redundancy + prior rejection, writes agent-ready briefs |
| **architecture-scanner** | Codebase health audit | Read-only; scans for shallow modules + deepening candidates, produces HTML report with before/after diagrams |
---
## The 20 Skills
Skills are **loaded automatically by agents**. You never invoke them directly.
| Skill | Used By | Purpose |
| ------- | --------- | --------- |
| **agent-common** | ALL agents | Shared preamble: memory protocol, CONTRACT envelope, output rules |
| **memory-and-handoff** | main session (router-gated) | Persist context across compaction; portable handoff package |
| **verification** | builder, verifier, investigator | Evidence before claims: gate function, validation levels, evidence array |
| **building** | component-builder | TDD RED-GREEN-REFACTOR, false-RED guard, integration & live proof |
| **debugging** | bug-investigator | Root cause analysis, feedback loop first, blast radius after fix |
| **code-review** | main session | Verify human/external review feedback before agreeing or implementing |
| **planning** | planner | Comprehensive plans + plan completeness gate |
| **plan-review-gate** | planner | Final fail-closed plan sanity gate before handoff |
| **architecture** | planner, builder (router-gated) | System & API design for multi-component work |
| **frontend** | UI work (router-gated) | Authoring + critique modes: UX, accessibility, DESIGN.md, AI-slop detection |
| **exploration** | PLAN workflow (router-gated) | Design brainstorm + throwaway spike modes with machine-readable handoff |
| **diff-driven-docs** | doc-syncer | Doc impact classification + audit-doc format |
| **research** | planner, bug-investigator (via researcher agent) | Synthesis-only: how to interpret research results |
| **codebase-hygiene** | code-reviewer, planner (router-gated) | Semantic-duplicate audit + shallow-module deepening |
| **codebase-design** | planner, builder, investigator, reviewer (router-gated) | Canonical deep-module vocabulary: module, interface, depth, seam, adapter, leverage, locality |
| **domain-modeling** | planner, doc-syncer (active); builder, investigator (read-only) | Active glossary discipline: challenge terms, sharpen language, write CONTEXT.md + ADRs |
| **mcp-cli** | researcher | On-demand MCP server use without permanent context pollution |
| **update** | maintainers | Maintenance meta-skill for updating cc10x itself |
| **cc10x-guide** | users asking about cc10x (model-invoked) | Answers questions about cc10x itself: install, setup, workflows, memory, troubleshooting; never executes work |
| **resolving-merge-conflicts** | any agent hitting a git conflict (model-invoked) | Resolve merge/rebase conflicts hunk by hunk by intent; never --abort |
> `cc10x-router` is the entry-point skill that routes every workflow; it ships alongside these 20.
---
### Task-Based Orchestration
cc10x uses Claude Code's Tasks system for workflow coordination:
```
┌─────────────────────────────────────────────────────────────────┐
│ BUILD: User Authentication │
│ ├── component-builder (pending) │
│ ├── code-reviewer (blocked by: builder) │
│ ├── failure-hunter (blocked by: builder) │
│ └── integration-verifier (blocked by: reviewer, hunter) │
└─────────────────────────────────────────────────────────────────┘
```
- **Dependency chains**: Agents wait for blockers to complete
- **Parallel execution**: reviewer + hunter run simultaneously
- **Resume capability**: TaskList() checks for active workflows
- **Automatic handoff**: Each agent updates status when done
- **Router-owned advancement**: only the router decides whether a workflow can continue
---
### Hooks
The plugin currently ships these Claude Code-native hooks:
| Hook | Purpose |
| ------ | --------- |
| `PreToolUse` | Guard protected files and workflow-owned writes |
| `SessionStart` | Rehydrate workflow context after restart or compaction |
| `PostToolUse` | Audit workflow artifact integrity after writes |
| `TaskCompleted` | Validate CC10X task metadata before task completion |
| `PostCompact` | Capture compaction events for workflow telemetry |
| `SubagentStop` | Audit subagent outputs for required contract markers |
| `PreCompact` | Snapshot workflow state before compaction |
| `Stop` | Snapshot workflow state on session stop |
| `StopFailure` | Log API failure telemetry asynchronously |
| `InstructionsLoaded` | Audit instruction-file loading asynchronously |
These hooks are intentionally minimal. They improve reliability without turning the plugin into a second runtime.
---
### Plan → Build Automation
Plans don't get lost. They flow automatically to the build phase.
```
Day 1: "plan a task tracker"
→ Planner creates docs/plans/2025-01-29-task-tracker-plan.md
→ Memory updated with plan reference
Day 2: "build it"
→ Router detects BUILD
→ component-builder finds plan in memory
→ Follows plan phases with TDD
```
---
### Expected Behavior
#### When You Say "Build a Task Tracker"
**cc10x Response:**
```
Detected BUILD intent. Executing BUILD workflow.
Loading memory...
✓ Memory loaded
Clarifying requirements (REQUIRED):
1. What framework/language? (Node.js, Python, etc.)
2. Should tasks have priorities, due dates, categories?
3. CLI app or web app?
4. Any features beyond basic CRUD?
Waiting for your answers before proceeding.
```
**Without cc10x:**
```
I'll help you build a task tracker! Let me start...
[Writes code without asking]
[Skips tests]
[Claims "it should work"]
```
---
### Files Structure
```
plugins/cc10x/
├── .claude-plugin/
│ └── plugin.json
├── hooks/
│ └── hooks.json
├── config/
│ └── hook-mode.json
├── scripts/
│ ├── cc10x_event_logger.py
│ ├── cc10x_git_guard.py
│ ├── cc10x_hooklib.py
│ ├── cc10x_posttooluse_artifact_guard.py
│ ├── cc10x_pretooluse_guard.py
│ ├── cc10x_sessionstart_context.py
│ ├── cc10x_state_persist.py
│ └── cc10x_task_completed_guard.py
├── tools/
│ ├── review_package.py
│ ├── phase_brief.py
│ └── live_harness_runner.py
├── tests/
│ └── fixtures/
├── agents/
│ ├── component-builder.md
│ ├── bug-investigator.md
│ ├── code-reviewer.md
│ ├── integration-verifier.md
│ ├── doc-syncer.md
│ ├── planner.md
│ ├── plan-gap-reviewer.md
│ ├── researcher.md
│ ├── triage-agent.md
│ ├── architecture-scanner.md
│ └── references/silent-failure-red-flags.md
│
└── skills/
├── cc10x-router/
│ ├── SKILL.md
│ └── references/
│ ├── workflow-artifact-and-hook-policy.md
│ ├── workflow-artifact.skeleton.json
│ ├── build-workflow.md
│ ├── debug-workflow.md
│ ├── review-workflow.md
│ ├── plan-workflow.md
│ ├── triage-workflow.md
│ ├── codebase-health-workflow.md
│ └── remediation-and-research.md
├── agent-common/SKILL.md
├── memory-and-handoff/SKILL.md
├── building/SKILL.md
├── debugging/SKILL.md
├── code-review/SKILL.md
├── planning/SKILL.md
├── plan-review-gate/SKILL.md
├── architecture/SKILL.md
├── frontend/SKILL.md
│ └── references/{ui-state-and-feedback,accessibility-and-forms,performance-and-layout,design-md-authoring,design-md-inspiration-index}.md
├── exploration/SKILL.md
├── diff-driven-docs/SKILL.md
├── research/SKILL.md
├── verification/SKILL.md
├── codebase-hygiene/SKILL.md
├── codebase-design/SKILL.md
│ └── references/{DEEPENING,DESIGN-IT-TWICE}.md
├── domain-modeling/SKILL.md
│ └── references/{CONTEXT-FORMAT,ADR-FORMAT}.md
├── mcp-cli/SKILL.md
├── resolving-merge-conflicts/SKILL.md
├── cc10x-guide/SKILL.md
└── update/SKILL.md
```
Additional developer docs live under:
```text
docs/cc10x-orchestration-bible.md
docs/cc10x-orchestration-logic-analysis.md
docs/cc10x-orchestration-safety.md
docs/router-invariants.md
```
If you need to understand or evolve the harness, start there after reading `cc10x-router`.
</details>
---
## Version History
<details>
<summary><strong>Release history (v5.3 → v12.8.0)</strong></summary>
| Version | Highlights |
| --------- | ------------ |
| **v10.1.20** | Escape the Claude Code sensitive-file gate: workflow state root relocated from `.claude/cc10x/v10/` to `.cc10x/v10/` across every prompt surface, runtime hook, and fixture. Every router fanout, event-log append, and memory refresh is now silent in default-permission setups. Audit now catches runtime/prompt path drift so this class of regression fails self-tests before release. |
| **v10.1.19** | Harmony hardening release: contradiction cleanup across router-facing instructions, router-owned self-contained handoffs, phase-local BUILD context, early memory capture before validation, review/hunt fan-in at the router, and full docs/release metadata alignment. |
| **v10.1.15** | Hook expansion: 4 audit-only hooks (PreCompact, Stop, StopFailure, InstructionsLoaded) for workflow state persistence and telemetry. 6→10 hook events. Zero blocking, zero context injection, router remains sole authority. |
| **v10.1.14** | Multi-repo harmony integration: 29 certified patterns from 11 reference repos via 3-phase harmony pipeline. Test tampering detection, claim extraction, environment escape hatches, analysis paralysis guards, near-miss negative testing, de-sloppify scans, plans-are-prompts principle, professional objectivity hard rules. |
| **v10.1.13** | Ruflo harmony integration: 29 prompt engineering edits across 16 files — research quality heuristics, multi-language silent-failure detection, friction-scan thresholds, rollback decision trees, plan completeness gates, behavioral TDD focus, partial-phase review scoping, abstraction thresholds, split-brain contradiction handling, evidence-before-reporting hard rules |
| **v10.1.12** | Prompt engineering uplift: 15 techniques from mattpocock/skills integrated across 13 files — durable decisions, tracer bullets, vertical-slice TDD, dependency taxonomy, HITL/AFK phases, opinionated review, friction scan, scope assessment, domain context injection |
| **v10.1.11** | DAG-visible PLAN review loop: the full bounded planning review chain is now pre-created in the task graph, with explicit branch pruning and `plan-gap-reviewer` restored to `gpt-5.4-mini` |
| **v10.1.10** | Always-on fresh planning review: every saved plan artifact now queues the bounded `plan-gap-reviewer` task before final plan handoff, with replay coverage locking it in |
| **v10.1.4** | Fresh planning review cleanup: raw user request passed to `plan-gap-reviewer`, lighter read-only reviewer contract, bounded pass counting fixed, docs/version surfaces refreshed |
| **v10.1.3** | Planning recovery: code-grounded plans, explicit plan-vs-code gap surfacing, stronger repo-aware plan review, and planning-specific replay coverage |
| **v10.1.2** | Trust-preserving latency instrumentation: verifier workload telemetry, phase-exit vs extended-audit classification, no proof-gating change |
| **v10.1.1** | Prompt-only hardening: sharper anti-false-completion wording, better trigger/description hygiene, reduced prompt dilution, no orchestration/runtime changes |
| **v10.1.0** | Competition-grade release: decision-grade planning, adversarial plan gates, proof-oriented BUILD, harsher VERIFY, and benchmark-backed prompt/harness hardening |
| **v10.0.0** | Trust-first recovery: agreement-first planning, phase-gated BUILD, stable workflow UUIDs, versioned v10 state, advisory internal skills |
| **v9.1.1** | Removed shipped MCP config to avoid startup warnings; MCP research remains optional via user-configured Claude Code MCP servers named `brightdata` and `octocode` |
| **v9.1.0** | Publication polish: intent-first planning, BDD-style scenario evidence, DDD-style domain language preservation, proof-of-work workflow artifacts, built-in harness drift audit |
| **v9.0.0** | Plugin-native packaging: bundled Claude Code hooks, optional plugin MCP acceleration, router-owned research quality model, workflow artifacts as durable truth |
| **v8.5.0** | Fix 1: READ-ONLY task completion as explicit mandatory gate (3-GATE). Fix 2b: CRITICAL+HIGH scope question via text (Rule 1a-SCOPE + Scope Decision Resume + scope-aware re-hunt) |
| **v8.0.0** | Radical simplification — remove Router Contract YAML from read-only agents; text-based verdict extraction; JUST_GO session mode; ~280 lines removed |
| **v7.9.0** | OBS-2/3/4/6/7/8/10/11/12/13/14 batch fix — self-healing verifier, explicit DEBUG-RESET marker, conditional frontend-patterns load |
| **v7.8.0** | OBS-1/9/15/16/DEBUG-RESET — 5-issue fix, 13/13 smoke test pass |
| **v6.0.21** | User standards support; multi-project docs; Linux install troubleshooting |
| **v6.0.20** | Agent self-report task completion; MCP docs; permissions fix for memory files |
| **v6.0.19** | Babysitter-inspired: Multi-signal HARD/SOFT scoring, evidence arrays, decision checkpoints, completion guard |
| **v6.0.0** | Orchestration hardening: Tasks contract correctness + Task-enforced gates + re-review loop |
| **v5.25.1** | GSD-inspired enhancements (wiring verification, hypothesis criteria) |
| **v5.25.0** | Critical orchestration fixes + README redesign |
| **v5.24.0** | Research persistence with THREE-PHASE pattern |
| **v5.23.0** | Plan-task linkage (legacy: metadata.planFile; now deprecated) |
| **v5.22.0** | Stub detection patterns |
| **v5.21.0** | Task-based orchestration with TaskCreate/TaskUpdate |
| **v5.20.0** | Goal-backward verification lens |
| **v5.13.0** | Parallel agent execution (~30-50% faster) |
| **v5.10.0** | Anthropic Claude 4.x best practices |
| **v5.9.1** | Plan→Build automatic connection |
<details>
<summary>Full version history</summary>
- **v8.0.0** - Radical Simplification: Removed Router Contract YAML from code-reviewer, silent-failure-hunter, integration-verifier. Replaced ~200-line YAML validation block in router with 30-line text extraction (reads heading from first 5 lines). Added JUST_GO session mode (AUTO_PROCEED flag). Simplified Empty Answer Guard — only ⚠️ REVERT gates block; all others auto-default. Removed REM-EVIDENCE retry loop (root cause of 6/6 stress test failures). Net: ~280 lines removed, 0 new complexity.
- **v7.9.0** - OBS-2/3/4/6/7/8/10/11/12/13/14 batch fix: self-healing integration-verifier (creates REM-FIX + blocks own task), explicit DEBUG-RESET marker written by router, conditional frontend-patterns load (.tsx/.jsx/.vue/.css/.scss/.html only)
- **v7.8.0** - OBS-1/9/15/16/DEBUG-RESET 5-issue fix, 13/13 smoke test pass
- **v6.0.19** - Babysitter-inspired enhancements: Multi-signal HARD/SOFT scoring (per-dimension review), evidence array protocol (structured proof), decision checkpoints (mandatory pause points), completion guard (final gate before Router Contract)
- **v6.0.0** - Orchestration hardening:
- Tasks contract correctness (no undocumented TaskCreate fields; canonical TaskUpdate object form)
- CC10X task namespacing + safer resume rules
- Task-enforced gates + re-review loop after remediation (prevents unreviewed changes)
- **v5.25.1** - GSD-inspired enhancements: Wiring verification patterns, hypothesis quality criteria, cognitive biases table
- **v5.25.0** - Critical orchestration fixes: Plan propagation, results collection, skill hierarchy, validation + README redesign
- **v5.24.0** - Research Documentation Persistence: THREE-PHASE research pattern
- **v5.23.0** - Plan-Task Linkage: metadata.planFile for context recovery (legacy; deprecated in v6.0.0)
- **v5.22.0** - Stub Detection Patterns: GSD-inspired stub detection
- **v5.21.0** - Task-Based Orchestration: TaskCreate, TaskUpdate, TaskList integration
- **v5.20.0** - Goal-Backward Lens: Verification enhancements
- **v5.19.0** - OWASP Reference + Minimal Diffs + ADR patterns
- **v5.18.0** - Two-Phase github-research
- **v5.13.1** - Bulletproof chain enforcement
- **v5.13.0** - Parallel agent execution
- **v5.12.1** - Fixed orphan skills
- **v5.12.0** - Pre-publish audit
- **v5.11.0** - Workflow chain enforcement
- **v5.10.6** - Foolproof Router with decision tree
- **v5.10.5** - Complete Permission-Free Audit
- **v5.10.4** - True Permission-Free Memory
- **v5.10.3** - Fixed invalid agent color
- **v5.10.2** - Permission-Free Memory
- **v5.10.1** - Router Supremacy
- **v5.10.0** - Anthropic Claude 4.x alignment
- **v5.9.1** - Plan→Build connection
- **v5.9.0** - Two-step save pattern
- **v5.8.1** - Router bypass prevention
- **v5.7.0** - Fixed agent keyword conflicts
- **v5.6.0** - Fixed agent tool misconfigurations
- **v5.5.0** - Fixed skill keyword conflicts
- **v5.4.0** - Router AUTO-EXECUTE
- **v5.3.0** - Confidence scoring, silent-failure-hunter
</details>
</details>
---
## Contributing
- Star the repository
- Report issues
- Suggest improvements
---
## License
MIT License
---
<p align="center">
<strong>cc10x v12.8.0</strong><br>
<em>The Intelligent Orchestrator for Claude Code</em>
</p>