stevesolun/ctx / docs
skill-router
FlaggedRepo-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.
toolbox/council-runner.md
View on GitHub# Council runner
[`src/council_runner.py`](https://github.com/stevesolun/ctx/blob/main/src/council_runner.py)
is the planner that turns a toolbox declaration into a concrete `RunPlan`
the hook system can execute.
## Responsibilities
1. **Resolve the toolbox** — merge global + per-repo config.
2. **Compute scope** — use explicit files, the current diff, the full repo,
or one-hop graph expansion when a graph edge map is supplied.
3. **Carry budget caps** — copy the toolbox token and second caps into the
plan so downstream execution can enforce them.
4. **Honor dedup** — reuse a cached plan when the toolbox policy is `cached`
and the matching hash is still inside `dedup.window_seconds`.
5. **Persist** — write the plan to
`~/.claude/toolbox-runs/<plan_hash>.json` for downstream reads.
## RunPlan
```python
@dataclass(frozen=True)
class RunPlan:
toolbox: str
agents: tuple[str, ...]
files: tuple[str, ...]
scope_mode: str
budget_tokens: int
budget_seconds: int
guardrail: bool
created_at: float
plan_hash: str
source: str # "fresh" | "cached"
```
The `plan_hash` is deterministic from the toolbox, agents, file set, and
effective scope mode, which lets dedup work without any additional state.
## CLI
```bash
# Build and persist a plan for the named toolbox
python -m council_runner plan --toolbox ship-it
# Build without persisting (useful for inspection)
python -m council_runner plan --toolbox ship-it --dry-run
# List recent plans
python -m council_runner history --limit 10
# Delete stale plans
python -m council_runner purge --older-than-days 30
```
## Budget estimation
The runner records `budget.max_tokens` and `budget.max_seconds` in the plan.
The downstream council execution is responsible for enforcing those caps.
## Dedup window
Dedup looks up the deterministic `plan_hash`. If the toolbox policy is
`cached` and the existing plan is still inside `dedup.window_seconds`, the
runner returns that cached plan instead of writing a fresh one.
## Graph-blast expansion
When callers provide a graph edge map, `graph-blast` expands changed files by
one hop. Without a graph map, graph-blast falls back to the changed set so the
CLI remains deterministic and cheap.
## Related
- [Hooks & triggers](hooks.md) — how a plan gets executed.
- [Verdicts & guardrails](verdicts.md) — what the council leaves behind.
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| 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: 472k | Updated | Claude CodeCodex | Verified | Install |
| 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: 322k | Updated | Claude CodeCodex | Verified | Install |
| dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependencies | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| 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 available | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |