Design — Architecture-Driven Plan Creation
Create exhaustively detailed implementation plans by investigating the existing codebase, researching web resources for optimal architecture and libraries, then refining through multi-agent review loops until the plan is robust enough for any LLM to execute flawlessly.
Behavioral Flow
- Analyze: Examine target requirements and existing system context
- Plan: Define design approach and structure based on type and format
- Design: Create comprehensive specifications with industry best practices
- Validate: Ensure design meets requirements and maintainability standards
- Document: Generate clear design documentation with diagrams and specifications
Key behaviors:
- Requirements-driven design approach with scalability considerations
- Industry best practices integration for maintainable solutions
- Multi-format output (diagrams, specifications, code) based on needs
- Validation against existing system architecture and constraints
Pipeline
/design [target]
│
Phase 1: Research ──────────── references/research-phase.md
│ Codebase investigation (Serena) + Web research (Context7, Perplexity, Exa)
│
Phase 2: Architecture Design
│ Optimal architecture + new library evaluation + Plan draft
│
Phase 3: Review Loop (max 5 rounds) ── references/review-loop.md
│ 3 parallel reviewers per round:
│ ├─ Architecture Reviewer ──── references/architecture-reviewer.md
│ ├─ Completeness Reviewer ──── references/completeness-reviewer.md
│ └─ Feasibility Reviewer ───── references/feasibility-reviewer.md
│ All 3 approved → Phase 4
│
Phase 4: Final Review ─────── references/final-reviewer.md
│ Holistic coherence check across all tasks
│
Phase 5: Plan Output ──────── references/plan-format.md
Save to docs/plans/YYYY-MM-DD-<target>-plan.md
EnterPlanMode for user approval"Weakest LLM Proof" Principle
Every step in the Plan MUST be executable by the lowest-performing LLM without failure.
| Required | Example |
|---|---|
| Exact file paths | src/auth/middleware.ts:45-67 |
| Complete code (no ellipsis) | Full copy-pasteable snippets |
| Exact commands + expected output | pnpm test -- auth.test.ts -> Tests: 5 passed |
| Dependency versions | pnpm add zod@3.23.8 |
| Verification after every step | Run test / check output / confirm state |
| Forbidden | Use Instead |
|---|---|
| "Add appropriate validation" | Write the exact Zod schema |
| "As needed" / "if necessary" | State the condition explicitly, cover both cases |
| "etc." / "and so on" | Enumerate every item |
| "Similarly to X" | Write out the full step independently |
Research Tools
| Tool | Purpose |
|---|---|
mcp__serena__get_symbols_overview | File structure, classes, functions |
mcp__serena__find_symbol | Specific patterns and interface details |
mcp__serena__find_referencing_symbols | Dependency graph |
mcp__context7__resolve-library-id -> query-docs | Current + candidate library docs |
mcp__perplexity__perplexity_research | Architecture best practices |
mcp__exa__web_search_exa | Code examples, real-world implementations |
Phase 2: Architecture Design
Based on Phase 1 research findings:
- Identify optimal architecture for the target
- Evaluate new libraries found in research (justified by evidence)
- Draft Plan using the template in
references/plan-format.md - Each Task = one logical unit, each Step = one atomic action (2-5 min)
Phase 5: Plan Output
- Save Plan to
docs/plans/YYYY-MM-DD-<target>-plan.md - Call
EnterPlanMode— write the complete Plan (not a summary) - Present to user:
- Review History (rounds completed, final reviewer confidence) - Markdown file path - Execution options: parallel subagents (one per task) / sequential in-session / manual
References
references/research-phase.md— Codebase + web research proceduresreferences/plan-format.md— Plan document template and task structurereferences/review-loop.md— 5-round parallel review orchestrationreferences/architecture-reviewer.md— Design coherence reviewer promptreferences/completeness-reviewer.md— Coverage and gap reviewer promptreferences/feasibility-reviewer.md— Technical risk reviewer promptreferences/final-reviewer.md— Holistic final reviewer prompt