myaidev-method/DEV_WORKFLOW_GUIDE.md

Comprehensive development framework with SPARC methodology for AI-assisted software development, multi-platform publishing (WordPress, PayloadCMS, Astro, Docusaurus, Mintlify), and Coolify deployment

# 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
# Slash command (in Claude Code)
/myai-sparc-workflow "Build user authentication system with JWT and refresh tokens"

# CLI command
npx myaidev-method sparc "Build user authentication system with JWT and refresh tokens"

# With technology preferences
npx myaidev-method sparc "Build e-commerce checkout" --tech-stack "react,node,stripe,postgres"

# Run specific phases only
npx myaidev-method 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
npx myaidev-method sparc "Build feature X"

# Run specific phases
npx myaidev-method sparc "Improve feature Y" --phases "architecture,review,documentation"

# Skip specific phase (use with caution)
npx myaidev-method 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
npx myaidev-method 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
npx myaidev-method 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@latest init --claude`
2. Run your first SPARC workflow: `npx myaidev-method 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