Torus-Framework: Instructions file for Claude Code

Torus-Framework

TOOLSHED (single MCP gateway)

All tools route through toolshed: run_tool(server, tool, args)

• memory: search_knowledge, get_memory, remember_this, fuzzy_search, record_attempt, record_outcome, query_fix_history, health_check, agent_coordination
• torus-skills: list_skills, invoke_skill, search_skills, self_improve, skill_usage, skill_health, record_outcome, trigger_evolution, capture_skill, skill_lineage
• search: terminal_history_search, transcript_context
• web-search: web_search
• indexer: code_search, code_callers, code_readers, code_path, code_blast_radius, code_hubs, code_clusters, code_cluster_detail
• Discovery: list_tools(group="memory") to see tools in a group

INDEX FIRST (for code searches)

BEFORE exploring code: Read .claude/GRAPH_REPORT.md in the project root for hubs, clusters, and file map.

• For targeted lookups: run_tool("indexer", "code_search", {"project": "<dir-name>", "query": "..."})
• code_callers/code_readers for call chains, code_blast_radius for impact
• If index returns hits, Read those files directly — do NOT grep/find/glob

MEMORY FIRST (Non-Negotiable)

BEFORE building/fixing ANYTHING: run_tool("memory", "search_knowledge", {"query": "..."})

• 0.5: use directly | 0.2-0.5: get_memory(id) to verify | <0.2: treat as unknown AFTER any fix/decision/failed-approach/preference: run_tool("memory", "remember_this", {"content": "...", "tags": "..."}) For errors: use Causal Chain (below) then remember_this()

THE LOOP (mandatory — do not skip steps)

memory → brainstorm → writing-plans → tests → implement → prove → review → commit

• Write failing tests BEFORE implementation — define "correct" before coding
• All steps are toolshed skills: run_tool("torus-skills", "invoke_skill", {"name": "brainstorm"}), etc.
• Do NOT use EnterPlanMode — brainstorm replaces it
• For quick fixes: memory → fix → test → commit (skip brainstorm/writing-plans)

SKILLS (via toolshed MCP — NOT the built-in Skill tool)

NEVER use the Skill tool for framework skills (brainstorm, commit, wrap-up, etc.) The built-in Skill tool is ONLY for: update-config, simplify, loop, schedule, claude-api, keybindings-help. All framework skills route through: run_tool("torus-skills", "invoke_skill", {"name": "..."}) Discovery: run_tool("torus-skills", "search_skills", {"query": "..."})