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/MAP.md

View on GitHub
# CTX Fit — Wayfinding Map

A low-resolution map of the CTX Fit effort: what is settled, what is a precise
open question, what is still fog, and what is deliberately out of scope. This
is an **index**, not a specification. Detailed evidence lives with the decision
or question that owns it.

Companion documents: [`CURRENT_STATE.md`](CURRENT_STATE.md) (audited facts),
[`IMPLEMENTATION_TRACKER.md`](IMPLEMENTATION_TRACKER.md) (execution ledger).

Status: charted 2026-08-09, after the Milestone 0 audit.

## Destination

A developer or engineering leader points CTX at a repository and receives a
decision they can act on:

> Here is the baseline we measured, the small set of configurations we tested
> and why we chose them, the verification evidence, what each cost, the best
> configuration **among those tested**, the limitations of the experiment, and
> the exact configuration changes required to adopt it.

The route is complete when that output is produced truthfully for a real
repository, with "no configuration beat the baseline" available as a valid
result.

## Decisions

Settled by the Milestone 0 audit. Each links to its evidence.

- **D1 — CTX Fit is a layer inside CTX, not a fork or a rewrite.** Rejecting a
  second parallel implementation is an explicit architecture constraint.
> **Superseded notice.** D2 and D8 below were settled under the earlier
> *evolution* mandate. The mandate changed to a rebuild, and both are now
> superseded by **ADR-011 / ADR-012** in [`DECISIONS.md`](DECISIONS.md):
> the experiment mechanisms are *extracted* into `ctx/core/execution.py` and
> `ctx/fit/experiment.py` rather than wrapped, and the benchmark scripts are
> deleted apart from the contamination controls and the deterministic bridge.
> `DECISIONS.md` is the authoritative record; D2 and D8 are retained here only
> as history.

- **D2 — (SUPERSEDED) The paired A/B runner is extended, never rewritten.**
  `scripts/ctx_ab_benchmark.py` already provides isolation, counterbalanced
  execution order, deterministic verification, and contamination controls.
  ([`CURRENT_STATE.md` §3](CURRENT_STATE.md))
- **D3 — The Fit repository profile extends `scan_repo.detect_stack()`.** A new
  analyzer would duplicate working repository intelligence.
- **D4 — CTX's bounded 0–5 selection and benefit closure are the search-space
  reducer.** This is the standing answer to combinatorial benchmark cost.
- **D5 — Token accounting is reused as-is; the dollar layer is new.** The
  existing usage normalizer refuses malformed usage rather than defaulting to
  zero, and that discipline must be inherited.
- **D6 — Implementation is gated on Milestone 0.** Satisfied by
  `CURRENT_STATE.md`.
- **D7 — The experiment's arm model is the central thing that must change.**
  Arms are a validated module constant and the treatment delta is a prompt
  suffix, so today the rig varies exactly one dimension.
- **D8 — (SUPERSEDED by ADR-012; the candidate-representation insight survives)**
  A candidate configuration is a `scenario.context` capability set, and each
  candidate runs as its own baseline-versus-candidate pair. Resolves Q1.
  `write_ctx_fixture` already materializes a per-run isolated CTX home from
  `scenario.context` (skills, agents, MCP servers) and installs skills into the
  harness, so CTX Fit orchestrates *above* the runner and changes none of its
  21 arm-coupling sites. Cost of the decision: candidates are compared
  indirectly, each against a shared baseline.
  ([`ARCHITECTURE_GAP_ANALYSIS.md` §1](ARCHITECTURE_GAP_ANALYSIS.md))
- **D9 — V1 varies CTX capability configuration within one harness, optionally
  across pinned models; harness comparison is out of scope.** Resolves Q4 from
  evidence rather than preference: the rig is Codex-only, `--model` is a
  run-level flag, and reasoning effort is fixed by the Codex runtime contract.
  The report must state plainly that harness was not varied.
- **D10 — CTX Fit lives in `src/ctx/fit/`,** the package layout, never the flat
  legacy modules. Resolves the placement half of Q8.
- **D11 — Spend is authorized per run by an explicit budget, never
  implicitly.** Resolves Q11. M1 and M2 perform no provider execution; from M3
  the pre-flight estimate, fail-safe-before-spend check, and `--dry-run` are
  the mechanism by which spend is authorized.

## Open questions

Precise enough to investigate now. Owner `coordinator` means a shared surface
that must be serialized; `research` means an independent read-only lane.

| ID | Question | Owner | Depends on | State |
| --- | --- | --- | --- | --- |
| Q1 | How does an arbitrary configuration become an experiment arm without forking the 522 KB runner? | coordinator | — | **Resolved → D8** |
| Q2 | Where does a price table come from, how is it versioned, and how does cost stay honestly unknown when usage is missing? | research | — | Open; research lane in flight |
| Q3 | How can valid, non-contaminated, verifiable tasks be derived from an arbitrary repository? | research | — | Open; research lane in flight. The hardest question. |
| Q4 | Is harness comparison in scope for V1? | coordinator | Q1 | **Resolved → D9** (single harness, from evidence) |
| Q5 | How are a repository's own verification commands discovered and trusted? | research | — | Open; research lane in flight |
| Q6 | What confidence statement is defensible at small task counts and single trials? | research | Q3 | Open |
| Q7 | What multi-objective / Pareto selection rule is used, and how is it explained? | research | Q2, Q6 | Open |
| Q8 | Where does `ctx fit` live, and what is the versioned result schema? | coordinator | — | **Placement resolved → D10**; result schema still open |
| Q9 | Verification depends on a Codex-managed macOS sandbox. What happens without it? | research | — | Open; research lane in flight |
| Q10 | How is a dollar budget enforced *before* spend, and how does the run fail safely? | coordinator | Q2 | Open; mechanism decided in D11, thresholds not yet designed |
| Q11 | Are cost-bearing provider runs authorized, and under what budget? | coordinator | — | **Resolved → D11** (per-run explicit budget; M1–M2 need none) |

## Fog

In scope, but not yet stateable as a precise question.

- **Continuous re-evaluation** (repository changed, new model, pricing changed).
  Revisit once the result schema exists (Q8).
- **Dashboard Fit view.** Depends on the result schema (Q8); extend the existing
  monitor rather than rebuilding it.
- **Configuration artifact generation and PR preparation.** Depends on knowing
  what a winning configuration actually contains (Q1, Q4).
- **Which dimensions are honestly comparable.** Depends on Q1 and Q4; the
  answer determines what the product may claim.
- **Dogfood corpus.** Development, calibration, and held-out repositories, with
  leakage prevention. Depends on Q3.

## Out of scope

Explicitly excluded from the current destination.

- Organization management, multi-tenant SaaS, billing, subscriptions,
  enterprise SSO, elaborate RBAC.
- Marketplace, public leaderboards, social features.
- Large visualization redesign or an arbitrary workflow builder.
- A generic agent platform, or a second knowledge-graph implementation.
- Recurring hosted evaluation infrastructure before the one-time Fit workflow
  works reliably.

## Frontier

Open, unblocked, and useful to advance now.

- **Concurrent research lanes (independent, read-only):** Q2, Q3, Q5, Q9.
- **Coordinator lane (shared surfaces, serialized):** Q1, then Q8.
- **Blocked on user judgment:** Q4 and Q11. Q11 blocks Milestones 3 and later
  outright; Milestones 1 and 2 need no provider spend and can proceed.

## Handoff condition

Wayfinding ends and specification begins when Q1, Q3, Q4, and Q11 are settled.
At that point the route to a first usable Fit report is execution rather than
uncertainty reduction, and the tracker can carry real tasks.
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