4f5542a47f
Revised Sprint 11e from training data export to workflow annotation foundation (routing types, skeleton AST, inference-to-routing bridge). Detailed plans for Sprints 12-19 covering workflow model, GUI overhaul, 6 new languages, orchestration engine, C++ self-hosting, Claude Code plugin, and workflow visualization. Created ARCHITECT.md with core thesis and design principles. Training data deferred to post-25 where real workflow decisions provide superior signal. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
139 lines
6.3 KiB
Markdown
139 lines
6.3 KiB
Markdown
# 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.
|