Command: gears story

Create and manage feature stories and specifications in your project.

Overview

The story command helps you document feature requirements before implementation. Stories serve as specifications that both humans and AI agents can understand, ensuring everyone knows what needs to be built and why.

Syntax

run gears story new <name>    # Create a new story
run gears story list          # Show all stories

Subcommands

`gears story new <name>`

Creates a new story file with a standard template.

Arguments:

<name> - Story name (will be slugified for filename)

Creates: .gears/story/story-{slug}.md

`gears story list`

Lists all stories in the project, organized by status.

Displays:

Active stories (currently in progress)
Queued stories (ready to implement)
Completed stories

Working with AI Agents

Story commands are designed for AI agent collaboration. Always have your agent run:

gears story new "Feature Name" - Agent sees the template and next steps
gears story list - Agent understands what features are planned, active, or complete

The output explicitly tells the agent what to do next when creating stories. This ensures consistent documentation and helps the agent understand your project roadmap.

Examples

Create a New Story

$ run gears story new "User Authentication"
✓ Created story: .gears/story/story-user-authentication.md

Agent next:
  1. Populate from user's request:
     - "What We're Building" (feature description)
     - "Why" (user need or business value)
     - "Acceptance Criteria" (3-5 testable conditions)
     - "Technical Notes" (approach and constraints)
  2. Add entry to .gears/story/index.md under "Queued Stories"
  3. Set Status to "Ready" when complete

The story file is created with this template:

# Story: User Authentication

**Status:** Draft
**Project:** _[project name]_
**Created:** 2026-03-25

## What We're Building

_[Plain English description of the feature. One paragraph.]_

## Why

_[Business or user reason. Why does this matter?]_

## Acceptance Criteria

- [ ] _[Criterion 1]_
- [ ] _[Criterion 2]_
- [ ] _[Criterion 3]_

## Technical Notes

_[Architectural considerations, constraints, approach decisions, related ADRs.]_

## Related

- ADR: _[link if applicable]_
- Artifact: _[link if applicable]_

List All Stories

$ gears story list

Active Stories (1):
  ✓ story-user-authentication.md - In Progress

Queued Stories (3):
  • story-file-upload-system.md - Ready
  • story-email-notifications.md - Ready
  • story-admin-dashboard.md - Draft

Completed Stories (5):
  ✓ story-project-initialization.md
  ✓ story-database-schema.md
  ✓ story-api-endpoints.md
  ✓ story-frontend-layout.md
  ✓ story-user-registration.md

Create and Populate a Story

# 1. Create the story
$ gears story new "Password Reset Flow"
✓ Created story: .gears/story/story-password-reset-flow.md

# 2. Edit the file and fill in details
# (Open in your editor and populate all sections)

# 3. Check it shows up in list
$ gears story list
Queued Stories (1):
  • story-password-reset-flow.md - Draft

Story File Structure

Status Field

Stories progress through these statuses:

Draft - Story created but not yet fully defined
Ready - Fully specified and ready to implement
In Progress - Currently being worked on
Complete - Implementation finished and verified

Update the status by editing the story file:

**Status:** Ready

What We're Building

A clear, plain-English description of the feature. One paragraph that explains:

What the feature is
What users will be able to do
What the outcome looks like

Example:

## What We're Building

A password reset system that allows users to securely reset their password via email. Users who forget their password can request a reset link, receive it via email, and set a new password through a secure token-based flow. The system will validate tokens, enforce password requirements, and notify users of successful password changes.

Why

The business or user reason for building this feature. Answers:

What user need does this address?
What problem does it solve?
Why is it important?
What's the value or impact?

Example:

## Why

Users frequently forget passwords, especially after periods of inactivity. Without a self-service reset option, they must contact support, causing frustration and support overhead. This feature reduces support tickets by 40% and improves user experience by enabling instant password recovery.

Acceptance Criteria

3-5 specific, testable conditions that define when the story is complete. Use checkboxes.

Example:

## Acceptance Criteria

- [ ] User can request password reset from login page
- [ ] Reset email is sent within 30 seconds with valid token
- [ ] Token expires after 1 hour
- [ ] User can set new password meeting all requirements (min 8 chars, etc.)
- [ ] User receives confirmation email after successful reset
- [ ] Old password no longer works after reset
- [ ] Invalid/expired tokens show clear error messages

Technical Notes

Implementation approach, architectural decisions, constraints, and technical considerations.

Example:

## Technical Notes

**Implementation Approach:**

- Use Laravel's built-in password reset functionality
- Token storage in `password_reset_tokens` table
- Email via queued job (using Redis queue)
- Rate limit: 3 reset requests per hour per email

**Security Considerations:**

- Tokens are hashed before storage
- Tokens valid for 1 hour only
- Reset invalidates all existing sessions
- Email validation before sending reset link

**Dependencies:**

- Mail configuration must be set up
- Redis queue for email jobs
- Email templates need design

**Related ADRs:**

- ADR-002: Using Laravel's native reset vs. custom implementation

Related Section

Links to related documentation:

## Related

- ADR: [ADR-002: Password Reset Implementation](../adr/002-password-reset.md)
- Story: [story-user-authentication.md](./story-user-authentication.md)
- Design: [Figma mockup](https://figma.com/...)

Common Workflows

Feature Development Flow

# 1. Create story
gears story new "Shopping Cart"

# 2. Populate story with requirements
# (Edit file to add all details)

# 3. Set status to Ready
# (Update Status field in file)

# 4. Implement feature
# (Do the coding work)

# 5. Mark acceptance criteria complete
# (Check off all boxes in file)

# 6. Set status to Complete
# (Update Status field to Complete)

# 7. Sync to cloud
gears sync push

Team Story Review

# Product Manager: Create story
gears story new "Analytics Dashboard"
# Fill in "What We're Building" and "Why"
# Set Status: Draft
gears sync push

# Developer: Pull and review
gears sync pull
gears story list
# Open story file, add Technical Notes
# Set Status: Ready
gears sync push

# Implementation: Work begins
# Update Status: In Progress

Story-Driven Development with AI

# 1. Create detailed story
gears story new "API Rate Limiting"
# Fill in all sections thoroughly

# 2. Share with AI agent
"Please implement the feature described in .gears/story/story-api-rate-limiting.md"

# 3. AI reads story and implements
# AI agent uses story as implementation spec

# 4. Verify acceptance criteria
# Check each criterion against implementation

# 5. Mark complete
# Update story status to Complete

Best Practices

Writing Good Stories

Do:

✅ Use clear, simple language
✅ Focus on user value and outcomes
✅ Make acceptance criteria specific and testable
✅ Include relevant technical constraints
✅ Link to related stories and ADRs
✅ Update status as work progresses

Don't:

❌ Write implementation code in stories (use ADRs for that)
❌ Make stories too large (split into multiple stories)
❌ Leave stories in Draft forever (complete or delete)
❌ Skip the "Why" section (context matters)

Story Size

Good size: Can be completed in 1-3 days
Too large: Takes more than a week → Split into multiple stories
Too small: Takes less than an hour → Combine with related work

Maintenance

# Regular review
gears story list

# Archive completed stories (optional)
mkdir .gears/story/completed
mv .gears/story/story-completed-feature.md .gears/story/completed/

# Keep index updated
# Edit .gears/story/index.md to reflect current state

Troubleshooting

Duplicate Story Names

Problem: Story with similar name already exists

$ gears story new "User Authentication"
✓ Created story: .gears/story/story-user-authentication.md

$ gears story new "User Authentication"
✓ Created story: .gears/story/story-user-authentication-1.md

Solution: Use more specific names or check existing stories first:

gears story list
ls .gears/story/

Story Not Showing in List

Problem: Created story doesn't appear in gears story list

Solution: Check the file's Status field. Only stories with recognized statuses appear:

**Status:** Ready ✅ Will appear
**Status:** Draft ✅ Will appear  
**Status:** todo ❌ Won't appear (invalid status)

Related Commands

gears init - Creates the story/ directory
gears adr - Document technical decisions from stories
gears session - Track daily progress on stories
gears sync - Share stories with team via cloud

Next Steps

After creating a story:

Populate all sections: Fill in What, Why, Criteria, Technical Notes
Review with team: Share for feedback
Set to Ready: Update status when fully specified
Implement: Use story as implementation guide
Track in session: Reference story in daily session files
Mark complete: Update status and check off acceptance criteria

← Command: session | Command: adr →