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

harness/clean-host-contract.md

View on GitHub
# Clean Host Contract

The clean-host contract is a release-hardening check for ctx. It builds the
current source tree into a wheel, installs that wheel into a fresh virtualenv,
redirects user-state environment variables into a temporary directory, and then
drives real console scripts.

It is intentionally implemented as `scripts/clean_host_contract.py`, not as a
public `ctx-*` command. The runner is infrastructure for maintainers until the
contract stabilizes.

## What It Proves

- The source tree can build a wheel.
- The built wheel installs into a clean virtualenv.
- Console-script entrypoints execute from the installed wheel.
- `ctx-init --hooks` writes Claude settings only under an isolated temp home.
- A deterministic fake Claude host reads the generated settings and executes
  the installed PostToolUse and Stop hook commands without calling Anthropic
  APIs.
- With `--run-live-claude`, a real Claude Code host can be exercised behind an
  explicit quota acknowledgement, non-spending preflights, and a hard budget
  cap. Hook execution is verified through a JSONL sentinel written by injected
  PostToolUse and Stop hooks under the temp root.
- `ctx-scan-repo --repo <path> --recommend` can scan a tiny FastAPI-like repo from the wheel.
- `ctx run` can start a session with a process-local fake LiteLLM provider.
- `ctx resume` can continue that session from the same isolated session store.
- `--deny-tool` blocks a model-requested ctx tool call before dispatch.
- Caller `PYTHONPATH` is stripped so the contract cannot accidentally import
  source-tree modules instead of the installed wheel.

## What It Skips

- It does not run `ctx-init --graph` by default; even the fast runtime graph
  install downloads or extracts a large release artifact, so it stays in
  dedicated public-install smoke tests.
- It does not execute hooks inside a live Claude Code process by default. The
  live host path is opt-in because it can consume Anthropic or provider quota.
- It does not connect to a real third-party MCP server.
- It does not browser-test the monitor dashboard.
- It does not simulate process kills or power loss during writes.

Those checks stay intentionally manual or opt-in until they are stable enough
for the default CI path.

## Local Usage

Run from the repository root:

```bash
python scripts/clean_host_contract.py --fast
```

For debugging, keep the temp directory:

```bash
python scripts/clean_host_contract.py --fast --keep-temp
```

To force a specific temp root:

```bash
python scripts/clean_host_contract.py --fast --temp-root /tmp/ctx-clean-host-debug
```

To run the real Claude Code host gate, use a shell with explicit non-file auth
available, acknowledge quota, and keep the budget small:

```bash
CTX_LIVE_CLAUDE_ACK=uses_quota \
python scripts/clean_host_contract.py --fast --run-live-claude --live-claude-max-budget-usd 0.05
```

Use `--claude-bin /path/to/claude` if `claude` is not on `PATH`. The live gate
runs `claude --version` and `claude auth status` before the budgeted prompt,
then appends sentinel hooks to the isolated `settings.json` and requires both
PostToolUse and Stop records in `live-claude-hooks.jsonl`. It intentionally
does not read OAuth or keychain state from the real user home; use explicit
environment/provider auth for this check.

## CI Usage

The main `.github/workflows/test.yml` workflow runs this contract on pushes and
pull requests. The standalone `.github/workflows/clean-host-contract.yml`
workflow remains available for manual runs and weekly scheduled drift checks.
CI uses the default fake-host path and does not spend model quota.

## Failure Triage

- Wheel build failure: inspect package metadata and `pyproject.toml`.
- Install failure: inspect dependency constraints and `pip check` output.
- `ctx-init` failure: inspect packaged entrypoints and hook module paths.
- Fake Claude hook-smoke failure: inspect generated `settings.json`, packaged
  hook module paths, and whether PostToolUse/Stop hook schemas changed.
- Live Claude gate failure: inspect explicit auth env/provider credentials,
  `claude auth status`, the budget cap, the injected sentinel hook entries, and
  `live-claude-hooks.jsonl` under the temp root.
- `ctx-scan-repo` failure: inspect installed flat-module entrypoints and
  resolver imports.
- `ctx run` or `ctx resume` failure: inspect LiteLLM provider import behavior,
  session store paths, and CLI metadata replay.
- Tool denial failure: inspect `--allow-tool`/`--deny-tool` policy handling in
  `src/ctx/cli/run.py` and `src/ctx/adapters/generic/loop.py`.
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