8.7 KiB
8.7 KiB
description
| description |
|---|
| Create detailed implementation specification from a GitHub issue through interactive planning |
Spec Issue Command
You are helping a developer create a detailed implementation specification from a GitHub issue.
Command Parameters
Issue Parameter:
--issue=<number>- GitHub issue number (optional - will prompt if not provided)
Repository Parameter:
--repo=<owner/repo>- Repository (default: auto-detect from git remote)
Usage Examples:
/git-workflow:spec-issue # Interactive - prompts for issue
/git-workflow:spec-issue --issue=15 # Spec for issue #15
/git-workflow:spec-issue --issue=22 --repo=owner/repo # Specify repo
Objective
Transform a high-level GitHub issue into a detailed, actionable implementation specification including:
- Overview and scope
- Architecture decisions and rationale
- Component design breakdown
- File structure
- Phased implementation checklist
- Technical considerations
- Next steps
Activated Agent
Activate: git-workflow-specialist agent
Activated Skills
github-workflow-patterns- For GitHub best practices and workflowsgithub-issue-analysis- For understanding issue structure and prioritization
Process
Step 0: Issue Selection
If --issue parameter is not provided, help user select an issue interactively.
Fetch Recent Issues
# List recent open issues
gh issue list --limit 20 --json number,title,labels,createdAt
Present Issue List
Display issues in a clear, scannable format:
Which issue would you like to create a spec for?
Recent open issues:
1. #22 - Define scripts for programmatic auditing checks [enhancement]
2. #21 - Compare performance using different models
3. #20 - Plugin creation through GH issue workflow
4. #17 - MCP Confluence Integration
5. #15 - Add Git-Workflow Plugin [enhancement, git, github]
6. #14 - Outline Python-Dev Plugin for personal use Marketplace [enhancement]
...
Enter issue number (or 'cancel' to exit):
User provides number:
- Validate the number exists in the list
- If valid, proceed to Step 1
- If invalid, show error and re-prompt
User types 'cancel':
- Exit gracefully: "Spec creation cancelled."
If --issue Provided
Skip the selection step and proceed directly to Step 1 with the provided issue number.
Step 1: Fetch Issue Details
Once issue number is selected, fetch complete issue information:
# Fetch issue with all details
gh issue view <number> --json title,body,labels,comments,createdAt,updatedAt
Parse and display:
Fetching issue #<number>...
✓ Issue loaded
Title: <issue-title>
Labels: [label1, label2, ...]
Created: <date>
Description:
<issue-body>
Comments: <number> comments
[Optionally show recent comments if relevant to planning]
Ready to create specification for this issue.
Validate issue exists:
- If issue not found: "❌ Issue # not found. Please check the issue number."
- Exit gracefully
Step 2: Interactive Planning
Ask clarifying questions to understand the implementation approach. Adapt questions based on issue content and labels.
Question 1: Implementation Type
What type of implementation is this?
1. 🔌 New plugin
2. 📝 New command in existing plugin
3. ✨ Feature enhancement to existing component
4. 🔧 Refactoring/improvement
5. 📚 Documentation
Enter choice (1-5):
Question 2: Architecture Pattern (if applicable)
For plugins or complex features:
What architecture pattern should we use?
1. Workflow Orchestration + Agent + Skills (complex, interactive workflows)
2. Commands + Skills (moderate complexity, reusable patterns)
3. Commands only (simple, standalone functionality)
Enter choice (1-3):
Question 3: Core Capabilities
Describe the core capabilities needed (1-2 sentences):
[User input]
Question 4: Components Needed
Based on architecture choice, ask about specific components:
For Agent + Skills + Commands:
What components are needed?
- Agent name/role:
- Skills (comma-separated):
- Commands (comma-separated):
For Commands + Skills:
What components are needed?
- Commands (comma-separated):
- Skills (comma-separated, if any):
Question 5: Implementation Phases
How should implementation be phased?
1. Single phase (implement all at once)
2. Multiple phases (specify below)
[If multiple phases]
Describe phases (one per line):
Phase 1:
Phase 2:
...
Question 6: Technical Constraints
Any technical constraints or considerations? (optional)
- Token budgets?
- Performance requirements?
- Integration dependencies?
[User input or skip]
Store all answers to use in spec generation (Step 3).
Step 3: Generate Specification
Using answers from Step 2 and the issue details, generate a comprehensive specification document.
Spec Structure
# [Issue Title] - Implementation Specification
**Generated**: [date]
**Status**: Design Specification for Implementation
---
## Overview
**Purpose**: [From core capabilities answer]
**Use Cases**:
- [Extracted from issue or inferred]
**Scope**:
- **Included**: [What will be implemented]
- **Excluded**: [What is out of scope, if any]
---
## Architecture Decision
**Pattern**: [From Question 2 answer]
**Rationale**:
[Explain why this pattern was chosen based on requirements]
**Benefits**:
- [List key benefits of this approach]
---
## Component Design
[Based on architecture choice - include agents, skills, commands sections]
### Agent (if applicable)
- **Name**: [agent-name]
- **Role**: [description]
- **Responsibilities**: [what it does]
### Skills (if applicable)
For each skill:
- **Name**: [skill-name]
- **Purpose**: [what it provides]
- **Used By**: [which components use it]
### Commands
For each command:
- **Name**: [command-name]
- **Purpose**: [what it does]
- **Parameters**: [list parameters]
- **Workflow**: [high-level flow]
---
## File Structure
\```
[directory tree of files to create]
\```
---
## Implementation Checklist
[Generate phases from Question 5]
### Phase 1: [name]
- [ ] Task 1
- [ ] Task 2
### Phase 2: [name]
- [ ] Task 1
---
## Technical Considerations
[From Question 6 or inferred from issue]
---
## Next Steps
1. Review specification
2. [Additional steps based on context]
Generate this spec based on all gathered information.
Step 4: Output Options
Present interactive output options:
✓ Specification generated successfully!
What would you like to do with this spec?
1. 📄 Write to markdown file
2. 💬 Post as comment to GitHub issue #<number>
3. 📺 Display in terminal only
4. ✅ Both - write to file AND post to issue
Enter your choice (1-4):
| Option | Actions | Commands |
|---|---|---|
| 1. Write to File | Prompt for path (default: ./specs/issue-<number>-spec.md)Create specs/ directoryWrite spec to file |
mkdir -p specscat > path <<'EOF' [spec] EOF |
| 2. Post to Issue | Post spec as comment to GitHub issue | gh issue comment <number> --body "[spec]" |
| 3. Display Only | Print full spec to console No file/issue creation |
(Display spec content) |
| 4. Both | Execute options 1 AND 2 Prompt for path, write file, post to issue |
(Combine 1 + 2) |
Confirmation messages (after execution):
- Option 1:
✓ Spec written to [path] - Option 2:
✓ Spec posted to https://github.com/<owner>/<repo>/issues/<number> - Option 3:
Note: Spec displayed only (not saved) - Option 4: Both confirmations from 1 + 2
Important Notes
- Be thorough: Generate comprehensive specs that answer implementation questions
- Be specific: Include concrete component names, file paths, and task breakdowns
- Be helpful: Provide context and rationale for decisions
- Be flexible: Adapt structure based on implementation type
- Ask when unclear: If issue is vague, ask clarifying questions
Error Handling
Issue not found:
❌ Issue #<number> not found in this repository.
Check:
- Issue number is correct
- You have access to this repository
- Issue hasn't been deleted
Try: gh issue list
gh command not available:
❌ GitHub CLI (gh) is not installed or not authenticated.
Install: https://cli.github.com/
Authenticate: gh auth login
Cannot proceed without gh CLI.
Invalid input:
❌ Invalid choice. Please enter 1, 2, 3, or 4.
[Re-prompt]
Remember: This command transforms ideas into actionable plans. Be thorough, ask good questions, and generate clear specifications that make implementation straightforward.
Remember: This command is fully interactive and guides users through creating comprehensive specs without requiring them to know all parameters upfront.