gh-sjnims-requirements-expert-plugins-requirements-expert/commands/init.md

---
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