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

View on GitHub
# CTX Fit — Planned Tasks (M0 planning snapshot — statuses are stale)

> **The per-task statuses below are stale. Do not read them as a claim about
> what is unbuilt, and do not claim work from them.** They are the snapshot
> taken during M0 planning, before the milestones were built, and they were
> never updated as the work landed. Milestones M3 through M10 are marked
> `NOT_STARTED` below and have in fact shipped, with implementation and tests:
> `200840ca` (M3 readiness), `ff78774e` (M4 candidate generation), `fae07e1f`
> (M5 experiment planning and budget gate), `3665cf41` (M6–M8 execution,
> verification states and recommendation), `78aa6f8a` (M9–M10 apply and
> pull-request preparation).
>
> **What is real is the code and its tests**, not this file:
> `src/ctx/fit/`, `src/ctx/cli/fit.py`, and `src/tests/fit/` — 273 tests, all
> passing. `ctx fit --help` and `ctx doctor --help` show the shipped command
> surface. `git log --oneline -- src/ctx/fit` shows how it got there.
>
> One correction worth carrying forward: M10 shipped as *prepare* a pull
> request, not *open* one. CTX Fit runs no git *write* commands: it reads history to derive tasks, but creates no branch, commits nothing, pushes nothing and never merges. `ctx fit --pr` prints
> a PR body and a suggested branch name; it creates no branch, commits nothing
> and never merges.
>
> Kept as the planning record of intent and rationale, which is still accurate.

Jira-style backlog. Companion to [`PRD.md`](PRD.md) (what and why),
[`CURRENT_STATE.md`](CURRENT_STATE.md) (what existed at audit time), and
[`CTX_AUDIT.md`](CTX_AUDIT.md) (keep/adapt/archive/delete).

**Status values:** `NOT_STARTED` · `IN_PROGRESS` · `BLOCKED` · `REVIEW` · `DONE`

**DONE requires:** implementation **+** tests **+** independent review **+**
evidence. Code existing is not DONE.

**Every task carries a Worker and a Reviewer.** For milestone-closing tasks the
reviewer set is Product + Architecture + Security + QA.

---

## M0 — Audit

### FIT-001 · Current-state audit
- **User story:** As the team, we need to know what CTX actually contains so we build on evidence rather than assumption.
- **Priority:** P0 · **Depends on:** — · **Worker:** coordinator · **Reviewer:** architecture
- **Status:** `DONE`
- **Tests:** n/a · **Evidence:** `CURRENT_STATE.md`, every claim cited to `file:line`; two of the coordinator's own claims corrected by the five-lane audit.

### FIT-002 · Architecture gap analysis
- **User story:** As the team, we need each Fit workflow step mapped to exists/partial/absent with an extend-refactor-replace decision.
- **Priority:** P0 · **Depends on:** FIT-001 · **Worker:** coordinator · **Reviewer:** architecture
- **Status:** `DONE`
- **Evidence:** `ARCHITECTURE_GAP_ANALYSIS.md`; resolved the arm-model question (D8) and V1 scope (D9).

### FIT-003 · Quarry classification (`CTX_AUDIT.md`)
- **User story:** As the team, we need every subsystem classified KEEP/ADAPT/ARCHIVE/DELETE so we can delete fearlessly with evidence.
- **Priority:** P0 · **Depends on:** FIT-001 · **Worker:** 5-lane audit workflow · **Reviewer:** architecture + product
- **Status:** `DONE`
- **Tests:** n/a
- **Evidence:** `CTX_AUDIT.md` — 130 components classified (14 KEEP, 38 ADAPT, 36 ARCHIVE, 42 DELETE); public surface 44 → 2. Independent architecture review reproduced the 10,741-LOC dead-code finding from a broader entry-point seed and corrected the lane headline; corrections applied in §3 and §3a.

### FIT-004 · Decision log
- **User story:** As the team, we need the target architecture and its rationale recorded once so decisions are not relitigated.
- **Priority:** P0 · **Depends on:** FIT-003 · **Worker:** coordinator · **Reviewer:** architecture
- **Status:** `DONE`
- **Evidence:** `DECISIONS.md` ADR-001…013, including ADR-012 superseding D8 and the superseded-notice added to `MAP.md`.
- **Notes:** A separate `ARCHITECTURE_PROPOSAL.md` was deliberately **not** created — it would have been a third overlapping document. The target architecture lives in `CTX_AUDIT.md` §2 (the KEEP core) plus `DECISIONS.md`. The canonical domain model is specified in `PRD.md` and tracked as FIT-040/FIT-080.

### FIT-005 · M0 review-gate remediation
- **User story:** As the team, the milestone gate must actually be able to reject, and its findings must be fixed rather than noted.
- **Priority:** P0 · **Depends on:** FIT-003 · **Worker:** coordinator · **Reviewer:** product + architecture
- **Status:** `DONE`
- **Tests:** `src/tests/fit/test_fit_profile.py` — 14 passing, including two new regressions for the defects found.
- **Evidence:** Both reviewers returned `accept-with-conditions`; every blocking objection was fixed, not argued: the evaluability overclaim, non-deterministic JSON, the duplicate tracker, the contradictory execution decision, the overstated audit headline, and front-door discoverability.

---

## M1 — Product skeleton · `DONE`

### FIT-010 · `ctx fit` command surface
- **User story:** As a developer, I run one obvious command and get an answer.
- **Priority:** P0 · **Worker:** coordinator · **Reviewer:** product
- **Status:** `DONE`
- **Tests:** `src/tests/fit/test_fit_profile.py` (CLI cases) · **Evidence:** `ctx --help` shows `{fit,run,resume,sessions}`; registered as a subcommand so the pinned console-script tuple is untouched; 168 CLI/packaging tests pass.

### FIT-011 · Safe-by-default behavior
- **User story:** As a developer, running `ctx fit` must never cost money or change files.
- **Priority:** P0 · **Worker:** coordinator · **Reviewer:** security
- **Status:** `DONE`
- **Tests:** dry-run test asserts no `$` figure is invented and states nothing was spent.

---

## M2 — Repository profile

### FIT-020 · Verification discovery
- **Status:** `DONE` · **Worker:** coordinator · **Reviewer:** QA
- **Evidence:** `src/ctx/fit/verification.py`; discovers test/lint/typecheck/build for Python, Node (lockfile-aware runner), Rust, Go, Make, each with source, confidence, and evidence; adversarial tests for malformed manifests and empty repositories.

### FIT-021 · Fit profile + existing AI config detection
- **Status:** `DONE` · **Worker:** coordinator · **Reviewer:** QA
- **Evidence:** `src/ctx/fit/profile.py`; versioned `ctx.fit.profile-v1`; detects `AGENTS.md`, `CLAUDE.md`, tool config, capability dirs; correctly found 26 skills in this repository.

### FIT-022 · Per-property provenance in the profile
- **User story:** As a user, I want to know *why* CTX believes something about my repository.
- **Priority:** P1 · **Depends on:** FIT-021 · **Worker:** TBD · **Reviewer:** QA
- **Status:** `NOT_STARTED`
- **Notes:** Verification commands already carry evidence; the stack half still relies on `scan_repo`'s shape. Normalize both.

---

## M3 — Readiness

### FIT-030 · Readiness dimension model
- **User story:** As an engineering leader, I want to know how suitable my repo is for AI agents and exactly what to fix.
- **Priority:** P0 · **Depends on:** FIT-021 · **Worker:** TBD · **Reviewer:** product + QA
- **Status:** `NOT_STARTED`
- **Notes:** Dimensions: verification, instructions, environment, CI, tool safety, architecture. Deterministic computation, versioned methodology, raw dimension scores always visible. An LLM must never invent the score.

### FIT-031 · Blockers and prioritized fixes
- **Priority:** P0 · **Depends on:** FIT-030 · **Reviewer:** product
- **Status:** `NOT_STARTED`
- **Notes:** Every recommendation must answer "how does this help an agent produce safer or more verifiable work?" If it cannot, the metric is deleted (anti-score-gaming).

### FIT-032 · Readiness rendering in `ctx fit`
- **Priority:** P0 · **Depends on:** FIT-030, FIT-031 · **Reviewer:** product
- **Status:** `NOT_STARTED`

### FIT-033 · Readiness adversarial tests
- **Priority:** P0 · **Reviewer:** QA
- **Status:** `NOT_STARTED`
- **Notes:** No tests; no instructions; monorepo; unknown language; huge repo; contradictory instructions.

---

## M4 — Candidate selection

### FIT-040 · `CandidateConfiguration` domain model
- **Priority:** P0 · **Depends on:** FIT-004 · **Reviewer:** architecture
- **Status:** `NOT_STARTED`
- **Notes:** id, provider, agent, model, reasoning level, instructions, skills, MCPs, tools, context policy, environment, configuration hash, selection reason. No important difference hidden in free-form prompt text.

### FIT-041 · Staged candidate search
- **Priority:** P0 · **Depends on:** FIT-040 · **Reviewer:** architecture
- **Status:** `NOT_STARTED`
- **Notes:** understand → compatibility filter → relevance filter (graph earns its place here) → cost filter → diversity selection. Never brute force.

### FIT-042 · Diversity policy
- **Priority:** P1 · **Depends on:** FIT-041 · **Reviewer:** product
- **Status:** `NOT_STARTED`
- **Notes:** Avoid three near-identical candidates. Target: best predicted quality, best predicted value, fast/simple, baseline, one exploratory.

### FIT-043 · Selection provenance
- **Priority:** P0 · **Depends on:** FIT-041 · **Reviewer:** product
- **Status:** `NOT_STARTED`
- **Notes:** Every candidate answers "why did CTX believe this was worth testing?"

---

## M5 — Experiment planning

### FIT-050 · Task derivation from the repository *(hardest task in the plan)*
- **Priority:** P0 · **Depends on:** FIT-021 · **Reviewer:** QA + architecture
- **Status:** `NOT_STARTED`
- **Notes:** Provenance mandatory; generated tasks labelled; historical solutions must not leak. `red_failure_contains` is the validity gate — a task that does not start red is not a task. Start with the narrowest defensible source and expand only with evidence.

### FIT-051 · Experiment plan object
- **Priority:** P0 · **Depends on:** FIT-040, FIT-050 · **Reviewer:** architecture
- **Status:** `NOT_STARTED`

### FIT-052 · `--dry-run` with cost estimate and budget gate
- **Priority:** P0 · **Depends on:** FIT-051 · **Reviewer:** security + product
- **Status:** `NOT_STARTED`
- **Notes:** Must show candidates, tasks, max executions, estimated cost, providers involved, files that may change. Fails safely when a budget would be exceeded.

---

## M6 — Execution · `BLOCKED`

### FIT-060 · Execution model and isolation
- **Priority:** P0 · **Depends on:** FIT-051 · **Reviewer:** security
- **Status:** `BLOCKED` — requires an authorized budget before any provider spend.
- **Notes:** execution_id, fit_run_id, candidate_id, task_id, commit, environment, timings, status, provider, model, tooling, cost, artifacts. Executions must not contaminate each other.

### FIT-061 · Cost record with completeness
- **Priority:** P0 · **Reviewer:** QA
- **Status:** `NOT_STARTED` *(can be built and unit-tested without spend)*
- **Notes:** States `priced_exact` / `priced_partial` / `unpriced` / `unpriceable`; total is `None` unless exact; folding takes the worst state. Adversarial test: a configuration must never appear cheaper because usage was missing.

### FIT-062 · Repetition and nondeterminism
- **Priority:** P1 · **Depends on:** FIT-060 · **Reviewer:** QA
- **Status:** `NOT_STARTED`
- **Notes:** Reliability as "2/3 verified"; retries always visible; never silently retry until success.

---

## M7 — Verification

### FIT-070 · Verification execution and hierarchy
- **Priority:** P0 · **Depends on:** FIT-020, FIT-060 · **Reviewer:** security + QA
- **Status:** `NOT_STARTED`
- **Notes:** deterministic tests > build/type/lint > acceptance scripts > structured evaluator > reviewer agent > self-report (never sufficient alone).

### FIT-071 · Flaky and infrastructure-failure handling
- **Priority:** P0 · **Depends on:** FIT-070 · **Reviewer:** QA
- **Status:** `NOT_STARTED`
- **Notes:** Distinguish `verification_pass` / `verification_fail` / `infrastructure_failure` / `flaky` / `inconclusive`. Never blame a candidate for known repository nondeterminism.

---

## M8 — Recommendation

### FIT-080 · `FitResult` canonical object
- **Priority:** P0 · **Reviewer:** architecture
- **Status:** `NOT_STARTED`
- **Notes:** Versioned and machine-readable. Every interface derives from it; no interface re-implements business logic.

### FIT-081 · Deterministic recommendation policy
- **Priority:** P0 · **Depends on:** FIT-080 · **Reviewer:** architecture + product
- **Status:** `NOT_STARTED`
- **Notes:** Threshold exclusion → critical-failure exclusion → Pareto frontier → documented default choice. An LLM may explain, never decide.

### FIT-082 · Confidence model
- **Priority:** P0 · **Depends on:** FIT-080 · **Reviewer:** QA
- **Status:** `NOT_STARTED`
- **Notes:** LOW/MEDIUM/HIGH from task count, diversity, repetitions, verification strength, cost completeness, consistency. No false precision.

### FIT-083 · No-improvement result
- **Priority:** P0 · **Depends on:** FIT-081 · **Reviewer:** product
- **Status:** `NOT_STARTED`
- **Notes:** "Keep current configuration" is a first-class success. Test that the product can return it.

---

## M9 — Apply

### FIT-090 · Artifact generation · **FIT-091** · Preview and apply · **FIT-092** · Rollback
- **Priority:** P0/P0/P1 · **Depends on:** FIT-080 · **Reviewer:** security + product
- **Status:** `NOT_STARTED`
- **Notes:** Show every change before applying; never silently modify; every artifact traceable to the recommendation; `--rollback <run-id>` or explicit Git instructions.

---

## M10 — PR *(terminal deliverable, not optional)*

### FIT-100 · Branch and PR preparation
- **Priority:** **P0** · **Depends on:** FIT-090 · **Reviewer:** security + product
- **Status:** `NOT_STARTED`
- **Notes:** ADR-014 makes the PR part of the product promise, not polish. Priority raised from P1. The PR contains evidence, not marketing, and is never auto-merged.

### FIT-101 · GitHub-first entry
- **User story:** As a user, I connect a GitHub repository rather than only running CTX inside a local checkout.
- **Priority:** P1 · **Depends on:** FIT-100 · **Reviewer:** security + product
- **Status:** `NOT_STARTED`
- **Notes:** Genuinely not started — `ctx fit [repo]` accepts a local path only. Local-first stays fully supported (ADR: local-first is not crippled); this would add the hosted-repo entry path. Credential handling is a security-review gate.

---

## Objective-function tasks *(from ADR-014)*

### FIT-110 · Reliability as a selection constraint
- **User story:** As a user, I need "works" to mean "worked every time we tried", not "worked once".
- **Priority:** P0 · **Depends on:** FIT-062 · **Reviewer:** QA
- **Status:** `NOT_STARTED`
- **Notes:** Repeated trials move from "when budget permits" to required for any recommendation. Defines and documents the reliability floor; a candidate below it is excluded before cost is even considered.

### FIT-111 · Lexicographic winner selection
- **User story:** As a user, I want to know exactly why one configuration won, in one sentence.
- **Priority:** P0 · **Depends on:** FIT-110, FIT-061 · **Reviewer:** architecture + product
- **Status:** `NOT_STARTED`
- **Notes:** Replaces the earlier Pareto-selection sketch (see FIT-081). Filter by reliability → minimize attributable cost → tie-break toward the simpler configuration. Candidates with incomplete cost are reported unranked rather than winning by having less data. Pareto survives as presentation only.

---

## Cross-cutting

### FIT-900 · Deletion program
- **Priority:** P1 · **Depends on:** FIT-003 · **Reviewer:** architecture + QA
- **Status:** `DONE (surface)` — command surface and console scripts landed; LOC deletion still open
- **Notes:** Execute the ARCHIVE/DELETE classifications with evidence. Success is measured in public commands and LOC removed while the gate stays green.

**Delivered.** The advertised command surface is now `{fit, doctor, advanced}`. `run`, `resume`, and `sessions` still work and are additionally reachable as `ctx advanced <command>`; they are hidden from help rather than removed, so existing scripts do not break. Bare `ctx` runs the product. Console scripts went from **45 to 7**. `src/tests/fit/test_cli_surface.py` pins all of this so the surface cannot quietly regrow.

**Not delivered: the target of 2 console scripts.** Five of the remaining seven are load-bearing and cannot be dropped by editing `pyproject.toml` alone:

| Script | Why it stays |
| --- | --- |
| `ctx` | The product. |
| `ctx-init` | First-run install path. |
| `ctx-mcp-server` | MCP hosts spawn it by name; renaming it breaks configured clients. |
| `ctx-scan-repo` | Invoked by CI lanes. |
| `ctx-source-registry` | Pinned by `src/tests/test_threat_model_docs.py:190` as a threat-model control. |
| `ctx-telemetry-export` | Invoked by CI lanes. |
| `ctx-telemetry-retention` | Invoked by CI lanes. |

Reaching 2 requires migrating each call site to `python -m`, updating the clean-host contract, and amending the threat-model test — a separate change with its own review, not a line in this one.

**Also fixed here.** `test_concurrent_cross_host_manage_prompts_apply_one_workspace_install` was flaking under full-suite load. Root cause confirmed by reproduction, not inference: two hosts contend for one lock, and the production default `lock_timeout_seconds=2.0` fails closed. Forcing `0.01` reproduces the exact gate signature (`status='failed'`, no permit). The production default is correct — a prompt hook must not stall — so the test now passes `lock_timeout_seconds=10.0`, matching the existing convention in `test_query_hook_delivery.py`.

### FIT-901 · Dogfood CTX Fit on CTX
- **Priority:** P1 · **Reviewer:** product
- **Status:** `NOT_STARTED`
- **Notes:** Mandatory, but must not be the only benchmark. Maintain development / calibration / held-out repository sets to prevent self-optimization.

### FIT-902 · README and docs rewrite
- **Priority:** P1 · **Depends on:** FIT-032 · **Reviewer:** product
- **Status:** `NOT_STARTED`
- **Notes:** Sell the outcome before the machinery; must pass the ten-second test.
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