whetstone_DSL/sprint18_plan.md

Sprint 18 Plan: Claude Code Plugin + MCP Workflow Tools

Context

This is the payoff sprint. Sprints 12 and 15 built the workflow model and orchestration engine. Sprint 18 builds the client side — the thing an engineer actually installs and uses.

The deliverable: a Claude Code MCP tool configuration that an engineer adds to their project, and suddenly Claude Code can orchestrate annotation-driven workflows. The engineer says "modernize this module" and the system:

1. Creates a skeleton with inferred annotations
2. Routes tasks (deterministic for simple stuff, Claude for complex stuff)
3. Executes what it can automatically
4. Surfaces the hard decisions to the human with full context
5. Tracks progress and handles review

This sprint doesn't build a custom plugin binary. It builds the MCP server tools and the prompt templates that make the existing whetstone_mcp binary work as an effective Claude Code tool server. The "plugin" is a configuration file pointing Claude Code at the whetstone_mcp server.

---

Phase 18a: Claude Code Integration (Steps 417-422)

Step 417: MCP Server Configuration + Discovery (12 tests)

• Generate .mcp.json configuration file for Claude Code
• Server manifest: all 68+ tools organized by category with descriptions
• Tool categories: AST, Diagnostics, Workflow, Routing, Project, File ops
• Auto-detection: whetstone_mcp binary path resolution
• Workspace detection: auto-find project root and language

Step 418: Workflow Prompt Templates (12 tests)

• MCP prompt templates that guide Claude through the workflow protocol:
  • architect_project — "Analyze this codebase and create an annotated skeleton"
  • modernize_module — "Modernize this legacy code with safety annotations"
  • port_to_language — "Port this module from {source} to {target}"
  • add_feature — "Add {feature} to this project using the workflow system"
  • review_pending — "Review and approve/reject pending work items"
• Each prompt includes the workflow protocol steps the agent should follow
• Prompts reference specific MCP tools by name

Step 419: Agent Workflow Loop (12 tests)

• The core interaction loop for an agent using the MCP tools:
  1. whetstone_infer_annotations on existing code
  2. whetstone_create_skeleton for new functionality
  3. whetstone_create_workflow to plan execution
  4. whetstone_orchestrate_run_deterministic for auto tasks
  5. whetstone_get_blockers to find what needs the agent
  6. For each agent task: read context bundle, generate code, whetstone_submit_result
  7. whetstone_get_progress to track completion
• Test that this loop works end-to-end through MCP

Step 420: Human Review Interface via MCP (12 tests)

• Tools for presenting review decisions to the engineer:
  • whetstone_get_review_queue — items awaiting human review
  • whetstone_get_review_context — full context for a review item (original skeleton, generated code, annotations, confidence, reasoning)
  • whetstone_approve_item — approve with optional feedback
  • whetstone_reject_item — reject with required feedback
• Review context formatted for human readability (not just raw JSON)

Step 421: Workspace Onboarding Flow (12 tests)

• First-time setup experience for a new workspace:
  1. Detect project languages from file extensions
  2. Index workspace files
  3. Run annotation inference on key files
  4. Suggest initial annotations and workflow
  5. Generate .whetstone/ directory with sidecar files
• whetstone_onboard_workspace tool that does this in one call

Step 422: Phase 18a Integration (8 tests)

• Full end-to-end: configure MCP → onboard workspace → create workflow → orchestrate → agent completes tasks → human reviews → complete
• All MCP tools documented with clear descriptions
• 75+ MCP tools total

---

Phase 18b: Multi-Model Dispatch (Steps 423-427)

The orchestration engine routes tasks to "slm", "llm", or "human" — but which specific model? Phase 18b adds model selection awareness.

Step 423: Model Profile Registry (12 tests)

• ModelProfile struct: name, contextWindow, costPerToken, capabilities, speed
• Pre-configured profiles: claude-opus, claude-sonnet, claude-haiku, local-slm
• Routing engine maps: "llm" → claude-sonnet (default), "slm" → claude-haiku
• Configurable overrides in .whetstone/config.json

Step 424: Context Window Optimization (12 tests)

• Given a model's context window, optimize the context bundle:
  • Small model (8k context) → aggressive truncation, local scope only
  • Medium model (32k) → file scope with budget
  • Large model (200k) → project scope, include related files
• Context assembly adapts automatically based on model profile

Step 425: Batch Submission for Agent Tasks (12 tests)

• When multiple agent tasks are ready, batch them for efficient submission
• Group by context overlap (tasks in same file share context)
• Batch format: shared context once + per-task instructions
• Reduces total token cost by ~30-50% for related tasks

Step 426: Cost Tracking + Reporting (12 tests)

• Track actual tokens used per task (from submitExternalResult metadata)
• Compare estimated vs actual costs
• Running cost total for the workflow
• Cost report: breakdown by worker type, language, task complexity

Step 427: Phase 18b Integration + Sprint Summary (8 tests)

• Model profiles select appropriate context window
• Batch submission reduces total tokens vs individual
• Cost tracking matches expected for a 10-task workflow
• Sprint 18 totals: 75+ tools, workflow operational end-to-end

---

Step & Test Summary

Phase	Steps	Tests	Theme
18a	417-422	68	Claude Code config, prompts, agent loop, review, onboarding
18b	423-427	56	Model profiles, context optimization, batching, cost tracking
Total	417-427	~124	11 steps

---

Key Architectural Decision

The "plugin" is not a custom binary or VS Code extension. It is:

1. The existing whetstone_mcp binary (headless MCP server)
2. A .mcp.json configuration file that tells Claude Code where to find it
3. MCP prompt templates that guide the agent through the workflow protocol
4. MCP tools organized into a coherent workflow

This means any MCP-compatible client (not just Claude Code) can drive Whetstone workflows. The protocol is the product, not a proprietary integration.