laststance/design

Design — Architecture-Driven Plan Creation

Codex Compatibility

When running this skill in Codex, translate Claude Code-only primitives before acting: AskUserQuestion -> chat/request_user_input, TodoWrite -> update_plan, Task/TaskCreate/TeamCreate/SendMessage -> spawn_agent/send_input/wait_agent when available and allowed, and EnterPlanMode/ExitPlanMode -> a concise chat plan plus explicit approval. Resolve Read/Write/Edit/Bash/WebSearch/WebFetch to Codex file/shell/web tools, and map ~/.claude/... paths to ~/.agents/... or ~/.codex/... unless the task explicitly targets Claude Code.

Cursor Compatibility

When running this skill in Cursor Agent, translate Claude Code-only primitives before acting: AskUserQuestion -> AskQuestion; TodoWrite -> Cursor TodoWrite or an equivalent checklist; Task/TaskCreate/TeamCreate/SendMessage/multi-agent flows -> Cursor Task (subagents), parallel Tasks, or run_in_background when allowed (TeamCreate/SendMessage may have no exact match); EnterPlanMode/ExitPlanMode -> Plan mode (SwitchMode / CreatePlan) plus explicit user approval. Resolve Read/Write/Edit/StrReplace/Bash/web/search/MCP via Cursor Composer or Agent equivalents. MCP names written as mcp__server__tool typically map to call_mcp_tool with configured server identifiers. Map ~/.claude/... to ~/.cursor/skills/, .cursor/skills/, and .cursor/rules/ unless the task explicitly targets Claude Code.

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

1. Analyze: Examine target requirements and existing system context
2. Plan: Define design approach and structure based on type and format
3. Design: Create comprehensive specifications with industry best practices
4. Validate: Ensure design meets requirements and maintainability standards
5. 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 [email protected] | | 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:

1. Identify optimal architecture for the target
2. Evaluate new libraries found in research (justified by evidence)
3. Draft Plan using the template in references/plan-format.md
4. Each Task = one logical unit, each Step = one atomic action (2-5 min)

Phase 5: Plan Output

1. Save Plan to docs/plans/YYYY-MM-DD-<target>-plan.md
2. Call EnterPlanMode — write the complete Plan (not a summary)
3. 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 procedures
• references/plan-format.md — Plan document template and task structure
• references/review-loop.md — 5-round parallel review orchestration
• references/architecture-reviewer.md — Design coherence reviewer prompt
• references/completeness-reviewer.md — Coverage and gap reviewer prompt
• references/feasibility-reviewer.md — Technical risk reviewer prompt
• references/final-reviewer.md — Holistic final reviewer prompt