| name | story-workflow |
| description | Refine, analyze, improve, and groom user stories / issues with structured templates and codebase-aware technical analysis. Supports ADO, Jira, GitLab, GitHub, and local markdown files as work item sources via provider adapters. Use this skill whenever the user mentions story refinement, story grooming, story analysis, story improvement, acceptance criteria, user story quality, sprint readiness, or commands like /story-improve, /story-refine, /story-analyze, or /story-groom. Also trigger when the user references work item or issue IDs (or local .md file paths) in the context of improving or reviewing story quality. This skill is never invoked autonomously — it only runs when explicitly requested by a human user.
|
| allowed-tools | Read, Write, Edit, Bash, Grep, Glob, Agent, mcp__azure-devops__*, mcp__jira__*, mcp__gitlab__*, mcp__github__*, mcp__zoho__* |
| argument-hint | <command> [work-item-id-or-filepath] |
Story Workflow Skill
A skill for improving user story / issue quality through structured refinement, readiness
analysis, and codebase-aware technical grooming. Integrates with the configured work item
provider (ADO, Jira, GitLab, GitHub, or local markdown file) via MCP or the filesystem
to read and post back to work items.
Provider Resolution
Before executing any command, read .claude/context/provider-config.md to determine
the active work item provider. Then read the corresponding adapter from
skills/providers/<provider>/work-items.md for exact tool names, parameter mappings,
and field extraction logic.
For local-markdown: The work item ID is a file path (absolute or relative), not a
numeric or key-style ID. No MCP call is needed — use the Read tool directly on the path.
Verify the file exists before proceeding; if it does not, inform the user and stop.
Usage
/story-workflow <command> [work-item-id] [extra-args...]
Examples:
/story-workflow improve 123456 (ADO)/story-workflow improve PROJ-123 (Jira)/story-workflow improve 42 (GitLab / GitHub)/story-workflow improve 123456 "Team decided to limit scope to admin users only, defer integrations"/story-workflow improve ./stories/auth-story.md (local-markdown)/story-workflow analyze 123456/story-workflow analyze ./stories/auth-story.md (local-markdown)/story-workflow refine PROJ-123/story-workflow groom 42/story-workflow groom ./stories/auth-story.md (local-markdown)
Argument Parsing
Parse $ARGUMENTS to extract the command and its arguments:
- First token (required): The command name — one of
improve, analyze, refine, groom.
- Second token (required): The Work Item / Issue ID (format depends on provider).
- Remaining tokens: Passed through as extra arguments (e.g., session notes for
improve or refine).
If the first token is missing or doesn't match a known command, show the usage line above
and list the four commands with one-line descriptions. Do not guess.
Command Routing
Route to the matching command file based on the first token:
| Command | File | Requires Work Item ID |
|---|
improve | commands/improve.md | Yes |
analyze | commands/analyze.md | Yes |
refine | commands/refine.md | Yes |
groom | commands/groom.md | Yes |
Read the command file and follow its instructions. Pass the work item ID and any extra
arguments to the command.
Validation before routing:
- If no work item ID was provided, ask for it — do not proceed without one.
- Check that
.claude/context/provider-config.md exists. If missing, remind the user to run /init-workspace first.
- For
local-markdown: verify the file at the given path exists and is readable. If not, report the resolved absolute path and stop.
Prerequisites
- Work item provider MCP tools available (as configured in
provider-config.md)
- Team repos cloned locally (for
groom command)
- Run
/init-workspace before using story commands (one-time setup)
Templates
Story templates and output formats live in templates/. Commands reference them as needed.
Do not modify templates during command execution.
Context Files
Generated by the standalone /init-workspace skill. Each developer generates their own
set by running /init-workspace. Files live at .claude/context/ (git-ignored):
.claude/context/provider-config.md — Provider settings, tool mappings, and field mappings..claude/context/repos-metadata.md — Describes each repo's purpose, stack, and domain..claude/context/repos-paths.md — Maps repo names to local filesystem paths..claude/context/conventions.md — Team coding patterns and architectural conventions.
