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/milestones/M1_SPIKE_FRICTION_LOG.md

View on GitHub
# M1 Spike — Friction Log and Rewrite Verdict

Purpose: the spike was commissioned to answer one question with evidence rather
than impression — **does the existing CTX architecture obstruct CTX Fit enough
to justify starting over?**

Method: build Milestone 1 (repository Fit profile, zero model spend) on top of
existing CTX and record every point of friction encountered.

Date: 2026-08-09.

## What was built

| Artifact | Purpose |
| --- | --- |
| `src/ctx/fit/verification.py` | Discovers how a repository verifies itself (test/lint/typecheck/build) with source, confidence, and evidence. Pure inspection; executes nothing. |
| `src/ctx/fit/profile.py` | Versioned `FitProfile` composing CTX's existing stack analysis with verification discovery, existing-AI-config inventory, and honestly-scoped optimization dimensions. |
| `src/ctx/cli/fit.py` | The `ctx fit` subcommand, with `--json` and `--dry-run`. |
| `src/tests/fit/test_fit_profile.py` | 11 tests including adversarial cases: no tests, malformed manifests, empty repository, missing path. |

Total: three new modules plus tests. **Two lines** of change to existing code
(a subparser registration and a dispatch branch in `src/ctx/cli/run.py`).

## Evidence

- `ctx fit .` on this repository correctly reports Python/JavaScript, all four
  verification commands with their exact `pyproject.toml` sources, both
  instruction files, the tool config, and 26 installed skills.
- `src/tests/fit` — **11 passed**.
- CLI, packaging, and Fit suites together — **168 passed**.
- `mypy src` — **no issues in 554 source files** (was 548; the six new files
  type cleanly).
- Ruff and formatting — clean.

## Friction encountered

Recorded honestly, including the parts that argue *against* the existing
architecture.

| # | Friction | Severity | Notes |
| --- | --- | --- | --- |
| F1 | `scan_repo` is a flat legacy module, so the new package layer imports across the layout split | **Low** | Resolved with a lazy import inside the function, which also keeps `ctx.fit` from depending on the legacy layout at import time. The migration is already documented as deliberate and incomplete. |
| F2 | `detect_stack` returns an untyped `dict` | **Low** | Fine at a boundary. `FitProfile` wraps it in a typed, versioned structure, so the untyped dict never leaks into Fit logic. |
| F3 | `build_system` detection is empty even for a repository with a declared build backend | **Low** | Not an architectural problem. Fit's own verification discovery covers it and is more precise, because it reads `[build-system]` directly. |
| F4 | No repository-native verification existed anywhere to reuse | **Medium** | The single largest genuinely-missing capability — but a rewrite would not have supplied it either. It had to be written regardless, and it was, in one self-contained module. |
| F5 | The umbrella CLI required editing a shared 2000-line module | **Very low** | Two lines. The subparser pattern was already there, and adding a subcommand needs no change to the console-script set pinned by `test_package_scaffold.py`. |

**No high-severity friction was encountered.** Nothing forced a workaround,
nothing required touching the engine, the graph, or the benchmark runner, and
no existing test needed modification.

## Verdict: evolve, do not rewrite

The spike is decisive, and the reasoning is arithmetic rather than aesthetic.

1. **The existing architecture did not obstruct the work.** Milestone 1 landed
   as three new files and two lines of change to existing code. A rewrite would
   have produced the same three files plus the obligation to rebuild everything
   else.
2. **The hard, missing capabilities are missing either way.** Verification
   discovery, task derivation, cost unification, and recommendation do not
   exist in CTX today. Starting over does not deliver them sooner; it only adds
   the cost of re-creating what already works.
3. **What a rewrite would destroy is the expensive part.** Counterbalanced
   execution order, workspace isolation, contamination controls, deterministic
   scenario verification, token accounting that refuses malformed usage, a
   nullable-cost discipline that never fakes a number, 8233 passing tests, and
   a green 19-lane gate. Experimental-fairness machinery is exactly the kind of
   code where a missed subtlety produces *confident wrong answers* — the worst
   possible defect in a product whose only value is trustworthy evidence.
4. **The instinct behind the rewrite question was still correct**, and it has
   been honored. The product surface is now genuinely simple: one command, no
   graph statistics, no entity taxonomy, no orchestration internals. CTX Fit
   depends on a deliberately short list and simply does not call the rest.
   Simplicity was achieved by *narrowing the surface*, not by deleting the
   foundation.

## Recommendation

Continue with evolution and a strict dependency diet. Reassess only if a later
milestone hits a genuinely high-severity friction — most plausibly in task
derivation (the hardest unsolved problem) or in unifying cost across the two
execution paths. Both are tracked as open questions rather than assumed
solved.

## Correction carried into the audit

The spike also confirmed a correction already applied to `CURRENT_STATE.md`:
CTX **does** have honest dollar accounting on the `ctx run` path
(nullable `cost_usd`, `attribution="unavailable"`, fail-closed `--budget-usd`),
and it **does** have per-execution budget controls. Only the A/B benchmark path
lacks cost, and only the *aggregate* campaign budget is missing. An earlier
draft of the audit overstated both gaps.
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