User Stories Manager

User Stories Manager

Manage user stories for tracking feature development, linking code artifacts, and monitoring progress.

Quick Commands

# List stories
./scripts/story-list.sh                    # All stories summary
./scripts/story-list.sh --status draft     # Filter by status
./scripts/story-list.sh --module invoices  # Filter by module

# Create new story
./scripts/story-create.sh "feature-name" --module admin-events

# Update story
./scripts/story-update.sh US-001 --status in-progress
./scripts/story-update.sh US-001 --priority high

# Link resources
./scripts/story-link.sh US-001 --migration 20251224_add_feature
./scripts/story-link.sh US-001 --test apps/web/__tests__/e2e/path/test.ts

# Validate
./scripts/story-validate.sh

# Statistics
./scripts/story-stats.sh

Directory Structure

docs/user-stories/
├── {module}/                    # Module directories (18 total)
│   ├── US-{number}-{slug}.md   # Story files
│   └── _module.yml             # Optional module metadata
├── story-template.md           # Template for new stories
├── index.json                  # Auto-generated index
└── README.md                   # Documentation

Story Format

Stories use markdown with YAML frontmatter:

---
id: US-001
title: Dancer Registration
module: authentication
status: in-progress
priority: high
acceptance_criteria:
  - "User can register with email/password"
  - "Profile created in database"
migration_ids:
  - "20251115120000_add_dancer_profiles"
db_tables:
  - profiles
  - auth.users
test_files:
  - "apps/web/__tests__/e2e/auth/01-registration-flow.test.ts"
dependencies: []
created_at: 2025-11-15
updated_at: 2025-12-15
---

# User Story: Dancer Registration

## Context
...

## User Story Statement
**As a** dancer
**I want to** create an account
**So that** I can participate in events

## Acceptance Criteria
1. User can register with email/password
2. Profile created in database

## Technical Implementation
...

Status Lifecycle

draft → in-progress → testing → done

Frontmatter Fields

Required

• id: Story identifier (e.g., "US-001")
• title: Human-readable title
• module: Module name
• status: draft, in-progress, testing, done
• priority: low, medium, high, critical
• acceptance_criteria: List of criteria

Optional

• assigned_to: Developer email
• migration_ids: Linked migration IDs
• db_tables: Affected database tables
• test_files: Linked test file paths
• dependencies: Other story IDs
• blockers: Current blockers
• notes: Implementation notes
• created_at: Creation date
• updated_at: Last update date
• completed_at: Completion date

Modules (18)

Development Workflow

Starting a Feature

1. Find or create a story:

   ./scripts/story-list.sh --status draft
   # or
   ./scripts/story-create.sh "new-feature" --module admin-events
   

2. Update status to in-progress:

   ./scripts/story-update.sh US-070 --status in-progress
   

3. As you implement, link resources:

   ./scripts/story-link.sh US-070 --migration 20251224_add_feature
   ./scripts/story-link.sh US-070 --test apps/web/__tests__/e2e/feature/test.ts
   

4. Mark complete when done:

   ./scripts/story-update.sh US-070 --status done
   

Finding Stories

# What needs work?
./scripts/story-list.sh --status draft
./scripts/story-list.sh --status in-progress

# What's in a module?
./scripts/story-list.sh --module invoices

# High priority items
./scripts/story-list.sh --priority critical
./scripts/story-list.sh --priority high

Validation

Stories are validated for:

• Valid frontmatter schema (Zod)
• Migration files exist
• Test files exist
• No duplicate IDs
• Acceptance criteria for non-draft stories
• Dependencies reference existing stories

Run validation:

./scripts/story-validate.sh

Integration with @ballee/user-stories

The skill wraps the @ballee/user-stories package:

import {
  getAllStories,
  getStoryById,
  getStoriesByModule,
  getStoriesByStatus,
  validateStoryCompleteness,
} from '@ballee/user-stories';

Related Skills

• wip-lifecycle-manager - For multi-step implementation tracking
• database-migration-manager - For creating migrations
• test-patterns - For writing E2E tests
• service-patterns - For service layer implementation