zhongwei/gh-sjnims-requirements-expert-plugins-requirements-expert
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Initial commit

Browse Source
This commit is contained in:
Zhongwei Li
2025-11-30 08:57:33 +08:00
commit b4a8193ca4
28 changed files with 7229 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

280
commands/init.md Normal file
View File

@@ -0,0 +1,280 @@
---
name: re:init
description: Initialize a GitHub Project for requirements management with custom fields and views
allowed-tools: [Bash, AskUserQuestion]
---
# Initialize Requirements Project
Initialize a GitHub Project for requirements management. This command is **idempotent** - safe to run multiple times without creating duplicates.
## Prerequisites Validation
1. **Check GitHub CLI:**
- Verify `gh` command exists: `command -v gh`
- If not found: "GitHub CLI (gh) is not installed. Install it:"
- macOS: `brew install gh`
- Other: <https://cli.github.com/>
2. **Check Authentication:**
- Run: `gh auth status`
- If command fails: "Not authenticated with GitHub. Run: `gh auth login`"
- Check output for required scopes: `repo` and `project`
- If missing `project` scope: "Refresh authentication with: `gh auth refresh -s project`"
- Note: Output could show "Token scopes: 'gist', 'project', 'read:org', 'repo', 'workflow'" format
3. **Detect Repository:**
- Get repository info: `gh repo view --json nameWithOwner`
- If fails: "Not in a git repository with GitHub remote. Navigate to your project repository."
- Parse JSON to extract nameWithOwner (format: `{"nameWithOwner":"owner/repo"}`)
- Split nameWithOwner on "/" to get the owner (before the "/")
- Example: "sjnims/requirements-expert" → owner="sjnims"
## Project Setup
4. **Get Project Name:**
- Use AskUserQuestion:
- question: "What should we name the GitHub Project for requirements tracking?"
- header: "Project Name"
- multiSelect: false
- options:
- label: "[Repository Name] Requirements"
description: "Standard naming convention following best practices (recommended)"
- label: "[Repository Name] Backlog"
description: "Alternative naming for backlog-style requirements tracking"
- label: "[Repository Name] Roadmap"
description: "Emphasizes long-term planning and feature roadmap view"
- Note: User can select "Other" to provide a custom project name
- Replace [Repository Name] placeholder with the repository name (the part after the "/" in `nameWithOwner` from step 3). For example, if `nameWithOwner` is "sjnims/requirements-expert", use "requirements-expert"
- Store the user's choice for project creation
5. **Check for Existing Project (Idempotency):**
- List existing projects: `gh project list --owner [owner] --format json`
- Parse JSON response: `{"projects":[{"id":"...","number":4,"title":"...","url":"..."}]}`
- Search the `projects` array for a project where `title` matches the chosen name
- If found:
- Inform user: "Found existing project '[title]' at [url]"
- Capture project `number` (not `id`) for subsequent commands
- Note: Project number is the sequential number (1, 2, 3...) visible in the URL
- Skip to step 7 (field creation)
- If not found:
- Proceed to create project
6. **Create GitHub Project:**
- Create project: `gh project create --owner [owner] --title "[name]" --format json`
- Parse JSON response to extract `number` and `url`
- If creation fails:
- Display the actual error message from gh CLI
- Use AskUserQuestion for interactive recovery:
- question: "Project creation failed. How would you like to proceed?"
- header: "Recovery"
- multiSelect: false
- options:
- label: "Retry"
description: "Try creating the project again"
- label: "Check permissions"
description: "Show commands to verify and fix GitHub CLI permissions"
- label: "Exit"
description: "Stop and let me fix the issue manually"
- Handle user choice:
- If "Retry": Re-execute the project creation command (line 64). If creation fails again, present the recovery options again (allowing user to continue trying, check permissions, or exit)
- If "Check permissions":
- Run: `gh auth status`
- Display the output
- Show refresh command: `gh auth refresh -s project`
- Explain: "Projects require 'repo' and 'project' scopes"
- Note: Projects are owner-scoped (user/org), not repository-scoped
- After showing diagnostics, present the same recovery options again (Retry, Check permissions, or Exit)
- If "Exit": Exit gracefully with message:
```
Project creation failed. Manual steps to resolve:
1. Check authentication: `gh auth status`
2. Verify scopes include 'repo' and 'project'
3. Refresh token if needed: `gh auth refresh -s project`
4. Ensure you have permission to create projects for owner: [owner]
5. Retry the command: `/re:init`
Error details: [show original error message]
```
- If creation succeeds:
- Inform user: "Created project: [name] at [url]"
- Capture project `number` for subsequent commands
## Custom Fields Setup
7. **Check Existing Fields:**
- List all existing fields once: `gh project field-list [project-number] --owner [owner] --format json`
- If command fails:
- Log warning: "Could not retrieve existing fields, will attempt to create all fields"
- Set field names list to empty (this ensures subsequent steps will attempt creation)
- Continue to step 8
- If command succeeds:
- Parse JSON response to extract field names
- Store the list of existing field names for use in subsequent steps
- Example: If response contains fields with names "Title", "Status", "Assignees", store these names
- This single query replaces multiple redundant field-list calls
8. **Create Type Field (If Missing):**
- Check if "Type" exists in the stored field names list from step 7
- If exists:
- Inform user: "Type field already exists, skipping creation"
- If not exists:
- Create field with all options in one command:
```
gh project field-create [project-number] --owner [owner] \
--name "Type" \
--data-type SINGLE_SELECT \
--single-select-options "Vision,Epic,Story,Task" \
--format json
```
- If command fails: Note the failure but continue (user can add field manually)
- Inform user: "Created Type field with options: Vision, Epic, Story, Task"
9. **Create Priority Field (If Missing):**
- Check if "Priority" exists in the stored field names list from step 7
- If exists:
- Inform user: "Priority field already exists, skipping creation"
- If not exists:
- Create field with all options:
```
gh project field-create [project-number] --owner [owner] \
--name "Priority" \
--data-type SINGLE_SELECT \
--single-select-options "Must Have,Should Have,Could Have,Won't Have" \
--format json
```
- If command fails: Note the failure but continue
- Inform user: "Created Priority field with MoSCoW options"
10. **Create Status Field (If Missing):**
- Check if "Status" exists in the stored field names list from step 7
- If exists:
- Inform user: "Status field already exists, skipping creation"
- If not exists:
- Create field with all options:
```
gh project field-create [project-number] --owner [owner] \
--name "Status" \
--data-type SINGLE_SELECT \
--single-select-options "Not Started,In Progress,Completed" \
--format json
```
- If command fails: Note the failure but continue
- Inform user: "Created Status field with workflow states"
## Views Setup (Manual Configuration Required)
11. **Views Setup - Manual Instructions:**
- Note: GitHub CLI does not support view creation or configuration
- All views must be created manually via the GitHub web interface
- Inform user: "Project views require manual setup in the GitHub web interface"
- Display project URL: [project-url]
**Manual Setup Instructions:**
1. **Access the project**:
- Open the project in your browser: [project-url]
- Or navigate to: Repository → Projects → [Project Name]
2. **Create recommended views**:
**View 1: "By Type" (Board View)**
- Click "+ New view" → Board
- Name: "By Type"
- Layout: Board
- Group by: Type
- Shows: All items grouped by Vision/Epic/Story/Task
**View 2: "By Priority" (Board View)**
- Click "+ New view" → Board
- Name: "By Priority"
- Layout: Board
- Group by: Priority
- Shows: All items grouped by Must Have/Should Have/Could Have/Won't Have
**View 3: "Active Work" (Table View)**
- Click "+ New view" → Table
- Name: "Active Work"
- Layout: Table
- Filter: Status = "In Progress"
- Shows: Only items currently being worked on
**View 4: "Backlog" (Table View)**
- Click "+ New view" → Table
- Name: "Backlog"
- Layout: Table
- Filter: Status = "Not Started"
- Shows: Work ready to be started
3. **Set default view** (optional):
- Click "..." menu on preferred view
- Select "Set as default"
## Success Reporting
12. **Display Success Message:**
```
✅ GitHub Project initialized successfully!
Project: [Project Name]
URL: [Project URL]
Custom Fields Created:
- Type (Vision, Epic, Story, Task)
- Priority (Must Have, Should Have, Could Have, Won't Have)
- Status (Not Started, In Progress, Completed)
Next Steps:
1. Run `/re:discover-vision` to create your product vision
2. Then `/re:identify-epics` to identify major capabilities
3. Use `/re:status` anytime to see project overview
```
## Error Handling
- Exit gracefully on any validation failure (steps 1-3)
- Display clear, actionable error messages
- If project creation fails: Show gh error output and suggest remedies
- If field creation fails: Note which fields failed but continue
- Views require manual setup: Provide comprehensive manual instructions
## Implementation Notes
**Key Architectural Points:**
- **Projects are owner-scoped, not repository-scoped**: Use `--owner [owner]` not `--repo`
- **Use project number, not project ID**: Commands expect the sequential number (1, 2, 3...) visible in URLs, not the GraphQL ID (PVT_xxx)
- **Field creation supports comma-separated options**: Use `--single-select-options "option1,option2,option3"` to create field and options in one command
- **Idempotency is critical**: Always check for existing resources before creating
**State Management:**
This command intentionally does NOT persist local state (e.g., project number in a `.local.md` file). Design rationale:
1. **GitHub is the source of truth**: All requirements data lives in GitHub Issues and Projects
2. **Idempotency**: Commands query GitHub directly, ensuring they always reflect current state
3. **Multi-machine support**: No local state means the plugin works identically across machines
4. **No sync issues**: Local state could become stale; direct queries are always accurate
Other `/re:*` commands will query GitHub to discover the project rather than relying on cached references.
**Command Execution:**
- All operations should be non-interactive (use `--format json` where available)
- Parse JSON output using `jq` or similar tools
- Use `--owner [owner]` for all project and field commands
- Project number is extracted from JSON response during creation or listing
**Error Handling:**
- Exit gracefully on validation failures (steps 1-3)
- Continue on non-critical failures (field/view creation)
- Provide clear, actionable error messages
- Include fallback manual instructions when CLI lacks functionality
**Testing Notes:**
- Verified with gh CLI version 2.x on macOS
- Commands tested: `gh project list`, `gh project create`, `gh project field-list`, `gh project field-create`
- View creation is not supported via CLI; manual setup via web interface is required