plan-architecture

Guides interactive architecture decision sessions producing high-level architecture decision documents.

Updated Aug 28, 2026
One-click install
npx skills add https://github.com/az9713/claude-code-hooks-tutorial --skill plan-architecture-az9713
Or copy as Structured Prompt for Agent▼
Please help me install this Agent Skill.
Skill: plan-architecture
Source: https://github.com/az9713/claude-code-hooks-tutorial/tree/main/skills/.claude/skills/plan-architecture
Command: npx skills add https://github.com/az9713/claude-code-hooks-tutorial --skill plan-architecture-az9713

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve? Turning a PRD, epic, or idea into sound technical direction is hard: teams either jump straight into task lists or over-architect. This Skill runs a structured working session that explores multiple approaches, weighs trade-offs, and records the high-level architecture decisions before any implementation planning begins. ## Core Features & Use Cases - Interactive exploration loop: Investigates the intent, surfaces 2-3 approaches with trade-offs, recommends a direction with reasoning, and waits for the user's call before going deeper. - Greenfield and brownfield modes: Explores the solution space for new builds, or reads the existing codebase first to decide how new work plugs into an existing system. - Architecture decision doc output: Produces a high-level decision document covering approaches considered, stack and libraries, data model, boundaries, missing pieces, spikes, and open questions — as a linked tracker page (Confluence/Jira via Atlassian MCP), a section in the PRD, or a standalone file. - Use Case: Given a Jira epic for a new notifications feature, run the skill to compare event-driven vs polling approaches, pick a stack, flag a spike for delivery reliability, and write the decision doc as a Confluence page linked to the epic. ## Quick Start Run the plan-architecture skill with the path to your PRD or epic, for example asking to explore architecture options for docs/prd-notifications.md and produce a decision document.

Frequently Asked Questions about plan-architecture

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I turn a PRD into a software architecture decision?▼

Pass the PRD path or tracker reference as input, and the skill runs an interactive session exploring 2-3 approaches with trade-offs, recommending stack, data model, and boundaries. The result is a high-level architecture decision doc, not a task-by-task implementation plan.

What is the difference between an architecture decision doc and an implementation plan?▼

An architecture decision doc records eng-lead-level calls: approach, stack, data shape, boundaries, and risks. An implementation plan breaks work into per-ticket steps and file edits, which this skill deliberately defers to a later planning step.

Can I use this with Jira or Confluence epics?▼

Yes. If the intent is a Confluence or Jira reference, the skill fetches it via the Atlassian MCP and can write the architecture doc as a separate page linked both ways to the epic, keeping intent and architecture as distinct sources.

Does architecture planning work differently for existing codebases?▼

Yes. In brownfield mode the skill reads the relevant parts of the existing codebase first, then decides how the new work plugs in, what it reuses, and what it must not break, rather than exploring the open solution space.

When should I use a spike instead of making an architecture decision?▼

Use a spike when a decision is uncertain or expensive to reverse. The skill frames each spike with the question, the smallest test to run within a timebox, and a decision rule mapping signals to outcomes.