A comprehensive requirements management plugin that guides users through the full requirements lifecycle using GitHub Projects for complete traceability and collaboration.
The Requirements Expert plugin helps you transform vague ideas into fully-structured, actionable requirements using a proven methodology:
Vision → Epics → User Stories → Tasks
Everything is managed in GitHub Projects with full parent/child hierarchy, making your entire product roadmap visible and trackable in one place.
- Interactive Discovery: Guided Q&A sessions for each phase using best practices
- Full Lifecycle Support: Vision → Epics → Stories → Tasks with feedback loops
- GitHub Projects Integration: All requirements stored as GitHub issues in GitHub Projects with true hierarchy
- MoSCoW Prioritization: Built-in prioritization framework at every level
- Automated Validation: Quality checks for completeness, consistency, and best practices
- Workflow Orchestration: Seamlessly move from one phase to the next with guided automation
- Claude Code: Install from claude.com/product/claude-code
- GitHub CLI (
gh): Installed and authenticated (gh auth login) - Git repository: A GitHub repository where you want to track requirements
- GitHub permissions:
repoandprojectscopes (read/write)
Verify setup:
gh auth status # Should show ✓ Logged in and list scopesIf project scope is missing, add it:
gh auth refresh -s project# Clone the repository
git clone https://github.com/sjnims/requirements-expert.git
cd requirements-expert
# Load the plugin (note: plugin root is in plugins/ subdirectory)
claude --plugin-dir plugins/requirements-expertIn Claude Code, run:
/install-plugin sjnims/requirements-expert
This installs the plugin from the GitHub marketplace.
/re:init
Creates a GitHub Project for your repository with custom fields (Type, Priority, Status). Provides instructions for configuring project views manually.
/re:discover-vision
Interactive Q&A session that helps you articulate:
- Problem statement
- Target users
- Success metrics
- Core value proposition
Creates a Vision issue in your GitHub Project.
/re:identify-epics
Analyzes your vision and guides you through identifying major features/capabilities. Creates Epic issues as children of the Vision issue.
/re:create-stories
Select an epic and break it down into user stories following INVEST criteria. Creates Story issues as children of the Epic.
/re:create-tasks
Break a story into concrete tasks with acceptance criteria. Creates Task issues as children of the Story.
/re:prioritize
Use MoSCoW framework (Must/Should/Could/Won't) to prioritize at any level.
/re:review
Runs automated validation checks:
- Completeness (all required sections present)
- Consistency (proper linking, no orphans)
- Quality (INVEST criteria for stories, clear acceptance criteria)
- Traceability (vision → epic → story → task chain)
/re:status
View project overview:
- Counts by type (X epics, Y stories, Z tasks)
- Completion status
- Validation results
- Recent activity
All requirements are stored as GitHub issues in GitHub Projects with this hierarchy:
📋 Vision (Issue, Type: Vision)
├── 🎯 Epic 1 (Child Issue, Type: Epic)
│ ├── 📝 Story 1 (Child Issue, Type: Story)
│ │ ├── ✅ Task 1 (Child Issue, Type: Task)
│ │ └── ✅ Task 2 (Child Issue, Type: Task)
│ └── 📝 Story 2 (Child Issue, Type: Story)
│ └── ✅ Task 3 (Child Issue, Type: Task)
└── 🎯 Epic 2 (Child Issue, Type: Epic)
└── 📝 Story 3 (Child Issue, Type: Story)
└── ✅ Task 4 (Child Issue, Type: Task)
- Type: Vision | Epic | Story | Task
- Priority: Must Have | Should Have | Could Have | Won't Have
- Status: Not Started | In Progress | Completed
priority:must-have,priority:should-have,priority:could-have,priority:wont-havetype:vision,type:epic,type:story,type:task
This plugin follows a stateless architecture where GitHub Projects is the single source of truth:
What this means:
- ✅ All requirements data lives in GitHub Issues and Projects
- ✅ No local files or cached state (no
.local.mdfiles) - ✅ Commands always query GitHub directly for current state
- ✅ Works identically across all machines and team members
Why this design?
- Real-time accuracy: Always reflects current project state
- Team collaboration: Everyone sees the same data
- Multi-machine: Use the plugin from any machine without sync
- No conflicts: No local state means no merge/sync issues
- GitHub native: Leverage GitHub's collaboration features fully
Data Flow:
flowchart LR
A[Claude Code<br/>requirements-expert] -->|gh CLI| B[GitHub API]
B -->|Query/Create| C[GitHub Projects]
C -->|Issues + Hierarchy| D[Requirements Data]
D -.->|No Local State| A
style A fill:#0969da,color:#fff
style C fill:#cf222e,color:#fff
style D fill:#1a7f37,color:#fff
Flow explanation:
/re:*commands use GitHub CLI (gh)- CLI talks to GitHub API
- Data stored in GitHub Projects (Issues with parent/child links)
- No local cache - always queries GitHub for current state
This design ensures that all team members always see the same, up-to-date requirements without manual synchronization.
User: "I'd like to build a web app that helps users track their fitness goals"
→ requirements-assistant agent detects this and suggests the plugin
→ User accepts, agent runs /re:init
→ Project created
→ Agent runs /re:discover-vision
→ Interactive Q&A creates Vision issue
→ Agent asks: "Continue to identify epics?"
→ User: "Yes"
→ Agent runs /re:identify-epics
→ ... continues through the lifecycle
User: "I have a vision defined, need help identifying epics"
→ requirements-assistant detects this
→ Agent runs /re:review to validate existing vision
→ If valid, runs /re:identify-epics
→ If issues found, suggests fixing them first
User: "I need to add another epic to my project"
→ User runs /re:identify-epics
→ Command detects existing epics
→ Offers to add new epic or refine existing ones
→ Creates new epic as child of Vision issue
| Command | Description |
|---|---|
/re:init |
Initialize GitHub Project with custom fields |
/re:discover-vision |
Interactive vision discovery session |
/re:identify-epics |
Identify and create epic issues |
/re:create-stories |
Break epic into user stories |
/re:create-tasks |
Break story into tasks with acceptance criteria |
/re:prioritize |
Prioritize requirements using MoSCoW |
/re:review |
Validate requirements for quality and completeness |
/re:status |
Show project overview and status |
The plugin includes eight specialized skills that provide methodology and best practices. Skills are automatically activated when Claude Code detects relevant context in your conversation:
- vision-discovery - How to discover and document product vision
- epic-identification - How to identify and define epics from vision
- user-story-creation - How to write effective user stories (INVEST criteria)
- task-breakdown - How to decompose stories into tasks with acceptance criteria
- prioritization - MoSCoW prioritization framework
- requirements-feedback - Continuous feedback and iteration practices
- shared-patterns - Common patterns for error handling, idempotency, and batch operations
- validation - Requirements validation methodology for completeness, consistency, quality, and traceability
Each skill provides structured guidance, templates, and best practices to ensure high-quality requirements at every level.
Proactively detects when you're working on requirements and offers help. Orchestrates the workflow by:
- Detecting requirements-related queries in your messages
- Suggesting appropriate commands based on context
- Automatically chaining phases (vision → epics → stories → tasks)
- Suggesting validation via
/re:reviewat key milestones - Invoking validation when quality concerns arise
This plugin follows an Agile-inspired requirements methodology:
The high-level product vision answering:
- What problem are we solving?
- Who are we solving it for?
- What does success look like?
Major capabilities or features that:
- Deliver significant value
- Are too large for a single iteration
- Align with the vision
Specific user-facing functionality following INVEST criteria:
- Independent: Can be developed separately
- Negotiable: Details can be discussed
- Valuable: Delivers user value
- Estimable: Size can be estimated
- Small: 1-5 days of work
- Testable: Can be verified
Format: "As a [user], I want [goal] so that [benefit]"
Each story requires 3-5 acceptance criteria that define testable completion conditions.
Concrete implementation steps with:
- Clear, actionable description
- 2-8 hours of work (up to 1-2 days maximum)
- 3-5 acceptance criteria (testable conditions)
- Dependencies identified
- Organized by layer: frontend, backend, data, testing, documentation
The plugin requires minimal configuration and auto-detects most settings:
Auto-detected from git remote in your current directory when running commands.
Requirements: You must run Claude Code from within a git repository that has a GitHub remote configured.
Uses GitHub CLI (gh) authentication. Verify you're logged in:
gh auth status # Should show logged in with 'repo' and 'project' scopesIf not authenticated or missing scopes:
gh auth login # Initial authentication
gh auth refresh -s project # Add project scope if neededAuto-generated from repository name during /re:init, or you can specify a custom name when prompted.
Ensure gh is installed and in your PATH:
brew install gh # macOS
gh auth loginThe plugin requires these GitHub permissions:
repo- To create and manage issuesproject- To create and manage projects
Check with:
gh auth statusRe-authenticate if needed:
gh auth refresh -s projectRun /re:init to create the project, or ensure the project exists in your repository.
GitHub Projects is required for parent/child relationships. Ensure:
- You're using GitHub Projects, not classic projects
- Your repository has Projects enabled
- You have write access to the project
Note: Classic GitHub Projects do not support parent/child issue relationships. You must use GitHub Projects (not classic projects).
The plugin uses labels like type:vision, type:epic, priority:must-have, etc. If labels don't exist in your repository, issues will be created without them.
To create required labels manually:
# Type labels
gh label create "type:vision" --color "0E8A16" --description "Vision requirement"
gh label create "type:epic" --color "1D76DB" --description "Epic requirement"
gh label create "type:story" --color "5319E7" --description "User story"
gh label create "type:task" --color "FBCA04" --description "Task"
# Priority labels (MoSCoW)
gh label create "priority:must-have" --color "B60205" --description "Must Have - Critical"
gh label create "priority:should-have" --color "D93F0B" --description "Should Have - Important"
gh label create "priority:could-have" --color "FBCA04" --description "Could Have - Nice to have"
gh label create "priority:wont-have" --color "C2E0C6" --description "Won't Have - Out of scope"Note: The /re:init command will prompt you to create these labels if they don't exist.
- Start with Vision: Always begin with
/re:discover-visionto establish clear direction - One Epic at a Time: Fully flesh out one epic before moving to the next
- Keep Stories Small: User stories should be 1-5 days of work (INVEST criteria)
- Clear Acceptance Criteria: Every story and task needs 3-5 testable acceptance criteria
- Regular Review: Run
/re:reviewfrequently to catch issues early - Prioritize Often: Use
/re:prioritizeat each phase to focus on high-value work - Iterate: Use the feedback loops to refine requirements as you learn
Contributions welcome! Please:
- Fork the repository
- Create a feature branch
- Test your changes locally with
claude --plugin-dir plugins/requirements-expert - Ensure commands, skills, and agents follow the existing patterns (see CLAUDE.md)
- Submit a pull request with a clear description of changes
This project wouldn't exist without the incredible work of others:
-
Claude - The AI assistant that helped design, build, and refine every aspect of this plugin. From architecture decisions to documentation, Claude was a true collaborator throughout.
-
Anthropic - For creating Claude and Claude Code, the powerful AI coding assistant that makes plugins like this possible.
-
GitHub - For GitHub Projects (the backbone of this plugin's data architecture), GitHub CLI, and GitHub Actions that power our CI/CD.
-
Open Source Tools - The quality tools that keep this project maintainable:
- markdownlint for consistent documentation
- lychee for link validation
- actionlint for workflow validation
- Issues: GitHub Issues
- Discussions: GitHub Discussions
See CHANGELOG.md for detailed release history.
Last updated: December 13, 2025