cc-tree

Language: English (canonical). Chinese: README.zh.md.

cc-tree is a Claude Code plugin that turns open-ended thinking into a tree you can audit. One universal radial-tree exploration engine, four swappable presets: divergent brainstorming, adversarial critique, design-space exploration, and code audit — same engine, different vocabulary. It is a disciplined, disk-persisted take on tree-of-thoughts search: every node is derived in full with file:line or URL evidence, defer / future-work / TODO / NEEDS-MORE-INFO leaves are hard-banned, and the run stops on substantive convergence rather than on a node budget.

claude plugin marketplace add skymanbp/cc-tree
claude plugin install cc-tree@cc-tree

Refactor of sci-paper's brainstorm + paper-attack-tree skills, stripped of paper-specific anchors and parameterized via presets.

1 · The problem, and what cc-tree does about it

1.1 The problem it targets

Ask any LLM to brainstorm, review this critically, compare these designs, or audit this file, and the same five failure modes come back every time. They are not model bugs; they are the lazy equilibria of free-form generation.

| Failure mode | What it looks like in practice | |---|---| | Shallow coverage | the three most obvious angles, then a summary | | Deferred leaves | "promising, but needs a deeper survey — future work": a non-result dressed as a result | | Pseudo-divergence | six branches that are one branch with the nouns swapped | | Convenient convergence | "that about covers it" — arriving exactly when new ideas get expensive | | Unverifiable output | a chat log: nothing cites a line, nothing survives the scroll-back |

The target effect is the inverse of every row: fixed-breadth coverage, no deferrals, deduplicated branches, a convergence test you can check, and every claim carrying a file:line or a URL.

1.2 What it does — five capabilities

| # | Capability | Invoke | What it yields | |---|---|---|---| | 1 | Exhaustive divergent exploration — grows research directions or solution paths outward from one topic until new high-value branches stop appearing, not until the chat trails off | /cc-tree:brainstorm | shortlist.md | | 2 | Adversarial critique of a finished artifact — reviewer-style attack on a document, argument, or proposal; every leaf resolves to CONFIRMED / MARGINAL / REFUTED, carrying the position it attacks and whatever defense the artifact already mounts | /cc-tree:attack | confirmed.md | | 3 | Design-space exploration — options × trade-offs × reversibility × cost × fit-with-constraints, ending in a comparison table and a RECOMMENDED short-list | /cc-tree:design | options.md | | 4 | Code audit — the findings a static linter structurally cannot produce: threat-model-dependent, contract-level, and cross-file reasoning bugs, each with file:line evidence and a proposed fix | /cc-tree:code-audit | findings.md | | 5 | Chaining the four — pipes one stage's top-K deliverable into the next: brainstorm → design → attack, diverging on directions, designing the best into options, attacking the winner before you commit | /cc-tree:tree-chain | per-stage, plus the handoff log |

All five are the same engine. A preset changes the vocabulary, never the loop — §10 of docs/ENGINE.md is the exact extension surface.

1.3 Working scope — what cc-tree is not

• Not a one-shot brainstorm tool. The engine is recursive and convergence-terminated; a real run takes minutes to hours.
• Not a chat interface. Only the §2.0 glossary grill may ask questions, before the root exists; then it runs to convergence unprompted (§F6). You steer with flags on the next invocation.
• Not a substitute for a domain expert. It produces a cited, structured exploration; a human still decides which leaves to act on.
• Not bundled with a model. It is pure prompt engineering on top of your existing Claude Code model setting.
• Not a linter. code-audit looks for what a static analyzer cannot: threat-model-dependent, contract-level, and cross-file reasoning bugs.

2 · How it works

2.1 The shape — one root, growing outward

cc-tree treats any open-ended thinking task as a phylogenetic tree growing outward from one root. The root is your input — a topic, a document, a code path, a design prompt. Every node is expanded by the same 12 framing passes, each child is fully derived and scored, and only the high-value (advances) leaves get re-expanded, until the tree reaches substantive convergence rather than an arbitrary count.

_{Inspired by the radial <em>tree of life</em>. The vocabulary the rest of this README uses is all in this one picture: <strong>root</strong> (the input at the centre — topic · artifact · code · design), <strong>node</strong> (one idea / critique / option / finding, each with the same 12-field derivation), <strong>depth</strong> (the concentric framing-recursion rings; branches stop at different rings because only <code>advances</code> leaves re-expand), <strong>width</strong> (the terminal leaves, wherever they land — set by convergence, not a hand-picked cap, and never counting a <code>blocked</code> tip until it is completed, per §0.1), and <strong>n</strong> (total nodes in the tree). Diagram source: <a href="tools/gen_radial_tree.py"><code>tools/gen_radial_tree.py</code></a>.}

  the tree grows OUTWARD from one root. a branch can WIN, hit a DEAD END, or
  keep BRANCHING and be judged again — no single winner, wins at any depth:

    ROOT ──┬── pruned                      (dead end at depth 1)
           ├── advances                    (a win at depth 1)
           └── advances ──┬── pruned        (this branch keeps going…)
                          └── advances ──┬── advances   (…a deeper win)
                                         └── blocked

  each node → 12 framings (§3.A–§3.L) → 12-field derivation → score → verdict;
  branches that keep advancing grow deeper; pruned / blocked ones stop.

2.2 The five irreducible steps

All five are specified in docs/ENGINE.md and binding on every preset.

flowchart LR
    R([root<br/>topic · artifact · code · design]) --> F{{12 framing passes<br/>§3.A–§3.L}}
    F --> D[per-node 12-field derivation<br/>evidence · no hedging · no defer]
    D --> S[score 5 dims → verdict]
    S -->|advances| RE((re-expand<br/>this leaf))
    RE --> F
    S -->|kept / pruned| K[keep in tree,<br/>don't re-expand]
    S -->|blocked| B[INCOMPLETE_FORBIDDEN<br/>drive to completion]
    B --> D
    S --> C{§6 convergence?<br/>6 conditions all true}
    C -->|no| RE
    C -->|yes| OUT[/final report +<br/>tree.md · tree.json/]

Step 1 — Ground the root (§2)

The preset supplies the recipe; the engine enforces that every root field carries a file:line, URL, or command-output citation. An optional glossary-grill prelude (§2.0) locks the root's technical noun-phrases to your project's term sheet before a single branch is generated, so the tree does not spend a hundred leaves solving the wrong problem.

Step 2 — Expand every node through 12 framings (§3)

Each node — root first, then every advances leaf — is put through all 12 framing passes, each of which must yield at least one child. The set is fixed so that the model cannot quietly skip the uncomfortable angles.

| Pass | What it forces | |---|---| | §3.A First-principles | Strip a load-bearing assumption; see what survives | | §3.B Inversion | Try the negation, the dual, the boundary where it fails | | §3.C Cross-disciplinary | Transplant tooling from ≥ 3 other fields | | §3.D Adversarial / red team | The 3 most damaging counter-arguments | | §3.E Constraint variation | Relax one constraint; tighten another | | §3.F Scale extrapolation | 1000× / 0.001× / domain boundary | | §3.G Substitution | Swap a component and observe the change | | §3.H Office-hours 6Q | YC-style demand-reality interrogation | | §3.I Contrarian | Which mainstream consensus might be wrong here? | | §3.J Failure-driven | Turn a concrete present failure into the next question | | §3.K High-risk asymmetric | Force ≥ 1 low-probability, paradigm-level branch | | §3.L Meta self-audit | 7-question audit of the model's own blind spots |

A thirteenth pass, §3.X, runs one external cross-check per node (WebSearch then WebFetch of the actual page) unless --no-online is set. Full prompts and per-preset examples: docs/framings.md.

Step 3 — Derive every child in 12 fields (§4)

Each child is filled into the preset's 12-field node schema — statement, parent framing, position, derivation, assumptions, predictions, defense, alternatives, fix/cost, external check, branch potential, provisional verdict. Blank, hedged, or deferred fields do not produce a weaker node; they produce an INCOMPLETE_FORBIDDEN node that blocks termination until it is driven to completion.

Step 4 — Score, then decide whether to recurse (§5)

Five preset-declared dimensions, each an integer 0–3, summed to a maximum of 15. score ≥ 11 (plus any preset-specific gate) → advances and the leaf is re-expanded; 8–10 → kept; ≤ 7 → pruned; anything dominated by an unverified claim → blocked. Near-duplicate siblings are merged at cosine similarity ≥ 0.85 (§5.4) so width means coverage, not repetition.

Step 5 — Stop only on substantive convergence (§6)

Six conditions must hold simultaneously: no incomplete node remains; the advances ratio over the last two rounds has fallen below --min-novelty-ratio; all 12 framings have fired; every advances leaf has been re-expanded and yielded nothing further; at least one fully derived §3.K high-risk branch exists; and no user cap has tripped. If a cap trips first, the engine reports WIDTH_CAP_REACHED / DEPTH_CAP_REACHED / ROUNDS_EXHAUSTED — truthfully, never as CONVERGED — and still completes every in-flight leaf first.

2.3 Engine invariants a preset may not weaken

| Invariant | Contract | |---|---| | 12 framing passes per node per round | §3.A–§3.L plus the §3.X external cross-check; --min-frameworks has a hard floor of 12 | | 12-field derivation per node | §4, every field non-empty, non-hedged, and citation-bearing | | 5-dimension scoring | §5.1, integer 0–3 each, max 15, mapped to a four-role verdict (§5.2) | | Sibling merging | §5.4 at cosine similarity ≥ 0.85; the merged node stays visible, tagged MERGED_INTO=<id> | | Six-condition convergence test | §6.1, with the explicit termination decis