Breakdown Epic Arch
Turn an Epic Product Requirements Document into a high-level technical architecture spec with diagrams and component boundaries before implementation.
Overview
breakdown-epic-arch is an agent skill most often used in Build (also Validate scope) that produces a high-level Epic Architecture Specification from an Epic PRD for a TypeScript Next.js monorepo stack.
Install
npx skills add https://github.com/github/awesome-copilot --skill breakdown-epic-archWhat is this skill?
- Acts as Senior Software Architect: Epic PRD in, Epic Architecture Specification Markdown out
- Output saved to /docs/ways-of-work/plan/{epic-name}/arch.md with overview, Mermaid system diagram, and structured sectio
- Assumes domain-driven design, Dockerized services, TypeScript Next.js App Router, Turborepo, tRPC, and Stack Auth
- Supports both self-hosted and SaaS deployment constraints in the architecture narrative
- Explicitly avoids production code in output except pseudocode for technical illustrations
Adoption & trust: 8.7k installs on skills.sh; 34.6k GitHub stars; 3/3 security scanners passed (skills.sh audits).
What problem does it solve?
You have an Epic PRD but no shared technical picture of components, deployment shape, and enablers before developers or coding agents start building.
Who is it for?
Solo builders or tech leads on Turborepo plus Next.js plus tRPC products who receive Epic PRDs and need architect-grade specs without writing code yet.
Skip if: One-off scripts, non-epic bugfixes, or teams that already have a signed system design and only need line-level coding tasks.
When should I use this skill?
You have an Epic PRD and need a high-level technical architecture specification for modular TypeScript Next.js development.
What do I get? / Deliverables
You get arch.md with overview, Mermaid system architecture, and epic-scoped technical guidance ready to drive breakdown into stories and implementation plans.
- Epic Architecture Specification Markdown (arch.md)
- Mermaid system architecture diagram
- Component and technical enabler outline for the epic
Recommended Skills
Journey fit
Spans multiple journey phases - primary shelf plus alternate fits below.
Architecture from an Epic PRD is the bridge between validated product intent and concrete build work in a monorepo SaaS stack. PM and planning subphase is where epics get technical direction, enablers, and system diagrams without jumping straight to code.
Where it fits
Size whether an epic fits self-hosted and SaaS deployment before committing sprint capacity.
Produce arch.md with user layer and service boundaries from the product manager’s Epic PRD.
Compare implemented services against the epic architecture diagram during a cross-team design review.
How it compares
Use instead of ad-hoc chat architecture when you need a filed epic spec under docs/ways-of-work/plan, not a disposable thread summary.
Common Questions / FAQ
Who is breakdown-epic-arch for?
It is for solo founders and small teams acting as architect after product hands off an Epic PRD for a Dockerized TypeScript SaaS or self-hosted product.
When should I use breakdown-epic-arch?
Use it in Validate when scoping a large epic into technical boundaries, and in Build PM when you need arch.md before splitting work across services, tRPC routers, and auth flows.
Is breakdown-epic-arch safe to install?
It is a planning prompt that may reference paths and stack choices; review the Security Audits panel on this Prism page before adding the parent awesome-copilot bundle.
SKILL.md
READMESKILL.md - Breakdown Epic Arch
# Epic Architecture Specification Prompt ## Goal Act as a Senior Software Architect. Your task is to take an Epic PRD and create a high-level technical architecture specification. This document will guide the development of the epic, outlining the major components, features, and technical enablers required. ## Context Considerations - The Epic PRD from the Product Manager. - **Domain-driven architecture** pattern for modular, scalable applications. - **Self-hosted and SaaS deployment** requirements. - **Docker containerization** for all services. - **TypeScript/Next.js** stack with App Router. - **Turborepo monorepo** patterns. - **tRPC** for type-safe APIs. - **Stack Auth** for authentication. **Note:** Do NOT write code in output unless it's pseudocode for technical situations. ## Output Format The output should be a complete Epic Architecture Specification in Markdown format, saved to `/docs/ways-of-work/plan/{epic-name}/arch.md`. ### Specification Structure #### 1. Epic Architecture Overview - A brief summary of the technical approach for the epic. #### 2. System Architecture Diagram Create a comprehensive Mermaid diagram that illustrates the complete system architecture for this epic. The diagram should include: - **User Layer**: Show how different user types (web browsers, mobile apps, admin interfaces) interact with the system - **Application Layer**: Depict load balancers, application instances, and authentication services (Stack Auth) - **Service Layer**: Include tRPC APIs, background services, workflow engines (n8n), and any epic-specific services - **Data Layer**: Show databases (PostgreSQL), vector databases (Qdrant), caching layers (Redis), and external API integrations - **Infrastructure Layer**: Represent Docker containerization and deployment architecture Use clear subgraphs to organize these layers, apply consistent color coding for different component types, and show the data flow between components. Include both synchronous request paths and asynchronous processing flows where relevant to the epic. #### 3. High-Level Features & Technical Enablers - A list of the high-level features to be built. - A list of technical enablers (e.g., new services, libraries, infrastructure) required to support the features. #### 4. Technology Stack - A list of the key technologies, frameworks, and libraries to be used. #### 5. Technical Value - Estimate the technical value (e.g., High, Medium, Low) with a brief justification. #### 6. T-Shirt Size Estimate - Provide a high-level t-shirt size estimate for the epic (e.g., S, M, L, XL). ## Context Template - **Epic PRD:** [The content of the Epic PRD markdown file]