zhongwei/gh-anton-abyzov-specweave-plugins-specweave-ado

Fork 0

Files

Zhongwei Li 19b5d00a1f Initial commit

2025-11-29 17:56:16 +08:00

4.1 KiB

Raw Permalink Blame History

SpecWeave Azure DevOps Plugin Hooks

Plugin: specweave-ado Location: plugins/specweave-ado/hooks/

Purpose

This hook automatically syncs SpecWeave increment progress to Azure DevOps Work Items after each task completion.

Key Features:

✅ Updates Azure DevOps work item status based on increment progress
✅ Syncs task completion state to ADO
✅ Bidirectional sync (local → Azure DevOps)
✅ Non-blocking (failures don't stop core workflow)
✅ Self-contained (no dependencies on core plugin)

Available Hooks

1. `post-task-completion.sh`

Triggers: After ANY task is marked complete (via TodoWrite tool)

Preconditions:

✅ Active increment exists (.specweave/increments/####/)
✅ metadata.json has .ado.item field
✅ Node.js installed
✅ ADO sync script exists (dist/commands/ado-sync.js)
✅ Azure DevOps PAT in .env

Actions:

Reads increment metadata
Calls ADO sync script (Node.js)
Updates Azure DevOps work item status
Logs all actions to .specweave/logs/hooks-debug.log

Example Flow:

Task T-003 completed in tasks.md
↓
Hook fires (PostToolUse + TodoWrite matcher)
↓
ADO sync script updates work item #4567
↓
Log: "[ADO] ✅ Azure DevOps sync complete"

Dependencies:

Node.js 18+
Azure DevOps PAT (.env)
jq for JSON parsing

Configuration

Hook Registration (`hooks.json`)

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "TodoWrite",
        "hooks": [
          {
            "type": "command",
            "command": "${CLAUDE_PLUGIN_ROOT}/hooks/post-task-completion.sh"
          }
        ]
      }
    ]
  }
}

Metadata Format

Increments must have metadata.json with Azure DevOps work item link:

{
  "ado": {
    "item": 4567,
    "url": "https://dev.azure.com/org/project/_workitems/edit/4567",
    "project": "MyProject"
  }
}

Environment Variables

Required in .env:

AZURE_DEVOPS_ORG=your-org
AZURE_DEVOPS_PROJECT=your-project
AZURE_DEVOPS_PAT=your_personal_access_token_here

Installation

Automatic (Recommended)

npx specweave init my-project
# Installs all plugins including specweave-ado
# Hooks auto-register via hooks.json

Manual (Development)

# Install plugin
/plugin install specweave-ado

# Verify hook registration
cat ~/.claude/settings.json | grep specweave-ado

Testing

Test Hook Independently

# Test syntax
bash -n plugins/specweave-ado/hooks/post-task-completion.sh

# Test execution (requires active increment + ADO work item)
./plugins/specweave-ado/hooks/post-task-completion.sh

Logging

All Azure DevOps sync actions are logged to:

.specweave/logs/hooks-debug.log

Example Log Output:

[2025-11-10] [ADO] 🔗 Azure DevOps sync hook fired
[2025-11-10] [ADO] 🔄 Syncing to Azure DevOps work item 4567
[2025-11-10] [ADO] ✅ Azure DevOps sync complete

Log Prefixes:

[ADO] - All messages from this hook
🔗 - Hook fired
🔄 - Syncing started
✅ - Success
⚠️ - Warning (non-blocking failure)
ℹ️ - Info (skipped due to precondition)

Architecture

Separation from Core Plugin

Before (v0.12.x):

Core hook (500+ lines)
├── Azure DevOps sync  ← Embedded in core!

After (v0.13.0+):

Core hook (330 lines)      ADO plugin hook (150 lines)
├── Core concerns          ├── Check for ADO work item
                           ├── Call Node.js sync script
                           └── Log actions

Key Benefits:

✅ Optional plugin: ADO sync only runs if specweave-ado installed
✅ Independent testing: Test ADO sync in isolation
✅ No core dependencies: Core plugin doesn't depend on Azure DevOps API

Core Plugin Hooks: plugins/specweave/hooks/README.md
Architecture Analysis: .specweave/increments/0018-strict-increment-discipline-enforcement/reports/HOOKS-ARCHITECTURE-ANALYSIS.md
ADO Sync Command: plugins/specweave-ado/commands/specweave-ado-sync.md

Version: v0.13.0+ Last Updated: 2025-11-10

4.1 KiB Raw Permalink Blame History Unescape Escape