specweave 0.6.8 → 0.7.0

package/plugins/specweave-github/agents/github-manager/AGENT.md

@@ -49,6 +49,55 @@ As the GitHub Manager agent, I specialize in:
 
 ---
 
+## 🚨 CRITICAL: Concept Mapping (MANDATORY)
+
+**BEFORE any sync operation, you MUST**:
+
+1. **Read the Mapping Reference**: [reference/github-specweave-mapping.md](../../reference/github-specweave-mapping.md)
+2. **Follow mapping rules EXACTLY** - No custom mappings allowed
+3. **Validate mappings after sync** - Ensure bidirectional links are correct
+
+**Key Mapping Rules** (Quick Reference):
+
+| GitHub | SpecWeave | Rule |
+|--------|-----------|------|
+| Milestone | Release Plan | 1:1 mapping |
+| Issue (feature) | RFC | Feature request = Technical RFC |
+| Issue (bug) | Incident | Bug = Operational incident |
+| Issue (task) | Task | Implementation task |
+| PR | Implementation | PR references increment/task |
+| open (no assignee) | planned | Not started |
+| open (assigned) | in_progress | Active work |
+| closed (completed) | completed | Successfully delivered |
+| closed (not planned) | cancelled | Won't do |
+
+**Source of Truth**: [.specweave/docs/internal/delivery/guides/tool-concept-mapping.md](../../../.specweave/docs/internal/delivery/guides/tool-concept-mapping.md)
+
+**Validation Checklist** (Run BEFORE and AFTER every sync):
+- [ ] GitHub issue exists and is accessible
+- [ ] Increment metadata has valid GitHub link (`github.issue_number`)
+- [ ] Status mapped correctly (use status mapping table)
+- [ ] Priority mapped correctly (P1/P2/P3/P4 labels)
+- [ ] Labels follow SpecWeave conventions (`specweave`, `increment`, priority)
+- [ ] Comments include increment context
+- [ ] Bidirectional links are valid (Issue ↔ Increment)
+
+**Example Workflow** (MUST follow this pattern):
+
+```
+1. Read mapping reference (MANDATORY first step)
+2. Read increment files (spec.md, tasks.md, metadata.json)
+3. Apply mapping rules to convert SpecWeave → GitHub
+4. Create/update GitHub issue via gh CLI
+5. Validate mapping (check bidirectional links)
+6. Update increment metadata with GitHub issue details
+7. Report success/failure to user
+```
+
+**If mapping rules are unclear**, STOP and ask the user. Never guess or create custom mappings.
+
+---
+
 ## When to Use This Agent
 
 Invoke the github-manager agent (via Task tool) for:

package/plugins/specweave-github/commands/{github-close-issue.md → close-issue.md}

@@ -1,5 +1,5 @@
 ---
-name: specweave.github.close-issue
+name: 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.
 ---
 

package/plugins/specweave-github/commands/{github-create-issue.md → create-issue.md}

@@ -1,5 +1,5 @@
 ---
-name: specweave.github.create-issue
+name: 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.
 ---
 

package/plugins/specweave-github/commands/{github-status.md → status.md}

@@ -1,5 +1,5 @@
 ---
-name: specweave.github.status
+name: status
 description: Check GitHub sync status for SpecWeave increment. Shows issue number, sync state, progress, last update, and any sync issues. Useful for troubleshooting and monitoring.
 ---
 

package/plugins/specweave-github/commands/{github-sync-tasks.md → sync-tasks.md}

@@ -1,5 +1,5 @@
 ---
-name: github-sync-tasks
+name: sync-tasks
 description: Sync SpecWeave increment tasks to GitHub issues (task-level granularity). Creates milestone, epic issue, and individual issues for each task.
 ---
 

package/plugins/specweave-github/commands/{github-sync.md → sync.md}

@@ -1,5 +1,5 @@
 ---
-name: specweave.github.sync
+name: sync
 description: Synchronize SpecWeave increment with GitHub issue. Updates issue with current progress, task checklist, labels, and comments. Bidirectional sync available.
 ---
 

package/plugins/specweave-github/reference/github-specweave-mapping.md

@@ -0,0 +1,377 @@
+# GitHub ↔ SpecWeave Concept Mapping
+
+**Purpose**: Quick reference for mapping GitHub concepts to SpecWeave architecture
+
+**Source of Truth**: [.specweave/docs/internal/delivery/guides/tool-concept-mapping.md](../../../.specweave/docs/internal/delivery/guides/tool-concept-mapping.md)
+
+**Last Synced**: 2025-11-04
+
+---
+
+## 🚨 CRITICAL: Agents MUST Follow This Mapping
+
+When syncing between GitHub and SpecWeave, you **MUST** use these exact mappings. Do not deviate or create custom mappings.
+
+---
+
+## Core Concept Mapping
+
+| GitHub Concept | SpecWeave Concept | Location | Mapping Rule |
+|----------------|-------------------|----------|--------------|
+| **Milestone** | Release Plan | `.specweave/docs/internal/delivery/release-v{version}.md` | 1 Milestone = 1 Release Plan |
+| **Project** | Increment or Release | Context-dependent | Board scope determines mapping |
+| **Issue (feature)** | RFC | `.specweave/docs/internal/architecture/rfc/####-{name}.md` | Feature request = Technical RFC |
+| **Issue (bug)** | Incident | `.specweave/docs/internal/operations/incidents/{id}.md` | Bug = Operational incident |
+| **Issue (task)** | Task | `.specweave/increments/####-{name}/tasks.md` | Implementation task |
+| **Pull Request** | Implementation | Code + increment link | PR references increment/task |
+| **Label** | Tag | `metadata.json` → tags | Filtering/categorization |
+| **Assignee** | Owner | Task ownership | Person responsible |
+| **Comment** | Progress Update | Task notes, discussions | Async collaboration |
+
+---
+
+## Status Mapping (MUST BE EXACT)
+
+| GitHub State | SpecWeave Status | Notes |
+|--------------|------------------|-------|
+| `open` (no assignee) | `planned` | Not started, no owner |
+| `open` (with assignee) | `in_progress` | Active development |
+| `closed` (completed) | `completed` | Successfully delivered |
+| `closed` (not planned) | `cancelled` | Won't do, out of scope |
+
+**Rule**: Check assignee and close reason to determine SpecWeave status
+
+---
+
+## Priority Mapping
+
+| GitHub Label | SpecWeave Priority | Description |
+|--------------|-------------------|-------------|
+| `priority: critical` | `P1` | Critical, must do now |
+| `priority: high` | `P2` | High priority |
+| `priority: medium` | `P3` | Medium priority |
+| `priority: low` | `P4` | Low priority, nice-to-have |
+| (no label) | `P3` | Default to medium |
+
+---
+
+## Issue Type Detection
+
+**How to classify GitHub issues** (use labels, title prefixes, or body content):
+
+```
+Is the issue...
+├─ A new feature request?
+│  → Create RFC: .specweave/docs/internal/architecture/rfc/####-{name}.md
+│
+├─ A bug/incident?
+│  → Create Incident: .specweave/docs/internal/operations/incidents/{id}.md
+│
+├─ An implementation task?
+│  → Add to tasks.md: .specweave/increments/####-{name}/tasks.md
+│
+└─ An architecture decision?
+   → Create ADR: .specweave/docs/internal/architecture/adr/####-{decision}.md
+```
+
+**Detection Rules**:
+1. **Feature Request**: Labels include `enhancement`, `feature`, OR title starts with `[Feature]`, `[RFC]`
+2. **Bug/Incident**: Labels include `bug`, `incident`, OR title starts with `[Bug]`, `[Incident]`
+3. **Task**: Labels include `task`, `chore`, OR title starts with `[Task]`, `T-###`
+4. **ADR**: Title starts with `[ADR]`, `[Decision]`, OR body contains "We need to decide"
+
+---
+
+## Milestone → Release Plan Mapping
+
+**Mapping Rule**: 1 GitHub Milestone = 1 SpecWeave Release Plan
+
+**Example**:
+```
+GitHub: Milestone "v1.0 - User Authentication" (Due: Jan 31)
+  ↓
+SpecWeave: .specweave/docs/internal/delivery/release-v1.0.md
+```
+
+**Release Plan Contents**:
+- What increments are included (list of increment IDs)
+- What features ship (user-facing)
+- Testing strategy (E2E, integration, unit)
+- Rollout plan (blue-green, canary, phased)
+- Rollback plan (how to revert if issues)
+- Success metrics (DORA, test coverage, uptime)
+
+---
+
+## Issue → Increment Mapping
+
+**Use Case**: Import GitHub issue as SpecWeave increment
+
+**Mapping Logic**:
+1. **Read GitHub Issue**:
+   - Title → Increment title
+   - Body → Spec.md executive summary
+   - Labels → Priority (P1/P2/P3/P4)
+   - Assignee → Increment owner
+
+2. **Create Increment**:
+   ```bash
+   .specweave/increments/####-{kebab-case-title}/
+   ├── spec.md          # From issue body
+   ├── plan.md          # Generated by architect agent
+   ├── tasks.md         # Parsed from issue checklist OR generated
+   └── metadata.json    # Links back to GitHub issue
+   ```
+
+3. **Store Bidirectional Link**:
+   ```json
+   {
+     "github": {
+       "issue_number": 123,
+       "issue_url": "https://github.com/owner/repo/issues/123",
+       "milestone": "v1.0",
+       "labels": ["enhancement", "P1"],
+       "synced_at": "2025-11-04T10:30:00Z"
+     }
+   }
+   ```
+
+---
+
+## Pull Request → Task Linking
+
+**Mapping Rule**: Each PR should reference the increment and task it implements
+
+**PR Title Format**:
+```
+T-007: Implement Claude plugin installer (#130)
+```
+
+**PR Body Template**:
+```markdown
+## Increment
+
+Implements: #130 (Increment 0004: Plugin Architecture)
+Task: T-007 - Implement Claude plugin installer
+
+## Changes
+
+- Added plugin installer CLI
+- Updated plugin loader to auto-install core plugin
+- Added tests for installer
+
+## Testing
+
+- ✅ Unit tests: `npm test src/cli/install.test.ts`
+- ✅ E2E tests: `npm run test:e2e`
+
+## Checklist
+
+- [x] Tests pass
+- [x] Documentation updated
+- [x] CHANGELOG.md updated
+- [x] Increment metadata updated
+
+Closes #130 (when all tasks done)
+```
+
+**Linking Rules**:
+- PR title starts with `T-###:` (task ID)
+- PR body includes `Implements: #issue-number`
+- Use `Closes #issue-number` ONLY when increment is 100% complete
+
+---
+
+## Comment → Progress Update Mapping
+
+**Trigger**: After task completion (post-task-completion hook)
+
+**Format** (posted to GitHub issue):
+```markdown
+## Progress Update
+
+**Increment**: 0004-plugin-architecture
+**Status**: 15% complete (7/48 tasks)
+**Last Updated**: 2025-11-04 10:30:00
+
+### Recently Completed
+- [x] T-007: Implement Claude plugin installer
+
+### Next Up
+- [ ] T-008: Add plugin validation
+- [ ] T-009: Test plugin loading
+
+### Files Changed
+- `src/cli/install.ts` (+127 lines)
+- `src/core/plugin-loader.ts` (+45 lines)
+- `tests/integration/install.test.ts` (+89 lines)
+
+---
+🤖 Auto-updated by SpecWeave GitHub Plugin
+```
+
+---
+
+## Label Conventions
+
+**SpecWeave Standard Labels** (auto-add these):
+- `specweave` - All SpecWeave-synced issues
+- `increment` - Increment tracking issue
+- `P1`, `P2`, `P3`, `P4` - Priority labels
+- `in-progress` - Active development
+- `testing` - Implementation done, testing phase
+- `ready-for-review` - All tasks complete, awaiting review
+- `blocked` - Blocked by external dependency
+
+**Project-Specific Labels** (respect existing):
+- Keep existing labels (don't remove them)
+- Add SpecWeave labels (don't replace)
+- Example: Issue has `frontend` + `enhancement` → Add `specweave` + `P2`
+
+---
+
+## Conflict Resolution Rules
+
+**Scenario**: Both GitHub issue and SpecWeave increment changed
+
+**Resolution Priority** (Source of Truth):
+1. **Status changes** → SpecWeave wins (local is source of truth)
+2. **Content changes** → GitHub wins (team collaboration via GitHub)
+3. **Task completion** → SpecWeave wins (local task tracking)
+4. **Assignee changes** → GitHub wins (team management via GitHub)
+
+**Conflict Handling**:
+```
+IF GitHub issue closed BUT SpecWeave increment not done
+  → Prompt user: "GitHub issue closed but increment not complete. Action?"
+    1) Close increment (trust GitHub)
+    2) Reopen issue (trust SpecWeave)
+    3) Manual resolution
+
+IF SpecWeave increment done BUT GitHub issue still open
+  → Auto-close GitHub issue (SpecWeave is source of truth for completion)
+
+IF Both changed status simultaneously
+  → Log conflict, prompt user for resolution
+```
+
+---
+
+## Examples
+
+### Example 1: Import GitHub Issue as Increment
+
+**GitHub Issue #123**:
+```
+Title: Add user authentication with OAuth2
+Labels: enhancement, P1
+Body: We need OAuth2 authentication with Google and GitHub providers...
+```
+
+**SpecWeave Result**:
+```
+.specweave/increments/0005-user-authentication/
+├── spec.md           # "Add user authentication with OAuth2"
+├── plan.md           # Architect generates implementation plan
+├── tasks.md          # PM generates 12 tasks
+└── metadata.json     # Links to GitHub issue #123
+```
+
+### Example 2: Sync Task Completion to GitHub
+
+**SpecWeave**: Complete T-007 (7/48 tasks, 15%)
+
+**GitHub**: Post comment to issue #130:
+```markdown
+## Progress Update
+**Status**: 15% complete (7/48 tasks)
+
+### Recently Completed
+- [x] T-007: Implement Claude plugin installer
+
+---
+🤖 Auto-updated by SpecWeave
+```
+
+### Example 3: Close Increment → Close Issue
+
+**SpecWeave**: `/specweave:done 0004` (all 48 tasks complete)
+
+**GitHub**: Close issue #130 with comment:
+```markdown
+✅ **Increment Completed**
+
+**Final Stats**:
+- 48/48 tasks completed (100%)
+- 127 test cases passing
+- Duration: 4 weeks
+
+**Deliverables**:
+- Plugin architecture implemented
+- 15 plugins migrated
+- Documentation updated
+
+Closing this issue as the increment is complete.
+
+---
+🤖 Auto-closed by SpecWeave
+```
+
+---
+
+## Traceability
+
+**From GitHub Issue to Code**:
+```
+GitHub Issue #123 "User Authentication"
+  ↓
+SpecWeave Increment: 0005-user-authentication
+  ↓
+spec.md → plan.md → tasks.md
+  ↓
+Code: src/services/auth/
+  ↓
+Tests: tests/e2e/auth.spec.ts
+  ↓
+Pull Requests: #45, #46, #47
+  ↓
+Deployment: production
+```
+
+**From Code to GitHub Issue**:
+```
+File: src/services/auth/oauth.ts
+  ↓
+Increment: 0005-user-authentication (via git blame or folder structure)
+  ↓
+GitHub Issue: #123 (via metadata.json)
+  ↓
+Milestone: v1.0 (release plan)
+```
+
+---
+
+## Validation Checklist
+
+**Before syncing, verify**:
+- [ ] GitHub issue exists and is accessible
+- [ ] Increment metadata has valid GitHub link
+- [ ] Status mapping follows rules above (no custom mappings)
+- [ ] Priority mapped correctly (P1/P2/P3/P4)
+- [ ] Labels follow SpecWeave conventions
+- [ ] Comments include increment context
+- [ ] Bidirectional links are valid
+
+---
+
+## Related Documentation
+
+- **Full Mapping Guide**: [.specweave/docs/internal/delivery/guides/tool-concept-mapping.md](../../../.specweave/docs/internal/delivery/guides/tool-concept-mapping.md)
+- **GitHub Sync Skill**: [../skills/github-sync/SKILL.md](../skills/github-sync/SKILL.md)
+- **GitHub Manager Agent**: [../agents/github-manager/AGENT.md](../agents/github-manager/AGENT.md)
+
+---
+
+**Last Updated**: 2025-11-04
+**Version**: 1.0.0
+**Plugin**: specweave-github

package/plugins/specweave-github/skills/github-sync/SKILL.md

@@ -76,10 +76,16 @@ This issue tracks SpecWeave increment `0004-plugin-architecture`.
 
 ### 2. Progress Updates (Increment → Issue)
 
-**Trigger**: After each `/specweave:do` task completion
+**Trigger**: After each `/specweave:do` task completion (via post-task-completion hook)
 
 **Actions**:
-1. Post comment to GitHub issue:
+1. **Update issue description** (v0.7.0+):
+   - Updates task checklist in issue body
+   - Marks completed tasks with `[x]`
+   - Updates progress bars
+   - Keeps issue description synchronized
+
+2. Post comment to GitHub issue:
    ```markdown
    **Task Completed**: T-007 - Implement Claude plugin installer
 
@@ -90,11 +96,13 @@ This issue tracks SpecWeave increment `0004-plugin-architecture`.
    🤖 Auto-updated by SpecWeave
    ```
 
-2. Update issue labels:
+3. Update issue labels:
    - Add `in-progress` label when first task starts
    - Add `testing` label when implementation phase completes
    - Add `ready-for-review` label when all tasks done
 
+**Note**: As of v0.7.0+, the post-task-completion hook automatically uses `--tasks` flag to update both the issue description AND add comments. This ensures the main issue stays in sync with increment progress.
+
 ### 3. Increment Completion (Close Issue)
 
 **Trigger**: `/specweave:done` closes increment

package/plugins/specweave-infrastructure/commands/{specweave.monitor-setup.md → monitor-setup.md}

@@ -1,3 +1,8 @@
+---
+name: monitor-setup
+description: Set up comprehensive monitoring and observability with Prometheus, Grafana, distributed tracing, and log aggregation
+---
+
 # Monitoring and Observability Setup
 
 You are a monitoring and observability expert specializing in implementing comprehensive monitoring solutions. Set up metrics collection, distributed tracing, log aggregation, and create insightful dashboards that provide full visibility into system health and performance.

package/plugins/specweave-infrastructure/commands/{specweave.slo-implement.md → slo-implement.md}

@@ -1,3 +1,8 @@
+---
+name: slo-implement
+description: Implement Service Level Objectives (SLOs) with reliability standards, SLIs, and error budget-based engineering practices
+---
+
 # SLO Implementation Guide
 
 You are an SLO (Service Level Objective) expert specializing in implementing reliability standards and error budget-based engineering practices. Design comprehensive SLO frameworks, establish meaningful SLIs, and create monitoring systems that balance reliability with feature velocity.