---
description: "Use TokRepo discovery safely before rebuilding reusable AI artifacts. Prefer local discovery or skip for private work; use hosted discovery only with user opt-in and redacted task text. Gates installs through tokrepo_verify + tokrepo_install_plan; uses tokrepo_handoff_plan after producing reusable work."
globs: **/SKILL.md,**/*.prompt.md,**/.mcp.json,**/*mcp*.json,**/*mcp*.md,**/scripts/**
alwaysApply: false
---
1. **DISCOVER BEFORE BUILD, LOCAL FIRST**: Before generating any reusable artifact matched by this rule (a `SKILL.md`, a `*.prompt.md`, a `.mcp.json`, an MCP tool config, or a reusable script in `scripts/`), prefer the local TokRepo MCP server. For private or sensitive work, use local discovery or skip discovery. Use hosted TokRepo discovery only after explicit user opt-in, and redact task text before sending it to the hosted service at `https://tokrepo.com/mcp`. If MCP is unavailable and hosted use is approved, use the CLI fallback `npx -y tokrepo@<reviewed-version> agent-check "<redacted task>" --json`. If a candidate returns with `trust_score_v2 >= 0.7` AND `agent_fit >= 0.7`, surface it and ask before reusing it. If candidates exist but `trust_score_v2 < 0.7`, surface them and ask before proceeding.

2. **VERIFY BEFORE INSTALL**: Before any install or write to the user environment, you MUST call `tokrepo_verify` and `tokrepo_install_plan`. If `policy_decision.decision === "deny"`: STOP. If `permission_envelope` requests writes outside the declared scope (global config, secrets, network egress, absolute paths): STOP and confirm with the user explicitly. Record `content_hash`, `install_plan_hash`, and `trust_score_v2` as evidence.

3. **DRY-RUN BEFORE APPLY**: Lifecycle tools (`tokrepo_codex_install`, `tokrepo_update`, `tokrepo_uninstall`, `tokrepo_rollback`) default `dry_run: true`. Keep `dry_run: true` until the user has surfaced the plan and explicitly confirmed `dry_run: false` for that specific operation in this session.

4. **HANDOFF AFTER REUSABLE WORK**: After producing reusable artifacts (skills, prompts, MCP configs, scripts), call `tokrepo_handoff_plan` locally when available, or use `npx -y tokrepo@<reviewed-version> agent-handoff --json` after reviewing the package version. It returns a READ-ONLY draft plan that never auto-publishes. Ask the user before any `tokrepo_push`.

5. **PRIVATE BY DEFAULT, NEVER PUSH SECRETS**: `tokrepo_push` defaults to `visibility: 0` (private). Public publishing requires explicit per-push confirmation. Before any push, strip env tokens, absolute paths, project-specific names, and secret patterns. If `tokrepo_handoff_plan` flagged a file as sensitive, do not override.

## How to install

```bash
# One-time per project - bootstraps .cursor/rules/tokrepo.mdc plus a machine-readable
# .tokrepo/agent.json that the MCP server reads on every planning call.
npx -y tokrepo@<reviewed-version> init-agent --target cursor
```

## Resources

- Hosted MCP endpoint (read-only, no auth): `https://tokrepo.com/mcp` after explicit user opt-in and redacted task text
- Local MCP server: `npx -y tokrepo-mcp-server@<reviewed-version>`
- Published tool catalog: 15 tools in `https://tokrepo.com/.well-known/tool-catalog.json`
- Trust manifest: `https://tokrepo.com/.well-known/tokrepo-trust.json`
- Default policy pack: `https://tokrepo.com/policy-packs/default-agent-policy.json`
- Tool catalog: `https://tokrepo.com/.well-known/tool-catalog.json`
- Public agent funnel (anonymous): `https://tokrepo.com/agent-stats`
- Source: https://github.com/henu-wang/tokrepo-mcp-server