Data-Driven Design Tooling

[lxsaah]

Summary

Add a conversational architecture agent to AimDB's MCP server. A developer describes a system in natural language; the agent reasons over it using AimDB's buffer semantics; a running instance is derived as a direct consequence — with no manual graph editing, no boilerplate, and no configuration the user has to set up themselves.

The Mermaid diagram, the DSL, and the running instance are all outputs of a conversation — not inputs to one.

Design doc: docs/design/023-M11-architecture-agent.md
Depends on: #M4 MCP Integration

---

Core Principles

• Ideation first — no user should ever touch a graph editor
• Skills travel with the server — agent capabilities served by the MCP server, not configured by the user
• The graph is a projection — Mermaid is read-only, generated from state.toml
• Proposals, not silent commits — every change is explicitly confirmed by the human
• Ambiguity resolved by questions, not assumptions

---

Components

1. MCP Server Extension

New tools added to the existing MCP server:

Tool	Description
get_architecture	Current architecture graph from state.toml
propose_change	Add/modify records or connectors as a pending proposal
resolve_proposal	Confirm, reject, or revise a proposal (confirm | reject | revise)
remove_record	Propose removal (cascades through Mermaid and codegen)
rename_record	Propose renaming (updates all references)
validate_against_instance	Check state.toml against live instance via AimX
get_buffer_metrics	Live metrics for a given record key

New resources: aimdb://architecture, aimdb://architecture/state, aimdb://architecture/conflicts, aimdb://architecture/decisions

New prompts: architecture_agent, resolve_buffer_type, propose_record, breaking_change_review, onboarding

2. aimdb-codegen Library (new crate)

Pure Rust, no async, no runtime dependencies. Reads state.toml and emits:

• .aimdb/architecture.mermaid — Mermaid projection of the architecture
• src/generated_schema.rs — value structs, key enums, and configure_schema()

Consumed by both the CLI (aimdb generate) and the MCP server.

3. CLI generate Subcommand

Supports cargo watch -s "aimdb generate && cargo check".

4. Structured Decision State (.aimdb/state.toml)

Persists records, fields, connectors, buffer choices, and decision rationale across sessions.

5. Conflict Detection

aimdb://architecture/conflicts compares state.toml against the running instance — surfaces missing records, buffer mismatches, connector mismatches.

6. VS Code Integration

• Status bar indicator (green/orange/red sync status)
• Mermaid preview via existing VS Code support
• Single MCP config block as the complete setup step

---

Implementation Phases

Phase	Scope	Deliverable
1	Prompt engineering	architecture_agent + 4 supporting prompts; 3 validated ideation sessions
2	aimdb-codegen library	state.toml parser, Mermaid renderer, Rust codegen, validation
3	CLI generate subcommand	aimdb generate with --check and --dry-run
4	MCP server extension	7 new tools, 4 new resources, 5 new prompts, conflict detection
5	VS Code polish	Status bar extension, documentation

Phase 3 (CLI) can ship independently of Phase 4 (MCP).

---

Codegen Output (per record)

1. Value struct with Serialize / Deserialize derives (fields from state.toml)
2. Key enum with #[derive(RecordKey)], #[key_prefix], #[key], #[link_address]
3. configure_schema() block wiring buffer type and connectors into AimDbBuilder

Supported field types: f64, f32, u8–u64, i8–i64, bool, String

---

Success Criteria

• A developer can describe a multi-record system in plain language and have a compiling, correctly-typed AimDB schema in under 10 minutes
• .aimdb/architecture.mermaid accurately reflects every architectural decision with no manual maintenance
• A new team member can understand the data architecture by reading the Mermaid graph and decisions table, without reading application code
• Changing a buffer type or adding a connector is a one-sentence conversation
• Generated code compiles against the aimdb-core API without modification