Project Creator

Project Creator

Guide creation and maintenance of project documentation in .project/ folder.

Quick Navigation

• Templates: assets/ folder
• Guides: references/ folder

When to Use

• Starting a new project
• Creating/updating .project/ documentation
• Planning user stories

Project Structure

.project/
├── about.md              # Project overview, goals, target audience
├── specs.md              # Technical specifications, versions
├── architecture.md       # System architecture with diagrams
├── project-context.md    # Cumulative decisions (optional)
└── stories/
    ├── stories.md        # Master list
    └── 001-story-name.md # Individual stories

Assets (Templates)

Guides (References)

Document Dependencies

about.md → specs.md → architecture.md → project-context.md → stories/

---

Workflow per Document

Standard Flow

1. Load guide from references/ 2. Check if document exists — read and assess if yes 3. Create/update using template from assets/ 4. Interview user with questions from guide 5. Draft content based on responses 6. Present draft, ask for feedback 7. Iterate until user confirms 8. Move to next document

Existing Documents

When documents already exist:

• Read and assess completion state
• Ask user: review/update or skip?
• Build on existing content — don't recreate
• Note gaps or inconsistencies

---

Communication Style

Always Do

• Ask one topic at a time
• Offer 2-3 formulation variants
• Explain technical concepts simply
• Summarize understanding before drafting
• Confirm before moving to next step

Never Do

• Assume answers
• Skip confirmation steps
• Use jargon without explanation
• Move to next document without confirmation
• Write specs without verifying latest versions

---

Example Interaction

Agent: Let's start with about.md. Can you describe what this project does in your own words?

User: It's an app for tracking expenses.

Agent: Great start! Here are some formulation options:

  1. "A personal finance app for tracking daily expenses"
  2. "An expense tracker that helps users manage spending"
  3. "A mobile app for recording and categorizing expenses"

  Which resonates most? Or combine elements?

User: Option 2, but for small businesses, not personal.

Agent: Updated formulation:

  "An expense tracker that helps small businesses
  manage spending and categorize business expenses."

  Does that capture it? Should we add reporting
  or team features?

---

Critical Rules

• NEVER assume project details — always ask
• ALWAYS offer formulation variants
• ALWAYS validate understanding with user
• NEVER proceed without user confirmation
• ALWAYS use templates from assets/
• NEVER allow version downgrades (only upgrades)

---

Example Questions

Questions are examples — adapt to each unique project:

About.md

• Can you describe your project in one sentence?
• What frustration does this solve for users?
• If you could only build 3 features, what would they be?
• How will you know if the project is successful?
• What will this project definitely NOT do?

Specs.md

• What devices/browsers must be supported?
• How many concurrent users do you expect?
• Is there existing infrastructure to integrate with?
• What's the team's experience with [technology]?
• Are there any compliance requirements?

Architecture.md

• What are the main parts of the system?
• How should components communicate?
• What data flows exist?
• How will it scale?
• How is it secured?

Stories

• What's absolutely essential for launch?
• What can wait until later?
• What's the logical order of features?
• Does feature X need feature Y first?

---

Helping Non-Technical Users

When user lacks technical knowledge:

1. Explain options simply

• "React is great for interactive UIs, Vue is simpler to learn"
• "PostgreSQL is reliable for structured data, MongoDB for flexible schemas"

2. Use analogies

• "The API is like a waiter taking orders to the kitchen"
• "The database is like a filing cabinet"
• "The cache is like a notepad for quick lookups"

3. Make recommendations with reasoning

• "Given your expected user count, I recommend..."
• "Since you need real-time updates, this pattern..."

4. Explain trade-offs

• Performance vs. simplicity
• Feature richness vs. learning curve
• Cost vs. scalability

Links

• Agent Skills Specification

[Project Name]

Vision

[What is this project? What future does it create? 2-3 sentences capturing the essence and ambition.]

Problem & Opportunity

The Problem

[What pain point or challenge does this project address? Be specific.]

The Opportunity

[Why is now the right time? What makes this approach viable?]

Goals

Primary Goals

1. [Goal 1] 2. [Goal 2] 3. [Goal 3]

Success Criteria

• [How will we know the project is successful?]
• [Measurable outcome 1]
• [Measurable outcome 2]

Target Audience

Primary Users

[Who are the main users? What do they need? What motivates them?]

User Personas

• [Persona 1]: [Description — role, needs, pain points]
• [Persona 2]: [Description — role, needs, pain points]

Value Proposition

[What unique value does this project provide? Why would users choose this over alternatives?]

Business Context

<!-- Remove this section if not applicable -->

Business Model

[How does/will this project generate value or revenue?]

Market Context

[Competitive landscape, market size, positioning]

Business Constraints

[Budget, timeline, partnerships, regulations]

Features & Capabilities

Core Features (MVP)

1. [Feature 1]: [What it does and why it matters] 2. [Feature 2]: [What it does and why it matters] 3. [Feature 3]: [What it does and why it matters]

Future Features

• [Feature for later phase]
• [Enhancement idea]

Scope Boundaries

In Scope

• [What this project will do]
• [Included capabilities]

Out of Scope

• [What this project will NOT do]
• [Explicit exclusions — important to set expectations]

Constraints & Considerations

• Timeline: [Key dates, deadlines, phases]
• Resources: [Team, budget, tools available]
• Technical: [Existing systems, integration requirements]
• Regulatory: [Compliance, legal, privacy requirements]

Stakeholders

Risks & Mitigations

Project Phases

• Phase 1 (MVP): [Description] — [Timeline]
• Phase 2: [Description] — [Timeline]
• Future: [Long-term vision]

System Architecture

Overview

[High-level description of the overall system architecture — what it is and how parts work together.]

Architecture Diagram

graph TB
    subgraph "Client Layer"
        WEB[Web App]
        MOB[Mobile App]
    end
    subgraph "API Layer"
        GW[API Gateway]
        AUTH[Auth Service]
    end
    subgraph "Application Layer"
        SVC1[Service 1]
        SVC2[Service 2]
    end
    subgraph "Data Layer"
        DB[(Database)]
        CACHE[(Cache)]
        QUEUE[Message Queue]
    end
    subgraph "External"
        EXT[Third-party APIs]
    end

    WEB --> GW
    MOB --> GW
    GW --> AUTH
    GW --> SVC1
    GW --> SVC2
    SVC1 --> DB
    SVC1 --> CACHE
    SVC2 --> DB
    SVC2 --> QUEUE
    SVC1 --> EXT

Architecture Principles

1. [Principle 1]: [Description and why it matters] 2. [Principle 2]: [Description] 3. [Principle 3]: [Description]

---

Frontend Architecture

<!-- Remove this section if no frontend -->

Overview

[Description of frontend architecture approach]

Technology Stack

Component Structure

src/
├── components/     # Reusable UI components
├── pages/          # Route-level components
├── hooks/          # Custom React hooks
├── services/       # API communication
├── store/          # State management
└── utils/          # Utility functions

Key Patterns

• [Pattern 1]: [Description]
• [Pattern 2]: [Description]

---

Backend Architecture

<!-- Remove this section if no backend -->

Overview

[Description of backend architecture approach — monolith, microservices, serverless, etc.]

Technology Stack

Service Structure

src/
├── controllers/    # Request handlers
├── services/       # Business logic
├── models/         # Data models
├── routes/         # API routes
├── middleware/     # Request middleware
└── utils/          # Utilities

API Design

---

Database Architecture

Database Selection

Data Model

erDiagram
    USER ||--o{ ORDER : places
    ORDER ||--|{ ORDER_ITEM : contains
    PRODUCT ||--o{ ORDER_ITEM : "ordered in"

    USER {
        uuid id PK
        string email
        string name
        timestamp created_at
    }
    ORDER {
        uuid id PK
        uuid user_id FK
        decimal total
        string status
    }

Key Entities

---

Integrations

External Services

Integration Diagram

sequenceDiagram
    participant App
    participant Service
    participant External

    App->>Service: Request
    Service->>External: API Call
    External-->>Service: Response
    Service-->>App: Processed Data

---

Infrastructure & Deployment

Docker Configuration

<!-- Remove if not using Docker -->

docker/
├── Dockerfile          # Application container
├── docker-compose.yml  # Local development
└── docker-compose.prod.yml  # Production

Container Architecture

graph LR
    subgraph "Docker Compose"
        APP[App Container]
        DB[Database Container]
        CACHE[Redis Container]
        PROXY[Nginx Proxy]
    end

    PROXY --> APP
    APP --> DB
    APP --> CACHE

Environments

CI/CD Pipeline

graph LR
    CODE[Code Push] --> BUILD[Build]
    BUILD --> TEST[Test]
    TEST --> DEPLOY[Deploy]
    DEPLOY --> MONITOR[Monitor]

---

Security Architecture

Authentication

[Authentication mechanism — JWT, OAuth2, sessions, etc.]

sequenceDiagram
    participant User
    participant App
    participant Auth
    participant API

    User->>App: Login
    App->>Auth: Authenticate
    Auth-->>App: Token
    App->>API: Request + Token
    API-->>App: Protected Data

Authorization

[Authorization model — RBAC, ABAC, permissions, etc.]

Data Protection

• At Rest: [Encryption method]
• In Transit: [TLS version]
• PII Handling: [Policy]

---

Scalability & Performance

Scaling Strategy

• Horizontal: [How components scale horizontally]
• Vertical: [When to scale vertically]

Caching Strategy

Performance Targets

---

Monitoring & Observability

Logging

• Format: [JSON structured]
• Aggregation: [Tool]
• Retention: [Period]

Metrics

Alerting

---

Technical Decisions

Project Context

This document accumulates important decisions, learnings, and context throughout project development.

Document Purpose

This file serves as a living record of:

• Important decisions and their rationale
• Learnings discovered during development
• Context that future developers need
• Changes to initial assumptions

Key Decisions

[YYYY-MM-DD] — [Decision Title]

Context: [What led to this decision]

Decision: [What was decided]

Rationale: [Why this choice was made]

Consequences: [Expected outcomes]

Alternatives Considered:

• [Alternative 1]: [Why rejected]
• [Alternative 2]: [Why rejected]

---

Learnings & Discoveries

[Area/Topic]

• [Learning 1]
• [Learning 2]

---

Assumption Changes

---

External Dependencies Notes

[Dependency Name]

• Quirks: [Known issues or behaviors]
• Workarounds: [Solutions found]
• Documentation gaps: [What's not documented]

---

Team Knowledge

Onboarding Notes

[Important things new team members should know]

Domain-Specific Terms

---

Performance Baselines

---

Integration Notes

[Integration Name]

• Setup: [How to set up]
• Gotchas: [Common pitfalls]
• Test accounts: [Reference to secure location]

---

Future Considerations

• [ ] [Item to address later]
• [ ] [Technical debt item]
• [ ] [Enhancement idea]

Technical Specifications

Version Policy

⚠️ STRICT RULE: Downgrading package versions is FORBIDDEN. Upgrading is allowed.

>

All dependencies must use the latest stable versions. If a specific version is required due to compatibility, document the reason.

---

Technology Stack

Frontend

<!-- Remove if no frontend -->

Backend

<!-- Remove if no backend -->

Database

DevOps & Infrastructure

---

Runtime Requirements

Browser Support

<!-- For web frontend -->

Server Runtime

---

External Services & APIs

---

Performance Requirements

Response Time

Throughput & Scale

Availability

• Uptime Target: [99.X%]
• Planned Maintenance Window: [Schedule]
• Maximum Unplanned Downtime: [X hours/month]

---

Security Requirements

Authentication

• Method: [JWT/Session/OAuth2]
• Token Lifetime: [Access: Xm, Refresh: Xd]
• MFA: [Required/Optional/Not required]

Authorization

• Model: [RBAC/ABAC/Custom]
• Roles: [Admin, User, etc.]

Secrets Management

CRITICAL: Never commit secrets to version control.

Local Development:

• Use .env.local for local secrets (gitignored)
• Template: .env.example with placeholder values

Production:

• [Cloud provider secrets manager / HashiCorp Vault / etc.]
• Secrets injected at runtime, not baked into images

Data Protection

• At Rest: [Encryption method]
• In Transit: TLS [Version]
• PII Handling: [Policy]
• Data Retention: [Policy]

Compliance

<!-- Remove if not applicable -->

• [ ] GDPR
• [ ] HIPAA
• [ ] SOC 2
• [ ] [Other]

---

Code Quality Standards

Linting & Formatting

Testing Requirements

Code Review

• Required Approvals: [Number]
• CI Checks Required: [Yes/No]
• Branch Protection: [Rules]

Git Workflow

• Branch Naming: [type]/[description] (e.g., feat/user-auth)
• Commit Messages: [Conventional Commits / Custom format]
• Main Branch: [main/master]

---

Development Environment

Required Tools

Recommended IDE Extensions

• [Extension 1]
• [Extension 2]
• [Extension 3]

Local Setup

# Commands to set up local environment
[Command 1]
[Command 2]

---

Deployment

Environments

CI/CD Pipeline

• Tool: [GitHub Actions / GitLab CI / etc.]
• Triggers: [Push, PR, Tag]
• Stages: [Build → Test → Deploy]

Deployment Strategy

• Method: [Rolling / Blue-Green / Canary]
• Rollback: [Automatic / Manual]
• Health Checks: [Endpoints]

---

Monitoring & Logging

Logging

Monitoring

---

Documentation Standards

• API Docs: [OpenAPI/Swagger / GraphQL Schema]
• Code Docs: [JSDoc / TSDoc / Docstrings]
• README: Required for each package/service
• Architecture Decision Records: [ADR format]

User Stories

Overview

Total Stories: [N] Completed: [X] In Progress: [Y] Planned: [Z]

Story Status Legend

• 🟢 Done — Implemented and verified
• 🔵 In Progress — Currently being worked on
• 🟡 Ready — Fully specified, ready for development
• ⚪ Draft — Needs more specification
• 🔴 Blocked — Cannot proceed

Stories List

MVP (Phase 1)

Phase 2

Story Details

001 — [Story Name]

File: 001-story-name.md

Summary: [One-line description]

---

002 — [Story Name]

File: 002-story-name.md

Summary: [One-line description]

---

Notes

• Stories should be implemented in priority order
• Dependencies must be completed before dependent stories
• Each story has detailed specification in its own file

Story [NNN]: [Story Name]

Metadata

• Status: [🟡 Ready / ⚪ Draft / 🔵 In Progress / 🟢 Done / 🔴 Blocked]
• Priority: [High / Medium / Low]
• Complexity: [S / M / L / XL]
• Dependencies: [Story numbers or "None"]

User Story

As a [type of user] I want to [action/goal] So that [benefit/value]

Description

[Detailed description of what this story involves]

Acceptance Criteria

• [ ] [Criterion 1]
• [ ] [Criterion 2]
• [ ] [Criterion 3]
• [ ] [Criterion 4]
• [ ] [Criterion 5]

UI/UX Notes

[Mockups, wireframes, design references]

Technical Notes

[Technical considerations, approach suggestions]

Out of Scope

• [What this story does NOT include]
• [Explicit exclusions]

Open Questions

• [ ] [Question 1]
• [ ] [Question 2]

References

• [Related document 1]
• [Related document 2]

About.md Guide

Purpose

The about.md file is the foundational document that describes what the project is, why it exists, and who it serves.

Creation Workflow

Phase 1: Initial Questions

Start with broad questions to understand the project:

1. What is this project?

• Ask for a brief description in user's own words
• Offer to help structure the description
• Suggest clearer formulations if needed

2. What problem does it solve?

• Help user articulate the pain points
• Ask about current alternatives and their limitations
• Probe for specific examples of the problem

3. Who will use this?

• Identify primary and secondary users
• Create user personas together
• Understand user needs and expectations

Phase 2: Deep Dive Questions

4. What makes this unique?

• Competitive differentiation
• Key value proposition
• Why users would choose this over alternatives

5. What are the goals?

• Short-term objectives
• Long-term vision
• Measurable success criteria

6. What's in and out of scope?

• Core features for MVP
• Features for later phases
• Explicit exclusions

Phase 3: Constraints & Context

7. What are the constraints?

• Timeline
• Budget
• Technical limitations
• Team size and skills

8. Who are the stakeholders?

• Decision makers
• Contributors
• External dependencies

Iteration Approach

After each section: 1. Present the draft 2. Ask for feedback 3. Offer alternative formulations 4. Revise based on input 5. Confirm before moving on

Completion Criteria

Document is ready when user confirms:

• [ ] Project description is accurate
• [ ] Problem statement is clear
• [ ] Target audience is well-defined
• [ ] Goals and success metrics are established
• [ ] Scope boundaries are set
• [ ] Constraints are documented

Common Pitfalls

• Too vague: "A web app for managing things" — push for specifics
• Too technical: Focus on value, not implementation details
• Missing why: Always explain the problem being solved
• No boundaries: Scope must have explicit limits

Sample Questions to Ask

• "Can you describe your project in one sentence?"
• "What frustration does this solve for users?"
• "If you could only build 3 features, what would they be?"
• "How will you know if the project is successful?"
• "What will this project definitely NOT do?"
• "Who absolutely needs to be involved?"

Architecture.md Guide

Purpose

The architecture.md file describes the system's structure, components, interactions, and technical decisions with supporting diagrams.

Prerequisites

Read and reference:

• about.md — for scope and features
• specs.md — for technology choices

Diagram Requirements

All major sections MUST include Mermaid diagrams generated based on project context.

Diagram Types to Include

1. System Overview — High-level component diagram 2. Data Flow — Sequence diagram for key operations 3. Data Model — ER diagram for entities 4. Infrastructure — Deployment architecture 5. Authentication — Security flow (if applicable)

Creation Workflow

Phase 1: Component Identification

1. What are the main parts?

• Based on features from about.md
• Based on tech stack from specs.md
• Help user decompose the system

2. Generate Initial Diagrams

• Create system overview diagram
• Present to user for validation
• Iterate until accurate

Phase 2: Interactions & Data

3. How do components talk?

• Communication patterns
• API contracts
• Event flows

4. What data exists?

• Main entities
• Relationships
• Data storage locations

Phase 3: Non-Functional Architecture

5. How will it scale?

• Scaling strategy
• Caching approach
• Load balancing

6. How is it secured?

• Authentication mechanism
• Authorization model
• Data protection

7. How is it monitored?

• Logging strategy
• Metrics collection
• Alerting approach

Phase 4: Decisions Documentation

8. Document key decisions

• Why each technology was chosen
• Alternatives considered
• Trade-offs made

Helping Non-Technical Users

When explaining architecture:

1. Use analogies

• "The API is like a waiter taking orders to the kitchen"
• "The database is like a filing cabinet"
• "The cache is like a notepad for quick lookups"

2. Explain why decisions matter

• "This pattern helps when traffic increases"
• "This separation makes future changes easier"

3. Present alternatives with pros/cons

   Option A: Monolith
   ✅ Simpler to start
   ❌ Harder to scale parts independently
   
   Option B: Microservices
   ✅ Scale components independently
   ❌ More complex to manage

When user lacks technical understanding:

1. Make recommendations based on:

• Project complexity (from about.md)
• Scale requirements (from specs.md)
• Team capabilities

2. Explain reasoning:

• "Given your expected user count, I recommend..."
• "Since you need real-time updates, this pattern..."

Mermaid Diagram Guidelines

System Overview Example

graph TB
    subgraph "Client"
        A[Web App]
        B[Mobile App]
    end
    subgraph "API Layer"
        C[API Gateway]
    end
    subgraph "Services"
        D[Auth Service]
        E[Core Service]
    end
    subgraph "Data"
        F[(PostgreSQL)]
        G[(Redis)]
    end
    A --> C
    B --> C
    C --> D
    C --> E
    E --> F
    E --> G

Sequence Diagram Example

sequenceDiagram
    actor U as User
    participant F as Frontend
    participant A as API
    participant D as Database
    
    U->>F: Submit Form
    F->>A: POST /data
    A->>A: Validate
    A->>D: INSERT
    D-->>A: Success
    A-->>F: 201 Created
    F-->>U: Show Success

Completion Criteria

• [ ] All major components are identified
• [ ] System overview diagram is accurate
• [ ] Data flow diagrams exist for key operations
• [ ] Data model is defined
• [ ] Security architecture is documented
• [ ] Scaling strategy is outlined
• [ ] Technical decisions are documented with rationale
• [ ] User understands and approves architecture

Project Context Guide

Purpose

The project-context.md file is a cumulative document that captures important decisions, learnings, and context throughout the project lifecycle.

Key Characteristics

• Living document: Updated continuously as project evolves
• Historical record: Captures the "why" behind decisions
• Onboarding tool: Helps new team members understand context
• Optional at start: Can have minimal content initially

Creation Workflow

Initial Setup

1. Explain the purpose

• "This document will grow over time"
• "It captures decisions and learnings"
• "Think of it as the project's memory"

2. Start with basics

• Any known constraints not in specs.md
• Initial assumptions to track
• Team knowledge to preserve

3. Set expectations

• Will be sparse at start
• Should be updated regularly
• Remind user to add entries

Questions for Initial Content

1. Are there any decisions already made?

• Technology choices with reasoning
• Design decisions
• Business constraints

2. What assumptions are being made?

• About users
• About scale
• About requirements

3. What domain knowledge is needed?

• Industry terms
• Business processes
• Stakeholder preferences

4. Are there known external dependencies?

• Third-party services
• APIs with quirks
• Integration requirements

When to Update

Remind user to update when:

• A significant decision is made
• An assumption proves wrong
• A non-obvious solution is found
• External dependency behavior is discovered
• Performance baselines are established

Entry Format

Each significant entry should include:

• Date: When the decision/discovery was made
• Context: What situation led to this
• Decision/Learning: What was decided or discovered
• Rationale: Why this conclusion
• Consequences: What follows from this

Section Purposes

Key Decisions

Major choices that shape the project. Include alternatives considered and why they were rejected.

Learnings & Discoveries

Non-obvious findings during development. Saves time for future developers.

Assumption Changes

Track when initial assumptions proved incorrect. Helps understand project evolution.

External Dependencies Notes

Undocumented behaviors, workarounds, and gotchas for third-party services.

Team Knowledge

Tribal knowledge that should be documented. Onboarding information.

Performance Baselines

Recorded metrics to compare against. Helps identify regressions.

Integration Notes

Setup instructions and pitfalls for integrations.

Future Considerations

Deferred items, technical debt, enhancement ideas.

Completion Criteria

At project start:

• [ ] Basic structure is in place
• [ ] Any pre-existing decisions are documented
• [ ] Initial assumptions are listed
• [ ] User understands the purpose
• [ ] User knows when to update

This document is never "complete" — it grows with the project.

Sample Prompts

• "Have any decisions already been made about this project?"
• "What assumptions are we making about the users?"
• "Are there any external services we need to integrate with?"
• "Is there domain-specific terminology we should document?"
• "What should a new team member know on day one?"

Specs.md Guide

Purpose

The specs.md file defines all technical requirements, technology choices, and quality standards for the project.

Critical Rule

⚠️ VERSION POLICY: Downgrading package versions is FORBIDDEN. Upgrading is allowed.

Always specify latest stable versions. If a newer version is incompatible, document the reason and provide alternatives.

Creation Workflow

Phase 1: Technology Stack Questions

1. Frontend (if applicable)

• What frameworks/libraries? (React, Vue, Angular, etc.)
• Styling approach? (CSS-in-JS, Tailwind, etc.)
• State management needs?
• Suggest latest stable versions for each

2. Backend (if applicable)

• Runtime environment? (Node.js, Python, Go, etc.)
• Framework preferences?
• API style? (REST, GraphQL, gRPC)

3. Database

• SQL or NoSQL needs?
• Data volume expectations?
• Real-time requirements?

4. Infrastructure

• Hosting preferences? (Cloud provider, self-hosted)
• CI/CD requirements?
• Containerization needs?

Phase 2: Requirements Questions

5. Performance

• Response time expectations?
• Expected load/users?
• Availability requirements?

6. Security

• Authentication method?
• Authorization model?
• Compliance needs? (GDPR, HIPAA, etc.)

7. Quality Standards

• Code style preferences?
• Testing requirements?
• Code review process?

Phase 3: Environment & Tools

8. Development Environment

• Team's current tools?
• IDE preferences?
• Required development tools?

9. Deployment

• How many environments?
• Deployment frequency?
• Rollback strategy?

Helping Non-Technical Users

When user lacks technical knowledge:

1. Explain options simply

• "React is great for interactive UIs, Vue is simpler to learn"
• "PostgreSQL is reliable for structured data, MongoDB for flexible schemas"

2. Make recommendations

• Based on project requirements from about.md
• Consider team expertise
• Prioritize maintainability

3. Explain trade-offs

• Performance vs. simplicity
• Feature richness vs. learning curve
• Cost vs. scalability

Version Research

Before specifying versions: 1. Check official documentation for latest stable 2. Verify compatibility between technologies 3. Note any known issues or deprecations

Completion Criteria

• [ ] All technologies have specified versions
• [ ] Performance requirements are quantified
• [ ] Security requirements are documented
• [ ] Quality standards are defined
• [ ] Development tools are listed
• [ ] Deployment strategy is outlined
• [ ] User understands and agrees with choices

Sample Questions

• "What devices/browsers must be supported?"
• "How many concurrent users do you expect?"
• "Is there existing infrastructure to integrate with?"
• "What's the team's experience with [technology]?"
• "Are there any compliance requirements?"
• "How often do you need to deploy updates?"
• "What's your acceptable downtime?"

Stories Guide

Purpose

Stories document features and requirements in a structured, prioritized format ready for implementation planning.

Two-Level Structure

1. stories.md — Master list of all stories with status and priorities 2. NNN-story-name.md — Individual story files with full details

Creation Workflow

Phase 1: Story Discovery

1. Review existing documents

• Features from about.md
• Capabilities implied by specs.md
• Components from architecture.md

2. Ask about priorities

• "What's absolutely essential for launch?"
• "What can wait until later?"
• "What's the logical order?"

3. Identify dependencies

• "Does story X need story Y first?"
• Group related stories
• Find parallel tracks

Phase 2: Story List Creation

4. Create stories.md

• List all identified stories
• Assign numbers (001, 002, etc.)
• Set initial statuses (mostly Draft)
• Note dependencies

5. Prioritize together

• MVP vs. later phases
• High/Medium/Low within phases
• User validates priority

Phase 3: Individual Story Files

6. Focus on first story

• Must be well-defined before development starts
• Complete acceptance criteria
• Clear scope boundaries

7. Sketch remaining stories

• Basic user story format
• Initial acceptance criteria
• Note that details will evolve

Story Naming Convention

NNN-descriptive-name.md

• NNN: Three-digit number (001, 002, 010, 100)
• descriptive-name: Kebab-case, meaningful name
• Numbers don't have to be sequential

Examples:

• 001-user-authentication.md
• 002-dashboard-layout.md
• 010-notification-system.md

Story Quality Criteria

Good Story

• Clear user benefit ("so that...")
• Testable acceptance criteria
• Bounded scope
• Known dependencies

Bad Story

• Technical task without user context
• Vague acceptance criteria
• Unbounded scope ("and also...")
• Missing dependencies

Acceptance Criteria Format

Each criterion should be:

• Specific: Clear what to verify
• Measurable: Can be objectively checked
• Testable: Can be demonstrated

Examples:

✅ Good:
- [ ] User can upload images up to 10MB in PNG, JPG, or GIF format
- [ ] Upload progress is shown with percentage
- [ ] Error message appears if file exceeds size limit

❌ Bad:
- [ ] Image upload works
- [ ] Good user experience
- [ ] Fast performance

Story Evolution

First story (before development)

• Complete and detailed
• All acceptance criteria defined
• Technical notes included
• No open questions

Later stories (can evolve)

• Basic structure present
• User story defined
• Initial acceptance criteria
• May have open questions
• Will be refined before implementation

Questions to Ask

For story list:

• "What features were mentioned in the about.md?"
• "What would make the MVP complete?"
• "What's nice-to-have vs. must-have?"

For individual stories:

• "Who is the user for this feature?"
• "What triggers this action?"
• "What's the happy path?"
• "What could go wrong?"
• "How will we know it's done?"

Completion Criteria

stories.md is ready when:

• [ ] All known stories are listed
• [ ] Priorities are assigned
• [ ] MVP stories are identified
• [ ] Dependencies are mapped
• [ ] User confirms completeness

First story is ready when:

• [ ] User story is clear
• [ ] All acceptance criteria are testable
• [ ] Scope boundaries are set
• [ ] No blocking open questions
• [ ] User confirms readiness

Other stories are ready when:

• [ ] Basic user story exists
• [ ] Initial acceptance criteria listed
• [ ] User understands they'll evolve