myaidev-method 0.2.1 → 0.2.3

package/DEV_WORKFLOW_GUIDE.md

@@ -0,0 +1,1353 @@
+# Development Workflow Guide - SPARC Methodology
+
+> **Systematic Software Development with the MyAIDev Method**
+
+This guide provides comprehensive documentation for using the MyAIDev Method's **SPARC development framework** - a 5-phase systematic approach to AI-assisted software development inspired by [GitHub Spec-Kit](https://github.com/github/spec-kit).
+
+## Table of Contents
+
+- [Overview](#overview)
+- [SPARC Methodology](#sparc-methodology)
+- [Phase 1: Architecture](#phase-1-architecture)
+- [Phase 2: Implementation](#phase-2-implementation)
+- [Phase 3: Testing](#phase-3-testing)
+- [Phase 4: Review](#phase-4-review)
+- [Phase 5: Documentation](#phase-5-documentation)
+- [Complete Workflow](#complete-workflow)
+- [CLI Commands](#cli-commands)
+- [Quality Standards](#quality-standards)
+- [Best Practices](#best-practices)
+- [Examples](#examples)
+- [Troubleshooting](#troubleshooting)
+
+## Overview
+
+The **MyAIDev Method** provides a comprehensive development framework featuring specialized AI agents for every phase of software development. The **SPARC methodology** ensures systematic, high-quality software delivery through:
+
+- **Structured Phases**: Clear progression from design to documentation
+- **Quality Gates**: Validation at each phase transition
+- **Specialized Agents**: Dedicated expertise for each development aspect
+- **File-Based Coordination**: Well-defined outputs guide the next phase
+- **Reproducible Workflows**: Consistent results across projects
+
+### Why SPARC?
+
+**SPARC** (Specification, Pseudocode, Architecture, Refinement, Completion) provides:
+
+✅ **Quality Assurance**: Built-in testing, review, and security standards
+✅ **Complete Coverage**: From design to deployment documentation
+✅ **Best Practices**: SOLID principles, Clean Code, OWASP security
+✅ **Traceability**: Full workflow history and decision tracking
+✅ **Efficiency**: Systematic approach reduces rework and errors
+
+## SPARC Methodology
+
+### The 5 Phases
+
+```
+┌────────────────────────────────────────────────────────┐
+│  SPARC: Systematic Software Development                 │
+└────────────────────────────────────────────────────────┘
+
+1. 🏗️  ARCHITECTURE (Specification + Architecture)
+   └─ Design system structure, APIs, data models
+
+2. 💻 IMPLEMENTATION (Pseudocode → Code)
+   └─ Write production-ready code with SOLID principles
+
+3. 🧪 TESTING (Architecture Validation)
+   └─ Create comprehensive test suites with 80%+ coverage
+
+4. 👁️  REVIEW (Refinement)
+   └─ Analyze code quality, security, performance
+
+5. 📚 DOCUMENTATION (Completion)
+   └─ Generate API docs, user guides, architecture specs
+```
+
+### Phase Dependencies
+
+Each phase builds upon the previous:
+
+```
+Architecture.md → Implementation → Tests → Review Report → Documentation
+     ↓               ↓              ↓          ↓               ↓
+  [Phase 1]      [Phase 2]      [Phase 3]  [Phase 4]     [Phase 5]
+```
+
+## Phase 1: Architecture
+
+### Purpose
+Design scalable system architecture, define API contracts, model data flows, and select appropriate technologies.
+
+### Agent
+**dev-architect** - System architecture and design specialist
+
+### Command
+```bash
+# Slash command (Claude Code)
+/myai-dev-architect "Design authentication system with JWT"
+
+# CLI command (npm)
+npm run dev:architect "Design real-time chat application"
+
+# With technology preferences
+npm run dev:architect "Design microservices" --tech-stack "node,kubernetes,postgres,redis"
+```
+
+### Deliverables
+
+**Output File**: `.myaidev-method/sparc/architecture.md`
+
+**Contains**:
+- System overview and requirements
+- High-level architecture with Mermaid diagrams
+- Component specifications and responsibilities
+- API contracts and endpoints (REST/GraphQL/gRPC)
+- Data models and schemas (SQL/NoSQL)
+- Technology stack recommendations
+- Security architecture and patterns
+- Scalability and performance planning
+- Deployment architecture
+
+### Example Output
+
+```markdown
+# System Architecture: Authentication System
+
+## 1. Overview
+Purpose: Secure user authentication with JWT tokens and refresh capabilities
+Target Scale: 10,000 concurrent users
+
+## 2. Architecture Design
+
+```mermaid
+graph TB
+    Client[Client Apps]
+    LB[Load Balancer]
+    API[API Servers]
+    Auth[Auth Service]
+    DB[(PostgreSQL)]
+    Cache[(Redis Cache)]
+
+    Client-->LB
+    LB-->API
+    API-->Auth
+    API-->DB
+    API-->Cache
+```
+
+## 3. API Specifications
+
+### POST /api/auth/login
+Request:
+```json
+{
+  "email": "user@example.com",
+  "password": "secure_password"
+}
+```
+
+Response (200 OK):
+```json
+{
+  "user": { "id": "uuid", "email": "user@example.com" },
+  "token": "eyJhbGc...",
+  "refreshToken": "eyJhbGc..."
+}
+```
+
+## 4. Data Models
+
+```sql
+CREATE TABLE users (
+  id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+  email VARCHAR(255) UNIQUE NOT NULL,
+  password_hash VARCHAR(255) NOT NULL,
+  created_at TIMESTAMP DEFAULT NOW()
+);
+```
+
+## 5. Security Considerations
+- JWT tokens with 15-minute expiration
+- bcrypt password hashing (10+ rounds)
+- HTTPS/TLS 1.3 for all communications
+- Rate limiting (100 requests/minute per IP)
+```
+
+### Options
+
+- `--tech-stack <stack>` - Preferred technology stack (comma-separated)
+- `--existing-code` - Analyze existing codebase before designing
+- `--output-dir <path>` - Custom output directory
+
+### Best Practices
+
+✅ Start with clear requirements and constraints
+✅ Use Mermaid diagrams for visual clarity
+✅ Document all architectural decisions with rationale
+✅ Consider security, performance, scalability from the start
+✅ Keep designs modular and extensible
+
+## Phase 2: Implementation
+
+### Purpose
+Implement features based on architecture specifications using SOLID principles, Clean Code practices, and security best practices.
+
+### Agent
+**dev-coder** - Production code implementation specialist
+
+### Command
+```bash
+# Slash command
+/myai-dev-code "Implement JWT authentication with refresh tokens"
+
+# CLI command
+npm run dev:code "Implement user registration"
+
+# Test-Driven Development mode
+npm run dev:code "Implement payment processing" --test-driven
+
+# Custom architecture file
+npm run dev:code "Implement auth" --architecture custom-arch.md
+```
+
+### Deliverables
+
+**Output Directory**: `.myaidev-method/sparc/code-output/`
+
+**Contains**:
+- Feature implementation code
+- Utility functions and helpers
+- Configuration files
+- Basic unit tests
+- Implementation notes
+
+### Quality Standards
+
+**Code Quality**:
+- SOLID principles (Single Responsibility, Open/Closed, etc.)
+- Clean Code: DRY, KISS, YAGNI ( "You Aren't Gonna Need It," is a software development principle that advises against building features or adding complexity until they are actually needed. By focusing on current requirements, teams can deliver value faster, reduce unnecessary work, avoid over-engineering, and create simpler, more maintainable code. The principle encourages developers to postpone implementing features or technical solutions until there is a clear and present need for them)
+- Modular and maintainable structure
+- Clear naming and organization
+
+**Security**:
+- Input validation on all user inputs
+- Error handling without exposing internals
+- No secrets in code (use environment variables)
+- OWASP Top 10 compliance
+
+**Documentation**:
+- Inline comments for complex logic
+- JSDoc/Sphinx documentation for public APIs
+- Clear function and variable names
+
+**Testing**:
+- 80%+ test coverage target
+- Testable code architecture
+- Dependency injection for flexibility
+
+### Example Output Structure
+
+```
+.myaidev-method/sparc/code-output/
+├── src/
+│   ├── auth/
+│   │   ├── authService.js       # Core authentication logic
+│   │   ├── tokenManager.js      # JWT token generation/validation
+│   │   └── passwordHash.js      # Password hashing utilities
+│   ├── middleware/
+│   │   └── authMiddleware.js    # Express authentication middleware
+│   └── models/
+│       └── User.js              # User data model
+├── tests/
+│   └── auth.test.js             # Basic unit tests
+└── README.md                    # Implementation notes
+```
+
+### Options
+
+- `--architecture <file>` - Path to architecture spec (default: `.myaidev-method/sparc/architecture.md`)
+- `--test-driven` - Use TDD approach (write tests first)
+- `--output-dir <path>` - Custom output directory
+
+### Best Practices
+
+✅ Follow architecture specifications closely
+✅ Write modular, testable code
+✅ Include comprehensive error handling
+✅ Add inline documentation for complex logic
+✅ Avoid hardcoding values, use configuration
+✅ Keep functions small and focused (Single Responsibility)
+
+## Phase 3: Testing
+
+### Purpose
+Create comprehensive test suites with unit tests, integration tests, and coverage analysis to ensure code quality and functionality.
+
+### Agent
+**dev-tester** - Testing and quality assurance specialist
+
+### Command
+```bash
+# Slash command
+/myai-dev-test "Test authentication module"
+
+# CLI command
+npm run dev:test "Test user registration"
+
+# With coverage report
+npm run dev:test "Test auth" --coverage
+
+# Integration tests focus
+npm run dev:test "Test checkout flow" --integration
+
+# Specify test framework
+npm run dev:test "Test API endpoints" --framework jest
+```
+
+### Deliverables
+
+**Output Directory**: `.myaidev-method/sparc/test-results/`
+
+**Contains**:
+- Unit test files
+- Integration test files
+- Test report with metrics
+- Coverage report
+- Quality gates validation
+- Recommendations for improvement
+
+### Coverage Standards
+
+**Critical Paths**: 80%+ coverage
+**Overall Project**: 60%+ coverage
+**Quality Gates**:
+- Pre-commit: Unit tests must pass
+- Pre-merge: Integration tests + 60% coverage
+- Pre-deployment: All tests + 80% critical path coverage
+
+### Test Patterns
+
+**AAA Pattern** (Arrange, Act, Assert):
+```javascript
+describe('Authentication Service', () => {
+  test('should generate valid JWT token', () => {
+    // Arrange
+    const user = { id: '123', email: 'test@example.com' };
+
+    // Act
+    const token = authService.generateToken(user);
+
+    // Assert
+    expect(token).toBeDefined();
+    expect(authService.verifyToken(token)).toEqual(user);
+  });
+});
+```
+
+### Options
+
+- `--coverage` - Generate coverage report
+- `--integration` - Focus on integration tests
+- `--framework <name>` - Testing framework (jest, mocha, pytest, etc.)
+- `--output-dir <path>` - Custom output directory
+
+### Best Practices
+
+✅ Write tests for all public APIs
+✅ Test edge cases and error scenarios
+✅ Keep tests independent and isolated
+✅ Use descriptive test names
+✅ Fast execution (<5s for unit tests)
+✅ Mock external dependencies
+
+## Phase 4: Review
+
+### Purpose
+Analyze code quality, security vulnerabilities, performance issues, and best practices compliance with actionable recommendations.
+
+### Agent
+**dev-reviewer** - Code quality and security analysis specialist
+
+### Command
+```bash
+# Slash command
+/myai-dev-review "Review authentication implementation"
+
+# CLI command
+npm run dev:review "Review user service"
+
+# Security-focused review
+npm run dev:review "Security audit for payment module" --security
+
+# Performance-focused review
+npm run dev:review "Review database queries" --performance
+```
+
+### Deliverables
+
+**Output File**: `.myaidev-method/sparc/review-report.md`
+
+**Contains**:
+- Executive summary with quality scores
+- Critical/High/Medium/Low priority issues
+- Security analysis (OWASP Top 10 compliance)
+- Performance metrics and bottlenecks
+- Code quality assessment
+- Technical debt evaluation
+- Testing recommendations
+- Actionable improvement plan
+
+### Review Standards
+
+**Code Quality**:
+- Complexity metrics (cyclomatic complexity, cognitive load)
+- Readability and maintainability scores
+- Code smells and anti-patterns
+- Naming conventions and organization
+
+**Security**:
+- OWASP Top 10 vulnerability scanning
+- Input validation coverage
+- Authentication/authorization checks
+- Secrets management
+- Error handling security
+
+**Performance**:
+- Algorithm complexity analysis (Big O notation)
+- Resource management (memory, connections)
+- N+1 query detection
+- Caching opportunities
+- Database optimization
+
+**Best Practices**:
+- SOLID principles adherence
+- Framework-specific standards
+- Design pattern usage
+- Documentation quality
+
+### Example Report Structure
+
+```markdown
+# Code Review Report: Authentication Module
+
+## Executive Summary
+**Overall Quality**: 8.5/10
+**Security Score**: 9/10
+**Performance**: 7.5/10
+
+## Critical Issues (Address Immediately)
+None
+
+## High Priority Issues
+1. **Performance**: N+1 query in user lookup (auth.js:45)
+   - **Impact**: Database performance degradation under load
+   - **Recommendation**: Use JOIN or batch query
+   - **Effort**: 1 hour
+
+## Medium Priority Issues
+2. **Code Quality**: High cyclomatic complexity in validateUser() (auth.js:78)
+   - **Impact**: Reduced maintainability
+   - **Recommendation**: Extract validation logic to separate functions
+   - **Effort**: 2 hours
+
+## Security Analysis (OWASP Top 10)
+✅ A01: Broken Access Control - Properly implemented
+✅ A02: Cryptographic Failures - bcrypt with 10 rounds
+⚠️ A03: Injection - Input validation present but could be strengthened
+```
+
+### Options
+
+- `--security` - Focus on security analysis (OWASP Top 10)
+- `--performance` - Focus on performance optimization
+- `--output-dir <path>` - Custom output directory
+
+### Best Practices
+
+✅ Review all code, not just changes
+✅ Prioritize issues by severity and impact
+✅ Provide actionable recommendations
+✅ Include code examples for fixes
+✅ Consider long-term maintainability
+
+## Phase 5: Documentation
+
+### Purpose
+Generate comprehensive API documentation, user guides, architecture docs, and code examples for maintainability and knowledge transfer.
+
+### Agent
+**dev-documenter** - Technical documentation specialist
+
+### Command
+```bash
+# Slash command
+/myai-dev-docs "Document authentication API"
+
+# CLI command
+npm run dev:docs "Document user service API"
+
+# User guide documentation
+npm run dev:docs "Create user guide for checkout" --type user-guide
+
+# Architecture documentation
+npm run dev:docs "Document system architecture" --type architecture
+
+# OpenAPI specification
+npm run dev:docs "Generate OpenAPI spec for API" --format openapi
+```
+
+### Deliverables
+
+**Output Directory**: `.myaidev-method/sparc/documentation/`
+
+**Contains**:
+- API reference documentation
+- User guides and tutorials
+- Architecture documentation
+- Code examples and snippets
+- Mermaid diagrams
+- OpenAPI/Swagger specs (if applicable)
+
+### Documentation Standards
+
+**Clarity**:
+- Simple language, clear examples
+- Visual aids (diagrams, screenshots)
+- Progressive difficulty (beginner to advanced)
+
+**Completeness**:
+- All public APIs documented
+- Edge cases and error scenarios covered
+- Authentication and authorization requirements
+- Rate limiting and quotas
+
+**Accuracy**:
+- Code examples tested and verified
+- Documentation synchronized with code
+- Version-specific information
+
+**Accessibility**:
+- Multiple formats (Markdown, HTML, PDF)
+- Searchable content
+- Well-organized structure
+- Table of contents and navigation
+
+### Example Documentation Structure
+
+```
+.myaidev-method/sparc/documentation/
+├── api/
+│   ├── authentication.md
+│   ├── users.md
+│   └── openapi.yaml
+├── user-guide/
+│   ├── getting-started.md
+│   ├── authentication-guide.md
+│   └── troubleshooting.md
+└── architecture/
+    ├── system-overview.md
+    ├── data-models.md
+    └── deployment.md
+```
+
+### Options
+
+- `--type <type>` - Documentation type: api, user-guide, architecture, technical
+- `--format <format>` - Output format: markdown, html, openapi, swagger
+- `--output-dir <path>` - Custom output directory
+
+### Best Practices
+
+✅ Write for your target audience
+✅ Include practical code examples
+✅ Keep documentation synchronized with code
+✅ Use diagrams for complex concepts
+✅ Provide troubleshooting sections
+✅ Version your documentation
+
+## Complete Workflow
+
+### Running All 5 Phases
+
+Execute the complete SPARC workflow with a single command:
+
+```bash
+# CLI command
+npm run sparc "Build user authentication system with JWT and refresh tokens"
+
+# Slash command
+/myai-sparc-workflow "Create payment processing module"
+
+# With technology preferences
+npm run sparc "Build e-commerce checkout" --tech-stack "react,node,stripe,postgres"
+
+# Run specific phases only
+npm run sparc "Refactor auth module" --phases "architecture,review,documentation"
+```
+
+### Workflow Execution
+
+```
+┌────────────────────────────────────────────────────────┐
+│  SPARC Workflow Execution                               │
+└────────────────────────────────────────────────────────┘
+
+🏗️  Phase 1: Architecture
+├─ Reading requirements...
+├─ Designing system architecture...
+├─ Creating Mermaid diagrams...
+└─ ✅ Output: .myaidev-method/sparc/architecture.md
+
+💻 Phase 2: Implementation
+├─ Reading architecture spec...
+├─ Implementing features...
+├─ Writing tests...
+└─ ✅ Output: .myaidev-method/sparc/code-output/
+
+🧪 Phase 3: Testing
+├─ Analyzing code...
+├─ Creating test suites...
+├─ Generating coverage report...
+└─ ✅ Output: .myaidev-method/sparc/test-results/
+
+👁️  Phase 4: Review
+├─ Code quality analysis...
+├─ Security audit (OWASP Top 10)...
+├─ Performance review...
+└─ ✅ Output: .myaidev-method/sparc/review-report.md
+
+📚 Phase 5: Documentation
+├─ Generating API docs...
+├─ Creating user guides...
+├─ Documenting architecture...
+└─ ✅ Output: .myaidev-method/sparc/documentation/
+
+🎉 SPARC Workflow Complete!
+```
+
+### Output Structure
+
+```
+.myaidev-method/
+├── sparc/
+│   ├── architecture.md              # Phase 1: Architecture
+│   ├── code-output/                 # Phase 2: Implementation
+│   ├── test-results/                # Phase 3: Testing
+│   ├── review-report.md             # Phase 4: Review
+│   └── documentation/               # Phase 5: Documentation
+├── tasks/
+│   └── workflow_20250120_123456.json
+└── workflows/
+    └── sparc_20250120_123456.json
+```
+
+## CLI Commands
+
+### Individual Phase Commands
+
+```bash
+# Phase 1: Architecture
+npm run dev:architect "Design real-time chat app"
+npm run dev:architect "Design microservices" --tech-stack "node,kubernetes,mongodb"
+
+# Phase 2: Implementation
+npm run dev:code "Implement chat service"
+npm run dev:code "Implement auth" --test-driven
+
+# Phase 3: Testing
+npm run dev:test "Test chat functionality" --integration --coverage
+npm run dev:test "Test API endpoints" --framework jest
+
+# Phase 4: Review
+npm run dev:review "Review chat implementation" --security
+npm run dev:review "Review database layer" --performance
+
+# Phase 5: Documentation
+npm run dev:docs "Document chat API"
+npm run dev:docs "Create deployment guide" --type architecture
+```
+
+### Complete Workflow Command
+
+```bash
+# Run all 5 phases
+npm run sparc "Build feature X"
+
+# Run specific phases
+npm run sparc "Improve feature Y" --phases "architecture,review,documentation"
+
+# Skip specific phase (use with caution)
+npm run sparc "Build feature Z" --skip-phase testing
+```
+
+## Quality Standards
+
+### Code Quality
+
+**SOLID Principles**:
+- **S**ingle Responsibility: Each class/function has one reason to change
+- **O**pen/Closed: Open for extension, closed for modification
+- **L**iskov Substitution: Derived classes substitutable for base classes
+- **I**nterface Segregation: Don't depend on unused interfaces
+- **D**ependency Inversion: Depend on abstractions, not concretions
+
+**Clean Code**:
+- **DRY** (Don't Repeat Yourself): Abstract common functionality
+- **KISS** (Keep It Simple, Stupid): Prefer simplicity over complexity
+- **YAGNI** (You Aren't Gonna Need It): Implement current requirements only
+
+### Security Standards
+
+**OWASP Top 10 Compliance**:
+1. Broken Access Control
+2. Cryptographic Failures
+3. Injection
+4. Insecure Design
+5. Security Misconfiguration
+6. Vulnerable Components
+7. Authentication Failures
+8. Software and Data Integrity Failures
+9. Security Logging Failures
+10. Server-Side Request Forgery
+
+### Testing Standards
+
+**Coverage Requirements**:
+- Critical paths: 80%+ coverage
+- Overall project: 60%+ coverage
+- Public APIs: 100% coverage
+
+**Test Types**:
+- Unit tests: Individual functions/methods
+- Integration tests: Component interactions
+- E2E tests: Complete user workflows
+
+### Performance Standards
+
+**Response Times**:
+- API endpoints: <200ms (p95)
+- Database queries: <50ms (p95)
+- Page load: <2s (p95)
+
+**Scalability**:
+- Horizontal scaling capability
+- Stateless design
+- Efficient resource usage
+
+## Best Practices
+
+### Architecture Phase
+
+✅ Start with clear requirements
+✅ Consider scalability from the start
+✅ Document all design decisions
+✅ Use visual diagrams (Mermaid)
+✅ Plan for security and performance
+
+### Implementation Phase
+
+✅ Follow architecture specifications
+✅ Write testable code
+✅ Use meaningful names
+✅ Handle errors gracefully
+✅ Document complex logic
+
+### Testing Phase
+
+✅ Write tests for all public APIs
+✅ Test edge cases and errors
+✅ Keep tests independent
+✅ Use descriptive test names
+✅ Aim for >80% critical path coverage
+
+### Review Phase
+
+✅ Review all code systematically
+✅ Prioritize issues by impact
+✅ Provide actionable recommendations
+✅ Check OWASP Top 10
+✅ Analyze performance bottlenecks
+
+### Documentation Phase
+
+✅ Write for your audience
+✅ Include code examples
+✅ Keep docs synchronized
+✅ Use diagrams for clarity
+✅ Provide troubleshooting
+
+## Examples
+
+### Example 1: Building a Next.js Blog with PayloadCMS Backend
+
+This comprehensive example demonstrates building a complete blog system using Next.js for the frontend and PayloadCMS as the headless CMS backend, then using MyAIDev Method's publishing workflow to create and publish content.
+
+#### Project Overview
+
+**Goal**: Build a modern blog platform with:
+- Next.js 14 frontend with App Router
+- PayloadCMS 2.x headless CMS backend
+- Content publishing workflow
+- SEO optimization
+- Responsive design
+
+#### Complete SPARC Workflow
+
+```bash
+# Execute complete SPARC workflow for the entire blog system
+npm run sparc "Build Next.js blog with PayloadCMS backend, including posts collection, user authentication, and content API" --tech-stack "nextjs,payloadcms,mongodb,typescript"
+```
+
+#### Phase-by-Phase Implementation
+
+**Phase 1: Architecture**
+```bash
+npm run dev:architect "Design Next.js blog with PayloadCMS backend" --tech-stack "nextjs,payloadcms,mongodb,typescript"
+```
+
+**Expected Output** (.myaidev-method/sparc/architecture.md):
+
+```markdown
+# System Architecture: Next.js Blog with PayloadCMS
+
+## 1. Overview
+- Frontend: Next.js 14 with App Router, React Server Components
+- Backend: PayloadCMS 2.x (headless CMS)
+- Database: MongoDB
+- Deployment: Vercel (frontend), self-hosted (PayloadCMS)
+
+## 2. Architecture Design
+
+```mermaid
+graph TB
+    Browser[Browser Client]
+    NextJS[Next.js Frontend]
+    PayloadAPI[PayloadCMS API]
+    MongoDB[(MongoDB)]
+    CDN[Vercel CDN]
+
+    Browser-->NextJS
+    NextJS-->PayloadAPI
+    PayloadAPI-->MongoDB
+    NextJS-->CDN
+```
+
+## 3. Collections (PayloadCMS)
+
+### Posts Collection
+```typescript
+{
+  slug: 'posts',
+  fields: [
+    { name: 'title', type: 'text', required: true },
+    { name: 'content', type: 'richText', required: true },
+    { name: 'excerpt', type: 'textarea' },
+    { name: 'coverImage', type: 'upload', relationTo: 'media' },
+    { name: 'author', type: 'relationship', relationTo: 'users' },
+    { name: 'publishedDate', type: 'date' },
+    { name: 'status', type: 'select', options: ['draft', 'published'] }
+  ]
+}
+```
+
+### Authors Collection
+```typescript
+{
+  slug: 'authors',
+  fields: [
+    { name: 'name', type: 'text', required: true },
+    { name: 'bio', type: 'textarea' },
+    { name: 'avatar', type: 'upload', relationTo: 'media' }
+  ]
+}
+```
+
+## 4. API Endpoints
+
+### PayloadCMS REST API
+- GET /api/posts - List all posts
+- GET /api/posts/:id - Get single post
+- POST /api/posts - Create post (authenticated)
+- PATCH /api/posts/:id - Update post (authenticated)
+
+### Next.js Routes
+- / - Homepage (list of posts)
+- /posts/[slug] - Individual post page
+- /author/[slug] - Author page
+```
+
+**Phase 2: Implementation**
+```bash
+npm run dev:code "Implement Next.js frontend and PayloadCMS backend"
+```
+
+**Expected Output** (.myaidev-method/sparc/code-output/):
+
+```
+code-output/
+├── payloadcms/
+│   ├── src/
+│   │   ├── collections/
+│   │   │   ├── Posts.ts
+│   │   │   ├── Authors.ts
+│   │   │   └── Media.ts
+│   │   ├── payload.config.ts
+│   │   └── server.ts
+│   └── package.json
+├── nextjs-blog/
+│   ├── app/
+│   │   ├── page.tsx              # Homepage
+│   │   ├── posts/
+│   │   │   └── [slug]/page.tsx   # Post detail page
+│   │   └── layout.tsx
+│   ├── components/
+│   │   ├── PostCard.tsx
+│   │   ├── PostContent.tsx
+│   │   └── AuthorBio.tsx
+│   ├── lib/
+│   │   └── payload.ts            # PayloadCMS API client
+│   └── package.json
+└── README.md
+```
+
+**Key Implementation Files**:
+
+`payloadcms/src/collections/Posts.ts`:
+```typescript
+import { CollectionConfig } from 'payload/types';
+
+export const Posts: CollectionConfig = {
+  slug: 'posts',
+  admin: {
+    useAsTitle: 'title',
+    defaultColumns: ['title', 'author', 'publishedDate', 'status'],
+  },
+  access: {
+    read: () => true,
+    create: ({ req: { user } }) => !!user,
+    update: ({ req: { user } }) => !!user,
+  },
+  fields: [
+    {
+      name: 'title',
+      type: 'text',
+      required: true,
+    },
+    {
+      name: 'content',
+      type: 'richText',
+      required: true,
+    },
+    {
+      name: 'excerpt',
+      type: 'textarea',
+      maxLength: 200,
+    },
+    {
+      name: 'slug',
+      type: 'text',
+      required: true,
+      unique: true,
+      admin: {
+        position: 'sidebar',
+      },
+    },
+    {
+      name: 'coverImage',
+      type: 'upload',
+      relationTo: 'media',
+    },
+    {
+      name: 'author',
+      type: 'relationship',
+      relationTo: 'authors',
+      required: true,
+    },
+    {
+      name: 'publishedDate',
+      type: 'date',
+      admin: {
+        position: 'sidebar',
+      },
+    },
+    {
+      name: 'status',
+      type: 'select',
+      options: ['draft', 'published'],
+      defaultValue: 'draft',
+      admin: {
+        position: 'sidebar',
+      },
+    },
+  ],
+};
+```
+
+`nextjs-blog/lib/payload.ts`:
+```typescript
+// PayloadCMS API client
+const PAYLOAD_API_URL = process.env.NEXT_PUBLIC_PAYLOAD_URL || 'http://localhost:3001';
+
+export async function getPosts() {
+  const res = await fetch(`${PAYLOAD_API_URL}/api/posts?where[status][equals]=published`, {
+    next: { revalidate: 60 } // ISR: revalidate every 60 seconds
+  });
+  return res.json();
+}
+
+export async function getPostBySlug(slug: string) {
+  const res = await fetch(`${PAYLOAD_API_URL}/api/posts?where[slug][equals]=${slug}`);
+  const data = await res.json();
+  return data.docs[0];
+}
+```
+
+`nextjs-blog/app/posts/[slug]/page.tsx`:
+```typescript
+import { getPostBySlug } from '@/lib/payload';
+import PostContent from '@/components/PostContent';
+
+export default async function PostPage({ params }: { params: { slug: string } }) {
+  const post = await getPostBySlug(params.slug);
+
+  return (
+    <article className="max-w-4xl mx-auto px-4 py-12">
+      <h1 className="text-4xl font-bold mb-4">{post.title}</h1>
+      <PostContent content={post.content} />
+    </article>
+  );
+}
+```
+
+**Phase 3: Testing**
+```bash
+npm run dev:test "Test Next.js blog and PayloadCMS integration" --integration --coverage
+```
+
+**Expected Output** (.myaidev-method/sparc/test-results/):
+- Unit tests for React components (25 tests)
+- Integration tests for PayloadCMS API (15 tests)
+- E2E tests for blog workflows (10 tests)
+- 82% overall coverage
+
+**Phase 4: Review**
+```bash
+npm run dev:review "Review Next.js blog implementation" --security --performance
+```
+
+**Expected Output** (.myaidev-method/sparc/review-report.md):
+- Security: 9/10 (API authentication secure, no XSS vulnerabilities)
+- Performance: 8.5/10 (ISR configured, image optimization needed)
+- Code Quality: 8/10
+- Recommendations: Add caching layer for API requests, optimize images
+
+**Phase 5: Documentation**
+```bash
+npm run dev:docs "Document Next.js blog and PayloadCMS setup"
+```
+
+**Expected Output** (.myaidev-method/sparc/documentation/):
+- Setup guide for PayloadCMS
+- Next.js deployment guide
+- API reference
+- Content publishing workflow guide
+
+#### Content Publishing Workflow
+
+After building the blog system, use MyAIDev Method's content creation and publishing workflow:
+
+**Step 1: Create Content with AI**
+```bash
+# In Claude Code, use the content writer agent
+/myai-content-writer "10 Best Practices for Next.js Performance Optimization" --word_count 1500 --tone technical --audience "web developers"
+```
+
+**Output**: Creates `10-best-practices-for-nextjs-performance.md` with:
+- SEO-optimized content
+- Proper frontmatter (title, excerpt, keywords)
+- Markdown formatting
+- Code examples
+
+**Step 2: Publish to PayloadCMS**
+```bash
+# Configure PayloadCMS credentials (one-time setup)
+/myai-configure payloadcms
+
+# Publish the article to PayloadCMS
+/myai-payloadcms-publish "10-best-practices-for-nextjs-performance.md" --collection posts --status draft
+```
+
+**What happens**:
+1. Converts markdown to Lexical rich text format
+2. Extracts frontmatter for metadata
+3. Creates post in PayloadCMS via API
+4. Sets author (from environment)
+5. Uploads any referenced images
+6. Returns post ID and admin URL
+
+**Step 3: Review in PayloadCMS Admin**
+- Navigate to PayloadCMS admin (http://localhost:3001/admin)
+- Review the draft post
+- Add cover image, adjust formatting
+- Set publish date
+- Change status to "published"
+
+**Step 4: View on Frontend**
+- Post automatically appears on Next.js frontend
+- ISR revalidates cache (60s interval)
+- SEO metadata automatically populated
+- Social sharing ready
+
+#### Alternative: WordPress Backend
+
+If using WordPress instead of PayloadCMS:
+
+```bash
+# Architecture with WordPress
+npm run dev:architect "Design Next.js blog with WordPress headless CMS" --tech-stack "nextjs,wordpress,mysql"
+
+# Implementation
+npm run dev:code "Implement Next.js frontend with WordPress REST API"
+
+# Content creation
+/myai-content-writer "Getting Started with Headless WordPress" --word_count 1200
+
+# Publish to WordPress
+/myai-wordpress-publish "getting-started-with-headless-wordpress.md" --status draft
+
+# WordPress automatically handles:
+# - Gutenberg block conversion
+# - Media library uploads
+# - SEO metadata (Yoast/RankMath)
+# - Categories and tags
+```
+
+#### Complete Project Timeline
+
+**Week 1: Architecture & Setup**
+- Day 1-2: Architecture design (SPARC Phase 1)
+- Day 3-4: PayloadCMS setup and collections
+- Day 5: Next.js project scaffolding
+
+**Week 2: Implementation**
+- Day 1-3: Frontend components (SPARC Phase 2)
+- Day 4-5: API integration and data fetching
+
+**Week 3: Testing & Review**
+- Day 1-2: Test suite creation (SPARC Phase 3)
+- Day 3-4: Code review and improvements (SPARC Phase 4)
+- Day 5: Bug fixes and optimization
+
+**Week 4: Documentation & Launch**
+- Day 1-2: Documentation (SPARC Phase 5)
+- Day 3: Content creation with AI agents
+- Day 4: Content publishing workflow
+- Day 5: Production deployment
+
+#### Publishing Workflow Diagram
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│  Content Creation & Publishing Workflow                      │
+└─────────────────────────────────────────────────────────────┘
+
+1. Create Content
+   /myai-content-writer "Article Topic" --word_count 1500
+   ↓
+   Output: article-topic.md (SEO-optimized markdown)
+
+2. Review & Edit
+   - Review generated content
+   - Make manual adjustments
+   - Add custom images/media
+   ↓
+
+3. Publish to CMS
+   /myai-payloadcms-publish "article-topic.md" --status draft
+   OR
+   /myai-wordpress-publish "article-topic.md" --status draft
+   ↓
+   Output: Post created in CMS (draft status)
+
+4. CMS Review
+   - Login to PayloadCMS/WordPress admin
+   - Review formatted content
+   - Add cover image, categories, tags
+   - Set publish date
+   - Change status to "published"
+   ↓
+
+5. Frontend Display
+   - Next.js ISR revalidates
+   - Post appears on blog
+   - SEO metadata active
+   - Social sharing ready
+   ↓
+
+6. Analytics & Optimization
+   - Monitor post performance
+   - Use AI to create follow-up content
+   - Iterate and improve
+```
+
+#### Benefits of This Workflow
+
+✅ **Systematic Development**: SPARC ensures complete coverage from design to docs
+✅ **AI-Assisted Content**: Generate SEO-optimized content in minutes
+✅ **Headless CMS**: Decouple content from presentation
+✅ **Modern Stack**: Next.js + PayloadCMS = fast, scalable, developer-friendly
+✅ **Quality Assurance**: Built-in testing, review, and documentation
+✅ **Flexible Publishing**: Draft workflow with CMS review before publish
+✅ **SEO Ready**: Automatic metadata, image optimization, performance
+
+### Example 2: Building Authentication System
+
+```bash
+# Complete workflow
+npm run sparc "Build JWT authentication with refresh tokens and role-based access control"
+```
+
+**Expected Outputs**:
+1. **Architecture** (.myaidev-method/sparc/architecture.md):
+   - System design with auth flow diagrams
+   - JWT token management strategy
+   - User and role data models
+   - Security patterns (token rotation, RBAC)
+
+2. **Implementation** (.myaidev-method/sparc/code-output/):
+   - authService.js, tokenManager.js
+   - User and Role models
+   - Express middleware
+   - Unit tests
+
+3. **Testing** (.myaidev-method/sparc/test-results/):
+   - 25 unit tests
+   - 10 integration tests
+   - 85% coverage report
+
+4. **Review** (.myaidev-method/sparc/review-report.md):
+   - Security: 9/10 (OWASP compliant)
+   - Quality: 8.5/10
+   - 2 medium-priority improvements
+
+5. **Documentation** (.myaidev-method/sparc/documentation/):
+   - API reference for /auth endpoints
+   - User guide for authentication
+   - Security best practices
+
+### Example 3: Individual Phase Workflow for Real-Time Chat
+
+```bash
+# Step 1: Design architecture
+npm run dev:architect "Design real-time chat application for 10k users"
+
+# Review architecture.md, make adjustments if needed
+
+# Step 2: Implement based on architecture
+npm run dev:code "Implement WebSocket chat server"
+
+# Step 3: Create comprehensive tests
+npm run dev:test "Test chat functionality" --integration --coverage
+
+# Step 4: Review implementation
+npm run dev:review "Review chat implementation" --security
+
+# Address review findings...
+
+# Step 5: Generate documentation
+npm run dev:docs "Document chat API and deployment"
+```
+
+### Example 4: E-Commerce with Content Management
+
+Building an e-commerce site with WordPress backend for content:
+
+```bash
+# Phase 1: Architecture
+npm run dev:architect "Design Next.js e-commerce with WordPress for blog and content" --tech-stack "nextjs,wordpress,stripe,mysql"
+
+# Phase 2: Implementation
+npm run dev:code "Implement e-commerce frontend with WordPress blog integration"
+
+# Create product descriptions with AI
+/myai-content-writer "Product Description: Premium Leather Wallet" --word_count 300 --tone persuasive
+
+# Create blog content for SEO
+/myai-content-writer "Complete Guide to Leather Care" --word_count 2000 --seo_keywords "leather care,wallet maintenance"
+
+# Publish to WordPress
+/myai-wordpress-publish "complete-guide-to-leather-care.md" --status published
+
+# WordPress integration provides:
+# - SEO-optimized blog posts
+# - Product descriptions
+# - Landing pages
+# - Category pages
+# - All managed via WordPress admin
+```
+
+## Troubleshooting
+
+### Common Issues
+
+#### "Architecture file not found"
+**Problem**: Implementation phase can't find architecture.md
+
+**Solution**:
+```bash
+# Specify custom architecture file
+npm run dev:code "Implement feature" --architecture path/to/arch.md
+
+# Or ensure architecture phase completed successfully
+npm run dev:architect "Design system first"
+```
+
+#### "Coverage below threshold"
+**Problem**: Tests don't meet 60% minimum coverage
+
+**Solution**:
+```bash
+# Generate coverage report to see gaps
+npm run dev:test "Test module" --coverage
+
+# Review coverage report in .myaidev-method/sparc/test-results/
+# Add tests for uncovered code paths
+```
+
+#### "Review finds critical security issues"
+**Problem**: OWASP compliance failures
+
+**Solution**:
+1. Review specific issues in review-report.md
+2. Address critical and high-priority issues
+3. Re-run review phase
+```bash
+npm run dev:review "Review fixed implementation" --security
+```
+
+### Getting Help
+
+1. **Review Documentation**: Check phase-specific documentation
+2. **Check Outputs**: Examine .myaidev-method/sparc/ for detailed reports
+3. **Run Individual Phases**: Isolate issues by running phases separately
+4. **GitHub Issues**: Report bugs at https://github.com/myaione/myaidev-method/issues
+
+## Conclusion
+
+The MyAIDev Method's SPARC workflow provides a comprehensive, systematic approach to software development. By following the 5 phases and adhering to quality standards, you can:
+
+✅ Deliver high-quality, production-ready software
+✅ Maintain comprehensive documentation
+✅ Ensure security and performance
+✅ Build maintainable, testable code
+✅ Follow industry best practices
+
+**Next Steps**:
+1. Initialize MyAIDev Method: `npx myaidev-method init --claude`
+2. Run your first SPARC workflow: `npm run sparc "Build your feature"`
+3. Review outputs in `.myaidev-method/sparc/`
+4. Iterate and improve based on review findings
+
+For more information, visit: https://github.com/myaione/myaidev-method