Skip to content

EliasOulkadi/shokunin / .pack/skills/plan

Planning agent for task breakdown and implementation planning. Use via spawn_subagent with skill='plan' when you need to explore a codebase and design an implementation approach before writing code.

Entered plan mode. Focus on exploring the codebase and designing an implementation approach without writing code.

In plan mode:

  1. Thoroughly explore the codebase to understand existing patterns
  2. Identify similar features and architectural approaches
  3. Consider multiple approaches and their trade-offs
  4. Design a concrete implementation strategy
  5. Write the plan and return its path

DO NOT write or edit any files yet (except the plan file). This is a read-only exploration and planning phase.

Workflow

Phase 1: Initial Understanding

Goal: Gain comprehensive understanding of the user's request.

Use only research agents — no other agent types.

  1. Understand the user's request and associated code

  2. Launch research agents in parallel (single message, multiple calls):

    • Use skill: 'research' for all exploration agents
    • Use the cheapest model available
    • 1 agent for isolated tasks with known files
    • Multiple agents for uncertain scope, multiple codebase areas, or pattern discovery
    • Max 3 agents — usually 1 is enough
  3. Use multiple agents when:

    • Task touches multiple parts of the codebase
    • Large refactor or architectural change
    • Many edge cases to consider
    • Need to compare different approaches

Phase 2: Design

Goal: Design an implementation approach based on exploration results.

Launch 1-3 design agents in parallel:

  • Default: 1 design agent for most tasks
  • Skip agents: Only for trivial tasks (typo fixes, single-line changes, simple renames)
  • Multiple agents: For complex tasks needing different perspectives

Example perspectives by task type:

  • New feature: simplicity vs performance vs maintainability
  • Bug fix: root cause vs workaround vs prevention
  • Refactoring: minimal change vs clean architecture

For each agent:

  • Provide comprehensive background from Phase 1
  • Describe requirements and constraints
  • Request a detailed implementation plan

Phase 3: Review

Goal: Review plans and ensure alignment with user's intentions.

  1. Read critical files identified by agents
  2. Verify plans align with the original request
  3. Do NOT call subagents here

Phase 4: Final Plan

Goal: Write the final plan. Include:

  • Only the recommended approach, not alternatives
  • Critical file paths to be modified
  • Verification section (how to test end-to-end)
  • Concise enough to scan, detailed enough to execute

Plan Structure Template

## Plan: [Feature Name]

### Summary
[1-2 sentence overview of what will be built/changed]

### Files to Modify
| File | Change |
|------|--------|
| path/to/file.ts | [what changes] |

### Implementation Steps
1. [Step 1]: [what to do, why, any gotchas]
2. [Step 2]: [what to do, why, any gotchas]
3. [Step 3]: [what to do, why, any gotchas]

### Architecture Decisions
| Decision | Choice | Rationale |
|----------|--------|-----------|
| [Decision] | [Choice] | [Why this over alternatives] |

### Risks & Mitigations
| Risk | Probability | Mitigation |
|------|-------------|------------|
| [Risk] | Low/Med/High | [Mitigation] |

### Verification
- [ ] [Test command / manual check]
- [ ] [Edge case to verify]

Common Planning Patterns

PatternWhen to use
SurgicalSmall, isolated change. Read 1-2 files, write plan in 1 message.
ScoutAdding to existing pattern. Find 3+ similar implementations first.
ArchitectNew feature or refactor. Full phases 1-4 with multiple agents.
EmergencyProduction bug. Skip to fix, plan doc optional.

Anti-Patterns

MistakeFix
Over-planning trivial changesSmall typo? Just fix it. Plan adds no value.
Under-planning complex changesNew feature across 10 files? Always go through phases 1-4.
Skipping verificationAlways include how to test the end result.
Too many alternatives in final planChoose one. Use the plan file, not a discussion document.
Designing without reading existing patternsAlways check 3+ similar implementations first.

Error Handling

CauseFix
Research subagent returns incomplete or empty resultsThe subagent may have hit a timeout or the codebase scope was too narrow. Re-launch with explicit file paths and a more focused query. If still empty, read the files directly.
Design subagent proposes a solution that contradicts codebase conventionsSubagent lacks the full context of the codebase style guide. Manually review the plan against 3+ existing implementations. Override the subagent recommendation and document the convention in the plan.
Plan file path conflicts with an existing fileThe skill writes to a plan path that already exists (e.g., PLAN.md was already created). Append a timestamp: PLAN-20260518-143000.md. Ask user if they want to overwrite or keep both.
Phase 1 exploration reveals the task is trivial (single-file, single-line)Full 4-phase planning is wasteful for a typo fix. Abort plan mode. Inform user the change is trivial and ask if they want to skip directly to implementation.
Plan exceeds 200 lines but user asked for conciseThe plan template encourages thoroughness but the user has a scanning constraint. Collapse "Files to Modify" to a 3-column table. Collapse "Implementation Steps" to bullet points without nested details.
User changes requirements mid-planning (Phase 3 or 4)The plan was built against stale requirements. Do not patch the existing plan. Return to Phase 1 with the new requirements. Archive the old plan with a deprecation comment.

Checklist

  • Codebase explored before writing the plan — dependencies, conventions, patterns identified
  • All edge cases and failure modes documented, not just happy path
  • Estimations include testing, documentation, and verification time
  • Dependencies and risks explicitly called out
  • Plan is reviewable independently — enough context for another developer to evaluate

Sources

  • "The Pragmatic Programmer" by David Thomas and Andrew Hunt (Addison-Wesley, 20th Anniversary Edition, 2019) — tracer bullet development and prototyping principles
  • "Software Architecture: The Hard Parts" by Neal Ford, Mark Richards, Pramod Sadalage, Zhamak Dehghani (O'Reilly, 2021) — architectural decision records and trade-off analysis
  • "A Philosophy of Software Design" by John Ousterhout (Yaknyam Press, 2nd Edition, 2021) — deep module design and complexity management
  • Google Design Docs culture (google.github.io/eng-practices/review/design-docs) — structured design document template and review process
  • RFC (Request for Comments) process documentation (github.com/rust-lang/rfcs) — community-driven technical proposal patterns
  • "Domain-Driven Design" by Eric Evans (Addison-Wesley, 2003) — bounded context mapping and ubiquitous language in planning
  • Nygard, Michael T. "Release It! Design and Deploy Production-Ready Software" (Pragmatic Bookshelf, 2nd Edition, 2018) — stability patterns and failure mode planning
brainstormingobra/superpowersYou MUST use this before any creative work - creating features, building components, adding functionality, modifying behavior, or planning anything new, in software or out of it (a talk, a business, a renovation).Stars: 322kUpdated Claude CodeCodexVerifiedInstall
brand-guidelinesanthropics/skillsApplies Anthropic's official brand colors and typography to any sort of artifact that may benefit from having Anthropic's look-and-feel. Use it when brand colors or style guidelines, visual formatting, or company design standards apply.Stars: 198kUpdated Claude CodeCodexVerifiedInstall
frontend-designanthropics/skillsGuidance for distinctive, intentional visual design when building new UI or reshaping an existing one. Helps with aesthetic direction, typography, and making choices that don't read as templated defaults.Stars: 198kUpdated Claude CodeCodexVerifiedInstall
mcp-builderanthropics/skillsGuide for creating high-quality MCP (Model Context Protocol) servers that enable LLMs to interact with external services through well-designed tools. Use when building MCP servers to integrate external APIs or services, whether in Python (FastMCP) or Node/TypeScript (MCP SDK).Stars: 198kUpdated Claude CodeCodexVerifiedInstall