specweave 1.0.593 → 2.0.3

package/plugins/specweave/commands/github-create.md

@@ -1,330 +0,0 @@
----
-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):**
-
-```bash
-# 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>`
-
-```bash
-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
-
-```bash
-# 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`:
-
-```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:
-
-```typescript
-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`:
-
-```markdown
-# [Increment {{id}}] {{title}}
-
-{{summary}}
-
-## Details
-
-- **Spec**: [spec.md]({{spec_url}})
-- **Priority**: {{priority}}
-- **Duration**: {{duration}}
-
-## Tasks
-
-{{tasks}}
-
----
-
-_Auto-created by SpecWeave_
-```
-
-### Bulk Create
-
-Create issues for multiple increments:
-
-```bash
-for i in 0004 0005 0006; do
-  sw:github:create-issue $i
-done
-```
-
-Or using a script:
-
-```bash
-# Create issues for all increments in backlog
-ls .specweave/increments/_backlog/ | while read inc; do
-  sw:github:create-issue $inc
-done
-```
-
-### Dry Run
-
-Preview issue body before creating:
-
-```bash
-sw:github:create-issue 0004 --dry-run
-```
-
-Output:
-```
-📄 Preview: Issue body for increment 0004 (❌ DEPRECATED FORMAT)
-
-Title: [Increment 0004] Plugin Architecture  # ❌ DEPRECATED
-Labels: specweave, increment, P1
-Milestone: v0.4.0
-
-Body:
----
-# [Increment 0004] Plugin Architecture  # ❌ DEPRECATED
-
-**Status**: Planning
-**Priority**: P1
-
-## Executive Summary
-
-Implement a modular plugin architecture for SpecWeave...
-
-[... full body ...]
-
----
-
-Run without --dry-run to create this issue.
-```
-
----
-
-**Command**: `sw:github:create-issue`
-**Plugin**: specweave-github
-**Agent**: github-sync
-**Version**: 1.0.0
-**Last Updated**: 2025-10-30

package/plugins/specweave/commands/github-pull.md

@@ -1,139 +0,0 @@
----
-description: Pull latest changes from GitHub Issues (like git pull). Imports comments, labels, and status changes.
----
-
-# GitHub Pull Command
-
-**Usage**: `sw-github:pull [increment-id]`
-
-**Purpose**: Pull latest changes from GitHub Issues to your local increment (like `git pull`)
-
----
-
-## Quick Start
-
-```bash
-# Pull for current/active increment
-sw-github:pull
-
-# Pull for specific increment
-sw-github:pull 0005
-```
-
----
-
-## What Gets Pulled
-
-| Field | Behavior |
-|-------|----------|
-| **Status** | Issue state (open/closed) -> increment status |
-| **Labels** | Priority labels imported |
-| **Comments** | New team comments imported to notes |
-| **Assignees** | Updated if changed |
-| **Milestone** | Iteration/sprint mapping |
-
----
-
-## Command Behavior
-
-When user runs this command:
-
-### 1. Resolve Increment
-
-```typescript
-const incrementId = args.incrementId || await findActiveIncrement();
-
-const metadata = JSON.parse(await fs.readFile(
-  `.specweave/increments/${incrementId}/metadata.json`, 'utf-8'
-));
-
-const issueNumber = metadata?.external_sync?.github?.issue;
-if (!issueNumber) {
-  console.log(`Not linked to GitHub. Run: sw-github:create ${incrementId}`);
-  return;
-}
-```
-
-### 2. Fetch and Compare
-
-```
-Use Skill tool: Skill({ skill: "sw-github:github-sync", args: "Pull changes from GitHub for increment {increment-id}.
-
-Issue: #{issueNumber}
-
-Steps:
-1. Fetch issue #{issueNumber} via gh api
-2. Compare GitHub state vs local status
-3. Apply conflict resolution (external wins for status)
-4. Import new comments to increment notes
-5. Update labels/assignees in metadata
-6. Display what changed"
-```
-
-### 3. Display Changes
-
-```
-Pulled from GitHub
-
-Issue: #123
-Repository: owner/repo
-
-Changes Applied:
-  Status: open -> closed (mapped to: completed)
-  Labels: +bug, +priority-high
-  Comments: 2 new imported
-
-Last synced: 2025-12-04 10:30:00
-URL: https://github.com/owner/repo/issues/123
-```
-
----
-
-## Status Mapping
-
-| GitHub State | SpecWeave Status |
-|--------------|------------------|
-| `open` | in-progress |
-| `closed` | completed |
-
----
-
-## Examples
-
-### Example 1: Simple Pull
-
-```
-User: sw-github:pull
-
-Claude:
-Pulling from GitHub...
-  Increment: 0005-payment-integration
-  Issue: #123
-
-Changes Applied:
-  Status: open -> closed (completed)
-
-Pull complete!
-```
-
-### Example 2: Not Linked
-
-```
-User: sw-github:pull 0005
-
-Claude:
-Increment 0005 not linked to GitHub yet.
-
-To link: sw-github:create 0005
-```
-
----
-
-## Related Commands
-
-| Command | Purpose |
-|---------|---------|
-| `sw-github:push` | Push local changes to GitHub |
-| `sw-github:sync` | Two-way sync (pull + push) |
-| `sw-github:status` | Check sync status |
-| `sw-github:create` | Create GitHub issue |

package/plugins/specweave/commands/github-push.md

@@ -1,151 +0,0 @@
----
-description: Push local progress to GitHub Issues (like git push). Updates issue with task completion checklist.
----
-
-# GitHub Push Command
-
-**Usage**: `sw-github:push [increment-id]`
-
-**Purpose**: Push local progress to GitHub Issues (like `git push`)
-
----
-
-## Quick Start
-
-```bash
-# Push current/active increment
-sw-github:push
-
-# Push specific increment
-sw-github:push 0005
-```
-
----
-
-## What Gets Pushed
-
-| Field | Source |
-|-------|--------|
-| **Task Checklist** | Updated from tasks.md completion |
-| **Comment** | Auto-generated progress update |
-| **Labels** | Status labels updated |
-| **State** | Closed if 100% complete |
-
----
-
-## Command Behavior
-
-When user runs this command:
-
-### 1. Check Permission Gate
-
-```typescript
-const config = JSON.parse(await fs.readFile('.specweave/config.json', 'utf-8'));
-const canUpdateExternal = config?.sync?.settings?.canUpdateExternalItems ?? false;
-
-if (!canUpdateExternal) {
-  console.log(`
-Permission Denied: GitHub writes disabled
-
-To enable: Set sync.settings.canUpdateExternalItems = true
-
-Or use read-only: sw-github:pull ${incrementId}
-`);
-  return;
-}
-```
-
-### 2. Calculate Progress
-
-```typescript
-const tasksContent = await fs.readFile(
-  `.specweave/increments/${incrementId}/tasks.md`, 'utf-8'
-);
-
-const totalTasks = (tasksContent.match(/### T-\d+/g) || []).length;
-const completedTasks = (tasksContent.match(/\[x\] completed/gi) || []).length;
-const percentage = Math.round((completedTasks / totalTasks) * 100);
-```
-
-### 3. Invoke Push Sync
-
-```
-Use Skill tool: Skill({ skill: "sw-github:github-sync", args: "Push progress to GitHub for increment {increment-id}.
-
-Issue: #{issueNumber}
-Progress: {completedTasks}/{totalTasks} ({percentage}%)
-
-Steps:
-1. Update issue body task checklist
-2. Add progress comment
-3. Update labels if needed
-4. Close issue if 100% complete (if canUpdateStatus)
-5. Update sync timestamp"
-```
-
-### 4. Display Result
-
-```
-Pushed to GitHub
-
-Issue: #123
-Repository: owner/repo
-
-Progress: 6/10 tasks (60%)
-
-Updates:
-  Task checklist: 6/10 checked
-  Comment: Progress update posted
-  Labels: +in-progress
-
-URL: https://github.com/owner/repo/issues/123
-```
-
----
-
-## Examples
-
-### Example 1: Simple Push
-
-```
-User: sw-github:push
-
-Claude:
-Pushing to GitHub...
-  Increment: 0005-payment-integration
-  Issue: #123
-
-Progress: 8/10 tasks (80%)
-Checklist updated, comment posted.
-
-Push complete!
-```
-
-### Example 2: 100% Complete
-
-```
-User: sw-github:push 0005
-
-Claude:
-Pushing to GitHub...
-
-Progress: 10/10 tasks (100%)
-
-Updates:
-  Task checklist: 10/10 checked
-  Comment: "All tasks complete!"
-  Issue: CLOSED
-
-Ready for next: sw:done 0005
-```
-
----
-
-## Related Commands
-
-| Command | Purpose |
-|---------|---------|
-| `sw-github:pull` | Pull changes from GitHub |
-| `sw-github:sync` | Two-way sync (pull + push) |
-| `sw-github:status` | Check sync status |
-| `sw-github:close` | Close issue with summary |

package/plugins/specweave/commands/github-reconcile.md

@@ -1,111 +0,0 @@
----
-description: Reconcile GitHub issue states with increment statuses. Fixes drift by closing issues for completed increments and reopening issues for resumed increments.
----
-
-# GitHub Status Reconciliation
-
-Scan all increments and fix any drift between local metadata.json status and GitHub issue states.
-
-## Usage
-
-```bash
-sw-github:reconcile [options]
-```
-
-## Options
-
-- `--dry-run`: Preview changes without making them
-- `--verbose`: Show detailed output for each issue checked
-- `--full`: Deep reconciliation — removes issue search cap (1000 vs 100) and paginates all milestones
-
-## What It Does
-
-1. **Scans** all non-archived increments
-2. **Compares** metadata.json status with GitHub issue state
-3. **Fixes** mismatches:
-   - `metadata=completed` + `GH=open` → **Close** the issue
-   - `metadata=in-progress` + `GH=closed` → **Reopen** the issue
-
-## When to Use
-
-- After manual metadata.json edits
-- After git pulls that changed increment statuses
-- When you notice open issues for completed work
-- As a periodic health check
-
-## Implementation
-
-Run the reconciliation using the GitHubReconciler:
-
-```typescript
-import { GitHubReconciler } from '../../../src/sync/github-reconciler.js';
-
-const reconciler = new GitHubReconciler({
-  projectRoot: process.cwd(),
-  dryRun: args.includes('--dry-run'),
-  full: args.includes('--full'),
-});
-
-const result = await reconciler.reconcile();
-
-// Report results
-console.log(`\nReconciliation complete:`);
-console.log(`  Scanned: ${result.scanned} increments`);
-console.log(`  Fixed: ${result.closed} closed, ${result.reopened} reopened`);
-if (result.errors.length > 0) {
-  console.log(`  Errors: ${result.errors.length}`);
-}
-```
-
-## Example Output
-
-```
-📊 Scanning 5 increment(s) for GitHub state drift...
-
-  ✅ Issue #765 (0056-plugin-fix/US-001): State matches (open)
-  ❌ Issue #771 (0066-import-wizard/US-003): OPEN but should be CLOSED (status=completed)
-     ✅ Closed issue #771
-  ❌ Issue #763 (0063-multi-repo/US-001): CLOSED but should be OPEN (status=in-progress)
-     ✅ Reopened issue #763
-
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-📊 RECONCILIATION SUMMARY
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-   Increments scanned: 5
-   Mismatches found:   2
-   Issues closed:      1
-   Issues reopened:    1
-   Errors:             0
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-```
-
-## Dry Run Mode
-
-```bash
-sw-github:reconcile --dry-run
-```
-
-Shows what would be changed without making any modifications:
-
-```
-  ❌ Issue #771 (0066-import-wizard/US-003): OPEN but should be CLOSED
-     [DRY RUN] Would close issue #771
-
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-📊 RECONCILIATION SUMMARY
-   ⚠️  DRY RUN - No changes were made
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-```
-
-## Requirements
-
-- GitHub CLI (`gh`) installed and authenticated
-- `sync.github.enabled = true` in config.json
-- `sync.settings.canUpdateExternalItems = true` in config.json
-
-## Related Commands
-
-- `sw-github:status`: View sync status for increments
-- `sw-github:sync`: Manual sync to GitHub
-- `sw:done`: Close increment (triggers auto-close)
-- `sw:resume`: Resume increment (now triggers auto-reopen)