whetstone_DSL/sprint23_plan.md

Sprint 23 Plan: Architect Mode + Tech Stack Selection

Context

The endgame feature: describe a problem in natural language, and the system proposes a technology stack, project structure, and annotated skeleton. This is the architect's power tool — not replacing the architect, but giving them a structured starting point they can review, modify, and approve.

Sprint 23 builds on everything: the annotation taxonomy (Sprints 10-11), the skeleton AST (Sprint 11e), the workflow model (Sprint 12), the orchestrator (Sprint 15), the language coverage (17+ languages), and the transpilation engine (Sprint 21).

---

Phase 23a: Problem Decomposition (Steps 471-476)

Step 471: Problem Description Parser (12 tests)

• Accept natural language problem description
• Extract structured requirements:
  • Functional requirements (what it should do)
  • Non-functional requirements (performance, security, scalability)
  • Platform constraints (web, mobile, embedded, server, CLI)
  • Integration requirements (databases, APIs, existing systems)
• Output: StructuredRequirements JSON with confidence per extraction
• This is the one place where LLM assistance is expected in the architecture — the extraction is an MCP prompt template, not hardcoded NLP

Step 472: Module Decomposition Engine (12 tests)

• Given StructuredRequirements, propose module structure:
  • Identify major subsystems (auth, data, API, UI, etc.)
  • Define module boundaries and interfaces
  • Estimate complexity per module
  • Identify cross-cutting concerns (logging, error handling, config)
• Output: ModuleGraph with nodes (modules) and edges (dependencies)
• Multiple decomposition strategies: microservice vs monolith vs layered

Step 473: Technology Stack Selector (12 tests)

• Given requirements + module graph, recommend tech stack:
  • Language selection per module (guided by requirements):
    • Performance-critical → Rust or C++
    • Web frontend → TypeScript
    • Data processing → Python
    • System scripting → Go or Python
    • Database → SQL dialect based on requirements
    • Embedded → C or assembly
  • Framework suggestions (as annotations, not framework-specific code)
  • Database selection based on data requirements
• Configurable preferences: "I prefer Rust for backend", "must use PostgreSQL"
• Output: TechStackDecision with reasoning per choice

Step 474: Skeleton Generation from Requirements (12 tests)

• Given module graph + tech stack:
  1. Create skeleton modules in chosen languages
  2. Create skeleton functions/classes with @Intent annotations from requirements
  3. Add routing annotations: @Complexity, @ContextWidth, @Automatability
  4. Add contract annotations: @Contract from functional requirements
  5. Add dependency annotations between modules
• Output: Multi-file skeleton project ready for workflow creation

Step 475: Architect Review Interface (12 tests)

• Present the proposed stack + skeleton to the architect for review:
  • Tech stack summary with reasoning
  • Module dependency graph (visual in GUI, structured in MCP)
  • Per-module: language choice, complexity estimate, key annotations
  • Modification tools: change language, merge modules, add modules, adjust routing
• Architect approves → skeleton becomes the project spec
• Architect modifies → re-run affected selections

Step 476: Phase 23a Integration (8 tests)

• Full flow: "Build a REST API for a bookstore with user auth, PostgreSQL, and a React frontend" → structured requirements → module decomposition → tech stack (TypeScript frontend, Python/Rust backend, PostgreSQL) → skeleton project → architect review → approved → workflow created
• 87+ MCP tools total

---

Phase 23b: Project Templates + Scaffolding (Steps 477-481)

Step 477: Architecture Templates (12 tests)

• Pre-built architecture patterns:
  • REST API: routes + handlers + models + middleware + database
  • CLI Tool: argument parsing + commands + output formatting
  • Library: public API + internal modules + tests + documentation stubs
  • Microservice: service + transport + storage + health check
  • Full Stack: frontend + backend + database + deployment config
• Templates are parameterized: entity names, field definitions, auth method
• Each template produces a fully-annotated skeleton project

Step 478: Scaffold File Generation (12 tests)

• Generate actual project files on disk from approved skeleton:
  • Source files with skeleton code + Semanno annotations
  • Project configuration (package.json, Cargo.toml, pyproject.toml, CMakeLists.txt)
  • Directory structure following language conventions
  • .gitignore appropriate for selected stack
  • .whetstone/ directory with sidecar files and workflow state
• Uses existing fileCreate/fileWrite MCP infrastructure

Step 479: Dependency + Build System Awareness (12 tests)

• Annotate dependencies between modules with build system info:
  • Python: imports and pip requirements
  • Rust: crate dependencies in Cargo.toml format
  • Node: npm packages in package.json format
  • C++: include paths and CMake targets
  • SQL: migration ordering
• Not full build system integration — annotation-level awareness for context

Step 480: Multi-Language Project Orchestration (12 tests)

• Workflow creation for multi-language projects:
  • Each module may be a different language
  • Cross-language interfaces annotated with @Link and @Shim
  • Build order respects cross-language dependencies
  • FFI boundaries explicitly annotated for human review
• Orchestrator handles multi-language workflow as a single project

Step 481: Phase 23b Integration + Sprint Summary (8 tests)

• REST API template → scaffold files on disk → workflow → orchestrate
• Multi-language project: Python service + Rust core + SQL schema
• Architect modifies tech stack mid-planning → skeleton regenerates
• All scaffolded files have proper annotations and structure
• Sprint 23 totals: architect mode operational, templates working

---

Step & Test Summary

Phase	Steps	Tests	Theme
23a	471-476	68	Problem decomposition, tech stack selection, skeleton generation
23b	477-481	56	Templates, scaffolding, build awareness, multi-language orchestration
Total	471-481	~124	11 steps