Skip to content
Back to search

cc10x

SkillGitHubIncomplete

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today

Check it deeper on your machine

Its scripts were only partly scanned.

As a Claude Code plugin, install it and then ask Claude Code:

/plugin marketplace add keithmackay/mackayi/plugin install scanskillsafety@mackayiDo a deep scan of https://github.com/romiluz13/cc10x with scanskillsafety

Or from a terminal, clone it and run it:

git clone https://github.com/keithmackay/scanskillsafety-skill ~/.claude/skills/scanskillsafetynode ~/.claude/skills/scanskillsafety/cli.cjs --deep 'https://github.com/romiluz13/cc10x'

It checks the exact commit: every file, its packages against OSV (api.osv.dev), how it compares with this page's scan (findsafeskills.com receives the repository's address), and, if you agree, Claude reading every file with your own Claude subscription. It never runs the code.

Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/romiluz13--cc10x/badge.svg)](/listings/romiluz13--cc10x)

HTML

<a href="/listings/romiluz13--cc10x"><img src="/api/listings/romiluz13--cc10x/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

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

| Variable | Why | | --- | --- | | `CLAUDE_CODE_ENABLE_TODO_TOOLS=1` | Claude Code ships its task tools by default only on some models. cc10x works without them (it falls back to tracking the graph in the workflow artifact) but this restores them on every model. | | `CLAUDE_CODE_TASK_LIST_ID` (optional) | Shares one task list across sessions. | | `CLAUDE_CONFIG_DIR` (optional) | Moves Claude Code's configuration directory off `~/.claude`. Wherever this README says `~/.claude`, read `$CLAUDE_CONFIG_DIR`. | | `CLAUDE_CODE_PLUGIN_CACHE_DIR` (optional) | Moves the plugins root off `~/.claude/plugins`. |

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](#memory-persistence).

---

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

.claude-plugin/marketplace.json · Manifest · 43 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.

  1. {
  2. "name": "cc10x",
  3. "owner": {
  4. "name": "Rom Iluz",
  5. "email": "rom@iluz.net",
  6. "url": "https://github.com/romiluz13"
  7. },
  8. "metadata": {
  9. "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.",
  10. "version": "12.10.0"
  11. },
  12. "plugins": [
  13. {
  14. "name": "cc10x",
  15. "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.",
  16. "author": {
  17. "name": "Rom Iluz",
  18. "email": "rom@iluz.net",
  19. "url": "https://github.com/romiluz13"
  20. },
  21. "homepage": "https://github.com/romiluz13/cc10x",
  22. "repository": "https://github.com/romiluz13/cc10x",
  23. "license": "MIT",
  24. "keywords": [
  25. "workflow-routing",
  26. "code-review",
  27. "tdd",
  28. "bdd",
  29. "debugging",
  30. "planning",
  31. "architecture",
  32. "frontend",
  33. "verification",
  34. "proof-of-work",
  35. "hooks",
  36. "qa",
  37. "claude-code"
  38. ],
  39. "category": "development-tools",
  40. "source": "./plugins/cc10x"
  41. }
  42. ]
  43. }
README.md · README · 975 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.

  1. <p align="center">
  2. <img src="assets/logo.png" alt="CC10x — The Loop Engine for Claude Code. Orange stylized X with starburst and CC10x wordmark." width="280" />
  3. </p>
  4. <h1 align="center">cc10x — The Loop Engine for Claude Code</h1>
  5. <p align="center">
  6. <em>Same model. Same Claude Code. Different outcome.</em>
  7. </p>
  8. <p align="center">
  9. The agent forgets between turns. <strong>The harness remembers across runs.</strong><br />
  10. 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.
  11. </p>
  12. <p align="center">
  13. <strong>1 router</strong> &nbsp;·&nbsp; <strong>14 specialist agents</strong> &nbsp;·&nbsp; <strong>21 skills</strong> &nbsp;·&nbsp; <strong>8 workflows</strong>
  14. </p>
  15. <p align="center">
  16. Fail-closed gates &nbsp;·&nbsp; survives compaction &nbsp;·&nbsp; dispatch-by-reference &nbsp;·&nbsp; test honesty gates &nbsp;·&nbsp; anti-anchored review
  17. </p>
  18. **Current version:** 12.10.0
  19. ---
  20. ## Install
  21. 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.
  22. **Step 1 — Add the marketplace** (once per machine):
  23. ```bash
  24. claude plugin marketplace add romiluz13/cc10x
  25. ```
  26. **Step 2 — Install the plugin:**
  27. ```bash
  28. claude plugin install cc10x@cc10x
  29. ```
  30. Inside a Claude Code session the same two steps are `/plugin marketplace add romiluz13/cc10x` and `/plugin install cc10x@cc10x`.
  31. Then say **"set up cc10x for me"** in Claude Code and restart. Done.
  32. ### Update
  33. ```bash
  34. claude plugin update cc10x@cc10x --scope user
  35. ```
  36. Use the scope you installed at (`user`, `project`, `local` or `managed`). Then run `/reload-plugins` in an open session, or restart Claude Code.
  37. **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**.
  38. ### Manual install from a clone
  39. ```bash
  40. git clone https://github.com/romiluz13/cc10x.git
  41. claude --plugin-dir "$PWD/cc10x/plugins/cc10x"
  42. ```
  43. `--plugin-dir` loads the plugin for that one session only. Skills are then namespaced `cc10x:<skill>`, and the router is `cc10x:cc10x-router`.
  44. ### Recommended environment variables
  45. | Variable | Why |
  46. | --- | --- |
  47. | `CLAUDE_CODE_ENABLE_TODO_TOOLS=1` | Claude Code ships its task tools by default only on some models. cc10x works without them (it falls back to tracking the graph in the workflow artifact) but this restores them on every model. |
  48. | `CLAUDE_CODE_TASK_LIST_ID` (optional) | Shares one task list across sessions. |
  49. | `CLAUDE_CONFIG_DIR` (optional) | Moves Claude Code's configuration directory off `~/.claude`. Wherever this README says `~/.claude`, read `$CLAUDE_CONFIG_DIR`. |
  50. | `CLAUDE_CODE_PLUGIN_CACHE_DIR` (optional) | Moves the plugins root off `~/.claude/plugins`. |
  51. ### Keep `.cc10x/` out of git
  52. 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](#memory-persistence).
  53. ---
  54. ## Quick Start Examples
  55. ### Build Something
  56. ```
  57. "build a user authentication system"
  58. → Router detects BUILD intent
  59. → Stops to resolve missing requirements first
  60. → component-builder drives RED → GREEN → REFACTOR
  61. → code-reviewer + failure-hunter run in parallel
  62. → integration-verifier checks wiring, artifacts, and behavior
  63. → Workflow state and memory are updated
  64. ```
  65. ### Fix a Bug
  66. ```
  67. "debug the payment processing error"
  68. → Router detects DEBUG intent
  69. → Loads prior failures and project memory
  70. → bug-investigator starts from logs and observed behavior
  71. → code-reviewer checks the fix path
  72. → integration-verifier confirms the bug is actually closed
  73. → Useful findings go back into memory
  74. ```
  75. ### Review Code
  76. ```
  77. "review this PR for security issues"
  78. → Router detects REVIEW intent
  79. → code-reviewer uses repo and git context
  80. → Reports findings only when confidence clears the bar
  81. → Every finding includes file:line evidence
  82. ```
  83. ### Test a Feature
  84. ```
  85. "write an end-to-end test plan for checkout and run it"
  86. → Router detects QA intent
  87. → one negotiation at step 0 records grants and the test-plan approval policy; the router asks once, batched, when a grant is set to ask — agents never ask
  88. → the topology is recalled from a machine-local record under ~/.cc10x/qa/topology/ (or $CC10X_HOME/qa/topology/ — set CC10X_HOME to an absolute path: the CLI resolves a relative one against the current directory) and written back after confirmation and after the run (a regression re-run that never recalled a record skips the write)
  89. → qa-researcher agents survey the code, specs and tickets, one source each
  90. → A test plan is reviewed by plan-gap-reviewer before anything is built
  91. → the reviewed test plan is shown on screen for approval (policy-controlled)
  92. → qa-harness-builder provisions the environment
  93. → code-reviewer + failure-hunter check the harness
  94. → qa-executor runs the plan and fills in the report
  95. ```
  96. ---
  97. ## Why cc10x
  98. 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.
  99. **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.
  100. | The pain you know | How cc10x handles it |
  101. | --- | --- |
  102. | "Done!" on red tests | `integration-verifier` is independent of the builder. Phase-exit gates block advancement on partial evidence. |
  103. | Silent failures nobody asked about | `failure-hunter` runs in parallel with review — greps for swallowed errors and empty catches. |
  104. | Context falls apart after compaction | Workflow state on disk with stable UUIDs. Memory files the router auto-heals. |
  105. | 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. |
  106. | 12 slash commands to remember | One router. Every request hits `cc10x-router` first. |
  107. | `.claude/` prompt spam on every fanout | State lives at `.cc10x/` — outside `.claude/`, so the harness's sensitive-file gate never fires. |
  108. | 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. |
  109. | 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. |
  110. | 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.) |
  111. ---
  112. ## How It Works
  113. **You describe the work. cc10x routes it, brings in the right specialists, and keeps the bar for "done" higher than a convincing paragraph.**
  114. ```
  115. YOU
  116. │
  117. ▼
  118. ┌────────────────────────┐
  119. │ cc10x-router │ ◄── only entry point
  120. │ detects intent │
  121. └────────────┬───────────┘
  122. │
  123. ┌────────┬────────┬──────────┼───────┬───────┬────────┬──────────────────┐
  124. ▼ ▼ ▼ ▼ ▼ ▼ ▼ ▼
  125. DEBUG PLAN REVIEW ORIENT QA TRIAGE CODEBASE- BUILD
  126. HEALTH (the default)
  127. Each workflow is a chain of the specialist agents. The full table is below.
  128. ┌──────────────────────────┐
  129. │ STATE (every workflow) │
  130. │ activeContext.md │
  131. │ patterns.md │
  132. │ progress.md │
  133. │ {wf}.json + .events │
  134. └──────────────────────────┘
  135. ```
  136. ---
  137. ## The 8 Workflows
  138. 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.
  139. | Priority | Workflow | Trigger words | What happens |
  140. | --- | --- | --- | --- |
  141. | 1 | **DEBUG** | error, bug, fix, broken, crash, debug | Reproduce from evidence → isolate cause → validate fix → prove no regression (`bug-investigator` → `code-reviewer` → `integration-verifier`) |
  142. | 2 | **PLAN** | plan, design, architect, roadmap, spec, brainstorm | Turn rough intent into an execution-ready plan with explicit decisions, then a bounded fresh review (`planner` → `plan-gap-reviewer`) |
  143. | 3 | **REVIEW** | review, audit, analyze, assess | High-signal review with confidence thresholds and file:line citations (`code-reviewer`). Advisory only: never creates code-changing tasks |
  144. | 4 | **ORIENT** | zoom out, explain, "how does X work", "walk me through" | Read-only orientation answered inline: no agents, no phase graph, no writes |
  145. | 5 | **QA** | test, QA, e2e, integration test, test plan, regression | Testing the code is the deliverable: grants negotiation → topology recalled from `~/.cc10x/qa/topology/` → survey (user action inventory + behaviour-varying surface) → test plan → plan review → on-screen plan approval → environment → execution (`qa-researcher` ×N → `plan-gap-reviewer` → `qa-harness-builder` → `qa-executor`) |
  146. | 6 | **TRIAGE** | triage, "incoming issues" | Categorize and verify incoming issues or PRs and write agent-ready briefs (`triage-agent`). Advisory only |
  147. | 7 | **CODEBASE-HEALTH** | codebase health, deepening, shallow modules | Scan for deepening candidates and produce an HTML report (`architecture-scanner`). Advisory only |
  148. | 8 | **BUILD** | build, implement, create, add (and everything else) | Clarify scope → TDD implementation → adversarial review → integration verification (`component-builder` → `code-reviewer` ∥ `failure-hunter` → `integration-verifier`) |
  149. The router file is the source of truth for the table: [`plugins/cc10x/skills/cc10x-router/SKILL.md`](plugins/cc10x/skills/cc10x-router/SKILL.md), section 1.
  150. ---
  151. ## Claude Setup Instructions
  152. This section is written for Claude Code to follow when the user says "set up cc10x for me".
  153. **When user says "set up cc10x", "install cc10x", or similar:**
  154. ### Step 1: Check Existing Files
  155. - Read `~/.claude/CLAUDE.md` (may not exist)
  156. - Read `~/.claude/settings.json` (may not exist)
  157. ### Step 2: Update `~/.claude/CLAUDE.md`
  158. **If file doesn't exist:** CREATE with the template below.
  159. **If file exists:** PREPEND the cc10x section below, keep user's existing content.
  160. > **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.
  161. ```markdown
  162. # CC10x Orchestration (Always On)
  163. 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.
  164. IMPORTANT: Minimal orientation means only the nearest project instructions, manifest, and immediate target surface. Do not do broad exploration before routing.
  165. IMPORTANT: Prefer retrieval-led reasoning over pre-training-led reasoning for orchestration decisions.
  166. 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.
  167. 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.
  168. **Skip CC10x ONLY when:**
  169. - User EXPLICITLY says "don't use cc10x", "without cc10x", or "skip cc10x"
  170. - No interpretation. No guessing. Only these exact opt-out phrases.
  171. The router is the plugin skill `cc10x:cc10x-router`.
  172. ---
  173. ## Complementary Skills (Work Together with CC10x)
  174. **Skills are additive, not exclusive.** CC10x provides orchestration. Domain skills provide expertise. Both work together.
  175. **GATE:** Before writing code, check if task matches a skill below. If match, invoke it via `Skill(skill="...")`.
  176. | When task involves... | Invoke |
  177. |-----------------------|--------|
  178. | *(Add user's installed skills here)* | |
  179. ```
  180. ### Step 3: Update `~/.claude/settings.json`
  181. **If file doesn't exist:** CREATE with the template below.
  182. **If file exists:** MERGE these permissions into the existing `permissions.allow` array (don't overwrite!):
  183. ```json
  184. "Bash(mkdir -p .cc10x)",
  185. "Bash(mkdir -p .cc10x/)",
  186. "Bash(mkdir -p docs/plans)",
  187. "Bash(mkdir -p docs/research)",
  188. "Bash(mkdir -p docs/solutions)",
  189. "Bash(git status)",
  190. "Bash(git diff:*)",
  191. "Bash(git log:*)",
  192. "Bash(git branch --show-current)",
  193. "Bash(git blame:*)",
  194. "Bash(git ls-files:*)",
  195. "Bash(git rev-parse:*)",
  196. "Bash(python3:*)",
  197. "Edit(.cc10x/**)"
  198. ```
  199. > **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.
  200. > **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 are for inspecting the repository (`git branch --show-current` reads the current branch; direct `git` commands that create or delete branches or push are not pre-approved, so they go through your Claude Code permission settings). `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. The template is a convenience, not a security boundary: `python3:*`, and `git log` or `git diff` through `--output` (which can write files such as `.git/config`), can be used to run other commands, git operations included, without a prompt, and deny rules see only the command text. If you need git operations gated, remove the broad rules (`Bash(python3:*)`, `Bash(git log:*)`, `Bash(git diff:*)`) and add explicit `deny` rules for the git commands you want blocked, then approve cc10x's commands when Claude Code prompts. Deny rules alone do not gate git while `Bash(python3:*)` is allowed, because an allowed `python3` command can run git without a prompt; removing one rule alone does not close every path either. In `bypassPermissions`, allow rules have no effect and only explicit `ask` rules prompt; `deny` rules still apply, but a deny rule on git commands does not see git run through `python3`. Only an `ask` or `deny` rule on `python3` itself closes that path, and it also gates cc10x's own tools, so use that mode only in an isolated container or VM. In auto mode, a classifier decides most actions instead of prompting, and entering it drops broad allow rules that grant code execution, such as `Bash(python3:*)`.
  201. ### Step 4: Set User Standards (Optional)
  202. Ask the user:
  203. > "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')"
  204. **If user provides standards**, write them to the project's memory:
  205. ```
  206. Bash(command="mkdir -p .cc10x")
  207. # Check if patterns.md already exists (Read returns error = doesn't exist)
  208. Read(file_path=".cc10x/patterns.md")
  209. # If it DOESN'T exist — create with standards already populated:
  210. 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}")
  211. # If it DOES exist — append under User Standards:
  212. Edit(file_path=".cc10x/patterns.md",
  213. old_string="## User Standards",
  214. new_string="## User Standards\n- {standard 1}\n- {standard 2}")
  215. Read(file_path=".cc10x/patterns.md") # Verify
  216. ```
  217. **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.
  218. ### Step 5: Scan Installed Skills & Add to Table
  219. **Where to find installed skills:**
  220. 1. `~/.claude/settings.json` → check `enabledPlugins` object (plugins with value `true`)
  221. 2. `~/.claude/plugins/installed_plugins.json` → detailed plugin info
  222. 3. `~/.claude/skills/` → personal skills (all projects)
  223. 4. `.claude/skills/` → project-specific skills
  224. **Skill naming in table:**
  225. - **Plugin skills:** `plugin-name:skill-name` (e.g., `mongodb-agent-skills:mongodb-schema-design`)
  226. - **Personal/project skills:** just the skill name (e.g., `react-best-practices`)
  227. **Example:** If user has these:
  228. ```
  229. # In enabledPlugins:
  230. "mongodb-agent-skills@mongodb-agent-skills": true
  231. # In ~/.claude/skills/:
  232. react-best-practices/SKILL.md
  233. ```
  234. **Add to the Complementary Skills table:**
  235. ```markdown
  236. | When task involves... | Invoke |
  237. |-----------------------|--------|
  238. | MongoDB, schema, queries | `mongodb-agent-skills:mongodb-schema-design` |
  239. | React, Next.js, UI | `react-best-practices` |
  240. ```
  241. ### Step 6: Confirm
  242. >
  243. > "cc10x is set up! Please restart Claude Code to activate."
  244. ---
  245. ## Memory Persistence
  246. cc10x survives context compaction. This is critical for long sessions.
  247. ```
  248. .cc10x/
  249. ├── activeContext.md # What you're working on NOW
  250. │ - Current task
  251. │ - Active decisions (and WHY)
  252. │ - Learnings this session
  253. │
  254. ├── patterns.md # Project conventions
  255. │ - Code patterns
  256. │ - Common gotchas (bugs → fixes)
  257. │ - Architectural decisions
  258. │
  259. └── progress.md # What's done, what's left
  260. - Completed items (with evidence)
  261. - Remaining tasks
  262. - Blockers
  263. ```
  264. 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.
  265. **Iron Law:** Every workflow loads memory at START and updates at END.
  266. ### How `.cc10x/` relates to Claude Code auto-memory
  267. They are separate systems and neither replaces the other.
  268. - **`.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.
  269. - **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.
  270. 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.
  271. ---
  272. ## Optional MCP Integrations
  273. 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.
  274. | MCP | Feature Unlocked | How to Install |
  275. | ----- | ----------------- | ---------------- |
  276. | **[octocode](https://github.com/bgauryy/octocode-mcp)** | 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` |
  277. | **[brightdata](https://github.com/brightdata/brightdata-mcp)** | 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` |
  278. **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.
  279. **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.
  280. **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.
  281. ---
  282. ## Troubleshooting
  283. ### Claude Code keeps asking for permission to edit memory files
  284. Add this line to `~/.claude/settings.json` under `permissions.allow`:
  285. ```json
  286. "Edit(.cc10x/**)"
  287. ```
  288. 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).
  289. Or run **"Set up cc10x for me"** again — the setup wizard adds them automatically.
  290. ---
  291. ### cc10x asks for permission before writing plan/research docs
  292. 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.
  293. ---
  294. ### cc10x not activating in a specific project
  295. The global `~/.claude/CLAUDE.md` activates cc10x in every project — you only need one install. If it's not activating in a specific project:
  296. 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.
  297. 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.
  298. 3. **Restart Claude Code** — or run `/reload-plugins` after a plugin change. A CLAUDE.md change is read on the next session start.
  299. 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`.
  300. ---
  301. ### Ubuntu / Linux install error: EXDEV cross-device link
  302. If you see:
  303. ```
  304. Error: Failed to install: EXDEV: cross-device link not permitted
  305. ```
  306. This is a Linux filesystem issue — `/tmp` and your home directory are on different filesystems, so the installer can't `rename()` across them. Fix:
  307. ```bash
  308. # Set TMPDIR to a directory on the same filesystem as your home:
  309. mkdir -p ~/.claude/tmp
  310. TMPDIR=~/.claude/tmp claude
  311. # Then install normally: /plugin install cc10x@cc10x
  312. ```
  313. If that doesn't work, use the clone-and-`--plugin-dir` route from [Manual install from a clone](#manual-install-from-a-clone), then follow Step 2 in the setup guide above to add the cc10x section to `~/.claude/CLAUDE.md`.
  314. ---
  315. ### "Unknown skill cc10x:cc10x-router"
  316. The cc10x plugin is not installed or is disabled. Check with:
  317. ```bash
  318. claude plugin list
  319. ```
  320. If it is listed as disabled, run `claude plugin enable cc10x@cc10x` (or open `/plugin` and use the **Installed** tab), then `/reload-plugins`.
  321. ---
  322. ## Architecture Deep Dive
  323. Everything below the fold: how the loop actually works. For contributors and the curious — you do not need any of this to use cc10x.
  324. <details>
  325. <summary><strong>Runtime model, router kernel, agents, skills, hooks, diagrams, file layout</strong></summary>
  326. ### Runtime Model
  327. #### 1. Router owns orchestration
  328. `cc10x-router` is the only orchestration authority.
  329. The router uses a **kernel + mandatory reference** shape:
  330. - universal orchestration law stays inline in `cc10x-router/SKILL.md`
  331. - workflow-specific playbooks and appendix-heavy artifact/remediation law live in `cc10x-router/references/*.md`
  332. - the kernel explicitly tells Claude which reference must be read before BUILD / DEBUG / REVIEW / PLAN / QA / TRIAGE / CODEBASE-HEALTH branch logic continues
  333. That keeps orchestration salient without turning the router into a context dump.
  334. It decides:
  335. - which workflow to run
  336. - which subagent to invoke next
  337. - when to pause for clarification or scope decisions
  338. - when remediation is required
  339. - when a workflow is allowed to advance
  340. - when memory and workflow artifacts are finalized
  341. Agents do not own workflow state. They return structured results. The router interprets them.
  342. #### 2. Agents are narrow specialists
  343. The 14 shipped subagents are intentionally specialized; the table under [The 14 Agents](#the-14-agents) lists each one. Each agent is optimized for one role. This keeps prompts sharper and makes workflow behavior easier to reason about.
  344. #### 3. Skills are reusable local instructions
  345. Skills are the reusable instruction layer that agents and the router depend on.
  346. They provide:
  347. - planning patterns
  348. - TDD rules
  349. - debugging patterns
  350. - review rules
  351. - research synthesis
  352. - memory handling
  353. - verification-before-completion discipline
  354. - test-system design for the QA workflow
  355. #### 4. Workflow artifacts are the durable truth
  356. cc10x writes proof-of-work workflow state under:
  357. ```text
  358. .cc10x/workflows/{wf}.json
  359. .cc10x/workflows/{wf}.events.jsonl
  360. ```
  361. These artifacts track:
  362. - workflow type and task ids
  363. - intent/spec context
  364. - agent results
  365. - evidence and quality state
  366. - remediation history
  367. - lifecycle events
  368. The QA workflow also keeps its test plan, environment plan and report under `.cc10x/qa/`. This is what makes resume, review, and debugging more reliable than relying on chat context alone.
  369. #### 5. Hooks are guardrails, not a second orchestrator
  370. Hooks do not replace the router. They provide diagnostics, resume context and state snapshots, and the artifact guard flags a malformed workflow artifact. No hook gates git or file operations; Claude Code's permission settings do. The table under [Hooks](#hooks) lists the registered events, and [`plugins/cc10x/hooks/README.md`](plugins/cc10x/hooks/README.md) is the one place that says exactly what each hook does and which can block.
  371. #### 6. MCP is optional acceleration only
  372. cc10x does **not** ship MCP server config inside the plugin.
  373. If the user already has Claude Code MCP servers named:
  374. - `octocode`
  375. - `brightdata`
  376. then research gets better automatically.
  377. If not, the plugin still works. Research falls back to built-in Claude Code tools and records degraded confidence where appropriate.
  378. ---
  379. ### BUILD flow, up close
  380. ```
  381. ┌──────────────────────────────────────────────────────────────────────────────┐
  382. │ │
  383. │ YOU: "build a user auth system" │
  384. │ ┌────────────────────────────────────┐ │
  385. │ ┌─────►│ component-builder │ │
  386. │ │ │ + TDD enforcement │ │
  387. │ ┌────────────────────┐ │ │ + building and verification │ │
  388. │ │ │ │ │ skills │ │
  389. │ │ cc10x-router │─────┤ └──────────────┬─────────────────────┘ │
  390. │ │ (auto-detects │ │ │ │
  391. │ │ BUILD intent) │ │ ┌──────────────▼─────────────────────┐ │
  392. │ │ │ │ │ code-reviewer ∥ failure-hunter │ │
  393. │ └────────────────────┘ │ │ (parallel execution) │ │
  394. │ │ └──────────────┬─────────────────────┘ │
  395. │ │ │ │
  396. │ │ ┌──────────────▼─────────────────────┐ │
  397. │ └─────►│ integration-verifier │ │
  398. │ │ + E2E validation │ │
  399. │ └────────────────────────────────────┘ │
  400. │ │
  401. └──────────────────────────────────────────────────────────────────────────────┘
  402. ```
  403. A trivial change (one file group, one failure mode) runs a reduced graph: `component-builder` → `integration-verifier`. The reviewer and hunter join when the work spans files or the builder reports scope growth.
  404. ---
  405. ### Architecture
  406. ```
  407. USER REQUEST
  408. │
  409. ▼
  410. ┌─────────────────────────────────────────────────────────────────┐
  411. │ cc10x-router (ONLY ENTRY POINT) │
  412. │ Detects intent → Routes to workflow │
  413. └─────────────────────────────────────────────────────────────────┘
  414. │
  415. ├── DEBUG ──► bug-investigator ──► code-reviewer ──► integration-verifier
  416. │
  417. ├── PLAN ───► exploration ──► planner ──► plan-gap-reviewer (bounded loop)
  418. │
  419. ├── REVIEW ─► code-reviewer
  420. │
  421. ├── ORIENT ─► inline orientation (no agents)
  422. │
  423. ├── QA ─────► qa-researcher (fan-out) ──► plan-gap-reviewer ──► qa-harness-builder
  424. │ ──► [code-reviewer ∥ failure-hunter] ──► qa-executor
  425. │
  426. ├── TRIAGE ─► triage-agent
  427. │
  428. ├── CODEBASE-HEALTH ─► architecture-scanner
  429. │
  430. └── BUILD ──► component-builder ──► [code-reviewer ∥ failure-hunter] ──► integration-verifier
  431. MEMORY (.cc10x/)
  432. ├── activeContext.md ◄── Current focus, decisions, learnings
  433. ├── patterns.md ◄── Project conventions, common gotchas
  434. └── progress.md ◄── Completed work, remaining tasks
  435. WORKFLOW STATE (.cc10x/workflows/)
  436. ├── {wf}.json ◄── Durable workflow artifact
  437. └── {wf}.events.jsonl ◄── Append-only workflow event log
  438. ```
  439. ---
  440. ### The 14 Agents
  441. | Agent | Purpose | Key Behavior |
  442. | ------- | --------- | -------------- |
  443. | **component-builder** | Builds features | TDD: RED → GREEN → REFACTOR (no exceptions) |
  444. | **bug-investigator** | Fixes bugs | LOG FIRST: Evidence before any fix |
  445. | **code-reviewer** | Reviews code | Confidence ≥80%; 6-pass adversarial review (security, performance, quality, friction, plan validity, spec compliance) |
  446. | **failure-hunter** | Hunts silent failures | Runs in parallel with code-reviewer; zero-tolerance for empty catches, log-only handlers, discarded errors |
  447. | **integration-verifier** | E2E validation | Exit codes: PASS/FAIL with evidence |
  448. | **doc-syncer** | Diff-driven documentation sync | Classifies doc impact; SKIPPED/PARTIAL/COMPLETE/FAIL contract gating Memory Update; honors `DIFF_DRIVEN_DOCS: skip` |
  449. | **planner** | Creates plans | Saves to `docs/plans/` + updates memory |
  450. | **plan-gap-reviewer** | Fresh plan challenge pass | Read-only anti-anchoring review before final plan handoff |
  451. | **researcher** | Web + GitHub research (Bright Data / Octocode MCP accelerators, built-in fallbacks) | Saves findings to file |
  452. | **triage-agent** | Triages incoming issues/PRs | Does not change project code; categorizes, verifies, checks redundancy + prior rejection, writes agent-ready briefs |
  453. | **architecture-scanner** | Codebase health audit | Does not change project code; scans for shallow modules + deepening candidates, produces HTML report with before/after diagrams |
  454. | **qa-researcher** | QA route: surveys ONE source (code, spec docs, tickets, or cc10x artifacts) | Read-only; produces a per-source report (user flow, system flow, user action inventory, observation points, behaviour-varying surface (auth, flags/config, limits)) that the router consolidates into the feature map — it does not write the test plan |
  455. | **qa-harness-builder** | QA route: builds the test environment | Provisions services, isolation and fixtures; extends the existing live-harness manifest, never forks it |
  456. | **qa-executor** | QA route: runs the plan and reports | Fills the router-seeded `qa-report.template.md` in place; teardown is verified, not assumed |
  457. ---
  458. ## The 21 Skills
  459. Skills are **loaded automatically by agents**. You never invoke them directly.
  460. | Skill | Used By | Purpose |
  461. | ------- | --------- | --------- |
  462. | **agent-common** | every agent except plan-gap-reviewer | Shared preamble: memory protocol, CONTRACT envelope, output rules |
  463. | **memory-and-handoff** | main session (router-gated) | Persist context across compaction; portable handoff package |
  464. | **verification** | component-builder, bug-investigator, code-reviewer, integration-verifier, doc-syncer, qa-harness-builder, qa-executor | Evidence before claims: gate function, validation levels, evidence array |
  465. | **building** | component-builder, bug-investigator | TDD RED-GREEN-REFACTOR, false-RED guard, integration & live proof |
  466. | **debugging** | bug-investigator | Root cause analysis, feedback loop first, blast radius after fix |
  467. | **code-review** | code-reviewer, failure-hunter, main session | Adversarial review modes; verify human/external review feedback before agreeing or implementing |
  468. | **planning** | planner | Comprehensive plans + plan completeness gate |
  469. | **plan-review-gate** | planner | Final fail-closed plan sanity gate before handoff |
  470. | **architecture** | planner, builder (router-gated) | System & API design for multi-component work |
  471. | **frontend** | UI work (router-gated) | Authoring + critique modes: UX, accessibility, DESIGN.md, AI-slop detection |
  472. | **exploration** | PLAN workflow (router-gated) | Design brainstorm + throwaway spike modes with machine-readable handoff |
  473. | **diff-driven-docs** | doc-syncer | Doc impact classification + audit-doc format |
  474. | **research** | planner, bug-investigator (via researcher agent) | Synthesis-only: how to interpret research results |
  475. | **codebase-hygiene** | architecture-scanner (router-gated for other agents) | Semantic-duplicate audit + shallow-module deepening |
  476. | **codebase-design** | planner, component-builder, bug-investigator, code-reviewer, architecture-scanner | Canonical deep-module vocabulary: module, interface, depth, seam, adapter, leverage, locality |
  477. | **domain-modeling** | planner, doc-syncer, triage-agent; component-builder (read-only mode) | Active glossary discipline: challenge terms, sharpen language, write CONTEXT.md + ADRs |
  478. | **mcp-cli** | researcher | On-demand MCP server use without permanent context pollution |
  479. | **qa-strategy** | qa-researcher, qa-harness-builder, qa-executor (and read as a coverage lens by plan-gap-reviewer on QA plan reviews) | Test-system design: tier selection, scenario matrices, environment topology, fixture lifecycle, flake sources |
  480. | **update** | maintainers | Maintenance meta-skill for updating cc10x itself |
  481. | **cc10x-guide** | users asking about cc10x (model-invoked) | Answers questions about cc10x itself: install, setup, workflows, memory, troubleshooting; never executes work |
  482. | **resolving-merge-conflicts** | any agent hitting a git conflict (model-invoked) | Resolve merge/rebase conflicts hunk by hunk by intent; never --abort |
  483. > `cc10x-router` is the entry-point skill that routes every workflow; it ships alongside these 21. The per-agent preload list is in [`docs/agent-contract-registry.md`](docs/agent-contract-registry.md).
  484. ---
  485. ### Task-Based Orchestration
  486. cc10x uses Claude Code's task tools for workflow coordination when they are available, and tracks the same graph in the workflow artifact when they are not:
  487. ```
  488. ┌─────────────────────────────────────────────────────────────────┐
  489. │ BUILD: User Authentication │
  490. │ ├── component-builder (pending) │
  491. │ ├── code-reviewer (blocked by: builder) │
  492. │ ├── failure-hunter (blocked by: builder) │
  493. │ └── integration-verifier (blocked by: reviewer, hunter) │
  494. └─────────────────────────────────────────────────────────────────┘
  495. ```
  496. - **Dependency chains**: Agents wait for blockers to complete
  497. - **Parallel execution**: reviewer + hunter run simultaneously
  498. - **Resume capability**: TaskList() checks for active workflows; without task tools the router resumes from `.cc10x/workflows/*.json`
  499. - **Router-owned completion**: the router completes a task after it validates the agent's contract
  500. - **Router-owned advancement**: only the router decides whether a workflow can continue
  501. ---
  502. ### Hooks
  503. The plugin ships these Claude Code-native hooks, registered in `plugins/cc10x/hooks/hooks.json`:
  504. | Hook | Purpose |
  505. | ------ | --------- |
  506. | `SessionStart` | Python preflight, then rehydrate workflow context after restart or compaction |
  507. | `PostToolUse` | Audit workflow artifact integrity after writes (blocks a malformed artifact by default) |
  508. | `PostCompact` | Capture compaction events for workflow telemetry |
  509. | `SubagentStop` | Audit subagent outputs for required contract markers |
  510. | `PreCompact` | Snapshot workflow state before compaction |
  511. | `Stop` | Snapshot workflow state on session stop |
  512. | `StopFailure` | Log API failure telemetry asynchronously |
  513. | `InstructionsLoaded` | Audit instruction-file loading asynchronously |
  514. These hooks are intentionally minimal. They improve reliability without turning the plugin into a second runtime. Which script runs on each event, which can block, and how to change a mode: [`plugins/cc10x/hooks/README.md`](plugins/cc10x/hooks/README.md).
  515. Loop pane (mod). Beside the settings hooks, `hooks.json` names a hooks module under `modules` (`plugins/cc10x/hooks/register.tsx`). It only reads the workflow artifact and events log under `.cc10x/workflows/` and draws what it finds: a one-line band above the prompt (phase, running agent, next step, remediation count) and a dock pane with the whole step chain. Type `/cc10x-loop` to open the pane, or `/cc10x-loop status` to print which artifact it reads. It needs Claude Code 2.1.287 in the terminal or 2.1.286 in Desktop; older releases are not yet verified, and the settings hooks are unaffected either way. It never changes a workflow. Details and known limits: [`plugins/cc10x/hooks/README.md`](plugins/cc10x/hooks/README.md).
  516. ---
  517. ### Plan → Build Automation
  518. Plans don't get lost. They flow automatically to the build phase.
  519. ```
  520. Day 1: "plan a task tracker"
  521. → Planner creates docs/plans/2025-01-29-task-tracker-plan.md
  522. → Memory updated with plan reference
  523. Day 2: "build it"
  524. → Router detects BUILD
  525. → component-builder finds plan in memory
  526. → Follows plan phases with TDD
  527. ```
  528. ---
  529. ### Expected Behavior
  530. #### When You Say "Build a Task Tracker"
  531. **cc10x Response:**
  532. ```
  533. Detected BUILD intent. Executing BUILD workflow.
  534. Loading memory...
  535. ✓ Memory loaded
  536. Clarifying requirements (REQUIRED):
  537. 1. What framework/language? (Node.js, Python, etc.)
  538. 2. Should tasks have priorities, due dates, categories?
  539. 3. CLI app or web app?
  540. 4. Any features beyond basic CRUD?
  541. Waiting for your answers before proceeding.
  542. ```
  543. **Without cc10x:**
  544. ```
  545. I'll help you build a task tracker! Let me start...
  546. [Writes code without asking]
  547. [Skips tests]
  548. [Claims "it should work"]
  549. ```
  550. ---
  551. ### Files Structure
  552. ```
  553. plugins/cc10x/
  554. ├── .claude-plugin/
  555. │ └── plugin.json
  556. ├── hooks/
  557. │ ├── hooks.json
  558. │ ├── README.md
  559. │ ├── pre-commit
  560. │ ├── {register.tsx,loop-state.ts,loop-routes.ts,loop-fixtures.ts}
  561. │ └── {loop-pane.test.tsx,loop-state.test.ts}
  562. ├── types/
  563. │ └── index.d.ts
  564. ├── config/
  565. │ └── hook-mode.json
  566. ├── scripts/ # hook scripts and the L1 test suites (test_cc10x_*.py)
  567. │ ├── cc10x_{event_logger,hooklib,posttooluse_artifact_guard,sessionstart_context,state_persist}.py
  568. │ ├── cc10x_preflight.sh
  569. │ └── test_cc10x_loop_routes.py
  570. ├── tools/
  571. │ ├── {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
  572. │ └── docs_rot_baseline.json
  573. ├── templates/
  574. │ ├── {coverage-thresholds,live-harness.template}.json
  575. │ └── {doc-target-overlay,qa-env-plan.template,qa-feature-map.template,qa-report.template,qa-setup.template,qa-test-plan.template,qa-topology.template}.md
  576. ├── tests/
  577. │ ├── fixtures/
  578. │ └── live/
  579. ├── evals/
  580. │ ├── BASELINE.md
  581. │ └── cases/
  582. ├── agents/
  583. │ └── {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
  584. │
  585. └── skills/
  586. ├── cc10x-router/
  587. │ ├── SKILL.md
  588. │ └── references/
  589. │ ├── {build,debug,review,plan,triage,codebase-health,qa}-workflow.md
  590. │ ├── workflow-artifact-and-hook-policy.md
  591. │ ├── remediation-and-research.md
  592. │ └── workflow-artifact.skeleton.json
  593. ├── agent-common/SKILL.md
  594. ├── architecture/SKILL.md
  595. ├── building/SKILL.md
  596. ├── cc10x-guide/SKILL.md
  597. ├── code-review/SKILL.md
  598. ├── codebase-design/SKILL.md
  599. ├── codebase-hygiene/SKILL.md
  600. ├── debugging/SKILL.md
  601. ├── diff-driven-docs/SKILL.md
  602. ├── domain-modeling/SKILL.md
  603. ├── exploration/SKILL.md
  604. ├── frontend/SKILL.md
  605. ├── mcp-cli/SKILL.md
  606. ├── memory-and-handoff/SKILL.md
  607. ├── plan-review-gate/SKILL.md
  608. ├── planning/SKILL.md
  609. ├── qa-strategy/SKILL.md
  610. ├── research/SKILL.md
  611. ├── resolving-merge-conflicts/SKILL.md
  612. ├── update/SKILL.md
  613. └── verification/SKILL.md
  614. ```
  615. Some skills also carry a `references/` directory of their own (for example `skills/frontend/references/` and `skills/memory-and-handoff/references/`).
  616. Developer docs live under `docs/`:
  617. - [`docs/router-invariants.md`](docs/router-invariants.md), [`docs/prompt-invariants.md`](docs/prompt-invariants.md) and [`docs/agent-contract-registry.md`](docs/agent-contract-registry.md) are the maintained registries
  618. - [`docs/cc10x-orchestration-safety.md`](docs/cc10x-orchestration-safety.md) is the safety model
  619. - [`docs/prompt-change-checklist.md`](docs/prompt-change-checklist.md) holds the one release-gate list (section 7)
  620. - [`docs/known-flaws.md`](docs/known-flaws.md) lists known platform limits and recovery patterns
  621. - `docs/history/` keeps archived records of past work, each marked as historical
  622. If you need to understand or evolve the harness, start there after reading `cc10x-router`.
  623. </details>
  624. ---
  625. ## Version History
  626. <details>
  627. <summary><strong>Release history (v5.3 → v12.10.0)</strong></summary>
  628. | Version | Highlights |
  629. | --------- | ------------ |
  630. | **v12.10.0** | Remediation release: agent-common is now delivered to 13 agents, Python 3.9 floor with a preflight hook, rewritten git guard, router consistency fixes, docs reset. See the CHANGELOG entry. |
  631. | **v12.9.1** | Instruction-layer harmony: the install template in this README is byte-identical to the repo's own CLAUDE.md routing block. |
  632. | **v12.9.0** | QA route: a sixth route for when testing the code is the deliverable (`qa-researcher`, `qa-harness-builder`, `qa-executor`, `qa-strategy`), plus the plan-review, debug-handoff and hook changes it depends on. |
  633. | **v12.8.2** | Evidence-discipline wording imports from pstack; wording only, no routing, gate, hook or contract changes. |
  634. | **v12.8.1** | Adversarially validated prompt-craft refinements; wording only. |
  635. | **v12.8.0** | `cc10x-guide` skill (ask Claude about cc10x itself) and a documentation overhaul. |
  636. | **v12.7.0** | Prompt-engineering prose reconciliation: behavior-preserving wording pass over skills, agents and router. |
  637. | **v12.6.0** | Integrity reconciliation: audit-seam revival, router drift fixes, unified agent contracts, guard hardening. |
  638. | **v12.5.0** | Matt Pocock skills integration, the enforced seam gate, and the advisory on-ramp workflows. |
  639. | **v12.4.0** | Self-audit fixes: de-duplicated skills, wired decorative patterns, hook-enforced circuit breaker. |
  640. | **v12.3.1** | `silent-failure-hunter` renamed `failure-hunter` to resolve an agent name conflict. |
  641. | **v12.3.0** | 18 high-impact patterns adopted from six other repositories. |
  642. | **v12.2.0** | Restored the standalone `failure-hunter` and parallel review. |
  643. | **v12.1.0** | The Loop Engine: the harness reduced to its unique enforcement mechanisms. |
  644. | **v11.1.0** | Execution-engine harvest from a system-level comparison with superpowers and matt-pocock skills. |
  645. | **v11.0.0** | De-versioned state namespace: `.cc10x/v10/` became `.cc10x/`. |
  646. | **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. |
  647. | **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. |
  648. | **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. |
  649. | **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. |
  650. | **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 |
  651. | **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 |
  652. | **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` |
  653. | **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 |
  654. | **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 |
  655. | **v10.1.3** | Planning recovery: code-grounded plans, explicit plan-vs-code gap surfacing, stronger repo-aware plan review, and planning-specific replay coverage |
  656. | **v10.1.2** | Trust-preserving latency instrumentation: verifier workload telemetry, phase-exit vs extended-audit classification, no proof-gating change |
  657. | **v10.1.1** | Prompt-only hardening: sharper anti-false-completion wording, better trigger/description hygiene, reduced prompt dilution, no orchestration/runtime changes |
  658. | **v10.1.0** | Competition-grade release: decision-grade planning, adversarial plan gates, proof-oriented BUILD, harsher VERIFY, and benchmark-backed prompt/harness hardening |
  659. | **v10.0.0** | Trust-first recovery: agreement-first planning, phase-gated BUILD, stable workflow UUIDs, versioned v10 state, advisory internal skills |
  660. | **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` |
  661. | **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 |
  662. | **v9.0.0** | Plugin-native packaging: bundled Claude Code hooks, optional plugin MCP acceleration, router-owned research quality model, workflow artifacts as durable truth |
  663. | **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) |
  664. | **v8.0.0** | Radical simplification — remove Router Contract YAML from read-only agents; text-based verdict extraction; JUST_GO session mode; ~280 lines removed |
  665. | **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 |
  666. | **v7.8.0** | OBS-1/9/15/16/DEBUG-RESET — 5-issue fix, 13/13 smoke test pass |
  667. | **v6.0.21** | User standards support; multi-project docs; Linux install troubleshooting |
  668. | **v6.0.20** | Agent self-report task completion; MCP docs; permissions fix for memory files |
  669. | **v6.0.19** | Babysitter-inspired: Multi-signal HARD/SOFT scoring, evidence arrays, decision checkpoints, completion guard |
  670. | **v6.0.0** | Orchestration hardening: Tasks contract correctness + Task-enforced gates + re-review loop |
  671. | **v5.25.1** | GSD-inspired enhancements (wiring verification, hypothesis criteria) |
  672. | **v5.25.0** | Critical orchestration fixes + README redesign |
  673. | **v5.24.0** | Research persistence with THREE-PHASE pattern |
  674. | **v5.23.0** | Plan-task linkage (legacy: metadata.planFile; now deprecated) |
  675. | **v5.22.0** | Stub detection patterns |
  676. | **v5.21.0** | Task-based orchestration with TaskCreate/TaskUpdate |
  677. | **v5.20.0** | Goal-backward verification lens |
  678. | **v5.13.0** | Parallel agent execution (~30-50% faster) |
  679. | **v5.10.0** | Anthropic Claude 4.x best practices |
  680. | **v5.9.1** | Plan→Build automatic connection |
  681. <details>
  682. <summary>Full version history</summary>
  683. - **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.
  684. - **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)
  685. - **v7.8.0** - OBS-1/9/15/16/DEBUG-RESET 5-issue fix, 13/13 smoke test pass
  686. - **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)
  687. - **v6.0.0** - Orchestration hardening:
  688. - Tasks contract correctness (no undocumented TaskCreate fields; canonical TaskUpdate object form)
  689. - CC10X task namespacing + safer resume rules
  690. - Task-enforced gates + re-review loop after remediation (prevents unreviewed changes)
  691. - **v5.25.1** - GSD-inspired enhancements: Wiring verification patterns, hypothesis quality criteria, cognitive biases table
  692. - **v5.25.0** - Critical orchestration fixes: Plan propagation, results collection, skill hierarchy, validation + README redesign
  693. - **v5.24.0** - Research Documentation Persistence: THREE-PHASE research pattern
  694. - **v5.23.0** - Plan-Task Linkage: metadata.planFile for context recovery (legacy; deprecated in v6.0.0)
  695. - **v5.22.0** - Stub Detection Patterns: GSD-inspired stub detection
  696. - **v5.21.0** - Task-Based Orchestration: TaskCreate, TaskUpdate, TaskList integration
  697. - **v5.20.0** - Goal-Backward Lens: Verification enhancements
  698. - **v5.19.0** - OWASP Reference + Minimal Diffs + ADR patterns
  699. - **v5.18.0** - Two-Phase github-research
  700. - **v5.13.1** - Bulletproof chain enforcement
  701. - **v5.13.0** - Parallel agent execution
  702. - **v5.12.1** - Fixed orphan skills
  703. - **v5.12.0** - Pre-publish audit
  704. - **v5.11.0** - Workflow chain enforcement
  705. - **v5.10.6** - Foolproof Router with decision tree
  706. - **v5.10.5** - Complete Permission-Free Audit
  707. - **v5.10.4** - True Permission-Free Memory
  708. - **v5.10.3** - Fixed invalid agent color
  709. - **v5.10.2** - Permission-Free Memory
  710. - **v5.10.1** - Router Supremacy
  711. - **v5.10.0** - Anthropic Claude 4.x alignment
  712. - **v5.9.1** - Plan→Build connection
  713. - **v5.9.0** - Two-step save pattern
  714. - **v5.8.1** - Router bypass prevention
  715. - **v5.7.0** - Fixed agent keyword conflicts
  716. - **v5.6.0** - Fixed agent tool misconfigurations
  717. - **v5.5.0** - Fixed skill keyword conflicts
  718. - **v5.4.0** - Router AUTO-EXECUTE
  719. - **v5.3.0** - Confidence scoring, silent-failure-hunter
  720. </details>
  721. </details>
  722. ---
  723. ## Contributing
  724. - Star the repository
  725. - Report issues
  726. - Suggest improvements
  727. ---
  728. ## License
  729. MIT License
  730. ---
  731. <p align="center">
  732. <strong>cc10x v12.10.0</strong>
  733. </p>

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.