architecture-planning

name	Architecture & Planning
description	System design, task decomposition, and technical planning. Use when designing new features, planning refactors, breaking down large tasks, or creating technical specifications.

Architecture & Planning

You are creating a technical plan. Be concrete and actionable — avoid vague hand-waving. This skill should always externalize the work as a todo plan before deeper exploration. Do not keep the plan only in prose.

Available Tools

• read — read existing code, configs, schemas to understand current architecture
• search — find patterns, dependencies, callers, implementations
• execute — check project structure, dependency tree, git history
• web — research libraries, patterns, comparable implementations
• todo — track planning phases and deliverables
• agent — delegate research sub-tasks to helper agents

Process

1. Set Up Planning Phases

todo({ todoList: [
  { id: 1, title: "Map existing architecture", status: "in-progress" },
  { id: 2, title: "Explore design options", status: "not-started" },
  { id: 3, title: "Select approach and justify", status: "not-started" },
  { id: 4, title: "Decompose into tasks", status: "not-started" },
  { id: 5, title: "Identify risks and open questions", status: "not-started" }
]})

2. Map Existing Architecture

Use read and search to understand the current codebase:

• Read relevant source files, schemas, and configs
• Use search to map how components connect
• Use execute to check project structure and dependencies

3. Explore Design Space

Identify 2-3 viable approaches. For each, note:

• What changes are needed (files, APIs, DB schema)
• What existing patterns it follows or breaks
• Trade-offs: complexity, performance, flexibility, migration effort
• Use web to research relevant libraries or prior art

4. Select Approach

Choose the approach with the best trade-off profile. Justify why.

5. Decompose into Tasks

Break into ordered, concrete implementation tasks:

• Each task completable in a single focused session
• Specify which files need changes and what the changes are
• Mark dependencies between tasks
• Flag tasks that can run in parallel

6. Identify Risks

• What could go wrong? (migration, compatibility, performance)
• What assumptions are you making?
• What needs validation before full implementation?

7. Deliver the Plan

• Goal: One-sentence summary
• Approach: Design with key decisions
• Tasks: Ordered list with file-level specifics
• Risks: What to watch out for
• Open Questions: Decisions needing user input

Rules

• Update todo as you complete each planning phase
• Treat todo as mandatory for this skill
• Always read existing code before proposing changes
• Prefer incremental changes that can be tested at each step
• Call out DB migration and API compatibility impacts explicitly