specweave 0.12.6 → 0.13.0

package/plugins/specweave/agents/pm/AGENT.md

@@ -27,50 +27,20 @@ These guides contain:
 
 ---
 
-## ⛔ CRITICAL: Increment Discipline (v0.6.0+ MANDATORY)
+## ⛔ CRITICAL: Increment Discipline (v0.6.0+)
 
 **THE IRON RULE**: You CANNOT plan increment N+1 until increment N is DONE.
 
-**ENFORCEMENT**: This is NON-NEGOTIABLE. You MUST enforce strict increment discipline.
+**ENFORCEMENT**: This is now handled by **UserPromptSubmit hook** (automatic, zero-token validation).
 
-### Pre-Planning Validation (Step 0 - MANDATORY)
+### How It Works (v0.13.0+)
 
-**BEFORE planning any new increment**, you MUST:
+**Discipline validation happens BEFORE you even execute**:
+- UserPromptSubmit hook checks for incomplete increments
+- If violations found: User gets blocked immediately (zero LLM tokens used)
+- If compliant: Planning proceeds normally
 
-```typescript
-// Import the status detector
-import { IncrementStatusDetector } from '../../src/core/increment-status';
-
-// Check for incomplete increments
-const detector = new IncrementStatusDetector();
-const incomplete = await detector.getAllIncomplete();
-
-if (incomplete.length > 0) {
-  // ❌ BLOCK IMMEDIATELY - Do NOT proceed with planning
-  console.log('❌ Cannot plan new increment! Previous increments incomplete.');
-  console.log('');
-
-  incomplete.forEach(status => {
-    console.log(`📋 ${status.id}: ${status.percentComplete}% complete`);
-    console.log(`   ${status.completedTasks}/${status.totalTasks} tasks done`);
-    if (status.pendingTasks.length <= 3) {
-      status.pendingTasks.forEach(task => {
-        console.log(`   - ${task.id}: ${task.title}`);
-      });
-    }
-  });
-
-  console.log('');
-  console.log('💡 Use /specweave:close to close incomplete increments.');
-  console.log('');
-
-  // EXIT - Do NOT plan
-  throw new Error('Increment discipline violation: Previous increments incomplete');
-}
-
-// ✅ If we reach here, all previous increments are complete
-// Proceed with planning
-```
+**You don't need to check manually** - the hook already validated compliance!
 
 ### Why This Matters
 

package/plugins/specweave/commands/specweave-increment.md

@@ -99,54 +99,34 @@ EOF
 
 **THIS IS NOT NEGOTIABLE** - Enforce strict increment discipline!
 
-```typescript
-// Import increment status detector
-import { IncrementStatusDetector } from '../core/increment-status';
-
-// Check for incomplete increments
-const detector = new IncrementStatusDetector();
-const incomplete = await detector.getAllIncomplete();
-
-if (incomplete.length > 0) {
-  // ❌ BLOCK IMMEDIATELY - Show error and exit
-  console.log(chalk.red.bold('\n❌ Cannot create new increment!\n'));
-
-  console.log(chalk.yellow('Previous increments are incomplete:\n'));
-
-  incomplete.forEach(status => {
-    console.log(chalk.yellow(`📋 Increment ${status.id}`));
-    console.log(`   Status: ${status.percentComplete}% complete (${status.completedTasks}/${status.totalTasks} tasks)`);
-
-    if (status.pendingTasks.length <= 5) {
-      console.log('   Pending:');
-      status.pendingTasks.forEach(task => {
-        console.log(`     - ${task.id}: ${task.title}`);
-      });
-    } else {
-      console.log(`   Pending: ${status.pendingTasks.length} tasks`);
-    }
-    console.log('');
-  });
-
-  console.log(chalk.blue('💡 What would you like to do?\n'));
-  console.log(chalk.white('1️⃣  Close incomplete increments:'));
-  console.log(chalk.dim('   /specweave:close\n'));
-
-  console.log(chalk.white('2️⃣  Check status:'));
-  console.log(chalk.dim('   /specweave:status\n'));
-
-  console.log(chalk.white('3️⃣  Force create (DANGEROUS - violates discipline!):'));
-  console.log(chalk.dim('   Add --force flag to bypass this check\n'));
-
-  console.log(chalk.yellow.bold('⚠️  The discipline exists for a reason:'));
-  console.log(chalk.yellow('   - Prevents scope creep'));
-  console.log(chalk.yellow('   - Ensures completions are tracked'));
-  console.log(chalk.yellow('   - Maintains living docs accuracy'));
-  console.log(chalk.yellow('   - Keeps work focused\n'));
-
-  // Exit - do NOT proceed
-  process.exit(1);
-}
+```bash
+# Run discipline check (exit codes: 0=pass, 1=violations, 2=error)
+if ! specweave check-discipline; then
+  echo ""
+  echo "❌ Cannot create new increment! Discipline violations found."
+  echo ""
+  echo "💡 What would you like to do?"
+  echo ""
+  echo "1️⃣  Close incomplete increments:"
+  echo "   /specweave:done <id>"
+  echo ""
+  echo "2️⃣  Check status:"
+  echo "   specweave check-discipline --verbose"
+  echo ""
+  echo "3️⃣  Force create (DANGEROUS - violates discipline!):"
+  echo "   Add --force flag to bypass this check"
+  echo ""
+  echo "⚠️  The discipline exists for a reason:"
+  echo "   - Prevents scope creep"
+  echo "   - Ensures completions are tracked"
+  echo "   - Maintains living docs accuracy"
+  echo "   - Keeps work focused"
+  echo ""
+  exit 1
+fi
+
+# ✅ Discipline check passed - proceed with planning
+echo "✅ Discipline check passed"
 ```
 
 **Why This is Strict** (changed from v0.5.0):

package/plugins/specweave/hooks/README.md

@@ -1,37 +1,79 @@
-# SpecWeave Hooks (Source of Truth)
+# SpecWeave Core Plugin Hooks
 
-**Location**: `src/hooks/` (version controlled, copied to new projects)
-**Installed to**: `.claude/hooks/` (via symlink or copy)
+**Plugin**: `specweave` (core plugin)
+**Location**: `plugins/specweave/hooks/`
 
 ---
 
 ## Purpose
 
-Hooks automate workflows and provide feedback during development:
+Core hooks automate SpecWeave's fundamental workflows:
 - **Sound notifications** when tasks complete or input is needed
-- **Documentation updates** after task completion
-- **Change detection** when docs are modified during implementation
-- **Regression checks** before starting implementation on brownfield projects
+- **Living docs sync** after task completion
+- **Translation** of non-English documentation
+- **Self-reflection** for AI-driven quality improvements
+
+**Note**: External tool sync (GitHub, JIRA, Azure DevOps) has been moved to respective plugin hooks as of v0.13.0. See "Architecture Changes" section below.
 
 ---
 
 ## Available Hooks
 
-### 1. `post-task-completion.sh`
+### 1. `user-prompt-submit.sh` ⭐ NEW (v0.13.0+)
+**Triggers**: BEFORE user's command executes (prompt-based hook)
+
+**Actions** (Zero-Token Validation):
+1. **Discipline enforcement** - Blocks `/specweave:increment` if incomplete increments exist
+2. **Context injection** - Adds active increment status to every prompt
+3. **Command suggestions** - Guides users to SpecWeave commands
+
+**Why This Is Better**:
+- ✅ **Zero LLM tokens** - Shell script validation (no PM agent invocation)
+- ✅ **Instant blocking** - User gets feedback before Claude even thinks
+- ✅ **Always current** - Context injected into every conversation
+- ✅ **Better UX** - Proactive guidance for new users
+
+**Example Output** (blocking):
+```json
+{
+  "decision": "block",
+  "reason": "❌ Cannot create new increment! You have 2 incomplete increment(s)..."
+}
+```
+
+**Example Output** (context injection):
+```json
+{
+  "decision": "approve",
+  "systemMessage": "📍 Active Increment: 0017-sync-architecture-fix (73% complete, 11/15 tasks)\n\n💡 TIP: Consider using SpecWeave commands..."
+}
+```
+
+---
+
+### 2. `post-task-completion.sh`
 **Triggers**: After ANY task is marked complete (via TodoWrite tool)
 
-**Actions**:
-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
+**Actions** (Core Concerns Only):
+1. **Session-end detection** - Smart inactivity tracking (15s threshold)
+2. **Sound notification** - Glass.aiff on macOS (only when session truly ends)
+3. **tasks.md updates** - Sync completion status from TodoWrite
+4. **Living docs sync** - Update permanent specs after completion
+5. **Translation** - Auto-translate non-English docs to English
+6. **Self-reflection** - Prepare AI reflection context
 
 **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
+**Architecture Note** (v0.13.0+): External tool sync (GitHub, JIRA, ADO) has been **removed from this hook** and moved to respective plugin hooks:
+- `plugins/specweave-github/hooks/post-task-completion.sh`
+- `plugins/specweave-jira/hooks/post-task-completion.sh`
+- `plugins/specweave-ado/hooks/post-task-completion.sh`
+
+**Benefits**:
+- ✅ **27% smaller** (330 lines, down from 452)
+- ✅ **No external tool dependencies** (gh CLI, JIRA API, ADO API)
+- ✅ **Cleaner separation** (core vs. external concerns)
+- ✅ **Optional plugins** (GitHub sync only runs if plugin installed)
 
 ---
 
@@ -75,124 +117,153 @@ Hooks automate workflows and provide feedback during development:
 
 ---
 
-## Installation
-
-### Method 1: Symlink (Recommended for Development)
-```bash
-# From SpecWeave repository root
-npx specweave install-hooks --symlink
-```
-
-This creates symlinks:
-```
-.claude/hooks/post-task-completion.sh → src/hooks/post-task-completion.sh
-.claude/hooks/human-input-required.sh → src/hooks/human-input-required.sh
-.claude/hooks/docs-changed.sh → src/hooks/docs-changed.sh
-.claude/hooks/pre-implementation.sh → src/hooks/pre-implementation.sh
-```
+## How Hooks Work (Claude Code Native)
 
-**Benefit**: Changes to `src/hooks/` immediately reflected in `.claude/hooks/`
+**CRITICAL**: Hooks are **NOT copied** to `.claude/hooks/`. They stay in `plugins/specweave/hooks/` and Claude Code discovers them automatically.
 
----
+### Hook Discovery (Automatic)
 
-### Method 2: Copy (For New Projects)
-```bash
-# When creating new project
-npx specweave init my-project
-```
+1. **Plugin Installation**: When you install the `specweave` plugin via `/plugin install specweave` (or automatically during `specweave init`)
+2. **Hook Registration**: Claude Code reads `plugins/specweave/.claude-plugin/plugin.json` which points to `hooks/hooks.json`
+3. **Hook Discovery**: Claude Code loads `plugins/specweave/hooks/hooks.json` which references hook scripts:
+   ```json
+   {
+     "hooks": {
+       "PostToolUse": [{
+         "matcher": "TodoWrite",
+         "hooks": [{
+           "type": "command",
+           "command": "${CLAUDE_PLUGIN_ROOT}/hooks/post-task-completion.sh"
+         }]
+       }]
+     }
+   }
+   ```
+4. **Execution**: When `TodoWrite` fires, Claude Code executes `plugins/specweave/hooks/post-task-completion.sh` using the `${CLAUDE_PLUGIN_ROOT}` variable
 
-This copies `src/hooks/` → `my-project/.claude/hooks/`
+**Key Insight**: `${CLAUDE_PLUGIN_ROOT}` resolves to the installed plugin directory automatically. NO copying needed!
 
-**Benefit**: New project gets its own copy of hooks (can customize if needed)
+### Installation (Automatic)
 
----
+Hooks are installed automatically when you:
 
-### Manual Installation
 ```bash
-# Copy hooks to .claude/hooks/
-mkdir -p .claude/hooks
-cp src/hooks/*.sh .claude/hooks/
-chmod +x .claude/hooks/*.sh
+# Option 1: Full project initialization
+specweave init my-project
+
+# Option 2: Plugin installation (if already initialized)
+/plugin install specweave
 ```
 
+**Result**: Claude Code automatically discovers and registers hooks. Nothing to copy or configure manually!
+
 ---
 
 ## Configuration
 
-Hooks are enabled by default. To customize behavior, hooks can check environment variables or use auto-detection.
-
-### Default Behavior
-- Sound notifications enabled (platform-specific)
-- Auto-update docs after task completion
-- Regression checks for brownfield projects
-
-### Customization
-Hooks use auto-detection for platform-specific features (macOS/Linux/Windows sound files).
+Hooks are configured via `.specweave/config.json` (created automatically during `specweave init`):
+
+```json
+{
+  "hooks": {
+    "post_task_completion": {
+      "sync_living_docs": true,        // Sync specs to living docs
+      "sync_tasks_md": true,           // Update tasks.md with completion status
+      "external_tracker_sync": true    // Sync to GitHub/Jira/ADO (if configured)
+    },
+    "post_increment_planning": {
+      "auto_create_issue": true        // Auto-create GitHub issue after planning
+    }
+  },
+  "sync": {
+    "enabled": true,
+    "activeProfile": "github-default",
+    "profiles": {
+      "github-default": {
+        "provider": "github",
+        "config": {
+          "owner": "your-org",
+          "repo": "your-repo"
+        }
+      }
+    }
+  }
+}
+```
 
----
+### Hook Behavior
 
-## Cross-Platform Support
+**post-task-completion**:
+- `sync_living_docs: true` - Automatically syncs increment specs to `.specweave/docs/internal/specs/` after task completion
+- `sync_tasks_md: true` - Updates `tasks.md` with completion status from `TodoWrite` events
+- `external_tracker_sync: true` - Syncs progress to GitHub/Jira/ADO (requires sync profile configured)
 
-### macOS
-- Uses `afplay` for sound
-- Sounds: Glass.aiff, Ping.aiff
+**post-increment-planning**:
+- `auto_create_issue: true` - Automatically creates GitHub issue after `/specweave:increment` completes
 
-### Linux
-- Uses `paplay` or `aplay`
-- Sounds: system sounds in `/usr/share/sounds/`
+### Sound Notifications
 
-### Windows
-- Uses PowerShell `Media.SoundPlayer`
-- Sounds: `C:\Windows\Media\chimes.wav`, `notify.wav`
+Sound notifications work automatically (platform-specific):
+- **macOS**: Uses `afplay` (Glass.aiff, Ping.aiff)
+- **Linux**: Uses `paplay` or `aplay` (system sounds)
+- **Windows**: Uses PowerShell `Media.SoundPlayer` (chimes.wav, notify.wav)
 
 ---
 
 ## Disabling Hooks
 
-### Temporarily
-```bash
-# Disable all hooks
-export SPECWEAVE_HOOKS_DISABLED=1
+### Option 1: Configuration (Recommended)
+Edit `.specweave/config.json`:
+```json
+{
+  "hooks": {
+    "post_task_completion": {
+      "sync_living_docs": false,        // Disable living docs sync
+      "sync_tasks_md": false,           // Disable tasks.md updates
+      "external_tracker_sync": false    // Disable external sync
+    }
+  }
+}
 ```
 
-### Permanently
-Delete or rename `.claude/hooks/` directory:
+### Option 2: Uninstall Plugin (Nuclear)
 ```bash
-mv .claude/hooks .claude/hooks.disabled
+/plugin uninstall specweave
 ```
+**Warning**: This disables ALL SpecWeave functionality, not just hooks!
 
 ---
 
 ## Customizing Hooks
 
-Hooks are bash scripts, so you can customize them:
+Hooks are bash scripts in the plugin. To customize:
 
-1. Edit `src/hooks/post-task-completion.sh` (for example)
-2. If using symlinks, changes are immediately active
-3. If using copies, run `npx specweave install-hooks` again
+1. **For development** (SpecWeave repo contributors):
+   - Edit `plugins/specweave/hooks/post-task-completion.sh`
+   - Changes take effect immediately (hooks run from plugin directory)
+
+2. **For users** (project using SpecWeave):
+   - NOT RECOMMENDED - Hooks are plugin-managed
+   - Configure behavior via `.specweave/config.json` instead
 
 ---
 
 ## Testing Hooks
 
-### Test post-task-completion
+### Validate Hook Syntax
 ```bash
-./.claude/hooks/post-task-completion.sh
-```
+# Test core hook
+bash -n plugins/specweave/hooks/post-task-completion.sh
 
-Expected:
-- Sound plays
-- Console output shows actions
-- Log created in `.specweave/logs/tasks.log`
-
-### Test human-input-required
-```bash
-./.claude/hooks/human-input-required.sh "Test question"
+# Test plugin hooks (if using external sync)
+bash -n plugins/specweave-github/hooks/post-task-completion.sh
 ```
 
-Expected:
-- Ping sound plays
-- Log created in `.specweave/logs/hooks.log`
+### Test Integrated Workflow
+1. Create increment: `/specweave:increment "test feature"`
+2. Complete a task (via TodoWrite)
+3. Check logs: `tail -f .specweave/logs/hooks-debug.log`
+4. Verify hook execution in logs
 
 ---
 
@@ -227,6 +298,132 @@ Logs are gitignored (in `.specweave/logs/`)
 
 ---
 
+## Architecture Changes (v0.13.0)
+
+### What Changed
+
+**External tool sync logic has been moved from core plugin to respective plugin hooks**:
+
+| External Tool | Old Location | New Location |
+|---------------|-------------|--------------|
+| **GitHub Issues** | `plugins/specweave/hooks/post-task-completion.sh` (lines 227-333) | `plugins/specweave-github/hooks/post-task-completion.sh` |
+| **JIRA** | `plugins/specweave/hooks/post-task-completion.sh` (lines 335-345) | `plugins/specweave-jira/hooks/post-task-completion.sh` |
+| **Azure DevOps** | `plugins/specweave/hooks/post-task-completion.sh` (lines 347-357) | `plugins/specweave-ado/hooks/post-task-completion.sh` |
+
+**Result**:
+- ✅ Core hook: 452 lines → 330 lines (27% reduction)
+- ✅ Each plugin hook: ~150-240 lines (self-contained)
+- ✅ Total: 871 lines (vs. 452 monolithic lines)
+
+### Why This Change?
+
+**Problem (Before v0.13.0)**:
+```
+Core hook (500+ lines)
+├── Core concerns (sound, docs, translation)
+├── GitHub sync logic (107 lines)      ← Embedded in core!
+├── JIRA sync logic (11 lines)         ← Embedded in core!
+└── Azure DevOps sync logic (11 lines) ← Embedded in core!
+
+Issues:
+❌ Tight coupling (core depends on gh CLI, JIRA API, ADO API)
+❌ Cannot opt out of GitHub sync even if not using it
+❌ Testing complexity (must mock all external tools)
+❌ Violates separation of concerns
+```
+
+**Solution (v0.13.0+)**:
+```
+Core hook (330 lines)           GitHub plugin hook (241 lines)
+├── Core concerns only          ├── GitHub API calls
+                                ├── Issue checkbox updates
+                                └── Progress comments
+
+JIRA plugin hook (150 lines)    ADO plugin hook (150 lines)
+├── JIRA API calls              ├── Azure DevOps API calls
+└── Issue status updates        └── Work item updates
+
+Benefits:
+✅ Separation of concerns (core vs. external tools)
+✅ Optional plugins (GitHub sync only if plugin installed)
+✅ Independent testing (test each hook in isolation)
+✅ No external dependencies in core plugin
+✅ Parallel execution (Claude Code runs all hooks concurrently)
+```
+
+### How It Works (Claude Code's Hook System)
+
+**When a task completes**:
+1. `TodoWrite` tool fires
+2. Claude Code triggers `PostToolUse` event
+3. **ALL registered hooks fire in parallel**:
+   - Core hook: Sound + Living docs + Translation + Reflection
+   - GitHub hook: Update issue checkboxes (if `specweave-github` installed)
+   - JIRA hook: Update issue status (if `specweave-jira` installed)
+   - ADO hook: Update work item (if `specweave-ado` installed)
+
+**Key Insight**: Each plugin registers its own hooks via `hooks.json`, enabling clean modularity.
+
+### Migration Guide
+
+**For existing projects** (v0.12.x → v0.13.0):
+
+**Option 1: Automatic (Recommended)**
+```bash
+# Re-run init to update hooks
+specweave init .
+# Overwrites .claude/hooks/ with new structure
+```
+
+**Option 2: Manual (Not Recommended)**
+```bash
+# Remove old monolithic hook
+rm .claude/hooks/post-task-completion.sh
+
+# Copy new plugin hooks
+cp -r plugins/specweave/hooks/.claude/hooks/
+cp -r plugins/specweave-github/hooks/ .claude/hooks/ (if using GitHub)
+cp -r plugins/specweave-jira/hooks/ .claude/hooks/ (if using JIRA)
+cp -r plugins/specweave-ado/hooks/ .claude/hooks/ (if using ADO)
+```
+
+**No breaking changes**: Existing increments with GitHub/JIRA/ADO links will continue to sync automatically.
+
+### Testing the New Architecture
+
+**Test core hook independently**:
+```bash
+bash -n plugins/specweave/hooks/post-task-completion.sh
+# Should show no syntax errors
+```
+
+**Test plugin hooks independently**:
+```bash
+bash -n plugins/specweave-github/hooks/post-task-completion.sh
+bash -n plugins/specweave-jira/hooks/post-task-completion.sh
+bash -n plugins/specweave-ado/hooks/post-task-completion.sh
+```
+
+**Test integrated workflow**:
+1. Create increment: `/specweave:increment "test"`
+2. Create GitHub issue: `/specweave-github:create-issue 0001`
+3. Complete a task (TodoWrite)
+4. Check logs: `tail -f .specweave/logs/hooks-debug.log`
+5. Verify:
+   - Core hook logs: `[$(date)]` messages
+   - GitHub hook logs: `[$(date)] [GitHub]` messages
+   - GitHub issue updated with checkboxes
+
+### Related Documentation
+
+- **Architecture Analysis**: `.specweave/increments/0018-strict-increment-discipline-enforcement/reports/HOOKS-ARCHITECTURE-ANALYSIS.md`
+- **GitHub Plugin Hooks**: `plugins/specweave-github/hooks/README.md`
+- **JIRA Plugin Hooks**: `plugins/specweave-jira/hooks/README.md`
+- **ADO Plugin Hooks**: `plugins/specweave-ado/hooks/README.md`
+- **Claude Code Hooks Guide**: https://code.claude.com/docs/en/hooks-guide
+
+---
+
 ## Future Enhancements
 
 Planned hooks:

package/plugins/specweave/hooks/hooks.json

@@ -1,5 +1,15 @@
 {
   "hooks": {
+    "UserPromptSubmit": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "${CLAUDE_PLUGIN_ROOT}/hooks/user-prompt-submit.sh"
+          }
+        ]
+      }
+    ],
     "PostToolUse": [
       {
         "matcher": "TodoWrite",