docs-stories Skill

Purpose

Provide complete CRUD operations for SDLC documentation in the Bestays project. This skill handles all story/task management and context retrieval operations.

Single Interface: Anytime you need to read/write anything about the codebase in terms of documenting, use this skill.

When to Use This Skill

CREATE:

• Creating new user stories
• Creating new tasks for stories

READ:

• Finding stories by domain or keywords
• Listing tasks for a story
• Getting current active task
• Retrieving full context for a user story (via index)
• Finding all files/commits/decisions for a story (via index)

UPDATE:

• Updating task state (NOT_STARTED, IN_PROGRESS, COMPLETED)
• Updating task phase (RESEARCH, PLANNING, IMPLEMENTATION, TESTING, VALIDATION)
• Adding commits to task record
• Adding modified files to task record
• Setting current active task

DELETE:

• Not implemented (stories/tasks are permanent audit trail)

Available Scripts

All scripts located in: .claude/skills/docs-stories/scripts/

Story Management

story_create.py - Create New User Story

Usage:

python3 .claude/skills/docs-stories/scripts/story_create.py <domain> <feature> <scope>

Arguments:

• domain: Story category (auth, booking, admin, infrastructure, etc.)
• feature: Main feature name (login, signup, dashboard, etc.)
• scope: Specific scope (admin, user, validation, etc.)

Example:

python3 .claude/skills/docs-stories/scripts/story_create.py auth login admin
# Creates: .sdlc-workflow/stories/auth/US-001-auth-login-admin.md

What it does:

1. Scans existing stories to find next story number
2. Creates story file from template
3. Replaces placeholders with provided values
4. Returns story ID and file path

---

story_find.py - Find Existing Stories

Usage:

python3 .claude/skills/docs-stories/scripts/story_find.py [domain] [--status STATUS]

Arguments:

• domain (optional): Filter by domain (auth, booking, etc.)
• --status (optional): Filter by status (READY, IN_PROGRESS, COMPLETED)

Examples:

# Find all stories
python3 .claude/skills/docs-stories/scripts/story_find.py

# Find all auth stories
python3 .claude/skills/docs-stories/scripts/story_find.py auth

# Find all completed stories
python3 .claude/skills/docs-stories/scripts/story_find.py --status COMPLETED

# Find completed auth stories
python3 .claude/skills/docs-stories/scripts/story_find.py auth --status COMPLETED

What it does:

1. Scans .sdlc-workflow/stories/ for story files
2. Parses story metadata (status, domain, title)
3. Filters by criteria
4. Returns list of matching stories

---

Task Management

task_create.py - Create New Task

Usage:

python3 .claude/skills/docs-stories/scripts/task_create.py <story_id> <task_number> <semantic_name>

Arguments:

• story_id: Parent story ID (e.g., US-001)
• task_number: Task number (1, 2, 3, etc.)
• semantic_name: Semantic slug (2-3 words, lowercase, hyphens)

Example:

python3 .claude/skills/docs-stories/scripts/task_create.py US-001 1 clerk-mounting
# Creates: .claude/tasks/TASK-001/
# With STATE.json: {"story": "US-001", "semantic_name": "clerk-mounting", ...}

What it does:

1. Creates task folder at .claude/tasks/TASK-{number}/
2. Creates phase subfolders (research/, planning/, etc.)
3. Creates STATE.json with metadata
4. Creates README.md from template
5. Returns task ID and folder path

---

task_list.py - List Tasks for Story

Usage:

python3 .claude/skills/docs-stories/scripts/task_list.py <story_id>

Arguments:

• story_id: Story ID to list tasks for (e.g., US-001)

Example:

python3 .claude/skills/docs-stories/scripts/task_list.py US-001
# Returns:
# TASK-001 (clerk-mounting): IN_PROGRESS, PLANNING phase
# TASK-002 (login-tests): NOT_STARTED, RESEARCH phase

What it does:

1. Scans .claude/tasks/ for tasks with matching story
2. Reads STATE.json for each task
3. Returns list with status and phase

---

task_get_current.py - Get Current Active Task

Usage:

python3 .claude/skills/docs-stories/scripts/task_get_current.py

Example:

python3 .claude/skills/docs-stories/scripts/task_get_current.py
# Returns: TASK-001 (US-001, clerk-mounting)

What it does:

1. Checks current git branch for TASK-XXX reference
2. Reads task STATE.json
3. Returns current task details

---

task_set_current.py - Set Current Active Task

Usage:

python3 .claude/skills/docs-stories/scripts/task_set_current.py <task_id>

Arguments:

• task_id: Task ID to make active (e.g., TASK-001)

Example:

python3 .claude/skills/docs-stories/scripts/task_set_current.py TASK-001
# Switches to task branch or updates tracking

What it does:

1. Validates task exists
2. Updates tracking (implementation depends on approach)
3. Returns confirmation

---

task_update_state.py - Update Task Status

Usage:

python3 .claude/skills/docs-stories/scripts/task_update_state.py <task_id> <status>

Arguments:

• task_id: Task ID (e.g., TASK-001)
• status: New status (NOT_STARTED, IN_PROGRESS, COMPLETED)

Example:

python3 .claude/skills/docs-stories/scripts/task_update_state.py TASK-001 IN_PROGRESS
# Updates STATE.json: {"status": "IN_PROGRESS", ...}

What it does:

1. Reads task STATE.json
2. Updates status field
3. Updates timestamp
4. Writes back to STATE.json

---

task_update_phase.py - Update Task Phase

Usage:

python3 .claude/skills/docs-stories/scripts/task_update_phase.py <task_id> <phase>

Arguments:

• task_id: Task ID (e.g., TASK-001)
• phase: New phase (RESEARCH, PLANNING, IMPLEMENTATION, TESTING, VALIDATION)

Example:

python3 .claude/skills/docs-stories/scripts/task_update_phase.py TASK-001 PLANNING
# Updates STATE.json: {"phase": "PLANNING", ...}

What it does:

1. Reads task STATE.json
2. Updates phase field
3. Updates timestamp
4. Writes back to STATE.json

---

task_add_commit.py - Add Commit to Task Record

Usage:

python3 .claude/skills/docs-stories/scripts/task_add_commit.py <task_id> <commit_hash>

Arguments:

• task_id: Task ID (e.g., TASK-001)
• commit_hash: Git commit hash

Example:

python3 .claude/skills/docs-stories/scripts/task_add_commit.py TASK-001 abc123def
# Updates STATE.json: {"commits": ["abc123def"], ...}

What it does:

1. Reads task STATE.json
2. Appends commit hash to commits array
3. Writes back to STATE.json

---

task_add_file_modified.py - Add Modified File to Task Record

Usage:

python3 .claude/skills/docs-stories/scripts/task_add_file_modified.py <task_id> <file_path>

Arguments:

• task_id: Task ID (e.g., TASK-001)
• file_path: Path to modified file (relative to project root)

Example:

python3 .claude/skills/docs-stories/scripts/task_add_file_modified.py TASK-001 apps/server/core/clerk.py
# Updates STATE.json: {"files_modified": ["apps/server/core/clerk.py"], ...}

What it does:

1. Reads task STATE.json
2. Appends file path to files_modified array (no duplicates)
3. Writes back to STATE.json

---

Context Indexing and Retrieval

context_index.py - Index All SDLC Artifacts

Status: To be implemented (US-001D)

Usage:

python3 .claude/skills/docs-stories/scripts/context_index.py [--story-id US-XXX] [--output PATH]

Arguments:

• --story-id (optional): Index specific story only
• --output (optional): Output path (default: .sdlc-workflow/.index/sdlc-index.json)

Example:

# Index all stories
python3 .claude/skills/docs-stories/scripts/context_index.py

# Index specific story
python3 .claude/skills/docs-stories/scripts/context_index.py --story-id US-001

# Custom output path
python3 .claude/skills/docs-stories/scripts/context_index.py --output /tmp/index.json

What it does:

1. Scans .sdlc-workflow/stories/ for story files
2. Scans .claude/tasks/ for task folders
3. Parses git log for commits with story/task references
4. Parses file headers for design patterns and trade-offs
5. Builds structured JSON index with bidirectional cross-references
6. Outputs: .sdlc-workflow/.index/sdlc-index.json

Index Schema:

{
  "metadata": {
    "generated": "2025-11-07T10:30:00Z",
    "total_stories": 5,
    "total_tasks": 12
  },
  "stories": {
    "US-001": {
      "id": "US-001",
      "title": "Login Flow Validation",
      "file": ".sdlc-workflow/stories/auth/US-001-...",
      "tasks": ["TASK-001-file-headers"],
      "commits": ["abc123"],
      "implementation_files": ["apps/frontend/tests/..."]
    }
  },
  "tasks": {
    "TASK-001-file-headers": {
      "story": "US-001",
      "folder": ".claude/tasks/TASK-001/",
      "decisions": "...",
      "files_modified": ["..."]
    }
  },
  "commits": {...},
  "files": {...}
}

---

Retrieving Full Context for a Story

Once the index is built, retrieve full context:

Step 1: Read the Index

import json
with open('.sdlc-workflow/.index/sdlc-index.json') as f:
    index = json.load(f)

Step 2: Query by Story ID

story = index['stories']['US-001']
# Returns: title, file, tasks, commits, files, acceptance_criteria

Step 3: Traverse Cross-References

# Get all tasks for story
tasks = [index['tasks'][task_id] for task_id in story['tasks']]

# Get all commits for story
commits = [index['commits'][commit_hash] for commit_hash in story['commits']]

# Get all files for story
files = [index['files'][file_path] for file_path in story['implementation_files']]

Common Query Templates

Query: "Full context for US-001"

Steps:

1. Read index
2. Get story metadata (title, acceptance criteria)
3. Get all tasks (semantic names, decisions, subagents)
4. Get all commits (timeline)
5. Get all files (design patterns, trade-offs)
6. Format output for readability

Expected Output:

# Full Context: US-001 - Login Flow Validation

## Story
- Title: Login Flow Validation
- Status: COMPLETED
- Acceptance Criteria:
  - Valid credentials authenticate user
  - Invalid credentials rejected
  - E2E tests passing

## Tasks
1. TASK-001-file-headers
   - Decision: Add file headers with design patterns for instant context
   - Trade-offs: Maintenance overhead vs clarity
   - Subagent: dev-backend-fastapi

## Timeline
- 2025-10-16: feat: add file headers (abc123)
- 2025-10-20: test: add E2E login tests (def456)

## Files Modified
- apps/server/core/clerk.py
  - Design Pattern: Singleton
  - Architecture Layer: Core Service
  - Trade-offs: Vendor lock-in vs faster development

## Time to Context: < 3 minutes

---

Query: "Files changed in US-001"

Steps:

1. Read index
2. Get story['implementation_files']
3. For each file, get metadata (design pattern, layer, trade-offs)
4. Format as list

Expected Output:

Files changed in US-001:
- apps/server/core/clerk.py (Singleton, Core Service)
- apps/server/api/clerk_deps.py (Dependency Injection, API Layer)
- apps/frontend/tests/e2e/login.spec.ts (Test, E2E Layer)

---

Query: "Timeline for US-001"

Steps:

1. Read index
2. Get story['commits']
3. Sort by date
4. Format chronologically

Expected Output:

Timeline for US-001:
- 2025-10-16 14:30: feat: add file headers to backend deps (abc123)
  Files: clerk.py, deps.py
  Task: TASK-001-file-headers

- 2025-10-20 10:15: test: add E2E login tests (def456)
  Files: login.spec.ts
  Task: TASK-002-login-tests

---

Query: "Decisions for US-001"

Steps:

1. Read index
2. Get all tasks for story
3. Extract decisions field from each task
4. Format as list

Expected Output:

Decisions for US-001:

TASK-001-file-headers:
- Chose Clerk over Auth0 for authentication
- Trade-offs: Vendor lock-in vs faster development
- Added file headers with design patterns for instant context

TASK-002-login-tests:
- Chose Playwright over Cypress for E2E tests
- Trade-offs: Newer tool vs more examples available

---

Query: "Trade-offs for authentication"

Steps:

1. Read index
2. Search files for "authentication" or "auth" keywords
3. Extract trade-offs sections from file headers
4. Format as list

Expected Output:

Trade-offs for authentication:

apps/server/core/clerk.py (Singleton):
- Pro: Shared Clerk client reduces memory usage
- Con: Vendor lock-in to Clerk
- When to revisit: If Clerk pricing becomes prohibitive

apps/server/api/clerk_deps.py (Dependency Injection):
- Pro: Easy to mock for testing
- Con: Extra indirection layer

---

Performance Expectations

Indexing:

• Time: < 10 seconds for 20 stories, 50 tasks, 150 commits
• Memory: < 500MB
• Output: < 2MB JSON file

Retrieval:

• Full context for any story: < 3 minutes (vs 30-60 minutes manual)
• Files changed query: < 30 seconds
• Timeline query: < 30 seconds
• Decisions query: < 30 seconds

---

Integration with Other Skills

sdlc-orchestrator skill:

• Orchestrator uses docs-stories to update task state during phase transitions
• Example: After completing planning phase, orchestrator calls task_update_phase.py TASK-001 IMPLEMENTATION

planning-quality-gates skill:

• Quality gates reference docs-stories for creating planning artifacts
• Example: Create planning/quality-gate-checklist.md via task folder structure

Memory MCP:

• Coordinator loads SDLC patterns from Memory MCP before using docs-stories
• Example: Load "Task Folder System" entity to understand structure

---

Best Practices

For Coordinators:

1. Always use docs-stories for story/task CRUD operations (don't manually create files)
2. Update task state after each phase transition
3. Run context_index.py periodically (after completing stories)
4. Use retrieval queries to restore context in new sessions

For Subagents:

1. Read task STATE.json to understand current task context
2. Add commits and files_modified after implementation
3. Reference task folder for implementation spec and decisions
4. Save reports to task folder (subagent-reports/)

For Both:

• Never bypass docs-stories scripts (maintain consistency)
• Always use semantic task names (self-documenting)
• Document decisions and trade-offs in task folders
• Update STATE.json after significant progress

---

Troubleshooting

Problem: story_create.py fails with "Not in a project with .claude/" Solution: Run from project root or any subdirectory containing .claude/

Problem: task_create.py fails with "Task already exists" Solution: Use different task number or delete existing task folder

Problem: Index is outdated after new commits Solution: Re-run context_index.py to rebuild index

Problem: Context retrieval returns no results for recent story Solution: Ensure story file exists and index has been built

---

Future Enhancements (Out of Scope)

• Delete operations (story/task archival)
• Story/task templates with variants
• Incremental indexing (only scan changed files)
• Web UI for browsing index
• Full-text search across decisions and reports
• Automated index rebuild on git commit (hook)

---

Skill Version: 1.0 Last Updated: 2025-11-07 Maintained By: Bestays SDLC Team