/auto

Automatically generate user stories from product artifacts like PRDs, mockups, API specs, or design documents. Saves time breaking down requirements into actionable stories.

Quick Start

Copy/agileflow:auto SOURCE=<file-or-url> [EPIC=<EP-ID>] [AUTO_CREATE=no]

Parameters

Examples

Preview Stories from PRD

Copy/agileflow:auto SOURCE=docs/requirements/auth-prd.md

Reads the authentication requirements document and generates story preview without creating files.

Generate from API Specification

Copy/agileflow:auto SOURCE=docs/api/openapi.json OWNER=AG-API

Extracts endpoints from OpenAPI/Swagger spec and generates one story per endpoint.

Generate from Figma Mockup

Copy/agileflow:auto SOURCE=https://figma.com/file/abc123 AUTO_CREATE=no

OCR's the mockup design to identify screens, forms, and interactions, then generates UI stories.

Generate and Create Immediately

Copy/agileflow:auto SOURCE=docs/requirements/payment-prd.md EPIC=EP-0011 AUTO_CREATE=yes

Generates stories and creates all files immediately (skip preview step).

Supported Source Types

Product Requirements Document (PRD)

Formats: .md, .docx, .pdf, .txt

Extracts:

• Feature descriptions
• User personas and use cases
• Success criteria and metrics
• Edge cases and error scenarios
• Non-functional requirements

Example:

Copy# User Authentication Feature
 
Users should be able to:
- Register with email and password
- Reset forgotten password via email
- Login with OAuth (Google, GitHub)
- Manage account settings
 
Requirements:
- Email verification required
- Password minimum 8 characters
- Session expires after 24 hours

Generated Stories: 4-6 stories covering registration, login, password reset, OAuth, and session management.

API Documentation

Formats: OpenAPI/Swagger JSON, API docs .md

Extracts:

• Endpoints (HTTP method + path)
• Request/response schemas
• Authentication requirements
• Error codes and edge cases
• Rate limiting and quotas

Example OpenAPI:

Copypaths:
  /api/users:
    post:
      summary: Create user
      requestBody:
        schema:
          properties:
            name: string
            email: string

Generated Stories: One per endpoint with acceptance criteria from schema.

UI Mockups & Designs

Formats: Figma URL, .png/.jpg (with OCR), design spec .md

Extracts:

• Screen layouts and components
• User interactions and flows
• Form fields and validation
• Navigation and links
• Design system usage

Example: Screenshot of login form generates stories for form component, validation, error messages, and password reset link.

User Flow Diagrams

Formats: Mermaid .mmd, PlantUML, flow diagrams (.png with OCR)

Extracts:

• Steps in user journey
• Decision points and branches
• Alternative paths
• Success and failure scenarios

Example: Authentication flow diagram generates stories for each step.

Story Generation Process

Step 1: Analyze Source

• Identify document type
• Extract requirements and features
• Group related requirements
• Parse technical specifications

Step 2: Group Features

• Related requirements become one story
• Avoid story duplication
• Ensure stories are independent
• Check INVEST criteria

Step 3: Generate Stories

• Create title from feature description
• Write acceptance criteria in Given/When/Then format
• Estimate effort (0.5d, 1d, 1.5d, 2d)
• Assign appropriate owner
• Identify dependencies

Step 4: Show Preview

• Display all generated stories
• Show estimates and owners
• Show story count and total effort
• Ask for approval before creating

Step 5: Create Files (if approved)

• Create epic (if not provided)
• Create story files with templates
• Create test stubs
• Update status.json
• Append to bus/log.jsonl

Story Generation Rules (INVEST)

Generated stories follow INVEST criteria:

Stories >2d are broken into smaller ones.

Estimation Guidelines

Example: PRD to Stories

Input PRD

Copy# User Authentication Feature
 
## Overview
Allow users to register, log in, and manage accounts.
 
## Requirements
- Users register with email and password
- Email verification required
- Password reset via email
- Login with OAuth (Google, GitHub)
- Session management and expiry

Generated Stories Preview

CopyStory Generation Preview
 
Source: docs/requirements/auth-prd.md
Epic: EP-0010 (User Authentication) - CREATED
Stories: 5
 
1. US-0050: User registration (1.5d, AG-API)
   "Users can register with email and password"
 
2. US-0051: Email verification (1d, AG-API)
   "Verify email before allowing login"
 
3. US-0052: Password reset flow (1d, AG-API)
   "Users can reset forgotten password"
 
4. US-0053: OAuth login - Google (1.5d, AG-API)
   "Users can log in with Google account"
 
5. US-0054: OAuth login - GitHub (1.5d, AG-API)
   "Users can log in with GitHub account"
 
Total Estimate: 6.5 days
Recommended Owner: AG-API
 
Create these stories? (YES/NO)

Acceptance Criteria Generation

Stories are generated with Given/When/Then format:

Copy## Acceptance Criteria
 
- Given a user on registration page
  When they enter valid email and 8+ character password
  Then account is created and verification email sent
 
- Given invalid password (< 8 characters)
  When they try to submit
  Then form shows "Password must be at least 8 characters"
 
- Given user opens verification email
  When they click verification link
  Then email is marked verified and login works

Output Files

The command creates:

1. Epic file (docs/05-epics/EP-XXXX.md)

   • Epic title and goal
   • Source document reference
   • Child stories list

2. Story files (docs/06-stories/EP-XXXX/US-XXXX.md)

   • Generated content from source
   • Acceptance criteria
   • Technical notes
   • Testing strategy

3. Test stubs (docs/07-testing/test-cases/US-XXXX.md)

   • Test structure aligned with AC
   • Placeholders for test implementation

4. Status tracking (docs/09-agents/status.json)

   • All stories added with status: ready

5. Communication (docs/09-agents/bus/log.jsonl)

   • Story generation event logged

Workflow

1. Prepare source document - Ensure PRD/spec is complete
2. Generate preview - Run /auto with AUTO_CREATE=no
3. Review generated stories - Check accuracy and completeness
4. Adjust if needed - Edit preview or regenerate with different parameters
5. Create stories - Run with AUTO_CREATE=yes or approve preview
6. Validate stories - Use /story-validate on generated stories
7. Plan sprint - Include validated stories in /sprint

Common Scenarios

Scenario: API has 15 endpoints

Problem: Too many stories (violates 0.5d-2d estimate rule)

Solution: Command automatically groups related endpoints:

• Endpoints for same resource (GET, POST, PATCH, DELETE) → One story
• List and detail endpoints → One story
• Authentication endpoints → One story

Result: 15 endpoints → 5-6 stories

Scenario: PRD has unclear requirements

Problem: Generated stories seem vague

Solution:

1. Clarify PRD with stakeholders first
2. Re-run /auto with updated source
3. Or manually edit generated stories with /story

Scenario: Generated stories don't match team velocity

Problem: Estimates seem too optimistic/pessimistic

Solution:

1. Review stories and adjust estimates
2. Consider team's historical velocity
3. Run /velocity to understand team capacity
4. Break large stories into smaller ones

Quality Checklist

Before approving generated stories:

• All stories have clear acceptance criteria
• Stories are independent (no hidden dependencies)
• Estimates are realistic (0.5d-2d range)
• Acceptance criteria uses Given/When/Then format
• Technical notes are accurate
• Stories cover main scenarios (happy path + edge cases)
• No stories are duplicated
• Epic goal is clear and specific
• Owner assignments are appropriate

Integration with Other Commands

• After generation: Use /story-validate to ensure quality
• Before sprint: Use /sprint to select stories
• For dependencies: Use /deps if stories have relationships
• During development: Use /babysit for implementation help
• For testing: Use /verify to run tests

Best Practices

• Start with requirements - Invest time in clear PRD or spec
• Review generated stories - Don't blindly accept AI generation
• Validate before sprint - Use /story-validate on all generated stories
• Group related requirements - More focused epic = better stories
• Be specific in source - Vague requirements → vague stories
• Consider dependencies - Manual review for hidden dependencies
• Estimate conservatively - Add buffer for unknowns

Limitations & Considerations

• AI may misinterpret - Review generated stories for accuracy
• Context matters - Generated stories may lack domain knowledge
• Dependencies are manual - Add cross-story dependencies manually
• Estimates vary by team - Adjust based on your velocity
• Technical details - May need manual additions to Architecture Context

Related Commands

• /epic - Create epics manually if needed
• /story - Create or edit individual stories
• /story-validate - Validate generated quality
• /sprint - Plan sprints with generated stories
• /deps - Visualize dependencies after generation