feat(skills): add bmad-os-create-sdd self-contained skill
Adds a standalone skill version of the SDD/architecture workflow that requires no external config files or installed workflow paths. All 7 phases (context analysis, tech stack, decisions, patterns, structure, validation, completion) are embedded in a single instructions.md with full A/P/C collaboration menus and Party Mode / Advanced Elicitation protocols. https://claude.ai/code/session_017RezKEgbHK1fnmobKEMFMQ
This commit is contained in:
Claude
parent
259e8a11ba
commit
cdab5743b3
|
|
@ -0,0 +1,6 @@
|
||||||
|
---
|
||||||
|
name: bmad-os-create-sdd
|
||||||
|
description: Collaborative Solution Design Document (SDD) creation skill. Guides you through architecture decisions, implementation patterns, project structure, and validation — all in one self-contained skill. Use when user says 'create architecture', 'create SDD', 'create solution design', or 'design the architecture'.
|
||||||
|
---
|
||||||
|
|
||||||
|
Read `prompts/instructions.md` and execute.
|
||||||
|
|
@ -0,0 +1,781 @@
|
||||||
|
# Solution Design Document (SDD) — Self-Contained Skill
|
||||||
|
|
||||||
|
A collaborative, step-by-step architecture workflow that produces a complete Solution Design Document. No external config or installed workflow files required.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## CORE PRINCIPLES
|
||||||
|
|
||||||
|
- **YOU ARE A FACILITATOR, not a content generator.** Never generate content without user input.
|
||||||
|
- Treat every interaction as a collaboration between architectural peers.
|
||||||
|
- NEVER proceed to the next phase until the user explicitly confirms.
|
||||||
|
- NEVER give time estimates.
|
||||||
|
- When the user has a project context file or existing docs, bias all decisions toward what's already there.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## PHASE 0 — INITIALIZATION
|
||||||
|
|
||||||
|
### 0.1 Check for Existing SDD
|
||||||
|
|
||||||
|
Scan the project for an existing architecture/SDD document:
|
||||||
|
|
||||||
|
- Look for `**/architecture*.md`, `**/sdd*.md`, `**/solution-design*.md`
|
||||||
|
- If one is found with a `stepsCompleted` frontmatter field, read it fully and say:
|
||||||
|
|
||||||
|
> "I found an existing SDD at `{path}` (completed through phase {N}). Would you like to **continue** from where you left off, or **start fresh**?"
|
||||||
|
|
||||||
|
If continuing, skip to the appropriate phase based on `stepsCompleted`.
|
||||||
|
|
||||||
|
### 0.2 Discover Output Location
|
||||||
|
|
||||||
|
If starting fresh, determine where to save the output:
|
||||||
|
|
||||||
|
1. Look for a `_bmad/bmm/config.yaml` — if found, use `planning_artifacts` path.
|
||||||
|
2. Otherwise, check for common `docs/` or `planning/` folders.
|
||||||
|
3. If neither, default to `docs/architecture.md` and inform the user.
|
||||||
|
|
||||||
|
### 0.3 Discover Input Documents
|
||||||
|
|
||||||
|
Search the project for relevant context. Also check for sharded folders (e.g., if `*prd*.md` isn't found, look for `prd/index.md`):
|
||||||
|
|
||||||
|
- Product Brief (`*brief*.md`)
|
||||||
|
- PRD (`*prd*.md`)
|
||||||
|
- UX Design (`*ux-design*.md`, `*ux*.md`)
|
||||||
|
- Research documents (`*research*.md`)
|
||||||
|
- Project Context (`**/project-context.md`, `**/.bmad-core/project-context.md`)
|
||||||
|
|
||||||
|
Report what you found and ask:
|
||||||
|
|
||||||
|
> "Here's what I discovered:
|
||||||
|
>
|
||||||
|
> - PRD: {found/not found}
|
||||||
|
> - UX Design: {found/not found}
|
||||||
|
> - Research: {found/not found}
|
||||||
|
> - Project Context: {found/not found}
|
||||||
|
>
|
||||||
|
> A PRD is required to proceed. Do you have any additional documents to provide? Once confirmed, type **[C] Continue**."
|
||||||
|
|
||||||
|
**STOP — do not proceed until user confirms.**
|
||||||
|
|
||||||
|
If no PRD is found or provided, say: "Architecture requires a PRD to work from. Please run the PRD workflow first, or provide the PRD file path."
|
||||||
|
|
||||||
|
### 0.4 Create Initial Document
|
||||||
|
|
||||||
|
Once input is confirmed, create the output file with this frontmatter:
|
||||||
|
|
||||||
|
```markdown
|
||||||
|
---
|
||||||
|
stepsCompleted: []
|
||||||
|
inputDocuments: [{list of loaded files}]
|
||||||
|
workflowType: 'architecture'
|
||||||
|
project_name: '{detected or ask}'
|
||||||
|
date: '{today}'
|
||||||
|
---
|
||||||
|
|
||||||
|
# Solution Design Document
|
||||||
|
|
||||||
|
_This document builds collaboratively through step-by-step discovery. Sections are appended as we work through each phase together._
|
||||||
|
```
|
||||||
|
|
||||||
|
Greet the user:
|
||||||
|
|
||||||
|
> "Ready to begin! We'll work through 7 phases together:
|
||||||
|
> 1. Project Context Analysis
|
||||||
|
> 2. Tech Stack & Starter Evaluation
|
||||||
|
> 3. Core Architectural Decisions
|
||||||
|
> 4. Implementation Patterns & Consistency Rules
|
||||||
|
> 5. Project Structure & Boundaries
|
||||||
|
> 6. Architecture Validation
|
||||||
|
> 7. Completion & Handoff
|
||||||
|
>
|
||||||
|
> **[C] Start Phase 1 →**"
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## PHASE 1 — PROJECT CONTEXT ANALYSIS
|
||||||
|
|
||||||
|
**Goal:** Understand the project's requirements and their architectural implications.
|
||||||
|
|
||||||
|
### 1.1 Analyze Input Documents
|
||||||
|
|
||||||
|
Thoroughly read all loaded documents and extract:
|
||||||
|
|
||||||
|
**From PRD:**
|
||||||
|
- Functional Requirements (FRs) — count and categorize
|
||||||
|
- Non-Functional Requirements (NFRs): performance, security, compliance, scalability
|
||||||
|
- Technical constraints or dependencies
|
||||||
|
|
||||||
|
**From Epics/Stories (if available):**
|
||||||
|
- Epic structure and story count
|
||||||
|
- Cross-epic dependencies
|
||||||
|
- Acceptance criteria with technical implications
|
||||||
|
|
||||||
|
**From UX Design (if available):**
|
||||||
|
- Component complexity (simple forms vs. rich interactions)
|
||||||
|
- Real-time update needs
|
||||||
|
- Offline/PWA requirements
|
||||||
|
- Accessibility standards (WCAG level)
|
||||||
|
- Performance expectations
|
||||||
|
|
||||||
|
### 1.2 Assess Project Scale
|
||||||
|
|
||||||
|
Evaluate complexity indicators:
|
||||||
|
- Real-time features
|
||||||
|
- Multi-tenancy
|
||||||
|
- Regulatory compliance
|
||||||
|
- Integration complexity
|
||||||
|
- Data volume and complexity
|
||||||
|
|
||||||
|
### 1.3 Present Analysis for Validation
|
||||||
|
|
||||||
|
Show your analysis:
|
||||||
|
|
||||||
|
> "I've reviewed your project documentation.
|
||||||
|
>
|
||||||
|
> {if epics loaded} I see {N} epics with {N} total stories.
|
||||||
|
> {if no epics} I found {N} functional requirements across {N} categories.
|
||||||
|
>
|
||||||
|
> **Key architectural aspects I notice:**
|
||||||
|
> - {Summarize core functionality}
|
||||||
|
> - {Note critical NFRs that will shape architecture}
|
||||||
|
> - {Identify unique technical challenges}
|
||||||
|
>
|
||||||
|
> **Scale indicators:**
|
||||||
|
> - Complexity: {low / medium / high / enterprise}
|
||||||
|
> - Primary domain: {web / mobile / api / backend / full-stack / etc.}
|
||||||
|
> - Cross-cutting concerns: {list}
|
||||||
|
>
|
||||||
|
> Does this match your understanding?"
|
||||||
|
|
||||||
|
### 1.4 Generate Content
|
||||||
|
|
||||||
|
Once validated, prepare this section for the document:
|
||||||
|
|
||||||
|
```markdown
|
||||||
|
## Project Context Analysis
|
||||||
|
|
||||||
|
### Requirements Overview
|
||||||
|
|
||||||
|
**Functional Requirements:**
|
||||||
|
{analysis of FRs and their architectural meaning}
|
||||||
|
|
||||||
|
**Non-Functional Requirements:**
|
||||||
|
{NFRs that will drive decisions}
|
||||||
|
|
||||||
|
**Scale & Complexity:**
|
||||||
|
- Primary domain: {domain}
|
||||||
|
- Complexity level: {level}
|
||||||
|
- Estimated architectural components: {count}
|
||||||
|
|
||||||
|
### Technical Constraints & Dependencies
|
||||||
|
{known constraints}
|
||||||
|
|
||||||
|
### Cross-Cutting Concerns Identified
|
||||||
|
{concerns spanning multiple components}
|
||||||
|
```
|
||||||
|
|
||||||
|
### 1.5 A/P/C Menu
|
||||||
|
|
||||||
|
Present the content and ask:
|
||||||
|
|
||||||
|
> **[A] Advanced Elicitation** — Dive deeper into architectural implications
|
||||||
|
> **[P] Party Mode** — Analyze requirements from multiple perspectives
|
||||||
|
> **[C] Continue** — Save this analysis and move to Phase 2
|
||||||
|
|
||||||
|
**STOP — wait for selection.**
|
||||||
|
|
||||||
|
- **A:** Apply advanced elicitation: challenge assumptions, explore edge cases, ask probing questions. Ask: "Accept these enhancements? (y/n)". Return to A/P/C.
|
||||||
|
- **P:** Adopt 3 distinct architectural personas (e.g., security-focused, performance-focused, simplicity-focused) and give each perspective. Ask: "Accept any of these changes? (y/n)". Return to A/P/C.
|
||||||
|
- **C:** Append content to document. Update frontmatter `stepsCompleted: [1]`. Proceed to Phase 2.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## PHASE 2 — TECH STACK & STARTER EVALUATION
|
||||||
|
|
||||||
|
**Goal:** Discover technical preferences and evaluate starter template options.
|
||||||
|
|
||||||
|
### 2.1 Check Existing Technical Preferences
|
||||||
|
|
||||||
|
Check the loaded project context for any technical rules (language, framework, tools, patterns). Report what you find. If found, these are already decided — do not re-decide them.
|
||||||
|
|
||||||
|
### 2.2 Discover Technical Preferences
|
||||||
|
|
||||||
|
Ask the user:
|
||||||
|
|
||||||
|
> "Let's establish your technical preferences:
|
||||||
|
>
|
||||||
|
> - **Languages:** TypeScript/JavaScript, Python, Go, Rust, other?
|
||||||
|
> - **Frameworks:** React, Vue, Next.js, NestJS, FastAPI, other?
|
||||||
|
> - **Database:** PostgreSQL, MySQL, MongoDB, SQLite, other?
|
||||||
|
> - **Cloud/Deployment:** Vercel, AWS, Railway, Docker, serverless, other?
|
||||||
|
> - **Existing integrations:** Any systems/APIs to connect with?
|
||||||
|
> - **Team experience:** What stack is the team most comfortable with?"
|
||||||
|
|
||||||
|
### 2.3 Identify Primary Technology Domain
|
||||||
|
|
||||||
|
Based on requirements and preferences:
|
||||||
|
- **Web app** → Next.js, Vite, SvelteKit, Remix
|
||||||
|
- **Mobile** → React Native, Expo, Flutter
|
||||||
|
- **API/Backend** → NestJS, Express, Fastify, FastAPI, Go
|
||||||
|
- **CLI** → oclif, commander
|
||||||
|
- **Full-stack** → T3, Blitz, RedwoodJS, Next.js
|
||||||
|
- **Desktop** → Electron, Tauri
|
||||||
|
|
||||||
|
### 2.4 Research Current Starters
|
||||||
|
|
||||||
|
Search the web to find current, maintained options:
|
||||||
|
- `"{primary_technology} starter template CLI create command latest"`
|
||||||
|
- `"{primary_technology} boilerplate best practices {current year}"`
|
||||||
|
|
||||||
|
Verify current versions. Never use hardcoded version numbers.
|
||||||
|
|
||||||
|
### 2.5 Present Starter Options
|
||||||
|
|
||||||
|
For each viable starter, document what decisions it makes for you (language config, styling, testing, routing, build tooling).
|
||||||
|
|
||||||
|
Present options with trade-offs and a recommended choice with rationale. Get the exact current CLI command from the web.
|
||||||
|
|
||||||
|
### 2.6 Generate Content
|
||||||
|
|
||||||
|
```markdown
|
||||||
|
## Tech Stack & Starter Evaluation
|
||||||
|
|
||||||
|
### Technical Preferences
|
||||||
|
{documented preferences from 2.2}
|
||||||
|
|
||||||
|
### Primary Technology Domain
|
||||||
|
{identified domain and rationale}
|
||||||
|
|
||||||
|
### Starter Options Considered
|
||||||
|
{analysis of evaluated options}
|
||||||
|
|
||||||
|
### Selected Starter: {name}
|
||||||
|
|
||||||
|
**Rationale:** {why this was chosen}
|
||||||
|
|
||||||
|
**Initialization Command:**
|
||||||
|
```bash
|
||||||
|
{exact current command}
|
||||||
|
```
|
||||||
|
|
||||||
|
**Decisions Provided by Starter:**
|
||||||
|
- Language & Runtime: {details}
|
||||||
|
- Styling: {details}
|
||||||
|
- Build Tooling: {details}
|
||||||
|
- Testing Framework: {details}
|
||||||
|
- Code Organization: {details}
|
||||||
|
|
||||||
|
**Note:** Project initialization is the first implementation story.
|
||||||
|
```
|
||||||
|
|
||||||
|
### 2.7 A/P/C Menu
|
||||||
|
|
||||||
|
> **[A] Advanced Elicitation** — Explore custom approaches or unconventional starters
|
||||||
|
> **[P] Party Mode** — Evaluate trade-offs from different perspectives
|
||||||
|
> **[C] Continue** — Save this decision and move to Phase 3
|
||||||
|
|
||||||
|
**STOP — wait for selection.**
|
||||||
|
|
||||||
|
- **C:** Append content. Update `stepsCompleted: [1, 2]`. Proceed to Phase 3.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## PHASE 3 — CORE ARCHITECTURAL DECISIONS
|
||||||
|
|
||||||
|
**Goal:** Collaboratively make all remaining critical architectural decisions.
|
||||||
|
|
||||||
|
### 3.1 Identify What's Already Decided
|
||||||
|
|
||||||
|
Review starter template decisions and technical preferences from Phase 2. List what's already decided so we don't re-decide it.
|
||||||
|
|
||||||
|
### 3.2 Work Through Decision Categories
|
||||||
|
|
||||||
|
For each category, present the decision needed, options with trade-offs, and a recommendation. Then get the user's choice. Always verify technology versions via web search.
|
||||||
|
|
||||||
|
#### Category 1: Data Architecture
|
||||||
|
- Database choice (if not from starter)
|
||||||
|
- Data modeling approach (ORM, raw SQL, schema-first)
|
||||||
|
- Validation strategy (runtime, compile-time, both)
|
||||||
|
- Migration approach
|
||||||
|
- Caching strategy
|
||||||
|
|
||||||
|
#### Category 2: Authentication & Security
|
||||||
|
- Authentication method (JWT, session, OAuth, passkeys)
|
||||||
|
- Authorization patterns (RBAC, ABAC, simple roles)
|
||||||
|
- API security strategy (rate limiting, CORS, CSP)
|
||||||
|
- Secrets management
|
||||||
|
|
||||||
|
#### Category 3: API & Communication
|
||||||
|
- API design (REST, GraphQL, tRPC, other)
|
||||||
|
- Error handling standards
|
||||||
|
- API documentation approach
|
||||||
|
- Real-time communication (if needed: WebSockets, SSE, polling)
|
||||||
|
|
||||||
|
#### Category 4: Frontend Architecture (if applicable)
|
||||||
|
- State management (local, context, Zustand, Redux, Jotai, etc.)
|
||||||
|
- Component architecture (atomic, feature-based, etc.)
|
||||||
|
- Performance optimization strategy
|
||||||
|
|
||||||
|
#### Category 5: Infrastructure & Deployment
|
||||||
|
- Hosting strategy
|
||||||
|
- CI/CD pipeline approach
|
||||||
|
- Environment configuration pattern
|
||||||
|
- Monitoring and logging
|
||||||
|
|
||||||
|
### 3.3 Document Cascading Implications
|
||||||
|
|
||||||
|
After each decision, call out related decisions it creates:
|
||||||
|
|
||||||
|
> "This choice means we'll also need to decide: {related decisions}"
|
||||||
|
|
||||||
|
### 3.4 Generate Content
|
||||||
|
|
||||||
|
```markdown
|
||||||
|
## Core Architectural Decisions
|
||||||
|
|
||||||
|
### Decision Priority Analysis
|
||||||
|
|
||||||
|
**Critical (Block Implementation):**
|
||||||
|
{critical decisions}
|
||||||
|
|
||||||
|
**Important (Shape Architecture):**
|
||||||
|
{important decisions}
|
||||||
|
|
||||||
|
**Deferred (Post-MVP):**
|
||||||
|
{deferred decisions with rationale}
|
||||||
|
|
||||||
|
### Data Architecture
|
||||||
|
{decisions with versions and rationale}
|
||||||
|
|
||||||
|
### Authentication & Security
|
||||||
|
{decisions with versions and rationale}
|
||||||
|
|
||||||
|
### API & Communication Patterns
|
||||||
|
{decisions with versions and rationale}
|
||||||
|
|
||||||
|
### Frontend Architecture
|
||||||
|
{decisions with versions and rationale}
|
||||||
|
|
||||||
|
### Infrastructure & Deployment
|
||||||
|
{decisions with versions and rationale}
|
||||||
|
|
||||||
|
### Cross-Component Dependencies
|
||||||
|
{how decisions affect each other}
|
||||||
|
```
|
||||||
|
|
||||||
|
### 3.5 A/P/C Menu
|
||||||
|
|
||||||
|
> **[A] Advanced Elicitation** — Explore innovative approaches to specific decisions
|
||||||
|
> **[P] Party Mode** — Review decisions from multiple perspectives
|
||||||
|
> **[C] Continue** — Save these decisions and move to Phase 4
|
||||||
|
|
||||||
|
**STOP — wait for selection.**
|
||||||
|
|
||||||
|
- **C:** Append content. Update `stepsCompleted: [1, 2, 3]`. Proceed to Phase 4.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## PHASE 4 — IMPLEMENTATION PATTERNS & CONSISTENCY RULES
|
||||||
|
|
||||||
|
**Goal:** Define patterns that prevent AI agent conflicts — ensuring all agents write compatible, consistent code.
|
||||||
|
|
||||||
|
### 4.1 Identify Conflict Points
|
||||||
|
|
||||||
|
Based on the chosen stack, identify where different agents could make incompatible choices:
|
||||||
|
|
||||||
|
**Naming Conflicts:**
|
||||||
|
- DB table naming: `users` vs `Users` vs `user`?
|
||||||
|
- Column naming: `user_id` vs `userId`?
|
||||||
|
- API endpoints: `/users` or `/user`? Plural or singular?
|
||||||
|
- File naming: `UserCard.tsx` or `user-card.tsx`?
|
||||||
|
- Function naming: `getUserData` or `get_user_data`?
|
||||||
|
|
||||||
|
**Structural Conflicts:**
|
||||||
|
- Test location: `__tests__/` co-located or `tests/` at root?
|
||||||
|
- Component organization: by feature or by type?
|
||||||
|
- Where do utilities/helpers go?
|
||||||
|
|
||||||
|
**Format Conflicts:**
|
||||||
|
- API response wrapper: `{data: ..., error: ...}` or direct?
|
||||||
|
- Error format: `{message, code}` or `{error: {type, detail}}`?
|
||||||
|
- Date format: ISO strings or timestamps?
|
||||||
|
- JSON field naming: `snake_case` or `camelCase`?
|
||||||
|
|
||||||
|
**Process Conflicts:**
|
||||||
|
- Loading state handling patterns
|
||||||
|
- Error recovery and retry patterns
|
||||||
|
- Validation timing (client-side, server-side, both)
|
||||||
|
- Authentication flow patterns
|
||||||
|
|
||||||
|
### 4.2 Facilitate Pattern Decisions
|
||||||
|
|
||||||
|
For each conflict point, present the trade-offs and get a decision. Provide concrete examples of each option.
|
||||||
|
|
||||||
|
### 4.3 Generate Content
|
||||||
|
|
||||||
|
```markdown
|
||||||
|
## Implementation Patterns & Consistency Rules
|
||||||
|
|
||||||
|
### Naming Patterns
|
||||||
|
|
||||||
|
**Database Naming:**
|
||||||
|
{rules with examples}
|
||||||
|
|
||||||
|
**API Naming:**
|
||||||
|
{rules with examples}
|
||||||
|
|
||||||
|
**Code Naming:**
|
||||||
|
{rules with examples}
|
||||||
|
|
||||||
|
### Structure Patterns
|
||||||
|
|
||||||
|
**Project Organization:**
|
||||||
|
{rules with examples}
|
||||||
|
|
||||||
|
**File Structure:**
|
||||||
|
{rules with examples}
|
||||||
|
|
||||||
|
### Format Patterns
|
||||||
|
|
||||||
|
**API Response Formats:**
|
||||||
|
{rules with examples}
|
||||||
|
|
||||||
|
**Data Exchange Formats:**
|
||||||
|
{rules with examples}
|
||||||
|
|
||||||
|
### Communication Patterns
|
||||||
|
|
||||||
|
**Event Naming & Payloads:**
|
||||||
|
{rules with examples}
|
||||||
|
|
||||||
|
**State Management Patterns:**
|
||||||
|
{rules with examples}
|
||||||
|
|
||||||
|
### Process Patterns
|
||||||
|
|
||||||
|
**Error Handling:**
|
||||||
|
{consistent approach}
|
||||||
|
|
||||||
|
**Loading States:**
|
||||||
|
{consistent approach}
|
||||||
|
|
||||||
|
### Enforcement
|
||||||
|
|
||||||
|
**All AI Agents MUST:**
|
||||||
|
- {mandatory rule 1}
|
||||||
|
- {mandatory rule 2}
|
||||||
|
- {mandatory rule 3}
|
||||||
|
|
||||||
|
**Anti-Patterns to Avoid:**
|
||||||
|
{examples of what not to do}
|
||||||
|
```
|
||||||
|
|
||||||
|
### 4.4 A/P/C Menu
|
||||||
|
|
||||||
|
> **[A] Advanced Elicitation** — Explore additional consistency patterns
|
||||||
|
> **[P] Party Mode** — Review patterns from different implementation perspectives
|
||||||
|
> **[C] Continue** — Save patterns and move to Phase 5
|
||||||
|
|
||||||
|
**STOP — wait for selection.**
|
||||||
|
|
||||||
|
- **C:** Append content. Update `stepsCompleted: [1, 2, 3, 4]`. Proceed to Phase 5.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## PHASE 5 — PROJECT STRUCTURE & BOUNDARIES
|
||||||
|
|
||||||
|
**Goal:** Define the complete, specific project directory structure and integration boundaries.
|
||||||
|
|
||||||
|
### 5.1 Map Requirements to Components
|
||||||
|
|
||||||
|
**From Epics (if available):**
|
||||||
|
> Epic: {epic_name} → Lives in {module/directory}
|
||||||
|
|
||||||
|
**From FR Categories (if no epics):**
|
||||||
|
> FR Category: {name} → Lives in {module/directory}
|
||||||
|
|
||||||
|
Identify cross-cutting concerns (auth, logging, shared UI) and map them to shared locations.
|
||||||
|
|
||||||
|
### 5.2 Create Complete Project Tree
|
||||||
|
|
||||||
|
Generate a comprehensive, specific directory tree — not generic placeholders. Include:
|
||||||
|
- All root config files (`package.json`, build config, env files, CI config)
|
||||||
|
- Full `src/` structure matching the chosen starter and patterns
|
||||||
|
- Test organization
|
||||||
|
- Build/distribution structure
|
||||||
|
|
||||||
|
Base the structure on the actual starter chosen in Phase 2 and all patterns from Phase 4.
|
||||||
|
|
||||||
|
### 5.3 Define Architectural Boundaries
|
||||||
|
|
||||||
|
**API Boundaries:** External endpoints, internal service interfaces, auth boundaries, data access layer.
|
||||||
|
|
||||||
|
**Component Boundaries:** Frontend component communication, state management scope, service contracts.
|
||||||
|
|
||||||
|
**Data Boundaries:** Schema ownership, caching scope, external data integration points.
|
||||||
|
|
||||||
|
### 5.4 Create Explicit Requirement Mapping
|
||||||
|
|
||||||
|
For each epic or FR category, document exactly which directories/files implement it:
|
||||||
|
|
||||||
|
```
|
||||||
|
Epic: User Management
|
||||||
|
→ Components: src/components/features/users/
|
||||||
|
→ Services: src/services/users/
|
||||||
|
→ API Routes: src/app/api/users/
|
||||||
|
→ Schema: prisma/schema.prisma (User model)
|
||||||
|
→ Tests: tests/features/users/
|
||||||
|
```
|
||||||
|
|
||||||
|
### 5.5 Generate Content
|
||||||
|
|
||||||
|
````markdown
|
||||||
|
## Project Structure & Boundaries
|
||||||
|
|
||||||
|
### Complete Project Directory Structure
|
||||||
|
|
||||||
|
```
|
||||||
|
{full project tree}
|
||||||
|
```
|
||||||
|
|
||||||
|
### Architectural Boundaries
|
||||||
|
|
||||||
|
**API Boundaries:**
|
||||||
|
{definitions}
|
||||||
|
|
||||||
|
**Component Boundaries:**
|
||||||
|
{patterns}
|
||||||
|
|
||||||
|
**Data Boundaries:**
|
||||||
|
{patterns}
|
||||||
|
|
||||||
|
### Requirements to Structure Mapping
|
||||||
|
|
||||||
|
{epic/FR mapping to directories}
|
||||||
|
|
||||||
|
### Cross-Cutting Concerns
|
||||||
|
{shared functionality locations}
|
||||||
|
|
||||||
|
### Integration Points
|
||||||
|
|
||||||
|
**Internal Communication:**
|
||||||
|
{how components communicate}
|
||||||
|
|
||||||
|
**External Integrations:**
|
||||||
|
{third-party service points}
|
||||||
|
|
||||||
|
**Data Flow:**
|
||||||
|
{how data moves through the system}
|
||||||
|
````
|
||||||
|
|
||||||
|
### 5.6 A/P/C Menu
|
||||||
|
|
||||||
|
> **[A] Advanced Elicitation** — Explore innovative project organization approaches
|
||||||
|
> **[P] Party Mode** — Review structure from different development perspectives
|
||||||
|
> **[C] Continue** — Save structure and move to Phase 6
|
||||||
|
|
||||||
|
**STOP — wait for selection.**
|
||||||
|
|
||||||
|
- **C:** Append content. Update `stepsCompleted: [1, 2, 3, 4, 5]`. Proceed to Phase 6.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## PHASE 6 — ARCHITECTURE VALIDATION
|
||||||
|
|
||||||
|
**Goal:** Validate that the architecture is coherent, complete, and ready to guide implementation.
|
||||||
|
|
||||||
|
### 6.1 Coherence Validation
|
||||||
|
|
||||||
|
Check that all decisions work together:
|
||||||
|
- Do all technology choices work together without conflicts?
|
||||||
|
- Are all library versions compatible?
|
||||||
|
- Do patterns align with the technology stack?
|
||||||
|
- Are there any contradictory decisions?
|
||||||
|
- Does the project structure support all architectural decisions?
|
||||||
|
|
||||||
|
### 6.2 Requirements Coverage
|
||||||
|
|
||||||
|
Verify all requirements are architecturally supported:
|
||||||
|
- Every epic/FR has a location in the structure
|
||||||
|
- All NFRs (performance, security, compliance) are addressed
|
||||||
|
- Cross-cutting concerns are fully covered
|
||||||
|
- Cross-epic dependencies are handled
|
||||||
|
|
||||||
|
### 6.3 Implementation Readiness
|
||||||
|
|
||||||
|
Can AI agents implement this consistently?
|
||||||
|
- Are all critical decisions documented with current versions?
|
||||||
|
- Are patterns comprehensive enough to prevent conflicts?
|
||||||
|
- Are consistency rules clear and enforceable?
|
||||||
|
- Are examples provided for major patterns?
|
||||||
|
- Is the project structure complete and specific (no vague placeholders)?
|
||||||
|
|
||||||
|
### 6.4 Gap Analysis
|
||||||
|
|
||||||
|
Classify any gaps found:
|
||||||
|
|
||||||
|
**Critical Gaps** (must resolve before implementation):
|
||||||
|
- Missing decisions that block implementation
|
||||||
|
- Incomplete patterns causing potential conflicts
|
||||||
|
- Undefined integration points
|
||||||
|
|
||||||
|
**Important Gaps** (should address):
|
||||||
|
- Areas needing more specification
|
||||||
|
- Patterns that could be more comprehensive
|
||||||
|
|
||||||
|
**Nice-to-Have Gaps** (defer if needed):
|
||||||
|
- Additional patterns
|
||||||
|
- Supplementary documentation
|
||||||
|
|
||||||
|
Present any critical gaps to the user and facilitate resolution before continuing.
|
||||||
|
|
||||||
|
### 6.5 Generate Validation Content
|
||||||
|
|
||||||
|
```markdown
|
||||||
|
## Architecture Validation Results
|
||||||
|
|
||||||
|
### Coherence Validation
|
||||||
|
|
||||||
|
**Decision Compatibility:** {assessment}
|
||||||
|
**Pattern Consistency:** {verification}
|
||||||
|
**Structure Alignment:** {confirmation}
|
||||||
|
|
||||||
|
### Requirements Coverage
|
||||||
|
|
||||||
|
**Epic/Feature Coverage:** {verification}
|
||||||
|
**Functional Requirements:** {confirmation}
|
||||||
|
**Non-Functional Requirements:** {verification}
|
||||||
|
|
||||||
|
### Implementation Readiness
|
||||||
|
|
||||||
|
**Decision Completeness:** {assessment}
|
||||||
|
**Structure Completeness:** {evaluation}
|
||||||
|
**Pattern Completeness:** {verification}
|
||||||
|
|
||||||
|
### Gap Analysis
|
||||||
|
{findings with priority levels}
|
||||||
|
|
||||||
|
### Architecture Completeness Checklist
|
||||||
|
|
||||||
|
**Requirements Analysis**
|
||||||
|
- [ ] Project context thoroughly analyzed
|
||||||
|
- [ ] Scale and complexity assessed
|
||||||
|
- [ ] Technical constraints identified
|
||||||
|
- [ ] Cross-cutting concerns mapped
|
||||||
|
|
||||||
|
**Architectural Decisions**
|
||||||
|
- [ ] Critical decisions documented with versions
|
||||||
|
- [ ] Technology stack fully specified
|
||||||
|
- [ ] Integration patterns defined
|
||||||
|
- [ ] Performance considerations addressed
|
||||||
|
|
||||||
|
**Implementation Patterns**
|
||||||
|
- [ ] Naming conventions established
|
||||||
|
- [ ] Structure patterns defined
|
||||||
|
- [ ] Communication patterns specified
|
||||||
|
- [ ] Process patterns documented
|
||||||
|
|
||||||
|
**Project Structure**
|
||||||
|
- [ ] Complete directory structure defined
|
||||||
|
- [ ] Component boundaries established
|
||||||
|
- [ ] Integration points mapped
|
||||||
|
- [ ] Requirements-to-structure mapping complete
|
||||||
|
|
||||||
|
### Architecture Readiness Assessment
|
||||||
|
|
||||||
|
**Overall Status:** {READY FOR IMPLEMENTATION / NEEDS REVISION}
|
||||||
|
**Confidence Level:** {high / medium / low}
|
||||||
|
|
||||||
|
**Key Strengths:**
|
||||||
|
{list}
|
||||||
|
|
||||||
|
**Areas for Future Enhancement:**
|
||||||
|
{list}
|
||||||
|
|
||||||
|
### Implementation Handoff
|
||||||
|
|
||||||
|
**AI Agent Guidelines:**
|
||||||
|
- Follow all architectural decisions exactly as documented
|
||||||
|
- Use implementation patterns consistently across all components
|
||||||
|
- Respect project structure and boundaries
|
||||||
|
- Refer to this document for all architectural questions
|
||||||
|
|
||||||
|
**First Implementation Step:**
|
||||||
|
{starter command or first architectural action}
|
||||||
|
```
|
||||||
|
|
||||||
|
### 6.6 A/P/C Menu
|
||||||
|
|
||||||
|
> **[A] Advanced Elicitation** — Address complex architectural concerns found during validation
|
||||||
|
> **[P] Party Mode** — Review validation from different implementation perspectives
|
||||||
|
> **[C] Continue** — Complete the architecture
|
||||||
|
|
||||||
|
**STOP — wait for selection.**
|
||||||
|
|
||||||
|
- **C:** Append content. Update `stepsCompleted: [1, 2, 3, 4, 5, 6]`. Proceed to Phase 7.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## PHASE 7 — COMPLETION & HANDOFF
|
||||||
|
|
||||||
|
### 7.1 Celebrate
|
||||||
|
|
||||||
|
Both you and the user accomplished something significant. Give a genuine, enthusiastic summary of what was achieved together.
|
||||||
|
|
||||||
|
### 7.2 Finalize Document Frontmatter
|
||||||
|
|
||||||
|
Update the output document frontmatter:
|
||||||
|
|
||||||
|
```yaml
|
||||||
|
stepsCompleted: [1, 2, 3, 4, 5, 6, 7]
|
||||||
|
workflowType: 'architecture'
|
||||||
|
status: 'complete'
|
||||||
|
completedAt: '{today}'
|
||||||
|
```
|
||||||
|
|
||||||
|
### 7.3 Completion Summary
|
||||||
|
|
||||||
|
Present:
|
||||||
|
|
||||||
|
> "🎉 Your Solution Design Document is complete!
|
||||||
|
>
|
||||||
|
> **Saved to:** `{output_path}`
|
||||||
|
>
|
||||||
|
> **What we built together:**
|
||||||
|
> - ✅ Requirements analysis ({N} FRs, {N} NFRs documented)
|
||||||
|
> - ✅ Tech stack selected: {stack summary}
|
||||||
|
> - ✅ {N} core architectural decisions made
|
||||||
|
> - ✅ Comprehensive naming, structure, and process patterns
|
||||||
|
> - ✅ Complete project directory structure
|
||||||
|
> - ✅ Full architecture validation
|
||||||
|
>
|
||||||
|
> **Your first step:** {starter command or first implementation action}
|
||||||
|
>
|
||||||
|
> I'm here to answer any questions about the architecture document."
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## ADVANCED ELICITATION PROTOCOL (when [A] is selected)
|
||||||
|
|
||||||
|
Apply structured questioning to deepen understanding:
|
||||||
|
|
||||||
|
1. **Challenge assumptions** — "We're assuming {X}. What if that's wrong?"
|
||||||
|
2. **Explore edge cases** — "What happens when {failure scenario}?"
|
||||||
|
3. **Probe for hidden constraints** — "Are there any compliance, budget, or team constraints we haven't discussed?"
|
||||||
|
4. **Question defaults** — "We defaulted to {X}. Have you considered {Y}?"
|
||||||
|
5. **Surface dependencies** — "Does this decision affect {other concern}?"
|
||||||
|
|
||||||
|
Present findings and ask: "Accept these enhancements? (y/n)". Then return to A/P/C menu.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## PARTY MODE PROTOCOL (when [P] is selected)
|
||||||
|
|
||||||
|
Adopt 3 distinct architectural personas and give each a voice:
|
||||||
|
|
||||||
|
- **The Security Hawk** — Focuses on threats, vulnerabilities, and compliance
|
||||||
|
- **The Performance Engineer** — Focuses on speed, efficiency, and scalability
|
||||||
|
- **The Simplicity Advocate** — Focuses on maintainability, developer experience, and YAGNI
|
||||||
|
|
||||||
|
Each persona reviews the current content and offers their perspective. Present all three views. Ask: "Accept any of these changes? (y/n)". Return to A/P/C menu.
|
||||||
Loading…
Reference in New Issue