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

toolbox/verdicts.md

View on GitHub
# Verdicts & guardrails

[`src/toolbox_verdict.py`](https://github.com/stevesolun/ctx/blob/main/src/toolbox_verdict.py)
owns the council's finding ledger. A `RunPlan` says *what should run*; a
`Verdict` says *what was found* and, if the level escalates high enough,
blocks `git commit`.

## Data model

```python
@dataclass(frozen=True)
class Evidence:
    file: str
    line: int | None = None
    note: str = ""

@dataclass(frozen=True)
class Finding:
    id: str                    # stable, hash(level|agent|title)
    level: str                 # "LOW" | "MEDIUM" | "HIGH" | "CRITICAL"
    title: str
    agent: str = ""
    evidence: tuple[Evidence, ...] = ()
    rationale: str = ""
    created_at: float = 0.0

@dataclass(frozen=True)
class Verdict:
    plan_hash: str
    level: str                 # max(findings)
    summary: str
    findings: tuple[Finding, ...]
    created_at: float
    updated_at: float
```

Level escalation is always `max(findings)`. Clearing a finding
re-escalates from whatever remains.

## Storage

```
~/.claude/toolbox-runs/
  abc123.json                # the RunPlan
  abc123.verdict.json        # the Verdict (sibling)
```

Same directory, same hash. A single `history` sweep covers both.

## Merge-by-id

Agents can refine a previous finding by recording with the same id.
The new record replaces the old one (rationale, evidence, level all
update). This is how a `security-reviewer` can start with a MEDIUM
finding, then bump it to CRITICAL after deeper analysis — without
leaving duplicate entries.

The default id is `sha256(level|agent|title)[:12]`, so the same
agent recording the same titled issue naturally dedups. Pass
`--id custom-value` if you need a different stable key.

## Blocking

`toolbox_hooks` reads `<plan>.verdict.json` after a `pre-commit`
council runs. If `level in {"HIGH", "CRITICAL"}` and the toolbox has
`guardrail: true`, it returns exit `2`, which stops the commit.

`LOW` and `MEDIUM` findings are logged but never block.

## CLI

```bash
# Record a finding
python -m toolbox_verdict record \
  --plan-hash abc123 \
  --level HIGH \
  --title "SQL injection in users.py" \
  --agent security-reviewer \
  --evidence src/users.py:42:unescaped input \
  --rationale "req.form values flow into raw SQL"

# Show the verdict
python -m toolbox_verdict show --plan-hash abc123

# JSON payload for piping
python -m toolbox_verdict show --plan-hash abc123 --json

# Recent verdicts (retrospective)
python -m toolbox_verdict retro --limit 10

# Only HIGH/CRITICAL
python -m toolbox_verdict retro --min-level HIGH

# Pretty-print the evidence chain
python -m toolbox_verdict explain --plan-hash abc123

# Remove a single finding
python -m toolbox_verdict clear --plan-hash abc123 --id <id>
```

## Evidence parsing

`parse_evidence()` accepts three forms, parsed right-to-left so Windows
drive-letter paths don't trip the delimiter:

- `src/foo.py` → `Evidence(file="src/foo.py")`
- `src/foo.py:42` → `Evidence(file="src/foo.py", line=42)`
- `src/foo.py:42:race on counter` → `Evidence(file=..., line=42, note=...)`
- `C:/Users/me/foo.py:17` → `Evidence(file="C:/Users/me/foo.py", line=17)`

Empty specs yield an `Evidence` with an empty file and are filtered out
at `build_finding()` time.

## Explain output

```
[verdict] plan=abc123  level=HIGH  2 finding(s): 1 high, 1 low
  - [HIGH] SQL injection in users.py  (agent: security-reviewer)
      why: req.form values flow into raw SQL
      evidence: src/users.py:42 — unescaped input
  - [LOW] style: trailing whitespace  (agent: code-reviewer)
      evidence: src/users.py:57
```

Findings render in severity-desc order so the blocking issue always
appears first.

## Retrospective

`recent_verdicts()` returns verdicts sorted by `updated_at` desc:

```
[retro] 3 recent verdict(s):
  - plan-crit   CRITICAL  BLOCK  1 finding(s): 1 critical
  - plan-hi     HIGH      BLOCK  2 finding(s): 1 high, 1 low
  - plan-ok     LOW       ok     1 finding(s): 1 low
```

## Related

- [Hooks & triggers](hooks.md) — where the `2` exit blocks the commit.
- [Council runner](council-runner.md) — where the plan hash comes from.
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