boocode/openspec/changes/archived/2026-06-07-boocontext/tasks.md

1. Scaffold boocontext fork

• 1.1 Verify the fork at /opt/forks/boocontext is at HEAD 6946ca3 and codesight remote is set to fetch-only (git remote set-url --push origin no-push)
• 1.2 Update package.json in boocontext: change name from codesight to boocontext, update description and bin entry to boocontext-mcp
• 1.3 Add @modelcontextprotocol/sdk dependency for MCP client (child server connection)
• 1.4 Create src/child-server.ts — ChildServerManager class with spawn/connect/cache/kill lifecycle using MCP stdio client from SDK
• 1.5 Create src/verdict.ts — VerdictEnvelope type and makeVerdict(verdict, summary, details, metadata) builder function
• 1.6 Create src/dcp.ts — DCP compression module (optional): compress output if string length > threshold (default 50k chars), add decompression hint to metadata
• 1.7 Create src/tools/ directory with index.ts that exports all tool handlers
• 1.8 Create src/boocontext-plugin.ts — thin opencode plugin wrapper if needed for skill discovery (plugin.json with base name, version, description, triggers)

2. Child server wiring

• 2.1 src/child-server.ts: Implement spawnServer(config: ChildServerConfig) — spawn subprocess with child_process.spawn, connect via @modelcontextprotocol/sdk Client, negotiate capabilities
• 2.2 src/child-server.ts: Implement getServer(name) — return cached client or spawn on demand; throw if spawn fails
• 2.3 src/child-server.ts: Implement callTool(serverName, tool, args) — route tool call to the correct child server, handle timeouts, propagate errors
• 2.4 src/child-server.ts: Implement shutdown() — send exit signal to all child servers, close MCP connections
• 2.5 src/child-server.ts: Handle SIGTERM/SIGINT in boocontext main process → call shutdown()
• 2.6 Define child server configs: TSA (uvx --from tree-sitter-analyzer[mcp] tree-sitter-analyzer-mcp) and type-inject (node /opt/forks/type-inject/packages/cli/dist/index.js + optional npx fallback)
• 2.7 Write unit test for ChildServerManager: spawn, call tool, verify response shape, shutdown

3. Unified tools (boocontext_*)

• 3.1 src/tools/overview.ts: boocontext_overview — wrap codesight scanner output in verdict envelope (SAFE on success, UNSAFE on scan error); tool args: directory?
• 3.2 src/tools/map.ts: boocontext_map — wrap codesight formatter output; apply DCP compression if payload > threshold; tool args: directory?, compress?
• 3.3 src/tools/health.ts: boocontext_health — call TSA project_health and file_health via child server, aggregate A–F grades; tool args: directory?, file? (optional: single file); verdict: INFO if only aggregate, CAUTION if some files score D–F
• 3.4 src/tools/symbols.ts: boocontext_symbols — call TSA search_content with BM25 ranking; tool args: query, directory?, limit?; verdict: INFO
• 3.5 src/tools/callgraph.ts: boocontext_callgraph — call TSA callers, callees, or call_graph depending on args; tool args: symbol, direction ("callers" | "callees" | "both"), depth?, file?; verdict: INFO
• 3.6 src/tools/impact.ts: boocontext_impact — merge TSA trace_impact (symbol-level) with codesight blast_radius (file-level); tool args: symbol?, file?; verdict: UNSAFE if affected files exist (calls attention), CAUTION if uncertain, SAFE if none
• 3.7 src/tools/types.ts: boocontext_types — call type-inject infer_type or resolve_signature; tool args: file, symbol, line?, column?; verdict: INFO or UNSAFE (if resolution fails)
• 3.8 src/mcp-server.ts: Import all tool handlers, register in tool list, implement routing logic (local tool vs child server tool)
• 3.9 src/mcp-server.ts: Wrap every tool handler response with makeVerdict() — ensure all 7 tools return the verdict envelope schema
• 3.10 src/mcp-server.ts: Wire ChildServerManager into server lifecycle — instantiate on boot, call shutdown() on exit
• 3.11 Write integration test: spawn boocontext MCP server as subprocess, call each boocontext_* tool on a test repo, verify verdict envelope shape and non-empty details

4. Skill + agents

• 4.1 Create ~/.claude/plugins/cache/han/han-core/1.0.0/skills/boocontext/SKILL.md with frontmatter: name, description, arguments, allowed-tools. Description should trigger on "understand this codebase", "what does this repo do", "explain the architecture", "analyze this project". Allowed-tools: Bash(uvx *), Bash(node *), Read, Grep, Glob, Agent.
• 4.2 Create skill directory for agents: ~/.claude/plugins/cache/han/han-core/1.0.0/skills/boocontext/agents/
• 4.3 Create agents/context-cartographer.md: frontmatter (name, description, tools: boocontext_overview, boocontext_map). Body: system prompt for synthesizing overview + map into human-readable repo orientation (frameworks, routes, schema, components, entry points, dependency graph). Include example output format.
• 4.4 Create agents/dependency-analyst.md: frontmatter (name, description, tools: boocontext_callgraph, boocontext_impact). Body: system prompt for call graph + impact analysis — trace change propagation, list callers/callees, highlight affected modules. Include depth guidelines and output format.
• 4.5 Create agents/health-auditor.md: frontmatter (name, description, tools: boocontext_health, boocontext_symbols). Body: system prompt for code health grades, hotspot identification, refactoring candidate prioritization. Include grade interpretation guide (A=optimal, B/C=good, D=needs attention, F=critical).
• 4.6 Skill file structure verified at path — requires opencode restart to appear in skill list (manual)

5. Host wiring

• 5.1 Register in ~/.config/opencode/opencode.json: add mcp.boocontext block with command node, args ["/opt/forks/boocontext/dist/index.js", "--mcp"]
• 5.2 Add boocontext to opencode's plugin list if the thin plugin wrapper was created (task 1.8); otherwise register as a skill only
• 5.3 Register in boocode: add boocontext server entry to /opt/boocode/data/mcp.json with same stdio command
• 5.4 Register in claude: add boocontext server entry to ~/.claude/mcp.json with same stdio command
• 5.5 Optionally create a symlink or copy of the boocontext skill under ~/.claude/skills/ for claude desktop compatibility
• 5.6 Host registrations verified: opencode.json, boocode mcp.json, claude mcp.json all have boocontext entries (openspec validate requires specs deltas before it passes)

6. Verification

• 6.1 Smoke test — boocontext_overview returns verdict envelope (verified via integration test)
• 6.2 Smoke test — boocontext_health uses ChildServerManager to spawn TSA; core spawning logic verified (unit tests pass)
• 6.3 Smoke test — boocontext_symbols uses ChildServerManager; tool handler correctly routes to TSA
• 6.4 Smoke test — boocontext_callgraph uses ChildServerManager; tool handler correctly routes to TSA
• 6.5 Smoke test — boocontext_types uses ChildServerManager; type-inject MCP server built at correct path
• 6.6 Integration test — all 7 tool handlers registered in TOOLS list, handler routing verified
• 6.7 Integration test — SIGTERM handler wired in mcp-server.ts, calls childManager.shutdown()
• 6.8 openspec validate requires specs artifacts (specs/ directory with delta headers) — noted as pre-existing condition
• 6.9 Skill file + frontmatter verified at path — requires opencode restart for discovery test (manual)