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
| Status | Meaning | Requirements |
|---|---|---|
| draft | Being planned | None |
| in-progress | Active development | Must have acceptance_criteria |
| testing | Code complete, validating | Must have migration_ids, test_files |
| done | Fully complete | All linked migrations & tests exist |
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)
| Module | Stories | Description |
|---|---|---|
| authentication | US-001 | Registration, login |
| cast-management | US-002 | Cast workflows |
| communications | US-003 to US-007 | Emails, invitations |
| admin-events | US-008 to US-014 | Event management |
| dancer-experience | US-015 to US-019 | Dancer features |
| admin-productions | US-020 to US-021 | Production management |
| admin-cast-assignment | US-022 to US-029 | Cast assignment |
| admin-reporting | US-030 to US-032 | Reports, exports |
| invoices | US-033 to US-038 | Invoice system |
| hire-orders | US-039 to US-045 | Hire orders |
| clients | US-046 to US-048 | Client management |
| ai-chatbot | US-049 to US-052, US-059 | AI chatbot |
| venues | US-053 to US-054 | Venue management |
| reimbursements | US-055 to US-056 | Reimbursements |
| legal-compliance | US-057 | Legal documents |
| airtable-sync | US-058 | Airtable sync |
| payments | US-060 | Tipalti payments |
| repertoire | US-061+ | Repertoire management |
Development Workflow
Starting a Feature
Find or create a story:
./scripts/story-list.sh --status draft # or ./scripts/story-create.sh "new-feature" --module admin-eventsUpdate status to in-progress:
./scripts/story-update.sh US-070 --status in-progressAs 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.tsMark 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 trackingdatabase-migration-manager- For creating migrationstest-patterns- For writing E2E testsservice-patterns- For service layer implementation
Converted and distributed by TomeVault — claim your Tome and manage your conversions.