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/loopflow-adapter-demo.md

View on GitHub
# LoopFlow adapter demo

Use this page as presenter notes for the LoopFlow owner. The short version:
LoopFlow stays the control language; ctx becomes a permissioned recommendation
sidecar that tells the loop which skills, agents, MCP tools, and user-owned LLM
harnesses are worth loading before the next plan.

## 30-second pitch

LoopFlow already owns the loop: `goal:`, `look at:`, plan, act, observe,
reflect, and `done when`. ctx should not replace that. ctx should run before
planning, read the same goal, verification checks, and failure context, and
return a read-only JSON contract:

- what the loop is allowed to load;
- which skills, agents, MCP servers, and harnesses fit the current goal;
- which related recommendations fit after the loop accepts or rejects part of a
  previous bundle;
- the `ctx-mcp-server` command and tool list for MCP-aware runners;
- a dry-run harness install command only when the user declares their own
  local/API model.

## Demo loop

```loop
loop "select ctx capabilities":
  goal: mcp agent loop local ollama filesystem
  look at: the repo plan, AGENTS.md, and the last failure
  done when "pytest src/tests/test_loopflow_adapter.py -q" passes
  ctx grants: skills, mcps, harnesses
  each cycle: plan, then act, then observe
  when it fails: reflect, then plan again
```

## Demo command

Run ctx immediately before LoopFlow plans:

```bash
python -m ctx.adapters.loopflow \
  --goal "mcp agent loop local ollama filesystem" \
  --loop-name "ctx capability selection" \
  --permissions skills,agents,mcps,harnesses \
  --own-llm \
  --model-provider ollama \
  --model ollama/llama3.1 \
  --selected local-ollama-file-operations \
  --rejected legacy-reviewer \
  --top-k 2
```

The same call can read a real `.loop` file:

```bash
python -m ctx.adapters.loopflow \
  --loop-file select-capabilities.loop \
  --permissions skills,agents,mcps,harnesses \
  --own-llm \
  --model-provider ollama \
  --model ollama/llama3.1
```

Add `--last-failure-file .loopflow/last-failure.txt` after LoopFlow has written
that file.

## Example payload

This excerpt is from the live adapter against the current ctx catalog. Exact
recommendation names can change as the graph changes, but the contract shape is
stable.

```json
{
  "version": "ctx.loop_adapter.v1",
  "adapter": "loopflow",
  "permissions": {
    "skills": true,
    "agents": true,
    "mcps": true,
    "harnesses": true
  },
  "loopflow": {
    "before_plan": "Call python -m ctx.adapters.loopflow before planning and inject this JSON as read-only context.",
    "use_tools": "use tools from the \"ctx\" server",
    "use_skills": "use skills: oocx-tfplan2md-agent-model-selection",
    "harness_rule": "Only load harnesses when the loop runs on a user-owned/API/local LLM."
  },
  "mcp_server": {
    "name": "ctx",
    "command": "ctx-mcp-server",
    "args": [],
    "tools": [
      "ctx__recommend_bundle",
      "ctx__graph_query",
      "ctx__recommend_related",
      "ctx__wiki_search",
      "ctx__wiki_get",
      "ctx__observe_dev_event",
      "ctx__load_entity",
      "ctx__mark_entity_used",
      "ctx__record_validation",
      "ctx__record_escalation",
      "ctx__unload_entity",
      "ctx__session_end",
      "ctx__session_state"
    ]
  },
  "capabilities": {
    "skills": [
      {
        "name": "oocx-tfplan2md-agent-model-selection",
        "type": "skill",
        "status": "installed",
        "installable": true,
        "load_status": "local-wiki",
        "source_path": "converted/oocx-tfplan2md-agent-model-selection/SKILL.md"
      },
      {
        "name": "nickcrew-claude-ctx-plugin-tool-selection",
        "type": "skill",
        "status": "available",
        "source_catalog": "skill-index",
        "install_command": "python -m ctx.adapters.claude_code.install.skill_install nickcrew-claude-ctx-plugin-tool-selection",
        "installable": false,
        "load_status": "external-install-required",
        "source_path": "python -m ctx.adapters.claude_code.install.skill_install nickcrew-claude-ctx-plugin-tool-selection"
      }
    ],
    "agents": [
      {"name": "oss-investigator-local-git-agent", "type": "agent"},
      {"name": "loop-operator", "type": "agent"}
    ],
    "mcps": [
      {"name": "local-ollama-file-operations", "type": "mcp-server"},
      {"name": "multi-model-advisor-ollama", "type": "mcp-server"}
    ],
    "harnesses": [
      {"name": "autogen", "type": "harness", "fit_score": 1.0},
      {"name": "langfuse", "type": "harness", "fit_score": 1.0}
    ]
  },
  "related_recommendations": [
    {
      "id": "mcp-server:ollama",
      "name": "ollama",
      "type": "mcp-server",
      "tldr": "mcp-server recommendation.",
      "reason": "related via local-ollama-file-operations; normalized score 1.000",
      "installable": true,
      "load_status": "local-wiki",
      "source_path": "entities/mcp-servers/ol/ollama.md",
      "selected": false,
      "selection_state": "suggested_related"
    }
  ],
  "agent_loop": {
    "before_act": "Load only the granted capability groups from capabilities.*.",
    "on_failure": "Pass the latest failure back as last_failure before the next plan.",
    "harness_install": "python -m harness_install --dry-run '--goal=mcp agent loop local ollama filesystem' --model-provider=ollama --model=ollama/llama3.1 -- autogen"
  },
  "warnings": []
}
```

## How LoopFlow would consume it

The smallest integration is a pre-plan hook:

```python
from ctx.adapters.loopflow import recommend_for_loop

ctx_payload = recommend_for_loop(
    goal=loop.goal,
    loop_name=loop.name,
    loop_kind="loopflow",
    look_at=loop.look_at,
    done_when=loop.done_when,
    last_failure=loop.last_failure_text,
    selected=loop.selected_ctx_ids,
    rejected=loop.rejected_ctx_ids,
    permissions={"skills", "agents", "mcps", "harnesses"},
    own_llm=runner.uses_user_owned_model,
    model_provider=runner.model_provider,
    model=runner.model,
)

loop.add_readonly_context("ctx", ctx_payload)

if ctx_payload["mcp_server"]["command"]:
    runner.register_mcp_server(
        name=ctx_payload["mcp_server"]["name"],
        command=ctx_payload["mcp_server"]["command"],
        args=ctx_payload["mcp_server"]["args"],
    )

if ctx_payload["loopflow"]["use_skills"]:
    loop.add_planning_hint(ctx_payload["loopflow"]["use_skills"])

for row in ctx_payload["related_recommendations"]:
    loop.add_planning_hint(f"consider related ctx recommendation: {row['id']}")
```

After a failed observe step, LoopFlow passes the new failure text back into the
next adapter call. That is the agent-loop back edge: LoopFlow keeps the retry
logic, and ctx refreshes recommendations based on what just failed.

For a long-lived runner that executes accepted recommendations, share one
`ActivationLeaseRegistry` across all nested or parallel loops:

```python
from ctx.adapters.loopflow import ActivationLeaseRegistry

leases = ActivationLeaseRegistry()

def apply_ctx_actions(actions):
    runner.load_all(actions.load)
    runner.mark_used(actions.use)
    runner.unload_all(actions.unload)

lease_id = f"{run.id}.{loop.id}.{loop.invocation_id}"
desired = loop.accepted_ctx_ids
with leases.lease(
    lease_id,
    desired=desired,
    used=lambda: loop.used_ctx_ids,
    permissions=loop.ctx_permissions,
    apply=apply_ctx_actions,
):
    loop.run()
```

The registry serializes transitions inside one host process. It commits
ownership only after `apply_ctx_actions` returns, so failed loads and unloads
remain retryable, and it unloads shared context only after the final owning
loop exits. Host load/unload operations must be idempotent because a host may
partially apply an action set before raising.

Each live context-manager lease ID must be unique; include the loop invocation
or attempt ID, not only the static loop name. Pass a `used` supplier so the
registry reads observed use after execution, including failure and cancellation
paths, rather than recording planned use before the loop starts.
The applier must be synchronous and must not call the registry or wait for a
worker that calls it. Such callback re-entry fails fast with
`ActivationLeaseBusyError` so it cannot deadlock all loop transitions. The
context manager waits for unrelated transitions automatically; direct
`sync(...)` or `release(...)` calls may either retry that error or explicitly
pass `wait_for_transition=True` when they are outside an applier.

The subprocess CLI is recommendation-only and does not coordinate activation
leases across processes. Recommendation feedback is stateless unless the runner
supplies `--session-id`; with that opt-in, canonical rejected IDs persist in the
local lifecycle store according to `--rejection-mode` (`use`, `replace`, or
`ignore`). This memory suppresses repeated recommendations only. It does not
create or share activation leases. A runner that needs live load/use/unload
behavior must use the direct Python integration above (or own a persistent
coordinator) and keep LoopFlow in control of physical tool changes.

## Permission model

The adapter fails closed:

- `--permissions skills` only returns skill recommendations.
- Goals that imply local files, `feature_implementation`, no API keys, or a
  clear programming language overfetch and then hide non-local, credentialed,
  generic-planning, or wrong-language capability and related rows.
- `--permissions mcps` returns MCP server recommendations and exposes only
  read-only ctx MCP tools: recommendation, graph query, and wiki lookup.
- Lifecycle MCP tools such as load, mark-used, validation, escalation, unload,
  and session tools are exposed only when all capability groups are granted:
  `skills`, `agents`, `mcps`, and `harnesses`.
- `--permissions harnesses` returns no harnesses unless `--own-llm` is present.
  `--model-provider` and `--model` improve ranking and dry-run command metadata;
  they are not user-owned model consent.
- `agent_loop.harness_install` is always a `--dry-run` command. It shows what
  would be installed; it does not mutate the host.

`.loop` files can request ctx grants with one small line:

```loop
ctx grants: skills, mcps, harnesses
```

CLI/API grants take precedence. If the command passes `--permissions`, those
grants replace the `.loop` line. If the API caller passes `permissions=...`,
that explicit set is authoritative. If neither is present, the `.loop` grants
are used; if none are present anywhere, the adapter returns no capabilities.

This lets a LoopFlow user decide whether a loop may use skills, agents, MCPs,
or harnesses without giving ctx authority to bypass the loop's own gates.

## Owner ask

The integration proposal for LoopFlow is intentionally small:

1. Add an optional `ctx` pre-plan hook in the LoopFlow runner.
2. Let `.loop` users grant capability groups: `skills`, `agents`, `mcps`,
   and `harnesses`.
3. Inject the returned JSON as read-only context before planning.
4. Register the ctx MCP server only when the adapter returns an MCP command.
5. Surface `agent_loop.harness_install` as an explicit user action, not an
   automatic install.

That gives LoopFlow the ctx graph, llm-wiki, MCP server, skill recommender, and
user-owned model harness recommendations while preserving LoopFlow's language,
human gates, and `done when` verification model.
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: 471kUpdated 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