specweave 0.1.9 → 0.3.1

package/src/commands/specweave.sync-github.md

@@ -0,0 +1,269 @@
+---
+name: specweave.sync-github
+description: Sync SpecWeave increments with GitHub issues. Supports import, export, bidirectional sync, and granular issue operations
+---
+
+# Sync GitHub Command
+
+You are a GitHub synchronization expert. Help the user sync between GitHub and SpecWeave with granular control.
+
+## Available Operations
+
+### Milestone-Level Operations
+
+**1. Import GitHub Milestone as SpecWeave Increment**
+```
+/specweave.sync-github import milestone-1
+```
+
+**2. Sync existing linked Increment with GitHub**
+```
+/specweave.sync-github sync 0003
+```
+
+**3. Export SpecWeave Increment to GitHub**
+```
+/specweave.sync-github export 0001
+```
+
+### Granular Issue Operations
+
+**4. Add specific Issue to existing Increment**
+```
+/specweave.sync-github add #42 to 0003
+/specweave.sync-github add #42              # Adds to current increment
+```
+
+**5. Create Increment from specific issues (cherry-pick)**
+```
+/specweave.sync-github create "User Authentication" from #42 #45 #47
+/specweave.sync-github create "Bug Fixes Sprint 1" from #10 #15 #20
+```
+
+**6. Show sync status**
+```
+/specweave.sync-github status
+/specweave.sync-github status 0003          # Status of specific increment
+```
+
+## Your Task
+
+When the user runs this command:
+
+1. **Parse the command arguments**:
+   - Operation: import, sync, export, add, create, or status
+   - ID: GitHub issue number (e.g., #123) or Increment ID (e.g., 0001)
+
+2. **Execute the operation**:
+
+   **For import Milestone**:
+   ```typescript
+   import { GitHubClient } from './src/integrations/github/github-client';
+   import { GitHubMapper } from './src/integrations/github/github-mapper';
+
+   const client = new GitHubClient();
+   const mapper = new GitHubMapper(client);
+   const result = await mapper.importMilestoneAsIncrement('milestone-1');
+   ```
+
+   **For add issue**:
+   ```typescript
+   import { GitHubIncrementalMapper } from './src/integrations/github/github-incremental-mapper';
+
+   const incrementalMapper = new GitHubIncrementalMapper(client);
+   const result = await incrementalMapper.addIssueToIncrement('0003', 42);
+   ```
+
+   **For create from issues**:
+   ```typescript
+   const result = await incrementalMapper.createIncrementFromIssues(
+     'User Authentication',
+     [42, 45, 47]
+   );
+   ```
+
+   **For sync**:
+   ```typescript
+   const result = await mapper.syncIncrement('0003');
+   ```
+
+   **For export**:
+   ```typescript
+   const result = await mapper.exportIncrementAsIssues('0001');
+   ```
+
+3. **Show results**:
+   - Display sync summary
+   - Show conflicts (if any)
+   - List created/updated files
+   - Provide links to GitHub and SpecWeave
+
+4. **Handle errors gracefully**:
+   - Check if GITHUB_TOKEN exists in environment
+   - Validate increment/issue exists
+   - Check repository is configured
+   - Show clear error messages
+
+## Examples
+
+### Example 1: Import Milestone
+**User**: `/specweave.sync-github import milestone-1`
+**You**:
+- Import Milestone "milestone-1" from GitHub
+- Show: "✅ Imported as Increment 0004"
+- List: "Created: spec.md, tasks.md, RFC document"
+- Link: "GitHub: https://github.com/user/repo/milestone/1 | Increment: .specweave/increments/0004/"
+
+### Example 2: Add Issue to Current Increment
+**User**: `/specweave.sync-github add #42`
+**You**:
+- Determine current increment (latest or from context)
+- Fetch issue #42 from GitHub
+- Add to increment's spec.md (under ## User Stories or ## Bugs based on labels)
+- Update tasks.md
+- Update RFC
+- Show: "✅ Added Issue #42 to Increment 0003"
+- Display: "Type: feature | Title: User authentication | Status: open"
+
+### Example 3: Add Bug Issue to Specific Increment
+**User**: `/specweave.sync-github add #123 to 0003`
+**You**:
+- Fetch issue #123 from GitHub (labeled as "bug")
+- Add to increment 0003's spec.md (under ## Bugs)
+- Update tasks.md
+- Update RFC
+- Show: "✅ Added Bug #123 to Increment 0003"
+- Display: "Type: bug | Priority: high | Title: Fix login redirect"
+
+### Example 4: Create Increment from Multiple Issues
+**User**: `/specweave.sync-github create "User Authentication" from #42 #45 #47`
+**You**:
+- Fetch all 3 issues from GitHub
+- Determine types based on labels (feature, bug, enhancement)
+- Create new increment 0005
+- Group by type in spec.md:
+  - ## User Stories (#42, #45)
+  - ## Technical Tasks (#47)
+- Generate RFC with all items
+- Show: "✅ Created Increment 0005 with 3 issues"
+- Display table:
+  ```
+  | Type    | Issue | Title              |
+  |---------|-------|--------------------|
+  | Feature | #42   | User login UI      |
+  | Feature | #45   | OAuth backend      |
+  | Task    | #47   | Setup provider     |
+  ```
+
+### Example 5: Sync Existing Increment
+**User**: `/specweave.sync-github sync 0003`
+**You**:
+- Read increment 0003
+- Find linked GitHub issues (from spec.md frontmatter.github_issues)
+- Fetch current state from GitHub
+- Detect changes (status, labels, assignees, comments)
+- Show conflicts if any
+- Apply sync bidirectionally:
+  - Update GitHub issue status based on task completion
+  - Update spec.md based on GitHub changes
+- Display: "✅ Synced 0003 | Updated: 2 issues | #42 → closed, #45 → in-progress"
+
+### Example 6: Status Overview
+**User**: `/specweave.sync-github status`
+**You**:
+- Scan all increments for GitHub metadata
+- Show table:
+  ```
+  | Increment | Title            | GitHub Issues | Last Sync          |
+  |-----------|------------------|---------------|--------------------|
+  | 0003      | Test Feature     | 0 issues      | 2025-10-28 17:42   |
+  | 0004      | User Auth        | 3 issues      | 2025-10-28 18:00   |
+  | 0005      | Bug Fixes        | 5 issues      | Never              |
+  ```
+
+## GitHub Issue Format
+
+When creating GitHub issues from increments, use this format:
+
+```markdown
+# [Increment ###] Title
+
+## Overview
+[From spec.md]
+
+## Business Value
+[From spec.md if exists]
+
+## User Stories
+
+- [ ] **US1**: [Title] (P1)
+  - Acceptance test 1
+  - Acceptance test 2
+- [ ] **US2**: [Title] (P2)
+  - Acceptance test 1
+
+## Implementation Tasks
+
+### Phase 1: [Phase Name]
+- [ ] **T001**: [Task description]
+- [ ] **T002**: [Task description]
+
+### Phase 2: [Phase Name]
+- [ ] **T010**: [Task description]
+
+## Documentation
+
+- [Specification](.specweave/increments/####-name/spec.md)
+- [Tasks](.specweave/increments/####-name/tasks.md)
+- [Architecture](.specweave/docs/architecture/) (if applicable)
+
+## Dependencies
+
+- Depends on: #[issue-number] (if applicable)
+
+## Success Criteria
+
+[From spec.md]
+
+---
+*Created by SpecWeave - [Learn more](https://github.com/specweave/specweave)*
+```
+
+## Bidirectional Sync
+
+When syncing an increment that already has `github_issues` in frontmatter:
+- Update existing issues instead of creating new ones
+- Sync status changes:
+  - Task completion → Close GitHub issue
+  - GitHub issue closed → Mark task as completed
+- Sync labels and priorities
+- Add comments with sync timestamps
+
+## Important Notes
+
+- Always check if GITHUB_TOKEN exists in environment
+- Never log tokens or credentials
+- Show clear progress messages
+- Display rich output with links
+- Use GitHub CLI (`gh`) if available for better integration
+- Respect rate limits (pause if needed)
+- Save sync results to test-results/ if requested
+
+## Error Handling
+
+- **Not a git repository**: "Error: Not a git repository. Initialize git first."
+- **No GitHub credentials**: "Error: GITHUB_TOKEN not set. Configure GitHub authentication."
+- **Increment not found**: "Error: Increment 0003 not found. Use /specweave.increment first."
+- **Issue not found**: "Error: Issue #42 not found in repository."
+- **Rate limit exceeded**: "Warning: GitHub rate limit reached. Waiting 60 seconds..."
+
+## Related Commands
+
+- `/specweave.sync-jira` - Sync to Jira
+- `/specweave.increment` - Create new increment
+- `/specweave.validate` - Validate increment quality
+- `/specweave.progress` - Check increment progress
+
+---
+
+**Granular Control**: Unlike simple milestone import/export, this command supports cherry-picking individual issues for maximum flexibility, just like the Jira sync integration.

package/src/commands/specweave.sync-jira.md

@@ -0,0 +1,197 @@
+---
+name: specweave.sync-jira
+description: Sync SpecWeave increments with JIRA epics/stories. Supports import, export, bidirectional sync, and granular item operations
+---
+
+# Sync Jira Command
+
+You are a Jira synchronization expert. Help the user sync between Jira and SpecWeave with granular control.
+
+## Available Operations
+
+### Epic-Level Operations
+
+**1. Import Jira Epic as SpecWeave Increment**
+```
+/specweave.sync-jira import SCRUM-123
+```
+
+**2. Sync existing linked Increment with Jira**
+```
+/specweave.sync-jira sync 0003
+```
+
+**3. Export SpecWeave Increment to Jira**
+```
+/specweave.sync-jira export 0001
+```
+
+### Granular Item Operations
+
+**4. Add specific Story/Bug/Task to existing Increment**
+```
+/specweave.sync-jira add SCRUM-1 to 0003
+/specweave.sync-jira add SCRUM-1              # Adds to current increment
+```
+
+**5. Create Increment from specific items (cherry-pick)**
+```
+/specweave.sync-jira create "User Authentication" from SCRUM-1 SCRUM-5 SCRUM-7
+/specweave.sync-jira create "Bug Fixes Sprint 1" from SCRUM-10 SCRUM-15 SCRUM-20
+```
+
+**6. Show sync status**
+```
+/specweave.sync-jira status
+/specweave.sync-jira status 0003              # Status of specific increment
+```
+
+## Your Task
+
+When the user runs this command:
+
+1. **Parse the command arguments**:
+   - Operation: import, sync, export, add, create, or status
+   - ID: Jira Epic key (e.g., SCRUM-123) or Increment ID (e.g., 0001)
+
+2. **Execute the operation**:
+
+   **For import Epic**:
+   ```typescript
+   import { JiraClient } from './src/integrations/jira/jira-client';
+   import { JiraMapper } from './src/integrations/jira/jira-mapper';
+
+   const client = new JiraClient();
+   const mapper = new JiraMapper(client);
+   const result = await mapper.importEpicAsIncrement('SCRUM-123');
+   ```
+
+   **For add item**:
+   ```typescript
+   import { JiraIncrementalMapper } from './src/integrations/jira/jira-incremental-mapper';
+
+   const incrementalMapper = new JiraIncrementalMapper(client);
+   const result = await incrementalMapper.addItemToIncrement('0003', 'SCRUM-1');
+   ```
+
+   **For create from items**:
+   ```typescript
+   const result = await incrementalMapper.createIncrementFromItems(
+     'User Authentication',
+     ['SCRUM-1', 'SCRUM-5', 'SCRUM-7']
+   );
+   ```
+
+   **For sync**:
+   ```typescript
+   const result = await mapper.syncIncrement('0003');
+   ```
+
+   **For export**:
+   ```typescript
+   const result = await mapper.exportIncrementAsEpic('0001', 'SCRUM');
+   ```
+
+3. **Show results**:
+   - Display sync summary
+   - Show conflicts (if any)
+   - List created/updated files
+   - Provide links to Jira and SpecWeave
+
+4. **Handle errors gracefully**:
+   - Check if .env credentials exist
+   - Validate increment/epic exists
+   - Show clear error messages
+
+## Examples
+
+### Example 1: Import Epic
+**User**: `/specweave.sync-jira import SCRUM-2`
+**You**:
+- Import Epic SCRUM-2 from Jira
+- Show: "✅ Imported as Increment 0004"
+- List: "Created: spec.md, tasks.md, RFC document"
+- Link: "Jira: https://... | Increment: .specweave/increments/0004/"
+
+### Example 2: Add Story to Current Increment
+**User**: `/specweave.sync-jira add SCRUM-1`
+**You**:
+- Determine current increment (latest or from context)
+- Fetch SCRUM-1 from Jira
+- Add to increment's spec.md (under ## User Stories)
+- Update tasks.md
+- Update RFC
+- Show: "✅ Added Story SCRUM-1 to Increment 0003"
+- Display: "Type: story | Title: User can login | Status: in-progress"
+
+### Example 3: Add Bug to Specific Increment
+**User**: `/specweave.sync-jira add SCRUM-10 to 0003`
+**You**:
+- Fetch SCRUM-10 from Jira (it's a Bug)
+- Add to increment 0003's spec.md (under ## Bugs)
+- Update tasks.md
+- Update RFC
+- Show: "✅ Added Bug SCRUM-10 to Increment 0003"
+- Display: "Type: bug | Priority: P1 | Title: Fix login redirect"
+
+### Example 4: Create Increment from Multiple Items
+**User**: `/specweave.sync-jira create "User Authentication" from SCRUM-1 SCRUM-5 SCRUM-7`
+**You**:
+- Fetch all 3 issues from Jira
+- Determine types (story, bug, task)
+- Create new increment 0005
+- Group by type in spec.md:
+  - ## User Stories (SCRUM-1, SCRUM-5)
+  - ## Technical Tasks (SCRUM-7)
+- Generate RFC with all items
+- Show: "✅ Created Increment 0005 with 3 work items"
+- Display table:
+  ```
+  | Type  | Jira Key | Title           |
+  |-------|----------|-----------------|
+  | Story | SCRUM-1  | User login UI   |
+  | Story | SCRUM-5  | OAuth backend   |
+  | Task  | SCRUM-7  | Setup provider  |
+  ```
+
+### Example 5: Sync Existing Increment
+**User**: `/specweave.sync-jira sync 0003`
+**You**:
+- Read increment 0003
+- Find linked Jira items (from spec.md frontmatter.work_items)
+- Fetch current state from Jira
+- Detect changes (status, priority, description)
+- Show conflicts if any
+- Apply sync bidirectionally
+- Display: "✅ Synced 0003 | Updated: 2 items | SCRUM-1 → in-progress, SCRUM-10 → completed"
+
+### Example 6: Status Overview
+**User**: `/specweave.sync-jira status`
+**You**:
+- Scan all increments for Jira metadata
+- Show table:
+  ```
+  | Increment | Title            | Jira Items | Last Sync          |
+  |-----------|------------------|------------|--------------------|
+  | 0003      | Test Epic        | 0 items    | 2025-10-28 17:42   |
+  | 0004      | User Auth        | 3 items    | 2025-10-28 18:00   |
+  | 0005      | Bug Fixes        | 5 items    | Never              |
+  ```
+
+## Important Notes
+
+- Always check if .env has Jira credentials before syncing
+- Never log secrets or tokens
+- Show clear progress messages
+- Display rich output with links
+- Save sync results to test-results/ if requested
+
+## Related Commands
+
+- `/specweave.sync-github` - Sync to GitHub issues
+- `/specweave.increment` - Create new increment
+- `/specweave.validate` - Validate increment quality
+
+---
+
+**Granular Control**: Unlike simple epic import/export, this command supports cherry-picking individual stories, bugs, and tasks for maximum flexibility.

package/src/commands/{validate.md → specweave.validate.md}

@@ -1,5 +1,5 @@
 ---
-name: validate
+name: specweave.validate
 description: Validate SpecWeave increment with rule-based checks and optional AI quality assessment
 ---
 
@@ -406,7 +406,7 @@ Remaining issues: 1 (requires manual review)
 
 **If `--always` flag OR user selects "Always run"**:
 
-1. Update `.specweave/config.yaml`:
+1. SpecWeave uses auto-detection
 ```yaml
 validation:
   quality_judge:
@@ -435,7 +435,7 @@ validation:
 Quality assessment will now run automatically for all future validations.
 
 To disable:
-  1. Edit .specweave/config.yaml
+  1. Initialize your project
   2. Set validation.quality_judge.always_run: false
 
 Or run: /validate-increment <id> (quality will run automatically)
@@ -781,7 +781,7 @@ validation:
 ## Related Commands
 
 - `/create-increment`: Create new increment (auto-validates on creation)
-- `/review-docs`: Review strategic documentation before implementation
+- `/sync-docs`: Review strategic documentation before implementation
 - `/close-increment`: Close increment (validates before closing)
 - `/sync-github`: Sync to GitHub (validates before sync)
 

package/src/hooks/README.md

@@ -18,16 +18,21 @@ Hooks automate workflows and provide feedback during development:
 ## Available Hooks
 
 ### 1. `post-task-completion.sh`
-**Triggers**: After ANY task is marked complete
+**Triggers**: After ANY task is marked complete (via TodoWrite tool)
 
 **Actions**:
-1. Plays completion sound (Glass.aiff on macOS, equivalent on Linux/Windows)
-2. Triggers `docs-updater` skill (if exists)
-3. Checks if CLAUDE.md needs update
-4. Logs task completion
+1. Plays completion sound **synchronously** (Glass.aiff on macOS, equivalent on Linux/Windows)
+2. Outputs JSON with systemMessage reminder to update docs
+3. Logs task completion
 
 **Sound**: Glass.aiff (or system equivalent)
 
+**Important**: Hooks cannot invoke slash commands or skills. The hook only:
+- Plays sound to notify user
+- Shows reminder message
+- Claude must manually update CLAUDE.md/README.md inline after each task
+- Living docs sync (via `/sync-docs`) happens after ALL tasks complete
+
 ---
 
 ### 2. `human-input-required.sh`
@@ -93,10 +98,10 @@ This creates symlinks:
 ### Method 2: Copy (For New Projects)
 ```bash
 # When creating new project
-npx specweave create-project my-project
+npx specweave init my-project
 ```
 
-This copies `src/hooks/` → `my-project/src/hooks/` → `my-project/.claude/hooks/`
+This copies `src/hooks/` → `my-project/.claude/hooks/`
 
 **Benefit**: New project gets its own copy of hooks (can customize if needed)
 
@@ -114,30 +119,15 @@ chmod +x .claude/hooks/*.sh
 
 ## Configuration
 
-Hooks respect `.specweave/config.yaml`:
-
-```yaml
----
-hooks:
-  enabled: true
-
-  # Sound notifications
-  sounds:
-    enabled: true
-    completion: /System/Library/Sounds/Glass.aiff  # macOS
-    input_required: /System/Library/Sounds/Ping.aiff
+Hooks are enabled by default. To customize behavior, hooks can check environment variables or use auto-detection.
 
-  # Auto-update docs
-  docs_updater:
-    enabled: true
-    auto_commit: false  # If true, auto-commit doc changes
+### Default Behavior
+- Sound notifications enabled (platform-specific)
+- Auto-update docs after task completion
+- Regression checks for brownfield projects
 
-  # Regression checks
-  regression:
-    enabled: true
-    require_baseline_tests: false  # If true, block if no baseline tests
----
-```
+### Customization
+Hooks use auto-detection for platform-specific features (macOS/Linux/Windows sound files).
 
 ---
 

package/src/hooks/post-task-completion.sh

@@ -1,32 +1,30 @@
 #!/bin/bash
 
 # SpecWeave Post-Task-Completion Hook
-# Runs automatically after ANY task is marked complete
+# Runs automatically after ANY task is marked complete via TodoWrite
 #
 # Actions:
-# 1. Play completion sound
-# 2. Trigger docs-updater skill (if exists)
-# 3. Update CLAUDE.md if needed
-# 4. Log completion
+# 1. Play completion sound (synchronously, not background)
+# 2. Output JSON systemMessage reminding to update docs
+# 3. Log completion
 
 set -e
 
 PROJECT_ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/../.." && pwd)"
-cd "$PROJECT_ROOT"
+cd "$PROJECT_ROOT" 2>/dev/null || true
 
-# Colors
-GREEN='\033[0;32m'
-BLUE='\033[0;34m'
-YELLOW='\033[1;33m'
-NC='\033[0m'
+# DEBUG: Log hook invocation
+mkdir -p .specweave/logs 2>/dev/null || true
+echo "[$(date)] Hook invoked! PWD=$PWD Args=$*" >> .specweave/logs/hooks-debug.log 2>/dev/null || true
+echo "[$(date)] Hook stdin:" >> .specweave/logs/hooks-debug.log 2>/dev/null || true
+cat >> .specweave/logs/hooks-debug.log 2>/dev/null || true
 
-echo -e "${BLUE}🔔 Task Completed${NC}"
-
-# 1. Play notification sound (cross-platform)
+# 1. Play notification sound SYNCHRONOUSLY (cross-platform)
 play_sound() {
   case "$(uname -s)" in
     Darwin)
-      afplay /System/Library/Sounds/Glass.aiff 2>/dev/null &
+      # Play synchronously (remove &)
+      afplay /System/Library/Sounds/Glass.aiff 2>/dev/null || true
       ;;
     Linux)
       paplay /usr/share/sounds/freedesktop/stereo/complete.oga 2>/dev/null || \
@@ -38,20 +36,17 @@ play_sound() {
   esac
 }
 
-play_sound &
-
-# 2. Trigger docs-updater (if skill exists)
-if [ -d "src/skills/docs-updater" ] || [ -d ".claude/skills/docs-updater" ]; then
-  echo -e "${YELLOW}📝 docs-updater skill will update documentation${NC}"
-fi
+# Play sound FIRST (synchronously)
+play_sound
 
-# 3. Check if CLAUDE.md needs update
-if git diff --name-only | grep -qE "(\.specweave/|src/skills/)"; then
-  echo -e "${YELLOW}📄 CLAUDE.md may need update (structural changes detected)${NC}"
-fi
+# 2. Log completion
+mkdir -p .specweave/logs 2>/dev/null || true
+echo "[$(date)] Task completed" >> .specweave/logs/tasks.log 2>/dev/null || true
 
-# 4. Log completion
-mkdir -p .specweave/logs
-echo "[$(date)] Task completed" >> .specweave/logs/tasks.log
-
-echo -e "${GREEN}✅ Post-task-completion hook complete${NC}"
+# 3. Output JSON to instruct Claude (systemMessage is shown to user)
+cat <<EOF
+{
+  "continue": true,
+  "systemMessage": "🔔 Task completed! Remember to update documentation with inline edits to CLAUDE.md and README.md as needed."
+}
+EOF