Initial commit

2025-11-29 17:56:38 +08:00
commit 712abd45e8
19 changed files with 5806 additions and 0 deletions
--- a/commands/specweave-github-update-user-story.md
+++ b/commands/specweave-github-update-user-story.md
@@ -0,0 +1,156 @@
+---
+name: specweave-github-update-user-story
+description: Update GitHub issue for user story with proper ACs and tasks
+---
+
+# Update User Story GitHub Issue
+
+**Purpose**: Update an existing GitHub issue for a user story to include:
+- ✅ Checkable acceptance criteria (GitHub task checkboxes)
+- ✅ Task connections (links to increment tasks)
+- ✅ Proper formatting and status
+
+**Usage**:
+```bash
+/specweave-github:update-user-story FS-031 US-004
+```
+
+**What It Does**:
+
+1. **Finds user story file**: `.specweave/docs/internal/specs/{project}/FS-031/us-004-*.md`
+2. **Parses content**:
+   - User story description (As a... I want... So that...)
+   - Acceptance criteria with completion status
+   - Tasks from increment tasks.md
+3. **Finds existing GitHub issue**: Searches for `[FS-031][US-004]` or `[FS-031 US-004]`
+4. **Updates issue body**: Replaces with properly formatted content including:
+   - Checkable ACs
+   - Task connections
+   - Status and progress
+
+**Arguments**:
+- `featureId` - Feature ID (e.g., `FS-031`)
+- `userStoryId` - User Story ID (e.g., `US-004`)
+
+**Example**:
+```bash
+# Update US-004 in FS-031
+/specweave-github:update-user-story FS-031 US-004
+
+# Output:
+# 🔍 Finding user story: FS-031/US-004
+#    📄 Found: .specweave/docs/internal/specs/default/FS-031/us-004-bidirectional-status-sync.md
+# 🔍 Searching for existing GitHub issue...
+#    🔗 Found issue #501: [FS-031][US-004] Bidirectional Status Sync
+# 📝 Building updated issue body...
+#    ✅ 6 acceptance criteria (4 completed)
+#    ✅ 6 tasks (3 completed)
+# 🚀 Updating GitHub issue #501...
+#    ✅ Updated successfully!
+#    🔗 https://github.com/owner/repo/issues/501
+```
+
+**What Gets Updated**:
+
+```markdown
+**Feature**: [FS-031](../../_features/_archive/FS-031/FEATURE.md)
+**Status**: complete
+**Priority**: P1
+**Project**: default
+
+---
+
+## User Story
+
+**As a** PM
+**I want** status changes in external tools to sync back to SpecWeave
+**So that** both systems stay in sync without manual updates
+
+📄 View full story: [`us-004-bidirectional-status-sync.md`](...)
+
+---
+
+## Acceptance Criteria
+
+Progress: 4/6 criteria met (67%)
+
+- [x] **AC-US4-01**: SpecWeave status change triggers external update (P1, testable)
+- [x] **AC-US4-02**: External issue close triggers SpecWeave prompt (P1, testable)
+- [x] **AC-US4-03**: External issue reopen triggers SpecWeave prompt (P2, testable)
+- [x] **AC-US4-04**: Sync logs include timestamp and reason (P2, testable)
+- [ ] **AC-US4-05**: Failed syncs retry with exponential backoff (P2, testable)
+- [ ] **AC-US4-06**: Sync works for GitHub, JIRA, and ADO (P1, testable)
+
+---
+
+## Implementation Tasks
+
+Progress: 3/6 tasks complete (50%)
+
+**Increment**: [0031-external-tool-status-sync](../../increments/0031-external-tool-status-sync/)
+
+- [x] [T-008: Create Status Sync Engine (Core)](../../increments/0031/tasks.md#t-008-create-status-sync-engine-core)
+- [x] [T-009: Implement GitHub Status Sync](../../increments/0031/tasks.md#t-009-implement-github-status-sync)
+- [x] [T-010: Implement JIRA Status Sync](../../increments/0031/tasks.md#t-010-implement-jira-status-sync)
+- [ ] [T-011: Implement ADO Status Sync](../../increments/0031/tasks.md#t-011-implement-ado-status-sync)
+- [ ] [T-018: Add Sync Event Logging](../../increments/0031/tasks.md#t-018-add-sync-event-logging)
+- [ ] [T-021: Error Handling & Retry Logic](../../increments/0031/tasks.md#t-021-error-handling-retry-logic)
+
+---
+
+🤖 Auto-synced by SpecWeave User Story Sync
+```
+
+**When to Use**:
+
+- ✅ After completing increment implementation (update task statuses)
+- ✅ After modifying acceptance criteria
+- ✅ When GitHub issue is missing proper formatting
+- ✅ When you want to refresh issue content from living docs
+
+**Related Commands**:
+- `/specweave-github:sync-epic FS-031` - Sync entire epic (all user stories)
+- `/specweave-github:create-issue 0031` - Create issue for increment
+- `/specweave-github:sync 0031` - Two-way sync for increment
+
+---
+
+## Implementation
+
+**File**: `plugins/specweave-github/lib/user-story-content-builder.ts`
+
+**Workflow**:
+1. Parse user story file with `UserStoryContentBuilder`
+2. Search GitHub for existing issue (title pattern matching)
+3. Build rich issue body with checkable ACs and task links
+4. Update issue via `gh issue edit` with new body
+
+**Error Handling**:
+- ✅ Graceful fallback if user story file not found
+- ✅ Clear error if GitHub issue doesn't exist
+- ✅ Validation of required fields (epic, status, etc.)
+
+---
+
+## Execution
+
+When user runs this command, the Claude Code assistant should:
+
+1. Extract `featureId` and `userStoryId` from command arguments
+2. Find user story file in living docs (search all projects)
+3. Use `UserStoryContentBuilder` to parse and build issue body
+4. Search for existing GitHub issue using `gh issue list --search`
+5. Update issue using `gh issue edit --body`
+6. Report success with issue URL
+
+**Tech Stack**:
+- TypeScript (UserStoryContentBuilder class)
+- GitHub CLI (`gh issue list`, `gh issue edit`)
+- YAML frontmatter parsing
+- Markdown formatting
+
+**Testing**:
+- Test with FS-031/US-004 (bidirectional status sync)
+- Verify ACs are checkable
+- Verify tasks link to correct increment tasks.md
+- Verify progress percentages are correct