specweave 0.4.1 → 0.6.0

package/plugins/specweave-github/commands/github-close-issue.md

@@ -0,0 +1,418 @@
+---
+name: specweave.github.close-issue
+description: Close GitHub issue for completed SpecWeave increment. Posts completion summary with final stats, deliverables, and closes the issue. Links closure in increment metadata.
+---
+
+# Close GitHub Issue for Completed Increment
+
+Close the GitHub issue associated with a completed SpecWeave increment.
+
+## Usage
+
+```bash
+/specweave:github:close-issue <increment-id> [options]
+```
+
+## Arguments
+
+- `increment-id`: Increment ID (e.g., `0004` or `0004-plugin-architecture`)
+
+## Options
+
+- `--force`: Force close even if increment not marked complete
+- `--comment`: Custom closing comment (default: auto-generated summary)
+- `--reopen`: Reopen a previously closed issue
+- `--skip-validation`: Skip PM gate validation
+
+## Examples
+
+```bash
+# Basic usage (auto-generates completion summary)
+/specweave:github:close-issue 0004
+
+# With custom comment
+/specweave:github:close-issue 0004 --comment "Merged to main, deploying to production"
+
+# Force close (skip validation)
+/specweave:github:close-issue 0004 --force
+
+# Reopen closed issue
+/specweave:github:close-issue 0004 --reopen
+```
+
+## What This Command Does
+
+1. **Validates Increment Completion**
+   - All tasks completed (48/48)
+   - All tests passing
+   - PM gates passed (from `/specweave:done`)
+   - Documentation updated
+
+2. **Generates Completion Summary**
+   ```markdown
+   ✅ **Increment Completed**
+
+   This increment has been successfully completed and is ready for release.
+
+   ## Final Stats
+
+   - **Tasks**: 48/48 completed (100%)
+   - **Duration**: 4 weeks (2025-10-01 → 2025-10-30)
+   - **Time Tracked**: 240 hours (estimated) / 235 hours (actual)
+   - **Test Coverage**: 127 test cases, 95% coverage
+   - **Priority**: P1
+
+   ## Deliverables
+
+   ✅ Plugin architecture implemented
+   ✅ 15 plugins migrated (github, kubernetes, frontend-stack, ...)
+   ✅ Documentation updated (ADRs, user guides, API docs)
+   ✅ E2E tests passing (Playwright suite)
+   ✅ Integration tests passing (Jest suite)
+
+   ## Key Changes
+
+   - Added plugin system with loader, manager, detector
+   - Implemented 4 adapters (Claude, Cursor, Copilot, Generic)
+   - Created 15 domain-specific plugins
+   - Updated all documentation
+   - Achieved 80% test coverage
+
+   ## Files Changed
+
+   - 48 files modified
+   - +12,500 lines added
+   - -3,200 lines removed
+   - Net: +9,300 lines
+
+   ## Related
+
+   - **Spec**: [spec.md](https://github.com/owner/repo/blob/main/.specweave/increments/0004/spec.md)
+   - **Plan**: [plan.md](https://github.com/owner/repo/blob/main/.specweave/increments/0004/plan.md)
+   - **Tests**: [tests.md](https://github.com/owner/repo/blob/main/.specweave/increments/0004/tests.md)
+
+   ## Next Steps
+
+   - Deploy to production (tracked in #135)
+   - Monitor for issues (see runbook)
+   - Plan next increment (0005-user-authentication)
+
+   ---
+
+   🎉 Thank you to all contributors!
+
+   🤖 Auto-closed by SpecWeave at 2025-10-30 17:00:00
+   ```
+
+3. **Posts Completion Comment**
+   ```bash
+   gh issue comment 130 --body "$(cat completion-summary.md)"
+   ```
+
+4. **Closes GitHub Issue**
+   ```bash
+   gh issue close 130
+   ```
+
+5. **Updates Metadata**
+   ```yaml
+   # .metadata.yaml
+   github:
+     issue_number: 130
+     issue_url: "https://github.com/owner/repo/issues/130"
+     closed_at: "2025-10-30T17:00:00Z"
+     closed_by: "specweave-github-plugin"
+     closing_comment_id: 1234590
+   ```
+
+6. **Reports Result**
+   ```
+   ✅ GitHub issue #130 closed!
+
+   Increment 0004 is complete.
+   Issue: https://github.com/owner/repo/issues/130 (closed)
+   ```
+
+## Configuration
+
+Settings from `.specweave/config.yaml`:
+
+```yaml
+plugins:
+  settings:
+    specweave-github:
+      # Auto-close issues when increment completes
+      auto_close_issue: true
+
+      # Validate before closing
+      require_validation: true
+
+      # Include in closing comment
+      closing_comment:
+        include_stats: true
+        include_deliverables: true
+        include_file_changes: true
+        include_next_steps: true
+```
+
+## Output Format
+
+### Success
+
+```
+🔒 Closing GitHub issue for increment 0004...
+
+Validation:
+✓ All tasks completed (48/48)
+✓ All tests passing (127/127)
+✓ PM gates passed
+✓ Documentation updated
+
+Generating completion summary...
+✓ Final stats calculated
+✓ Deliverables listed
+✓ File changes summarized
+
+Closing issue...
+✓ Posted completion comment (ID: 1234590)
+✓ Issue #130 closed
+✓ Metadata updated
+
+✅ GitHub Issue Closed!
+
+Issue #130: https://github.com/owner/repo/issues/130
+Status: Closed
+Closed at: 2025-10-30 17:00:00
+
+Increment 0004 is complete! 🎉
+```
+
+### Validation Failure
+
+```
+❌ Cannot close issue: Validation failed
+
+Increment 0004 is not yet complete:
+
+Issues:
+✗ Tasks: 45/48 completed (3 remaining)
+  - T-046: Update documentation
+  - T-047: Run E2E tests
+  - T-048: Final review
+
+✗ Tests: 2 tests failing
+  - TC-105: Plugin unload test
+  - TC-127: E2E sync test
+
+✗ PM Gates: Not run yet
+  - Run /specweave:done 0004 first
+
+Fix these issues, then retry:
+  /specweave:github:close-issue 0004
+
+Or force close (not recommended):
+  /specweave:github:close-issue 0004 --force
+```
+
+## Requirements
+
+- GitHub CLI (`gh`) installed and authenticated
+- Increment marked as complete (via `/specweave:done`)
+- Valid GitHub issue exists for increment
+
+## Error Handling
+
+**Increment not complete**:
+```
+❌ Error: Increment 0004 is not complete
+
+Status: in_progress (should be: completed)
+
+Complete the increment first:
+  /specweave:done 0004
+
+Then close the issue:
+  /specweave:github:close-issue 0004
+```
+
+**Issue not found**:
+```
+❌ Error: No GitHub issue found for increment 0004
+
+Check .metadata.yaml for issue number.
+
+Create issue first:
+  /specweave:github:create-issue 0004
+```
+
+**Issue already closed**:
+```
+ℹ️  Issue #130 is already closed
+
+Closed by: @developer1
+Closed at: 2025-10-30 16:00:00
+
+Use --reopen to reopen the issue.
+```
+
+**Permission denied**:
+```
+❌ Error: Insufficient permissions to close issue #130
+
+Required: Write or Admin access to repository
+
+Contact repository admin for access.
+```
+
+## Related Commands
+
+- `/specweave:done <increment-id>`: Mark increment complete (run this first)
+- `/specweave:github:sync <increment-id>`: Sync final progress before closing
+- `/specweave:github:status <increment-id>`: Check issue status
+
+## Tips
+
+1. **Auto-Close**: Enable `auto_close_issue: true` for automatic closing when running `/specweave:done`
+
+2. **Final Sync**: Always run `/specweave:github:sync` before closing to ensure latest progress is posted
+
+3. **Validation**: Don't skip validation (`--force`) unless absolutely necessary - it ensures quality
+
+4. **Custom Comments**: Use `--comment` for release-specific notes (deployment status, known issues, etc.)
+
+5. **Reopening**: If increment needs more work after closing, use `--reopen` to reopen the issue
+
+## Advanced
+
+### Custom Closing Template
+
+Create `.specweave/github/closing-template.md`:
+
+```markdown
+# 🎉 Increment {{id}} Completed!
+
+{{summary}}
+
+## Achievements
+
+{{deliverables}}
+
+## Stats
+
+- Duration: {{duration}}
+- Team size: {{team_size}}
+- Commits: {{commit_count}}
+
+## Deployment
+
+- Merged to: {{branch}}
+- Deployed to: {{environment}}
+- Release: {{version}}
+
+## Thank You
+
+Special thanks to:
+{{contributors}}
+
+---
+
+_Closed by SpecWeave on {{date}}_
+```
+
+### Conditional Closing
+
+Close only if specific conditions met:
+
+```yaml
+plugins:
+  settings:
+    specweave-github:
+      closing_conditions:
+        # Require all tests passing
+        - type: "tests"
+          threshold: 100
+          required: true
+
+        # Require coverage >= 80%
+        - type: "coverage"
+          threshold: 80
+          required: true
+
+        # Require PR merged
+        - type: "pr_merged"
+          required: true
+
+        # Require approval from tech lead
+        - type: "approval"
+          approvers: ["@tech-lead"]
+          required: true
+```
+
+### Post-Closing Actions
+
+Trigger actions after closing:
+
+```yaml
+plugins:
+  settings:
+    specweave-github:
+      post_close:
+        # Create release tag
+        - action: "create_tag"
+          format: "increment-{{id}}"
+
+        # Trigger deployment
+        - action: "github_workflow"
+          workflow: "deploy.yml"
+          inputs:
+            increment: "{{id}}"
+
+        # Notify team
+        - action: "slack_notification"
+          channel: "#releases"
+          message: "Increment {{id}} completed! 🎉"
+
+        # Archive to notion
+        - action: "notion_export"
+          database: "Completed Increments"
+```
+
+### Bulk Close
+
+Close multiple completed increments:
+
+```bash
+# Close all completed increments
+/specweave:github:close-issue --status completed --all
+
+# Close specific increments
+for i in 0004 0005 0006; do
+  /specweave:github:close-issue $i
+done
+```
+
+### Reopen with Context
+
+Reopen issue with explanation:
+
+```bash
+/specweave:github:close-issue 0004 --reopen \
+  --comment "Reopening: Critical bug found in production (issue #140). Need to add rollback mechanism."
+```
+
+### Close and Lock
+
+Close and lock issue to prevent further comments:
+
+```bash
+/specweave:github:close-issue 0004 --lock \
+  --lock-reason "resolved"  # or "off-topic", "spam", "too heated"
+```
+
+---
+
+**Command**: `/specweave:github:close-issue`
+**Plugin**: specweave-github
+**Agent**: github-manager
+**Version**: 1.0.0
+**Last Updated**: 2025-10-30

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

@@ -0,0 +1,307 @@
+---
+name: specweave.github.create-issue
+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.
+
+## Usage
+
+```bash
+/specweave: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
+/specweave:github:create-issue 0004
+
+# With custom labels
+/specweave:github:create-issue 0004 --labels "urgent,backend"
+
+# Assign to developer
+/specweave:github:create-issue 0004 --assignee @developer1
+
+# Add to project
+/specweave:github:create-issue 0004 --project 3
+
+# Force recreate
+/specweave: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-manager` agent via the Task tool:
+
+```typescript
+const agent = new TaskAgent('github-manager', {
+  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!
+
+Issue #130: [Increment 0004] Plugin Architecture
+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 /specweave:github:status 0004 to check sync state.
+```
+
+## Related Commands
+
+- `/specweave:github:sync <increment-id>`: Update existing issue
+- `/specweave:github:close-issue <increment-id>`: Close issue
+- `/specweave:github:status <increment-id>`: Check sync status
+
+## Tips
+
+1. **Auto-Create**: Enable `auto_create_issue: true` in config to auto-create issues when running `/specweave: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
+  /specweave: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
+  /specweave:github:create-issue $inc
+done
+```
+
+### Dry Run
+
+Preview issue body before creating:
+
+```bash
+/specweave:github:create-issue 0004 --dry-run
+```
+
+Output:
+```
+📄 Preview: Issue body for increment 0004
+
+Title: [Increment 0004] Plugin Architecture
+Labels: specweave, increment, P1
+Milestone: v0.4.0
+
+Body:
+---
+# [Increment 0004] Plugin Architecture
+
+**Status**: Planning
+**Priority**: P1
+
+## Executive Summary
+
+Implement a modular plugin architecture for SpecWeave...
+
+[... full body ...]
+
+---
+
+Run without --dry-run to create this issue.
+```
+
+---
+
+**Command**: `/specweave:github:create-issue`
+**Plugin**: specweave-github
+**Agent**: github-manager
+**Version**: 1.0.0
+**Last Updated**: 2025-10-30