Skip to content

stevesolun/ctx / docs

skill-router

Flagged

Repo-aware recommendation manager for ctx. Scans the active repository, identifies stack and workflow signals, recommends a capped set of skills, agents, and MCP servers, and unloads helpers that no longer match the current work after user confirmation. Harnesses are recommended by the custom-model onboarding flow or loop adapters and then attach to the same recommendation layer.

FileKindSize
SKILL.mdskill md9.3 KB
assets/javascripts/catalog.jsscript2.5 KB
assets/javascripts/repo-stats-refresh.jsscript3.2 KB
backup-hook-install.mdmarkdown9.2 KB
catalog.mdmarkdown10.3 KB
ctx-fit/ARCHITECTURE_CANDIDATES.mdmarkdown12.9 KB
ctx-fit/ARCHITECTURE_GAP_ANALYSIS.mdmarkdown10.7 KB
ctx-fit/CTX_AUDIT.mdmarkdown11.6 KB
ctx-fit/CURRENT_STATE.mdmarkdown16.3 KB
ctx-fit/DECISIONS.mdmarkdown15.7 KB
ctx-fit/GOOD_FIRST_ISSUES.mdmarkdown20.6 KB
ctx-fit/IMPLEMENTATION_TRACKER.mdmarkdown697 B
ctx-fit/MAP.mdmarkdown7.8 KB
ctx-fit/PRD.mdmarkdown9.7 KB
ctx-fit/STATE.mdmarkdown60.9 KB
ctx-fit/milestones/M1_SPIKE_FRICTION_LOG.mdmarkdown5.5 KB
ctx-fit/milestones/MILESTONE_00_AUDIT.mdmarkdown5.1 KB
ctx-fit/planned_tasks.mdmarkdown17.7 KB
dashboard.mdmarkdown24.7 KB
enterprise-readiness-review.mdmarkdown8.7 KB
entity-onboarding.mdmarkdown18.0 KB
harness/attaching-to-hosts.mdmarkdown16.2 KB
harness/clean-host-contract.mdmarkdown4.5 KB
harness/loopflow-adapter-demo.mdmarkdown11.1 KB
huggingface-publish.mdmarkdown3.3 KB
index.mdmarkdown22.4 KB
knowledge-graph.mdmarkdown22.7 KB
marketplace-registry.mdmarkdown4.0 KB
memory-anchor.mdmarkdown2.7 KB
plans/ctx-agent-reviewer-workbench.mdmarkdown12.4 KB
plans/unified-capability-engine.mdmarkdown59.0 KB
qa/dashboard-user-story-status.csvother26.0 KB
qa/feature-user-story-status.csvother92.5 KB
research/context-engineering-guidance-audit.mdmarkdown10.4 KB
services/macos/com.claude.backup.watchdog.plistother1.7 KB
services/systemd/claude-backup-watchdog.serviceother1.3 KB
skill-lifecycle-and-dashboard.mdmarkdown6.2 KB
skill-quality-install.mdmarkdown6.2 KB
skill-router/index.mdmarkdown2.5 KB
skill-stack-matrix.mdmarkdown5.5 KB
skills-health.mdmarkdown3.5 KB
stack-signatures.mdmarkdown6.2 KB
telemetry.mdmarkdown24.7 KB
threat-model.mdmarkdown15.0 KB
toolbox/behavior-miner.mdmarkdown2.6 KB
toolbox/configuration.mdmarkdown4.0 KB
toolbox/council-runner.mdmarkdown2.4 KB
toolbox/hooks.mdmarkdown2.6 KB
toolbox/index.mdmarkdown3.0 KB
toolbox/intent-interview.mdmarkdown3.0 KB
toolbox/starters.mdmarkdown3.0 KB
toolbox/templates/docs-review.jsonconfig599 B
toolbox/templates/fresh-repo-init.jsonconfig533 B
toolbox/templates/refactor-safety.jsonconfig634 B
toolbox/templates/security-sweep.jsonconfig636 B
toolbox/templates/ship-it.jsonconfig676 B
toolbox/verdicts.mdmarkdown4.0 KB

ctx-fit/CTX_AUDIT.md

View on GitHub
# CTX Audit — The Quarry

Milestone 0 deliverable. Every significant CTX subsystem classified
`KEEP` / `ADAPT` / `ARCHIVE` / `DELETE` against the CTX Fit product mandate.

Method: five parallel read-only classification lanes plus coordinator
verification. **130 components** classified. Every claim is anchored to a
`file:line` or an executed command. The governing question for each component
was: *if we were creating CTX Fit today from zero, would we deliberately design
this?*

Date: 2026-08-09. Baseline: ~156K source LOC, ~186K test LOC, 8,233 tests, 44
public console scripts, 19-lane preflight green.

## 1. Result

| Classification | Components |
| --- | --- |
| KEEP | 14 |
| ADAPT | 38 |
| ARCHIVE | 36 |
| DELETE | 42 |

**Public surface: 44 console scripts → 2** (`ctx`, `ctx-mcp-server`) — a 95
percent reduction. Only `ctx` is meant for humans; `ctx-mcp-server` survives
because its *name is a contract string* embedded in shipped artifacts and in
any MCP configuration `ctx fit --apply` writes.

Removable code, per lane, before de-duplicating overlap:

| Lane | Source LOC removable | Notes |
| --- | --- | --- |
| A — Public CLI | ~21,900 | includes the 12,205-LOC monitor package also counted in E |
| B — Graph/catalog | ~25,100 | production and curation, not consumption |
| C — Engine/runtime | see §3 — **two different claims, only one proven** | |
| D — Benchmark | ~21,100 gross | estimate revised; see §3a |
| E — Supporting | ~32,000 | plus ~29,000 test LOC |

Lanes overlap (the dashboard is counted in both A and E), so these do not sum
cleanly. The honest statement is: **on the order of 100K+ source LOC and 80K+
test LOC are removable** — well over half the repository — without losing any
capability CTX Fit needs. Precise de-duplicated figures are computed during the
deletion program, not asserted here.

## 2. The new core — everything classified KEEP

This is the entire surviving foundation. It is remarkably small, and it is the
most useful output of the audit.

| Component | LOC | Why it earns its place |
| --- | --- | --- |
| `ctx` console script (`ctx.cli.run:main`) | — | The one binary a human types. Already hosts `fit`. |
| `ctx-mcp-server` | — | Machine entrypoint; its name is a hard-coded contract in shipped assets and applied configs. |
| Distribution name `claude-ctx` | — | **Do not rename.** Users type `ctx`, never the distribution name; a rename costs adoption and buys nothing. |
| `src/ctx/engine/planner.py:46-593` | ~550 | `BoundedCapabilityPlanner` — literally the mandate's "candidate search-space reduction with explainable selection". Pure, no I/O. |
| `src/ctx/engine/benefit.py` + `capability_schema.py` | 1,695 | The cost/benefit policy that makes "verified work per dollar" possible, and stops a catalog scoring itself. |
| `src/ctx/engine/observation.py` | 274 | Maps repository + task to planner signals without leaking private prose into artifacts. |
| `runtime-availability.json` + `eligible_catalog.py` + `production_catalog.py` | 1,845 + 19KB | The real product asset: where a candidate is simultaneously identified, described, ranked, installable, and verifiable. |
| `src/ctx/runtime/workspace_identity.py` | 95 | Proves a trial ran where it claims. |
| Validity controls (`validate_evaluator_controls`) | 61 | The cheapest guard against a meaningless experiment — a task that already passes, or that no patch can satisfy. |
| Honest token accounting (`extract_token_usage`) | — | The reference implementation of "unknown stays unknown". |
| Deterministic provider bridge | 646 | Tests the pair executor without spending provider tokens. |
| `src/ctx/adapters/hook_config.py` | 298 | Locked, validated JSON merge — exactly what `--apply` needs to edit a user's settings safely. |
| `src/ctx/utils/` (`_fs_utils`, `_file_lock`, `_secret_scan`, `_safe_name`) | 1,222 | Highest value-per-LOC in the repository. Fit executes untrusted repository code and writes into user repositories. |
| `src/cosine_ranker.py` | 174 | Dependency-light, correct, the only part of the embedding stack worth keeping. |

Total surviving core: **roughly 7,000 LOC** plus a 19KB catalog asset.

## 3. The hardest finding — the event-sourced capability engine

Lane C examined `src/ctx/engine/` (20,959 LOC) and `src/ctx/runtime/`
(28,875 LOC) — 49,834 source LOC backed by 47,301 test LOC and 1,652 tests,
roughly 23 percent of the whole suite. This is recent, heavily reviewed,
high-quality work.

**Corrected after independent architecture review.** An earlier draft of this
section headlined "~46,200 of 49,834 (93%) removable". That figure conflated
two different claims, and only one of them is proven. The correction matters
more than the original number, so it is stated first.

| Claim | Status | Figure |
| --- | --- | --- |
| **Proven dead** — reachable only from tests, no production consumer | **Verified twice, independently** | **10,741 LOC** |
| **Not needed by the future product** — reachable today, but serves a lifecycle CTX Fit does not have | Judgement, not reachability | remainder of the lane |

A second reviewer rebuilt the AST import graph from **all 45 console-script
entry points** — a broader seed set than the original audit used — and
deliberately did *not* suppress the `__init__` re-export hubs. It reproduced
the 10,741 figure exactly, and concluded the original audit **understated** the
dead-code finding.

But the same graph contradicts the 93 percent headline as written: with today's
entry points, **35,993 LOC of the lane are reachable** (20,821 of
`src/ctx/engine`, 15,172 of `src/ctx/runtime`), much of it through the `ctx`
binary itself. Removing that code is a *product decision* requiring real work,
not the deletion of unreachable code. Only the 10,741 LOC can be removed on
reachability evidence alone.

**Practical consequence.** The deletion program starts with the proven-dead
10,741 LOC, which is safe and mechanical. Everything beyond that is sequenced
behind the milestones that actually replace it, and is re-measured before each
step rather than asserted here.

### 3a. Two further review corrections

- **ADR-011's ~900 LOC extraction estimate is roughly 2x optimistic.** Seeding
  the five named mechanisms plus the `Scenario` model and computing the
  transitive in-file call closure yields 56 definitions, not the handful
  assumed. Budget accordingly.
- **ADR-011's delete list swallowed machinery the PRD depends on.** The
  ~21,100 LOC figure includes ~6,012 LOC of holdout and exposure-ledger code
  (`ctx_ab_holdout*.py`, `ctx_ab_exposure_ledger.py`) — the contamination
  controls the PRD's own risk table names as the mitigation for invalid tasks.
  That code is reclassified **ADAPT**, not DELETE.

The decisive evidence for the proven-dead cluster is not opinion. The auditor built an AST import graph over
all of `src/` (excluding tests) and computed reachability from every real entry
point — `ctx.cli.run`, `ctx.cli.fit`, `ctx.cli.recommend`,
`ctx.mcp_server.server`, the four hook adapters, and `ctx_init` — suppressing
the `__init__.py` re-export hubs that otherwise import everything. The result:

> `managed_query_service` (4,130), `managed_query_store` (2,263),
> `managed_artifact_registry` (1,615), `managed_query` (520), `composition`
> (1,140), `agent_file` (715), `activation_execution` (358) —
> **10,741 LOC reachable only from tests.**

Confirmed independently: grepping `src/` outside `src/tests/` and
`src/ctx/runtime/` for `open_managed_query_service`, `ManagedQueryService`,
`dispatch_release_skill_install`, or `activate_installed_release_skill` returns
**nothing**.

This must be stated plainly, because it includes work completed earlier in this
same session: the signed-consent repair, the `composition.execute_activation`
seam, and the expired-activation retirement slice all live inside that
test-only cluster.

That work was not *wrong*. It was correct engineering against the previous goal
— a durable, consent-gated capability lifecycle for managing a user's installed
tools. The **goal changed**. CTX Fit evaluates configurations in isolated
throwaway workspaces and emits configuration files for a human to apply; it
needs no durable consent ledger, no activation lifecycle, and no crash-recovery
journal. Retaining 46K LOC because it was expensive to build is precisely the
sunk-cost reasoning the mandate forbids.

What survives from the lane is the genuinely reusable intelligence: the bounded
planner, the benefit policy, observation normalization, and workspace identity —
about 2,600 LOC of the 49,834.

## 4. Lane summaries

**Lane A — Public CLI.** 44 scripts → 2. `ctx fit` should become the default
when no subcommand is given; `run`/`resume`/`sessions` move under
`ctx advanced`. Note a real dependency: `test_package_scaffold.py:126-149`
asserts `run` and `resume` appear in top-level `ctx --help`, so that test
changes with the restructure. `README.md:31-33` currently teaches
`ctx-init --graph` and `ctx-scan-repo --recommend` and must be rewritten.

**Lane B — Graph and catalog.** The decisive split is **consumption** (needed
at Fit time to rank candidates, ~4,649 LOC of which 550–800 survives as an
extracted ranking module) versus **production/curation** (building and
maintaining the corpus, ~21,650 LOC — arguably not part of the product at all).
The graph becomes an invisible optimizer answering only "which 2–5 candidates
are worth evaluating?"

**Lane C — Engine/runtime.** See §3.

**Lane D — Benchmark.** The valuable mechanisms are extracted rather than
wrapped: workspace isolation, counterbalancing, usage extraction, verification
execution, and the validity controls move into a new
`src/ctx/core/execution.py` (~450 LOC) plus `src/ctx/fit/experiment.py`
(~450 LOC), replacing ~21,100 LOC of scripts. Net ≈ **−38,000 LOC**. This
reverses the earlier "call the 522KB script as a black box" decision (D8) —
see §6.

**Lane E — Supporting.** The dashboard (14,323 LOC) is archived, not
redesigned. Host installers largely die with the old product; only
`hook_config.py` survives for `--apply`. Telemetry keeps a small product-signal
set. `src/ctx/utils/` is the highest value-per-LOC asset in the lane.

## 5. Deletion is gated

The tree is **largely untracked**, so deletions are not currently recoverable
through Git. No ARCHIVE or DELETE action executes until the working tree is
committed to a branch. This is recorded as a hard precondition on the deletion
program (FIT-900) rather than a preference.

Additional standing rules for every removal: identify dependents, inspect
tests, docs, CLI/API usage and integration points, confirm no reusable logic is
lost, and keep the 19-lane gate green after each step.

## 6. Decision superseded

`ARCHITECTURE_GAP_ANALYSIS.md` **D8** decided that CTX Fit would call
`scripts/ctx_ab_benchmark.py` as an unmodified black-box pairwise primitive.
That was the correct decision under the *evolution* mandate, where not touching
a 522KB module was the dominant concern.

Under the rewrite mandate it is superseded: extracting ~900 LOC of genuinely
valuable mechanism and deleting ~21,100 LOC beats preserving a script that
cannot be imported and that hardcodes its arms in 21 places. The mandate
explicitly prefers deletion over wrapper chains. **D8 is replaced by D12**,
recorded in `DECISIONS.md`.

## 7. What this buys

- A product a new developer understands in ten seconds, with one command.
- A core of roughly 7,000 LOC instead of 156,000.
- Every remaining line traceable to the product promise.
- Substantially less to maintain, test, and explain.

The audit's most useful output is not the deletion list. It is the KEEP list in
§2: the proof that a genuinely small, coherent product can be built from parts
CTX already owns and has already tested.
reverse-engineer-anythingmorluto/reaReverse engineer native, managed, Electron/JavaScript, packaged, firmware, and browser targets with REA, and build agent environments (AgentEnv bundles) of web applications from a live instance or a capture, and of Linux desktop apps with a task from a request. Use shipped-artifact or requested runtime evidence to explain features, compare versions, decompile code, or guide a reconstruction. Skip REA for ordinary source-repository architecture analysis.Stars: 472kUpdated Claude CodeCodexVerifiedInstall
diagnosing-superpowersobra/superpowersUse when a superpowers session went wrong and your human partner wants to know why — repeated work, ignored plans, stumbles, poor results, a skill that didn't fire, "it took too long", "why is it so expensive", "what is it doing" — or wants to build a bug report for the superpowers maintainers, for the current session or a past one identified by id or path, on any harness.Stars: 322kUpdated Claude CodeCodexVerifiedInstall
dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependenciesStars: 322kUpdated Claude CodeCodexVerifiedInstall
executing-plansobra/superpowersUse when executing an implementation plan in the current session as the implementer yourself — your human partner chose inline execution, or no subagent tool is availableStars: 322kUpdated Claude CodeCodexVerifiedInstall