/github-create

description: Create a GitHub issue for a SpecWeave increment. Generates issue from increment specs with task checklist, labels, and milestone. Links issue to increment metadata.

Create GitHub Issue from Increment

Create a GitHub issue for the specified SpecWeave increment.

⛔ MANDATORY: Sync Living Docs BEFORE Creating Issue

**GitHub issue content is generated FROM living docs.** If living docs don't exist or are stale, the issue will be incomplete.

**You MUST run `sw:sync-specs` BEFORE creating (unless using sw:sync-progress):**

# STEP 1: Ensure living docs exist and are current
sw:sync-specs <increment-id>

# STEP 2: Then create GitHub issue
sw-github:create <increment-id>

**Why?**

• Issue body is generated from `.specweave/docs/internal/specs/FS-XXX/`
• User stories and ACs come from living docs
• Task checklist reflects living docs structure
• Without sync-specs, issue will be created from raw increment spec.md (less structured)

**Note:** `sw:sync-progress` calls sync-specs automatically before creating issues.

---

**Usage**: `sw-github:create <increment-id>`

sw:github:create-issue <increment-id> [options]

Arguments

• `increment-id`: Increment ID (e.g., `0004` or `0004-plugin-architecture`)

Options

• `--force`: Force create even if issue already exists
• `--labels`: Comma-separated labels (default: from config)
• `--milestone`: Milestone name (default: from config)
• `--assignee`: Assign to user (@username)
• `--project`: Add to GitHub project (project number)

Examples

# Basic usage
sw:github:create-issue 0004

# With custom labels
sw:github:create-issue 0004 --labels "urgent,backend"

# Assign to developer
sw:github:create-issue 0004 --assignee @developer1

# Add to project
sw:github:create-issue 0004 --project 3

# Force recreate
sw:github:create-issue 0004 --force

What This Command Does

1. **Loads Increment**

• Reads `.specweave/increments/<increment-id>/`
• Parses `spec.md`, `plan.md`, `tasks.md`
• Checks `.metadata.yaml` for existing issue

2. **Detects Repository**

• Extracts repo from git remote
• Format: `owner/repo`
• Verifies write permissions

3. **Generates Issue Body**

• Executive summary from `spec.md`
• Task checklist from `tasks.md`
• Progress tracker (0% initially)
• Links to increment files

4. **Creates GitHub Issue** (via GitHub CLI)

• Uses `gh issue create`
• Applies labels (specweave, increment, priority)
• Sets milestone (if configured)
• Assigns to user (if specified)

5. **Updates Metadata**

• Saves issue number to `.metadata.yaml`
• Stores issue URL
• Logs creation timestamp

6. **Reports Result**

• Issue number and URL
• Labels applied
• Milestone set
• Auto-sync status

Requirements

• GitHub CLI (`gh`) installed and authenticated
• Write access to repository
• Valid increment directory

Configuration

Settings from `.specweave/config.yaml`:

plugins:
  settings:
    specweave-github:
      repo: "owner/repo"  # Auto-detected from git remote
      default_labels:
        - "specweave"
        - "increment"
      milestone: "v0.4.0"  # Optional

Error Handling

**Increment not found**:

❌ Error: Increment '0004' not found

Check: ls .specweave/increments/

**Issue already exists**:

⚠️  GitHub issue already exists for increment 0004

Issue #130: https://github.com/owner/repo/issues/130

Use --force to recreate (will close existing issue first).

**GitHub CLI not authenticated**:

❌ Error: GitHub CLI not authenticated

Please run: gh auth login

Then retry this command.

**No write permissions**:

❌ Error: Insufficient permissions

Required: Write access to owner/repo

Contact repository admin to request access.

Implementation

This command invokes the `github-sync` agent via the Task tool:

const agent = new TaskAgent('github-sync', {
  prompt: `Create GitHub issue for increment ${incrementId}`,
  context: {
    incrementPath: `.specweave/increments/${incrementId}`,
    options: { force, labels, milestone, assignee, project }
  }
});

await agent.execute();

The agent handles:

• File reading (spec.md, tasks.md)
• GitHub API calls (via `gh` CLI)
• Metadata updates
• Error handling

Output Format

Success

📦 Creating GitHub issue for increment 0004...

✓ Increment loaded: 0004-plugin-architecture
✓ Repository detected: owner/repo
✓ Issue body generated (2,500 characters)

Creating issue...
✓ Issue #130 created
✓ Labels applied: specweave, increment, P1
✓ Milestone set: v0.4.0
✓ Metadata updated

✅ GitHub Issue Created! (❌ DEPRECATED FORMAT)

Issue #130: [Increment 0004] Plugin Architecture  # ❌ DEPRECATED
URL: https://github.com/owner/repo/issues/130

Auto-sync enabled: progress will update automatically after each task.

Failure

❌ Failed to create GitHub issue

Error: API rate limit exceeded
Rate limit resets at: 2025-10-30 15:30:00

Options:
1. Wait 30 minutes
2. Use authenticated token (higher limit)

Run sw:github:status 0004 to check sync state.

Related Commands

• `sw:github:sync <increment-id>`: Update existing issue
• `sw:github:close-issue <increment-id>`: Close issue
• `sw:github:status <increment-id>`: Check sync status

Tips

1. **Auto-Create**: Enable `auto_create_issue: true` in config to auto-create issues when running `sw:inc`

2. **Templates**: Customize issue template in `.specweave/github/issue-template.md`

3. **Labels**: Use labels for filtering in GitHub Projects:

• `specweave`: All SpecWeave increments
• `increment`: Differentiate from regular issues
• `P0`/`P1`/`P2`/`P3`: Priority levels

4. **Milestones**: Group increments by release milestone for progress tracking

5. **Projects**: Add issues to GitHub Projects for Kanban-style tracking

Advanced

Custom Issue Body Template

Create `.specweave/github/issue-template.md`:

# [Increment {{id}}] {{title}}

{{summary