Generate Application Design Document

User Request: $ARGUMENTS

Context

• Project root: !pwd
• Package.json: @package.json
• Existing design docs: !ls -la .agents/rules/ 2>/dev/null || echo "No .claude/skills directory yet"

Goal

Create a comprehensive Application Design Document based on deep codebase analysis and user input. The document provides a high-level overview of the application's architecture, core features, user experience, and business logic while remaining technology-agnostic and focused on the "what" rather than the "how".

Process

1. Initial Analysis

• Analyze project structure and existing codebase
• Review package.json for project name and dependencies
• Check for existing documentation in .agents/rules/
• Identify key application features and patterns
• Think deeply about the application's purpose and architecture

2. Codebase Deep Dive

Think harder about the application's architecture and business logic.

Analyze the codebase to understand:

• Application Structure: Main modules, features, and components
• User Flows: Authentication, navigation, key user journeys
• Data Models: Conceptual relationships and entities
• Business Logic: Core rules, workflows, and processes
• Integrations: External services and APIs
• Security Patterns: Authentication and authorization approaches

Extended thinking helps identify non-obvious patterns, understand complex business rules from code, and make strategic decisions about what aspects are most important to document.

3. Interactive Q&A Session

CRITICAL: Ask project stage question FIRST, then 4-7 additional questions:

• Use lettered/numbered options for easy response
• Focus on business goals and user needs
• Gather context for proper documentation

4. Update Project Configuration

Based on project stage response:

• Update .agents/rules/status.mdc with current stage
• Set appropriate DO/DON'T priorities for the stage
• Document stage-specific development guidelines in the Cursor rule

5. Generate Document

Create comprehensive app design document following the standard structure

6. Save and Organize

• Create .agents/rules/ directory if needed
• Save as 1-app-design-document.mdc
• Suggest next steps (tech stack doc, PRD, etc.)

Required Questions Template

🎯 CRITICAL: Project Stage Assessment (Ask First!)

1. What stage is your application currently in?

a) Pre-MVP - Building initial version, not deployed to production yet
b) MVP - Basic version deployed and live with early users
c) Production - Mature application with established user base
d) Enterprise - Large scale deployment, multiple teams involved

2. Based on your selected stage, here are the development priorities:

• Pre-MVP Priorities:

  • ✅ DO: Core functionality, security basics, input validation, working features
  • ❌ DON'T: Unit tests, performance optimization, accessibility polish, perfect code
  • 🚀 Focus: Ship fast with security, iterate based on feedback

• MVP Priorities:

  • ✅ DO: Critical path testing, basic monitoring, user feedback loops
  • ❌ DON'T: Comprehensive test coverage, advanced patterns, premature optimization
  • 🚀 Focus: Stability for early users, rapid iteration

• Production Priorities:

  • ✅ DO: Testing, monitoring, performance, accessibility, documentation
  • ❌ DON'T: Skip security reviews, ignore technical debt
  • 🚀 Focus: Reliability, scalability, user experience

• Enterprise Priorities:

  • ✅ DO: Comprehensive testing, security audits, team coordination, compliance
  • ❌ DON'T: Skip documentation, ignore code standards
  • 🚀 Focus: Team efficiency, maintainability, compliance

📋 Context-Specific Questions (Ask 4-7 based on analysis)

3. Application Purpose & Users

• What is the primary problem your application solves?
• Who are your target users and what are their main goals?

4. Unique Value Proposition

• What makes your application unique compared to existing solutions?
• What's your competitive advantage?

5. User Roles & Permissions

• What different types of users interact with your system?
• Examples: end users, admins, moderators, content creators, viewers

6. Core User Journeys

• What are the 2-3 most critical user flows?
• Example: Sign up → Create content → Share → Get feedback

7. Business Model & Growth

• How does this application generate value?
• Options: SaaS subscription, marketplace, freemium, advertising, one-time purchase

8. Integration Ecosystem

• What external services must you integrate with?
• Examples: payment processors, email services, analytics, social platforms

9. Scale & Performance Goals

• What scale are you planning for in the next 12 months?
• Users: dozens, hundreds, thousands, millions?
• Geographic: local, national, global?

10. Success Metrics

• How will you measure if your application is successful?
• Examples: user retention, revenue, engagement, conversion rates

Document Structure

The generated document must follow this high-level structure:

Introduction

• Application overview and purpose
• Target audience and user base
• Core value proposition
• Business context and goals

Core Features

• Feature Category 1: (e.g., User Management)
  • Purpose and user benefit
  • Key functionalities
  • User experience considerations
• Feature Category 2: (e.g., Content Creation)
  • Purpose and user benefit
  • Key functionalities
  • User experience considerations
• [Additional feature categories as needed]

User Experience

• User personas and roles
• Key user journeys and flows
• Interface design principles
• Accessibility and usability considerations

System Architecture

• High-level system components
• Data flow and relationships
• Integration points and external services
• Security and privacy approach

Business Logic

• Core business rules and processes
• Data models and relationships (conceptual)
• Workflow and state management
• Validation and business constraints

Future Considerations

• Planned enhancements and features
• Scalability considerations
• Potential integrations
• Long-term vision and roadmap

Target Audience

The document should be accessible to:

• Business stakeholders who need to understand the application's purpose and capabilities
• Product managers planning features and roadmaps
• Designers creating user interfaces and experiences
• New developers joining the project who need a high-level understanding
• Technical leaders making architectural decisions

The language should be clear, business-focused, and avoid technical implementation details.

Writing Principles

DO:

• Business Focus: Describe WHAT the application does, not HOW
• User Value: Emphasize benefits and outcomes for users
• Clear Language: Write for non-technical stakeholders
• Visual Thinking: Use diagrams and flows where helpful
• Future Ready: Consider growth and evolution paths

DON'T:

• Technical Details: No code snippets or implementation specifics
• Technology Stack: Save for 2-tech-stack.mdc document
• Database Schemas: Keep data models conceptual
• API Specifications: Focus on capabilities, not endpoints
• Performance Metrics: Describe goals, not technical benchmarks

Output

• Format: Markdown (.mdc)
• Location: .agents/rules/
• Filename: 1-app-design-document.mdc

Execution Steps

1. Start with Analysis

• Use Read, Glob, and Grep to explore the codebase
• Identify key features and patterns
• Look for existing documentation
• Use extended thinking: "Think deeply about this codebase's architecture, business purpose, and how different components work together to serve users"

2. Interactive Q&A

• MUST ASK PROJECT STAGE FIRST
• Present questions with numbered/lettered options
• Wait for user responses before proceeding

3. Update Project Status in Cursor Rule

Update .agents/rules/status.mdc with the project stage information:

---
description: Project status and stage-specific development guidelines
globs:
alwaysApply: true
---

# Project Status Guidelines

## Current Project Stage: [Stage Name]

**Stage**: [Pre-MVP | MVP | Production | Enterprise]

### DO Care About (Current Stage Priorities)

[Stage-specific DO priorities from template below]

### DO NOT Care About (Skip for Velocity)

[Stage-specific DON'T priorities from template below]

### Development Approach

[Stage-specific development focus]

## Stage-Based Development Guidelines

[Keep existing stage categories and guidelines from the original file]

Stage-Specific Content:

• Pre-MVP:

  • ✅ DO: Core functionality, security basics, input validation, working features
  • ❌ DON'T: Unit tests, performance optimization, accessibility polish, perfect code
  • 🚀 Focus: Ship fast with security, iterate based on feedback

• MVP:

  • ✅ DO: Critical path testing, basic monitoring, user feedback loops
  • ❌ DON'T: Comprehensive test coverage, advanced patterns, premature optimization
  • 🚀 Focus: Stability for early users, rapid iteration

• Production:

  • ✅ DO: Testing, monitoring, performance, accessibility, documentation
  • ❌ DON'T: Skip security reviews, ignore technical debt
  • 🚀 Focus: Reliability, scalability, user experience

• Enterprise:

  • ✅ DO: Comprehensive testing, security audits, team coordination, compliance
  • ❌ DON'T: Skip documentation, ignore code standards
  • 🚀 Focus: Team efficiency, maintainability, compliance

4. Generate Document

• Follow the standard structure
• Tailor content to project stage
• Keep language accessible

5. Save and Next Steps

• Create directories: mkdir -p docs .claude/skills
• Save design document: .agents/rules/1-app-design-document.mdc
• Update Claude rule: .agents/rules/status.mdc
• Suggest: "Would you like me to create a technical stack document next?"