Sprint 20-25 architecture plans — completing the roadmap

Sprint 20: Legacy code ingestion + modernization workflows
Sprint 21: Semantic cross-language transpilation engine
Sprint 22: Assembly languages (x86/ARM) + C++ remaining gaps
Sprint 23: Architect mode — problem description to tech stack + skeleton
Sprint 24: Security annotations, OWASP detection, secure transpilation
Sprint 25: Self-hosting, end-to-end scenarios, polish, release prep

Cumulative: ~508 steps, ~5000 tests, 19+ languages, 90+ MCP tools,
80+ annotation types across 10 subjects. Post-25 training data harvest
builds on real workflow decisions accumulated across all sprints.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

sprint23_plan.md

@@ -0,0 +1,133 @@
+# 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 |