cc10x — The Loop Engine for Claude Code

Same model. Same Claude Code. Different outcome.

The agent forgets between turns. The harness remembers across runs.
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.

1 router  ·  14 specialist agents  ·  21 skills  ·  8 workflows

Fail-closed gates  ·  survives compaction  ·  dispatch-by-reference  ·  test honesty gates  ·  anti-anchored review

Current version: 12.10.0

Install

cc10x needs Python 3.9 or newer on PATH (3.13 is the version the test suite runs on): every hook except the preflight is a python3 script. A SessionStart preflight tells the agent when python3 is missing or too old.

Step 1 — Add the marketplace (once per machine):

claude plugin marketplace add romiluz13/cc10x

Step 2 — Install the plugin:

claude plugin install cc10x@cc10x

Inside a Claude Code session the same two steps are /plugin marketplace add romiluz13/cc10x and /plugin install cc10x@cc10x.

Then say "set up cc10x for me" in Claude Code and restart. Done.

Update

claude plugin update cc10x@cc10x --scope user

Use the scope you installed at (user, project, local or managed). Then run /reload-plugins in an open session, or restart Claude Code.

Auto-update is off by default for third-party marketplaces such as romiluz13/cc10x, so a new release does not arrive on its own. Either update by hand as above, or open /plugin, go to the Marketplaces tab, select the marketplace and choose Enable auto-update.

Manual install from a clone

git clone https://github.com/romiluz13/cc10x.git
claude --plugin-dir "$PWD/cc10x/plugins/cc10x"

--plugin-dir loads the plugin for that one session only. Skills are then namespaced cc10x:<skill>, and the router is cc10x:cc10x-router.

Recommended environment variables

Keep .cc10x/ out of git

cc10x writes memory and workflow state under .cc10x/ in each project. It is session state, not source, so gitignore .cc10x/ in each project: add the line .cc10x/ to its .gitignore. How it relates to Claude Code's own memory is under Memory Persistence.

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

Test a Feature

"write an end-to-end test plan for checkout and run it"

→ Router detects QA intent
→ qa-researcher agents survey the code, specs and tickets, one source each
→ A test plan is reviewed by plan-gap-reviewer before anything is built
→ qa-harness-builder provisions the environment
→ code-reviewer + failure-hunter check the harness
→ qa-executor runs the plan and fills in the report

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. The same model, constrained and looped correctly, does better than the same model running free. That's the whole bet.

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       │
                   └────────────┬───────────┘
                                │
   ┌────────┬────────┬──────────┼───────┬───────┬────────┬──────────────────┐
   ▼        ▼        ▼          ▼       ▼       ▼        ▼                  ▼
 DEBUG     PLAN    REVIEW     ORIENT    QA    TRIAGE  CODEBASE-          BUILD
                                                      HEALTH          (the default)

   Each workflow is a chain of the specialist agents. The full table is below.

                 ┌──────────────────────────┐
                 │  STATE (every workflow)  │
                 │  activeContext.md        │
                 │  patterns.md             │
                 │  progress.md             │
                 │  {wf}.json + .events     │
                 └──────────────────────────┘

The 8 Workflows

The router picks the workflow from the request's primary deliverable. When more than one fits, the lower priority number wins; anything that matches no other row is BUILD.

The router file is the source of truth for the table: plugins/cc10x/skills/cc10x-router/SKILL.md, section 1.

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.

# CC10x Orchestration (Always On)

IMPORTANT: For multi-step development work (build, debug, review, plan), do minimal orientation first, then invoke cc10x-router before planning, implementation, review, or code changes.
IMPORTANT: Minimal orientation means only the nearest project instructions, manifest, and immediate target surface. Do not do broad exploration before routing.
IMPORTANT: Prefer retrieval-led reasoning over pre-training-led reasoning for orchestration decisions.
IMPORTANT: The router is the default for multi-step development work. Route write-heavy BUILD/DEBUG work through it; the router's fail-closed gates and durable artifacts are the value. A small edit still routes: the router runs a single trivial change as BUILD with trivial scope (a reduced task graph that keeps the verifier's proof path), and anything that spans files, has separable concerns, or changes a contract gets the full chain.

Precedence (highest first): explicit user instructions > project standards (CLAUDE.md / repo conventions) > approved plans and design docs > domain-specific skills > cc10x internal skills > router defaults. The router enforces quality; it does not override the user.

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

The router is the plugin skill `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!):

"Bash(mkdir -p .cc10x)",
"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/**)"

What Edit(.cc10x/**) does. It pre-approves file edits under .cc10x/ at any depth, so memory files, workflow artifacts and QA files stop prompting on every write. Claude Code applies an Edit(...) rule to every file-editing tool, Write included, so one rule covers both; a Write(.cc10x/*) allow rule does nothing (Claude Code warns that only Edit(...) rules are matched), which is why this template no longer has one. Claude Code drops a project's permissions.allow entries until you trust the workspace, so put the rule in your user settings or trust the folder first.

What the Bash rules do. The mkdir -p rules create fixed directories (a rule matches the command text exactly, so .cc10x and .cc10x/ are two rules) and the git rules read repository state (git branch:* also lets Claude create branches; the git guard hook still denies pushes and forced deletes). Bash(python3:*) is broad: it approves any python3 command, not just cc10x's tools. It is in the template because every BUILD phase records its base SHA (git rev-parse HEAD) and the router builds review diff packages and phase briefs by running plugin tools via python3; without it, every phase prompts mid-workflow. If you do not want to pre-approve every python3 command, drop that rule and approve the plugin's python3 calls when prompted.

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:

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

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.

How .cc10x/ relates to Claude Code auto-memory

They are separate systems and neither replaces the other.

• .cc10x/ (cc10x memory): per-project files that cc10x's router and agents read at the start and write at the end of each workflow, plus the workflow artifacts and event logs. They hold this project's task context, conventions and progress, and they live in the project directory.
• Claude Code auto-memory: notes Claude Code itself keeps for you across conversations, stored under your Claude configuration directory (~/.claude, or $CLAUDE_CONFIG_DIR), outside the project. cc10x neither reads nor writes it.

Use auto-memory for preferences that follow you across projects, and .cc10x/ for what one project's workflows need to resume. Keep .cc10x/ out of git, as above.

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.

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 this line to ~/.claude/settings.json under permissions.allow:

"Edit(.cc10x/**)"

It covers the live .cc10x/ namespace at any depth (see Step 3 of the setup instructions for what it does and why there is no Write(...) rule).

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 router reference — the CLAUDE.md section names the plugin skill cc10x:cc10x-router. A relative path like plugins/cc10x/skills/cc10x-router/SKILL.md only resolves inside the cc10x repo itself, not in your projects.
3. Restart Claude Code — or run /reload-plugins after a plugin change. A CLAUDE.md change is read on the next session start.
4. Check Python — if the session start printed a CC10X python warning, the hooks are silently off until Python 3.9 or newer is on PATH.

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:

# 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, use the clone-and---plugin-dir route from Manual install from a clone, then follow Step 2 in the setup guide above to add the cc10x section to ~/.claude/CLAUDE.md.

"Unknown skill cc10x:cc10x-router"

The cc10x plugin is not installed or is disabled. Check with:

claude plugin list

If it is listed as disabled, run claude plugin enable cc10x@cc10x (or open /plugin and use the Installed tab), then /reload-plugins.

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.

.cc10x/workflows/{wf}.json
.cc10x/workflows/{wf}.events.jsonl

┌──────────────────────────────────────────────────────────────────────────────┐
│                                                                              │
│   YOU: "build a user auth system"                                            │
│                                     ┌────────────────────────────────────┐   │
│                              ┌─────►│  component-builder                 │   │
│                              │      │  + TDD enforcement                 │   │
│   ┌────────────────────┐     │      │  + building and verification       │   │
│   │                    │     │      │    skills                          │   │
│   │   cc10x-router     │─────┤      └──────────────┬─────────────────────┘   │
│   │   (auto-detects    │     │                     │                         │
│   │    BUILD intent)   │     │      ┌──────────────▼─────────────────────┐   │
│   │                    │     │      │  code-reviewer ∥ failure-hunter    │   │
│   └────────────────────┘     │      │  (parallel execution)              │   │
│                              │      └──────────────┬─────────────────────┘   │
│                              │                     │                         │
│                              │      ┌──────────────▼─────────────────────┐   │
│                              └─────►│  integration-verifier              │   │
│                                     │  + E2E validation                  │   │
│                                     └────────────────────────────────────┘   │
│                                                                              │
└──────────────────────────────────────────────────────────────────────────────┘

USER REQUEST
     │
     ▼
┌─────────────────────────────────────────────────────────────────┐
│                    cc10x-router (ONLY ENTRY POINT)              │
│              Detects intent → Routes to workflow                │
└─────────────────────────────────────────────────────────────────┘
     │
     ├── DEBUG ──► bug-investigator ──► code-reviewer ──► integration-verifier
     │
     ├── PLAN ───► exploration ──► planner ──► plan-gap-reviewer (bounded loop)
     │
     ├── REVIEW ─► code-reviewer
     │
     ├── ORIENT ─► inline orientation (no agents)
     │
     ├── QA ─────► qa-researcher (fan-out) ──► plan-gap-reviewer ──► qa-harness-builder
     │              ──► [code-reviewer ∥ failure-hunter] ──► qa-executor
     │
     ├── TRIAGE ─► triage-agent
     │
     ├── CODEBASE-HEALTH ─► architecture-scanner
     │
     └── BUILD ──► component-builder ──► [code-reviewer ∥ failure-hunter] ──► integration-verifier

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

┌─────────────────────────────────────────────────────────────────┐
│  BUILD: User Authentication                                     │
│  ├── component-builder (pending)                                │
│  ├── code-reviewer (blocked by: builder)                        │
│  ├── failure-hunter (blocked by: builder)                       │
│  └── integration-verifier (blocked by: reviewer, hunter)        │
└─────────────────────────────────────────────────────────────────┘

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

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.

I'll help you build a task tracker! Let me start...
[Writes code without asking]
[Skips tests]
[Claims "it should work"]

plugins/cc10x/
├── .claude-plugin/
│   └── plugin.json
├── hooks/
│   ├── hooks.json
│   ├── README.md
│   └── pre-commit
├── config/
│   └── hook-mode.json
├── scripts/                # hook scripts and the L1 test suites (test_cc10x_*.py)
│   ├── cc10x_{event_logger,git_guard,hooklib,posttooluse_artifact_guard,pretooluse_guard,qa_isolation_guard,sessionstart_context,state_persist,task_completed_guard}.py
│   └── cc10x_preflight.sh
├── tools/
│   ├── {doc_consistency_check,fixture_registry,harness_audit,latency_audit,live_harness_runner,phase_brief,preload_probe,prompt_clause_assertions,release_gate,review_package,token_usage_report,workflow_replay_check}.py
│   └── docs_rot_baseline.json
├── templates/
│   ├── {coverage-thresholds,live-harness.template}.json
│   └── {doc-target-overlay,qa-env-plan.template,qa-feature-map.template,qa-report.template,qa-setup.template,qa-test-plan.template}.md
├── tests/
│   ├── fixtures/
│   └── live/
├── evals/
│   ├── BASELINE.md
│   └── cases/
├── agents/
│   └── {architecture-scanner,bug-investigator,code-reviewer,component-builder,doc-syncer,failure-hunter,integration-verifier,plan-gap-reviewer,planner,qa-executor,qa-harness-builder,qa-researcher,researcher,triage-agent}.md
│
└── skills/
    ├── cc10x-router/
    │   ├── SKILL.md
    │   └── references/
    │       ├── {build,debug,review,plan,triage,codebase-health,qa}-workflow.md
    │       ├── workflow-artifact-and-hook-policy.md
    │       ├── remediation-and-research.md
    │       └── workflow-artifact.skeleton.json
    ├── agent-common/SKILL.md
    ├── architecture/SKILL.md
    ├── building/SKILL.md
    ├── cc10x-guide/SKILL.md
    ├── code-review/SKILL.md
    ├── codebase-design/SKILL.md
    ├── codebase-hygiene/SKILL.md
    ├── debugging/SKILL.md
    ├── diff-driven-docs/SKILL.md
    ├── domain-modeling/SKILL.md
    ├── exploration/SKILL.md
    ├── frontend/SKILL.md
    ├── mcp-cli/SKILL.md
    ├── memory-and-handoff/SKILL.md
    ├── plan-review-gate/SKILL.md
    ├── planning/SKILL.md
    ├── qa-strategy/SKILL.md
    ├── research/SKILL.md
    ├── resolving-merge-conflicts/SKILL.md
    ├── update/SKILL.md
    └── verification/SKILL.md

Version History

Contributing

• Star the repository
• Report issues
• Suggest improvements

License

MIT License

cc10x v12.10.0

{
  "name": "cc10x",
  "owner": {
    "name": "Rom Iluz",
    "email": "rom@iluz.net",
    "url": "https://github.com/romiluz13"
  },
  "metadata": {
    "description": "cc10x v12.10.0 - The Loop Engine: a harness for Claude Code. One router sends each request to one of eight workflows (build, debug, review, plan, QA, orient, triage, codebase health) run by specialist subagents, with fail-closed gates, workflow artifacts on disk, hook guardrails, test honesty gates, fresh-context verification, and memory that survives compaction.",
    "version": "12.10.0"
  },
  "plugins": [
    {
      "name": "cc10x",
      "description": "The Loop Engine: a harness for Claude Code. One router sends each request to one of eight workflows (build, debug, review, plan, QA, orient, triage, codebase health) run by specialist subagents, with fail-closed gates, workflow artifacts on disk, hook guardrails, test honesty gates, fresh-context verification, and memory that survives compaction.",
      "author": {
        "name": "Rom Iluz",
        "email": "rom@iluz.net",
        "url": "https://github.com/romiluz13"
      },
      "homepage": "https://github.com/romiluz13/cc10x",
      "repository": "https://github.com/romiluz13/cc10x",
      "license": "MIT",
      "keywords": [
        "workflow-routing",
        "code-review",
        "tdd",
        "bdd",
        "debugging",
        "planning",
        "architecture",
        "frontend",
        "verification",
        "proof-of-work",
        "hooks",
        "qa",
        "claude-code"
      ],
      "category": "development-tools",
      "source": "./plugins/cc10x"
    }
  ]
}