| name | play-story |
| description | Put a story "in play" by fetching it from GitHub Projects, gathering NFRs, collecting context, and creating ADRs as needed. Invokable with /play-story. |
Play Story Workflow
Overview
Orchestrates the complete story preparation workflow:
- Checks for active story — handles existing work gracefully
- Pulls latest master
- Fetches next Ready story via
/github:story-fetch
- Gathers NFRs via
/arch:gather-nfr
- Collects technical context via
/scout:gather-context
- Creates ADR if needed via
/arch:create-adr
- Displays summary and suggests next steps
Primary entry point for developers starting work on a new story.
Workflow
Step 1: Pull Latest Changes from Master
git fetch origin master
CURRENT_BRANCH=$(git branch --show-current)
if ! git diff-index --quiet HEAD --; then
git stash push -u -m "Auto-stash before pulling master (play-story)"
STASHED=true
fi
git checkout master && git pull origin master
[ "$CURRENT_BRANCH" != "master" ] && git checkout "$CURRENT_BRANCH"
[ "$STASHED" = "true" ] && git stash pop
echo "✓ Master branch updated"
Step 2: Check for Active Story
STORY_FILE="$CLAUDE_PROJECT_DIR/${AGENT_DOCS_DIR:-docs}/active-story.yaml"
[ -f "$STORY_FILE" ] && ACTIVE_STORY_EXISTS=true || ACTIVE_STORY_EXISTS=false
If active story exists, prompt:
⚠️ Active story in progress: #123 - Implement payment checkout
[1] Continue with current story
[2] Switch to a different story
[3] View current story details
[4] Cancel
If switching, archive the current story:
TIMESTAMP=$(date +%Y%m%d-%H%M%S)
mv "$STORY_FILE" "${STORY_FILE%.yaml}-${TIMESTAMP}.yaml"
Step 3: Fetch Next Ready Story
→ Step 2/5: Fetching next Ready story from GitHub Projects
Invoke skill: github:story-fetch
Expected: $AGENT_DOCS_DIR/active-story.yaml created, GitHub status → "In Progress".
If fetch fails, display error and exit. Configuration required — see references/configuration.md.
Step 4: Gather Non-Functional Requirements
→ Step 3/5: Collecting non-functional requirements
Invoke skill: arch:gather-nfr
Expected: interactive Q&A, NFRs saved to active-story.yaml.
If incomplete, offer: continue without NFRs / retry / cancel.
Step 5: Gather Technical Context
→ Step 4/5: Gathering technical context
Invoke skill: scout:gather-context
Expected: docs, codebase, ADRs searched; context saved to active-story.yaml.
If incomplete, offer: continue with partial context / retry / cancel.
Step 6: Create ADR (Conditional)
→ Step 5/5: Creating Architecture Decision Record
Determine if ADR is needed from story labels, NFRs, and context. If yes, invoke skill: arch:create-adr.
Expected: ADR file created in $ADR_DIR, reference saved to active-story.yaml.
If creation fails, offer: continue without ADR / retry / cancel.
Step 7: Final Summary
Display complete story preparation. See references/output-format.md for full format.
Step 8: Offer Quick Actions
What would you like to do next?
[1] Start implementation (open ADR + story in editor)
[2] Review ADR before starting
[3] View story details in browser
[4] Create feature branch
[5] Nothing
Choice:
| Choice | Action |
|---|
| 1 | Open ADR file and GitHub issue URL |
| 2 | Read and display ADR file |
| 3 | open <story URL> |
| 4 | git checkout -b feature/[story-slug]-[timestamp] |
| 5 | Exit |
Error Handling
| Error | Response |
|---|
| Configuration missing | ❌ Configuration not found. See references/configuration.md |
| GitHub auth failed | ❌ Run: gh auth login |
| No Ready stories | ℹ️ No Ready stories in project. Add stories and set Status=Ready. |
| Workflow interrupted | Save partial progress; show completed/pending steps; offer resume instructions |
| Skill execution failed | Show error, troubleshooting tips, and partial progress |
Full error details and troubleshooting: references/troubleshooting.md.
Configuration
See references/configuration.md for required .claude/story-workflow-config.json schema.
Integration
/play-story (this skill)
↓
├── /github:story-fetch
├── /arch:gather-nfr
├── /scout:gather-context
└── /arch:create-adr (conditional)
Then: implement → /git:commit → /github:pull-request
Run skills individually when you only need one step:
/github:story-fetch
/arch:gather-nfr
/scout:gather-context
/arch:create-adr
Best Practices
Use /play-story when starting work on a new story, beginning a development session, or switching stories.
Skip /play-story when you already have an active story prepared or only need one step — run that skill directly instead.
Archive management:
ls -t "$CLAUDE_PROJECT_DIR/${AGENT_DOCS_DIR:-docs}/active-story-"*.yaml | tail -n +6 | xargs rm
Supporting Files
