Sprint 12-19 architecture plans + roadmap through Sprint 25
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>
This commit is contained in:
Bill
138
sprint18_plan.md
Normal file
138
sprint18_plan.md
Normal file
@@ -0,0 +1,138 @@
|
||||
# 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.
|
||||
Reference in New Issue
Block a user