Design

Phase 1: UI Design (if applicable and Gemini Step 3 skipped)

• TUI layout: doc/05_design/<feature>_tui.md
• GUI layout: doc/05_design/<feature>_gui.md
• Skip if feature has no UI component

Phase 2: Architecture Evaluation

• Evaluate candidate patterns for the feature
• Apply MDSOC (virtual capsules, feature transforms) where appropriate
• Check alignment with existing doc/04_architecture/ ADRs
• Identify cross-cutting concerns for MDSOC weaving

Output: doc/04_architecture/<feature>.md

MDSOC Application Checklist

• Does the feature cross module boundaries? -> Virtual capsule candidate
• Does the feature add cross-cutting behavior? -> Feature transform candidate
• Does the feature need runtime composition? -> Adapter pattern candidate
• See src/compiler/85.mdsoc/ for existing MDSOC infrastructure

Phase 3: System Test Design

• SSpec BDD tests with built-in matchers only
• Every REQ-NNN must have at least one test
• Include edge cases and error paths

Output:

• Test specs: doc/06_spec/app/<app_name>/feature/<feature>_spec.spl
• Test plan: doc/03_plan/sys_test/<feature>.md

Built-in Matchers (ONLY these are allowed)

to_equal(expected)        # Exact equality
to_be(expected)           # Identity/reference equality
to_be_nil()               # Nil check
to_contain(item)          # Collection/string contains
to_start_with(prefix)     # String prefix
to_end_with(suffix)       # String suffix
to_be_greater_than(val)   # Numeric comparison
to_be_less_than(val)      # Numeric comparison

• Use to_equal(true) not to_be_true()
• Use to_equal(false) not to_be_false()

SSpec Test Template

use std.spec.SSpec

describe "<Feature>":
    describe "REQ-001: <requirement name>":
        it "should <expected behavior>":
            val result = <invoke feature>
            expect(result).to_equal(<expected>)

        it "should handle edge case: <description>":
            val result = <invoke with edge input>
            expect(result).to_equal(<expected>)

        it "should return error for invalid input":
            val result = <invoke with bad input>
            expect(result.error?).to_equal(true)

Phase 4: Detail Design

• Data structures, algorithms, module interactions, error handling
• Output: doc/05_design/<feature>.md
• Agent tasks: doc/03_plan/agent_tasks/<feature>.md

Phase 5: Quality Check

• Verify every REQ-NNN has test coverage
• Check SSpec quality: real assertions, edge cases, error paths
• Verify architecture alignment with MDSOC rules
• Ask user if architecture/design needs changes

Artifacts Produced

Multi-LLM Collaboration

• If Claude (Step 1) or Codex (Step 2) produced research, build on it
• If Gemini (Step 3) produced UI design, incorporate it — do not overwrite
• Tag Codex-produced artifacts with <!-- codex-design --> comment

Rules

• If requirements missing, do research first — never design without requirements
• If another LLM already created artifacts, review and extend — never overwrite
• Every REQ-NNN must have test coverage
• All code in .spl — no Python, no Bash
• Generics use <> not []
• NO inheritance — use composition, traits, mixins
• Use Result<T, E> + ? for error handling
• For MCP, LSP, and tool servers, explicitly review startup path, hot request paths, cache or index strategy, and invalidation strategy
• Call out full-tree scans, repeated file reads, and per-request subprocesses as design risks unless the operation is explicitly maintenance or reindex work
• Define startup and representative request-latency budgets for performance-sensitive features
• Require an observability plan for perf-sensitive paths: timings, counters, or debug diagnostics