--- 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=` - GitHub issue number (optional - will prompt if not provided) **Repository Parameter:** - `--repo=` - Repository (default: auto-detect from git remote) **Usage Examples:** ```bash /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 workflows - **`github-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 ```bash # 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: ```bash # Fetch issue with all details gh issue view --json title,body,labels,comments,createdAt,updatedAt ``` **Parse and display:** ``` Fetching issue #... ✓ Issue loaded Title: Labels: [label1, label2, ...] Created: Description: Comments: 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 ```markdown # [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 # 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--spec.md`)
Create `specs/` directory
Write spec to file | `mkdir -p specs`
`cat > path <<'EOF' [spec] EOF` | | **2. Post to Issue** | Post spec as comment to GitHub issue | `gh issue comment --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///issues/` - 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 # 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.