Skip to content

WORKFLOW.md

Latest commit

 

History

History
697 lines (551 loc) · 19.6 KB

WORKFLOW.md

File metadata and controls

697 lines (551 loc) · 19.6 KB
Raw

Complete Development Workflow Guide

This guide walks you through the entire development process using the AI-Driven Development Framework, from raw idea to production deployment.

🎯 Overview

The framework uses a phased approach with specialized agents working together:

Idea/Concept
    ↓
Phase 0: Planning & Brainstorming (Claude Prompts)
    ↓
Phase 1: Formal Documentation (Agents)
    ↓
Phase 2: Implementation (Parallel Agents)
    ↓
Phase 3: Validation & Polish (Agents)
    ↓
Production-Ready Application

📋 Phase 0: Planning & Brainstorming

Goal: Transform rough ideas into structured plans

When to use: Start of any new project or major feature

Step 1: Senior Engineer Brainstorm

Prompt: agents/00-planning/senior-engineer-brainstorm.md Use with: Any AI assistant (Cursor, Claude, GitHub Copilot, ChatGPT, etc.)

Input:

  • What you're building
  • Who it's for
  • Why it matters
  • How it's different

Output:

  • MVP Flow (step-by-step)
  • Launch Features with tech requirements
  • Future Features roadmap
  • System diagram (SVG)
  • Clarifying questions

Example:

Context: Building a recipe app that converts restaurant dishes to home recipes
Output: MVP flow with 6 core steps, 5 launch features, system architecture

Step 2: Product Designer Brief

Prompt: agents/00-planning/product-designer-brief.md

Input:

  • Feature list from Step 1
  • Aesthetic preferences
  • Platform requirements (iOS/Android/Web)
  • Design inspiration images

Output:

  • Feature-by-feature functional briefs
  • Screen-by-screen state descriptions
  • Animation specifications
  • UI/UX detailed breakdown

Example:

Input: "User Authentication" feature
Output: 5 screens × 3-4 states each with full UI/UX details

Step 3: Technical Spec Writer

Prompt: agents/00-planning/technical-spec-writer.md

Input:

  • Features from Steps 1 & 2
  • Tech stack choices
  • Platform constraints

Output:

  • File system structure
  • API relationships per feature
  • Detailed requirements
  • Implementation pseudocode
  • Edge cases covered

📄 Phase 1: Formal Documentation

Goal: Create comprehensive, structured documentation that serves as the source of truth

When to use: After brainstorming, before implementation

Agent 1: Product Manager

Agent: agents/01-documentation/product-manager.md

Input:

  • Brainstorming outputs from Phase 0
  • Business goals and constraints
  • Target audience definition

Process:

  1. Restate understanding
  2. Ask clarifying questions
  3. Create structured documentation

Output: docs/project-documentation/product-manager-output.md

Contains:

  • Executive Summary (elevator pitch, problem, audience, USP, metrics)
  • Feature Specifications (user stories, acceptance criteria, priorities)
  • Functional Requirements (user flows, state management, validation)
  • Non-Functional Requirements (performance, scalability, security)
  • UX Requirements (information architecture, error prevention)
  • Critical Questions Checklist

Example Feature Spec:

**Feature**: Photo Capture & Upload
**User Story**: As a foodie, I want to photograph restaurant dishes, so that I can generate recipes
**Acceptance Criteria**:
  - Given user opens camera, when they tap capture, then photo saves with metadata
  - Given poor lighting, when capture attempted, then system suggests flash/HDR
**Priority**: P0 (Core MVP functionality)
**Dependencies**: Device camera permissions, image storage service
**Technical Constraints**: Must support iOS 14+, Android 10+
**UX Considerations**: One-tap capture, immediate visual feedback

Agent 2: UX/UI Designer

Agent: agents/01-documentation/ux-ui-designer.md

Input:

  • docs/project-documentation/product-manager-output.md
  • Design inspiration and brand guidelines

Process:

  1. Create complete Design System
  2. Design feature-by-feature with all states
  3. Document screen specifications
  4. Create implementation guidelines

Output: docs/design-documentation/ (complete structure)

Directory Structure Created:

design-documentation/
├── README.md
├── design-system/
│   ├── style-guide.md              # Colors, typography, spacing, components
│   ├── components/                  # Button, form, navigation specs
│   ├── tokens/                      # Design token definitions
│   └── platform-adaptations/        # iOS/Android/Web specifics
├── features/
│   └── [feature-name]/
│       ├── README.md
│       ├── user-journey.md          # Step-by-step user flows
│       ├── screen-states.md         # Every UI state documented
│       ├── interactions.md          # Animations & transitions
│       ├── accessibility.md         # WCAG compliance
│       └── implementation.md        # Developer handoff notes
└── accessibility/
    └── guidelines.md

Example Design System Output:

### Primary Button Component
**Variants**: Primary, Secondary, Ghost
**States**: Default, Hover, Active, Focus, Disabled, Loading
**Sizes**: Small (32px), Medium (44px), Large (56px)

**Visual Specs**:
- Height: 44px (medium)
- Padding: 12px 24px
- Border Radius: 8px
- Background: Linear gradient(#8B0000, #600000)
- Typography: 16px, Semibold, -0.2px letter-spacing

**Interaction**:
- Hover: Scale 1.02, shadow elevation increase
- Active: Scale 0.98, darker gradient
- Transition: 200ms cubic-bezier(0.4, 0, 0.2, 1)

Agent 3: System Architect

Agent: agents/01-documentation/system-architect.md

Input:

  • Product Manager output
  • Design documentation
  • Tech stack preferences

Process:

  1. Comprehensive requirements analysis
  2. Technology stack decisions with rationale
  3. System component design
  4. Data architecture specifications
  5. API contract definitions
  6. Security and performance foundations

Output: docs/project-documentation/architecture-output.md

Contains:

  • Executive Summary
  • Technology Stack (Frontend, Backend, Database, Infrastructure)
  • System Components (boundaries, interactions, data flow)
  • Database Schema (tables, relationships, indexes, migrations)
  • API Specifications (endpoints, request/response schemas, auth)
  • Security Architecture
  • Performance Architecture
  • Implementation guidelines for each team

Example API Spec:

### POST /api/recipes/generate

**Authentication**: Required (Bearer token)
**Rate Limit**: 10 requests/minute per user

**Request Body**:
```json
{
  "image_url": "string (required, max 10MB)",
  "menu_description": "string (required, 10-500 chars)",
  "tasting_notes": "string (optional, max 1000 chars)",
  "dietary_restrictions": ["string"] (optional)
}

Response 200:

{
  "recipe_id": "uuid",
  "title": "string",
  "ingredients": [{"name": "string", "quantity": "string"}],
  "instructions": [{"step": 1, "description": "string", "duration_minutes": 5}],
  "total_time_minutes": 45,
  "difficulty": "medium",
  "serves": 4
}

Errors:

  • 400: Invalid image format or size
  • 401: Authentication required
  • 429: Rate limit exceeded
  • 500: AI processing failed

---

## 🔨 Phase 2: Implementation

**Goal**: Build the application with parallel, specialized development

**When to use**: After documentation is complete and approved

### Parallel Agent Execution

All implementation agents can work **simultaneously** because they all read from the same source documentation:

docs/project-documentation/ docs/design-documentation/ ↓ ↓ ↓ ↓ ↓ Backend Frontend QA DevOps Security


### Agent 4: Senior Backend Engineer
**Agent**: `agents/02-implementation/senior-backend-engineer.md`

**Input**:
- Architecture document (API specs, database schema)
- Product manager output (business logic, acceptance criteria)

**Responsibilities**:
1. **Database Migrations**: Generate and run migration scripts first
2. **API Implementation**: Build endpoints per specifications
3. **Business Logic**: Implement domain rules and workflows
4. **Data Validation**: Enforce constraints and rules
5. **Error Handling**: Comprehensive error responses
6. **Security**: Input sanitization, authentication middleware

**Output**:
- Complete backend codebase
- Database migration files
- API endpoint implementations
- Unit and integration tests
- API documentation

**Example Work**:

Task: Implement recipe generation endpoint

  1. Create database migration for recipes table
  2. Run migration: alembic upgrade head
  3. Implement RecipeService with AI integration
  4. Create /api/recipes/generate endpoint
  5. Add validation middleware
  6. Write unit tests for business logic
  7. Write integration tests for endpoint

### Agent 5: Senior Frontend Engineer
**Agent**: `agents/02-implementation/senior-frontend-engineer.md`

**Input**:
- Design documentation (component specs, user journeys)
- Architecture document (API contracts, state management)
- Product manager output (user stories, acceptance criteria)

**Responsibilities**:
1. **Component Implementation**: Build UI per design specs
2. **State Management**: Implement specified patterns
3. **API Integration**: Connect to backend endpoints
4. **Navigation**: Implement routing and flows
5. **Responsive Design**: All breakpoints per specs
6. **Accessibility**: WCAG compliance implementation

**Output**:
- Complete frontend codebase
- Reusable component library
- API integration layer
- Responsive layouts
- Accessibility implementation

**Example Work**:

Task: Implement photo capture screen

  1. Read design specs for camera-screen
  2. Build CameraScreen component with all states
  3. Integrate Expo Camera API per architecture
  4. Implement upload to backend API
  5. Add loading, error, and success states
  6. Ensure 44px touch targets per accessibility
  7. Write component tests

### Agent 6: QA & Test Automation Engineer
**Agent**: `agents/02-implementation/qa-test-automation-engineer.md`

**Multi-Mode**: Backend / Frontend / E2E

**Input**:
- All documentation (for understanding requirements)
- Codebase (for test generation)

**Responsibilities**:
1. **Test Planning**: Coverage strategy from specs
2. **Backend Tests**: API endpoint testing, business logic validation
3. **Frontend Tests**: Component testing, user interaction simulation
4. **E2E Tests**: Complete user journey automation
5. **Performance Tests**: Load testing, benchmarking
6. **Bug Reporting**: Detailed issue documentation

**Context-Based Operation**:

Backend Context:

  • API contract validation
  • Database integration tests
  • Business logic unit tests

Frontend Context:

  • Component rendering tests
  • User interaction simulation
  • State management validation

E2E Context:

  • Full user journey automation
  • Cross-browser testing
  • Real environment validation

### Agent 7: DevOps & Deployment Engineer
**Agent**: `agents/02-implementation/devops-deployment-engineer.md`

**Multi-Mode**: Local Development (Phase 3) / Production (Phase 5)

**Input**:
- Architecture document (infrastructure requirements)
- Security specifications (compliance needs)

**Responsibilities**:

**Local Development Mode** (Phase 3):
1. Create simple Dockerfiles for each service
2. Write docker-compose.yml for local orchestration
3. Environment configuration templates
4. Development scripts (build, run, test)
5. Local networking and service discovery

**Production Mode** (Phase 5):
1. Infrastructure as Code (Terraform/Pulumi)
2. CI/CD pipeline configuration
3. Environment setup (dev/staging/prod)
4. Monitoring and alerting setup
5. Security configurations
6. Backup and disaster recovery

**Example Local Setup**:
```yaml
# docker-compose.yml
version: '3.8'
services:
  frontend:
    build: ./frontend
    ports: ["3000:3000"]
    volumes: ["./frontend:/app"]  # Hot reload
  backend:
    build: ./backend
    ports: ["3001:3001"]
    volumes: ["./backend:/app"]
  db:
    image: postgres:15-alpine
    environment:
      POSTGRES_DB: appdb
      POSTGRES_USER: dev
      POSTGRES_PASSWORD: dev

Agent 8: Security Analyst

Agent: agents/02-implementation/security-analyst.md

Multi-Mode: Quick Scan / Comprehensive Audit

Input:

  • Complete codebase
  • Architecture document
  • Security requirements

Responsibilities:

  1. Code Security: SAST analysis for vulnerabilities
  2. Dependency Scanning: CVE checks on all packages
  3. Infrastructure Security: Cloud config validation
  4. API Security: Endpoint security assessment
  5. Data Protection: Encryption and privacy validation
  6. Compliance: GDPR, CCPA, SOC2 checks

Operating Modes:

Quick Scan (During Development):
- New code changes only
- New dependencies
- Critical vulnerabilities
- Immediate feedback

Comprehensive Audit (Pre-Deployment):
- Full codebase analysis
- Complete dependency tree
- Infrastructure review
- Threat modeling
- Compliance validation

Agent 9: Feature Documenter (Proactive)

Agent: agents/02-implementation/feature-documenter.md

Invocation: Automatic when features are built

Input:

  • Newly implemented code
  • Original specifications
  • GitHub issues/tickets

Responsibilities:

  1. Document features as they're built
  2. Keep documentation in sync with code
  3. Create simple and comprehensive templates
  4. Link to related specs and files

Output: docs/features/[feature-name].md

Contains:

  • What the feature does
  • How it works
  • Files changed/added
  • Key functions/components
  • How to test
  • Dependencies
  • Notes & TODOs

✅ Phase 3: Validation & Polish

Goal: Ensure implementation matches specifications and meets quality standards

When to use: After implementation, before deployment

Agent 10: Reqing Ball (Requirements Validator)

Agent: agents/03-validation/reqing-ball.md

Model: Claude Opus (for maximum accuracy)

Input:

  • Product requirements
  • Architecture documentation
  • Design specifications
  • Implemented codebase

Process:

  1. Requirements Traceability: Map specs to implementation
  2. Implementation Quality: Compare actual vs. specified behavior
  3. User Journey Validation: Trace flows through code
  4. Gap Analysis: Identify missing or incorrect implementations

Output: docs/project-documentation/reqing-ball-output.md

Contains:

## Executive Summary
- Overall Compliance Score: 87% implemented correctly
- Critical Gaps: 3 P0 requirements not met
- Improvements Found: 5 enhancements beyond spec

## Feature-by-Feature Analysis
### Photo Capture Feature
**Status**: ⚠️ Partial

| Requirement | Specified | Actual | Status |
|-------------|-----------|--------|--------|
| REQ-001 | Flash toggle visible | Not implemented | ❌ |
| REQ-002 | HDR auto-detect | Working | ✅ |
| REQ-003 | Image validation | Enhanced with ML | 🌟 |

## Critical Misses (P0 - Must Fix)
- **Flash Control**: Missing UI control for camera flash
- **Impact**: Users can't control lighting in dim environments
- **Remediation**: Add toggle button to camera UI (2 hours)

## Recommendations
1. Week 1: Fix flash control, add missing validation
2. Month 1: Optimize image processing performance

Agent 11: Polisher (Design Quality)

Agent: agents/03-validation/polisher.md

Input:

  • Design documentation (for comparison)
  • Product requirements (for context)
  • Implemented UI (for analysis)

Process:

  1. Read project context and design system
  2. Holistic assessment of design quality
  3. Systematic analysis (visual, interaction, content, technical)
  4. Detailed inspection (pixel-level)
  5. Prioritized recommendations

Output: docs/project-documentation/polisher-output.md

Contains:

## Polish Review: Recipe Generation App

### 🌟 Excellence Observed
- Visual hierarchy is clear with proper use of maroon accents
- Smooth animations using proper easing functions

### 🔴 Priority 1: Must Fix

#### Spacing Inconsistency
**Issue**: Mixed 12px, 16px, 20px gaps break visual rhythm
**Current**: Inconsistent vertical spacing between sections
**Recommendation**: Standardize to 16px with 24px for major sections
**Impact**: Creates predictable rhythm, improves scannability

#### Touch Target Sizing
**Issue**: Secondary buttons only 36px on mobile
**Current**: Below 44px minimum for accessibility
**Recommendation**: Increase to 44px minimum height
**Impact**: Reduces mis-taps by ~23% (Fitts's Law)

### 🟡 Priority 2: Should Fix

#### Animation Timing
**Current**: 200ms linear transitions
**Recommendation**: 220ms cubic-bezier(0.4, 0, 0.2, 1)
**Rationale**: Slight longer duration with ease-out feels more natural

### 🟢 Priority 3: Perfection Details
- Icon vertical alignment off by 1px due to visual weight
- Loading skeleton should pulse subtly for better feedback

🔄 Iterative Development

The framework supports iterative development:

Adding New Features

  1. Start at Phase 1 (Product Manager for new feature spec)
  2. Designer adds to design documentation
  3. Architect updates architecture if needed
  4. Implementation agents build feature
  5. Validation agents check compliance

Refactoring Existing Code

  1. Document current state with Feature Documenter
  2. Create "should be" specs with Product Manager
  3. Use Reqing Ball to identify gaps
  4. Implementation agents refactor
  5. Validation agents verify improvements

Bug Fixes

  1. QA Engineer documents bug with test case
  2. Implementation agents fix (Backend/Frontend)
  3. QA Engineer verifies fix
  4. Feature Documenter updates docs

📊 Success Metrics

Documentation Quality

  • All specifications are unambiguous
  • Acceptance criteria are testable
  • Requirements traceable to business goals
  • Edge cases documented
  • Cross-references accurate

Implementation Quality

  • All P0 requirements implemented
  • Design fidelity matches specs
  • Accessibility compliance (WCAG AA)
  • Performance meets targets
  • Security best practices followed

Validation Results

  • Reqing Ball compliance > 90%
  • Polisher finds only minor issues
  • All QA tests passing
  • Security scan shows no critical issues
  • Production deployment successful

🎓 Best Practices

1. Documentation First

Always complete Phase 1 before Phase 2. Parallel implementation only works with complete specs.

2. Version Control Everything

All documentation and code in git. Agents reference specific versions.

3. Use Agent Checklists

Each agent has quality checklists—ensure they're all checked before moving on.

4. Iterate Based on Validation

Use Reqing Ball and Polisher feedback to improve, not just to "pass."

5. Keep Documentation Updated

Feature Documenter should be invoked for every feature built.

6. Leverage Parallel Execution

Backend, Frontend, QA, DevOps, and Security can all work simultaneously.

🚨 Common Pitfalls

❌ Skipping Documentation Phase

Problem: Implementation agents need complete specs Solution: Always complete Phase 1 fully

❌ Sequential Implementation

Problem: Wastes time; agents can work in parallel Solution: Start all implementation agents at once

❌ Ignoring Validation

Problem: Issues compound and are harder to fix Solution: Run Reqing Ball and Polisher regularly

❌ Not Using Context Modes

Problem: DevOps/QA/Security agents need proper context Solution: Clearly specify the mode when invoking

❌ Outdated Documentation

Problem: Implementation diverges from docs Solution: Use Feature Documenter proactively

📞 Next Steps

  1. Initialize your project: Run scripts/init-new-project.sh
  2. Start with Phase 0: Use brainstorming prompts
  3. Move to Phase 1: Run Product Manager agent
  4. Continue through phases: Follow this workflow
  5. Iterate and improve: Use validation feedback

Happy Building! 🚀