Initial commit
This commit is contained in:
Zhongwei Li
3
skills/ado-sync/.gitignore
vendored
Normal file
3
skills/ado-sync/.gitignore
vendored
Normal file
@@ -0,0 +1,3 @@
|
||||
test-results/
|
||||
*.log
|
||||
.DS_Store
|
||||
414
skills/ado-sync/README.md
Normal file
414
skills/ado-sync/README.md
Normal file
@@ -0,0 +1,414 @@
|
||||
# ado-sync Skill
|
||||
|
||||
**Status**: To be developed
|
||||
**Priority**: Medium
|
||||
|
||||
## Purpose
|
||||
|
||||
Bidirectional sync between SpecWeave increments and Azure DevOps (ADO)
|
||||
|
||||
**Note**: This skill handles ONLY Azure DevOps. For JIRA, see `jira-sync` skill.
|
||||
|
||||
## Features
|
||||
|
||||
### Export to ADO
|
||||
- Create ADO work items from SpecWeave increments
|
||||
- Map spec.md user stories → ADO User Stories
|
||||
- Map tasks.md tasks → ADO Tasks
|
||||
- Create Features if specified in spec.md
|
||||
- Set Area Paths, Iterations, priorities
|
||||
|
||||
### Import from ADO
|
||||
- Sync ADO updates back to SpecWeave
|
||||
- Import existing ADO work items as increments
|
||||
- Update status, assignees, comments
|
||||
|
||||
### Bidirectional Sync
|
||||
- Keep status in sync (New, Active, Resolved, Closed)
|
||||
- Sync descriptions and acceptance criteria
|
||||
- Sync comments and attachments
|
||||
- Handle conflicts intelligently
|
||||
|
||||
## ADO-Specific Concepts
|
||||
|
||||
### Mapping: SpecWeave → Azure DevOps
|
||||
|
||||
| SpecWeave | Azure DevOps |
|
||||
|-----------|--------------|
|
||||
| spec.md (with Feature) | Feature |
|
||||
| spec.md User Story | User Story |
|
||||
| tasks.md Task | Task |
|
||||
| Acceptance Tests (spec.md) | Acceptance Criteria (User Story) |
|
||||
| Acceptance Criteria (tasks.md) | Task checklist |
|
||||
| Status: planned | New |
|
||||
| Status: in-progress | Active |
|
||||
| Status: completed | Closed |
|
||||
|
||||
### ADO Structure Example
|
||||
|
||||
**spec.md with ADO structure**:
|
||||
```markdown
|
||||
---
|
||||
increment: 002-payment-processing
|
||||
status: planned
|
||||
structure: ado
|
||||
ado_feature: 456
|
||||
---
|
||||
|
||||
## Feature: Payment Processing
|
||||
**ADO**: 456
|
||||
**Area Path**: Platform/Payments
|
||||
**Iteration**: Sprint 12
|
||||
|
||||
### User Story: Subscribe to Plan
|
||||
**ADO**: 789
|
||||
**Priority**: 1
|
||||
**Area Path**: Platform/Payments
|
||||
**Iteration**: Sprint 12
|
||||
|
||||
**Description**:
|
||||
As a user, I want to subscribe to a monthly plan...
|
||||
|
||||
**Acceptance Criteria**:
|
||||
- User can select plan
|
||||
- Payment processed
|
||||
- Subscription activated
|
||||
```
|
||||
|
||||
**tasks.md creates Tasks**:
|
||||
```markdown
|
||||
## Tasks for ADO-789 (Subscribe to Plan)
|
||||
|
||||
### Task T001: Create StripeService
|
||||
**ADO**: 790 (Task under User Story 789)
|
||||
**Agent**: nodejs-backend
|
||||
**Area Path**: Platform/Payments/Backend
|
||||
**Iteration**: Sprint 12
|
||||
|
||||
**Description**: Create Stripe service class...
|
||||
|
||||
**Acceptance Criteria**:
|
||||
- [ ] StripeService class exists
|
||||
- [ ] Unit tests passing
|
||||
```
|
||||
|
||||
## Authentication
|
||||
|
||||
**Personal Access Token (PAT)**:
|
||||
|
||||
|
||||
**OAuth 2.0** (for apps):
|
||||
```yaml
|
||||
ado_sync:
|
||||
url: "https://dev.azure.com/your-org"
|
||||
project: "YourProject"
|
||||
auth_type: "oauth"
|
||||
client_id: "${ADO_CLIENT_ID}"
|
||||
client_secret: "${ADO_CLIENT_SECRET}"
|
||||
```
|
||||
|
||||
## Configuration
|
||||
|
||||
|
||||
|
||||
## Workflow
|
||||
|
||||
### Export Workflow (SpecWeave → ADO)
|
||||
|
||||
```
|
||||
User: Creates increment in SpecWeave
|
||||
.specweave/increments/0002-payment/
|
||||
spec.md (with structure: ado)
|
||||
tasks.md
|
||||
|
||||
↓ ado-sync detects new increment
|
||||
|
||||
Creates in ADO:
|
||||
Feature: 456 "Payment Processing"
|
||||
Area Path: Platform/Payments
|
||||
Iteration: Sprint 12
|
||||
|
||||
User Story: 789 "Subscribe to Plan"
|
||||
Area Path: Platform/Payments
|
||||
Iteration: Sprint 12
|
||||
|
||||
Task: 790 "Create StripeService"
|
||||
Area Path: Platform/Payments/Backend
|
||||
Iteration: Sprint 12
|
||||
|
||||
Task: 791 "Create API endpoints"
|
||||
|
||||
Links created:
|
||||
spec.md → ADO-789
|
||||
tasks.md T001 → ADO-790
|
||||
tasks.md T002 → ADO-791
|
||||
```
|
||||
|
||||
### Import Workflow (ADO → SpecWeave)
|
||||
|
||||
```
|
||||
User: Updates ADO work item status to "Active"
|
||||
|
||||
↓ ADO service hook triggers
|
||||
|
||||
ado-sync:
|
||||
Detects change to ADO-789
|
||||
Finds linked increment: 002-payment
|
||||
Updates: .specweave/increments/0002-payment/spec.md
|
||||
status: planned → in-progress
|
||||
```
|
||||
|
||||
### Bidirectional Sync
|
||||
|
||||
```
|
||||
User: Checks off task in tasks.md
|
||||
- [x] T001: Create StripeService
|
||||
|
||||
↓ ado-sync detects change
|
||||
|
||||
Updates ADO:
|
||||
Work Item 790 status → Closed
|
||||
|
||||
User: Changes ADO-789 to "Closed" in Azure DevOps
|
||||
|
||||
↓ ADO service hook triggers
|
||||
|
||||
ado-sync updates SpecWeave:
|
||||
.specweave/increments/0002-payment/spec.md
|
||||
status: in-progress → completed
|
||||
```
|
||||
|
||||
## API Integration
|
||||
|
||||
### Azure DevOps REST API Endpoints Used
|
||||
|
||||
```typescript
|
||||
// Create Feature
|
||||
POST https://dev.azure.com/{org}/{project}/_apis/wit/workitems/$Feature?api-version=7.0
|
||||
Content-Type: application/json-patch+json
|
||||
|
||||
[
|
||||
{
|
||||
"op": "add",
|
||||
"path": "/fields/System.Title",
|
||||
"value": "Payment Processing"
|
||||
},
|
||||
{
|
||||
"op": "add",
|
||||
"path": "/fields/System.AreaPath",
|
||||
"value": "Platform/Payments"
|
||||
},
|
||||
{
|
||||
"op": "add",
|
||||
"path": "/fields/System.IterationPath",
|
||||
"value": "Sprint 12"
|
||||
}
|
||||
]
|
||||
|
||||
// Create User Story (linked to Feature)
|
||||
POST https://dev.azure.com/{org}/{project}/_apis/wit/workitems/$User%20Story?api-version=7.0
|
||||
|
||||
[
|
||||
{
|
||||
"op": "add",
|
||||
"path": "/fields/System.Title",
|
||||
"value": "Subscribe to Plan"
|
||||
},
|
||||
{
|
||||
"op": "add",
|
||||
"path": "/relations/-",
|
||||
"value": {
|
||||
"rel": "System.LinkTypes.Hierarchy-Reverse",
|
||||
"url": "https://dev.azure.com/{org}/_apis/wit/workItems/456"
|
||||
}
|
||||
}
|
||||
]
|
||||
|
||||
// Create Task (linked to User Story)
|
||||
POST https://dev.azure.com/{org}/{project}/_apis/wit/workitems/$Task?api-version=7.0
|
||||
|
||||
[
|
||||
{
|
||||
"op": "add",
|
||||
"path": "/fields/System.Title",
|
||||
"value": "Create StripeService"
|
||||
},
|
||||
{
|
||||
"op": "add",
|
||||
"path": "/relations/-",
|
||||
"value": {
|
||||
"rel": "System.LinkTypes.Hierarchy-Reverse",
|
||||
"url": "https://dev.azure.com/{org}/_apis/wit/workItems/789"
|
||||
}
|
||||
}
|
||||
]
|
||||
|
||||
// Update status
|
||||
PATCH https://dev.azure.com/{org}/{project}/_apis/wit/workitems/{id}?api-version=7.0
|
||||
|
||||
[
|
||||
{
|
||||
"op": "add",
|
||||
"path": "/fields/System.State",
|
||||
"value": "Active"
|
||||
}
|
||||
]
|
||||
```
|
||||
|
||||
## Service Hooks (Webhooks)
|
||||
|
||||
### Setup ADO Service Hook
|
||||
|
||||
1. Go to Project Settings → Service hooks
|
||||
2. Create new service hook:
|
||||
- Service: Web Hooks
|
||||
- Trigger: Work item updated
|
||||
- URL: `https://your-app.com/api/webhooks/ado`
|
||||
- Filters: Area path = Platform/Payments (optional)
|
||||
|
||||
### Service Hook Handler
|
||||
|
||||
```typescript
|
||||
// Receives ADO service hook
|
||||
POST /api/webhooks/ado
|
||||
|
||||
// ado-sync processes:
|
||||
1. Verify request (optional: check secret)
|
||||
2. Extract work item data
|
||||
3. Find linked SpecWeave increment
|
||||
4. Update spec.md or tasks.md
|
||||
5. Commit changes (optional)
|
||||
```
|
||||
|
||||
## ADO-Specific Features
|
||||
|
||||
### Area Paths
|
||||
|
||||
**Organize work by area**:
|
||||
```markdown
|
||||
# spec.md
|
||||
---
|
||||
ado_area_path: "Platform/Payments"
|
||||
---
|
||||
```
|
||||
|
||||
Maps to ADO Area Path for organization.
|
||||
|
||||
### Iterations/Sprints
|
||||
|
||||
**Assign to sprint**:
|
||||
```markdown
|
||||
# spec.md
|
||||
---
|
||||
ado_iteration: "Sprint 12"
|
||||
---
|
||||
```
|
||||
|
||||
Or auto-detect current sprint:
|
||||
```yaml
|
||||
# config.yaml
|
||||
ado_sync:
|
||||
auto_detect_iteration: true
|
||||
```
|
||||
|
||||
### Work Item Types
|
||||
|
||||
**ADO supports custom work item types**:
|
||||
- Epic → Feature → User Story → Task (default)
|
||||
- Custom types supported via config
|
||||
|
||||
```yaml
|
||||
ado_sync:
|
||||
work_item_types:
|
||||
epic: "Epic"
|
||||
feature: "Feature"
|
||||
story: "User Story"
|
||||
task: "Task"
|
||||
```
|
||||
|
||||
### Custom Fields
|
||||
|
||||
**Sync custom fields**:
|
||||
```yaml
|
||||
ado_sync:
|
||||
custom_fields:
|
||||
- name: "Custom.Priority"
|
||||
map_from: "priority" # From spec.md frontmatter
|
||||
- name: "Custom.Estimate"
|
||||
map_from: "estimate"
|
||||
```
|
||||
|
||||
## Conflict Resolution
|
||||
|
||||
**Scenario**: Both SpecWeave and ADO updated simultaneously
|
||||
|
||||
**Strategy**:
|
||||
1. **Timestamp-based**: Latest change wins
|
||||
2. **User prompt**: Ask user which to keep (via Ping.aiff)
|
||||
3. **Merge**: Combine changes if possible
|
||||
|
||||
**Example**:
|
||||
```
|
||||
SpecWeave: status → in-progress (10:00 AM)
|
||||
ADO: status → closed (10:05 AM)
|
||||
|
||||
ado-sync:
|
||||
Latest is ADO (10:05 AM)
|
||||
Update SpecWeave → completed
|
||||
🔔 Ping.aiff: "ADO conflict resolved - ADO version used"
|
||||
```
|
||||
|
||||
## Error Handling
|
||||
|
||||
**Common errors**:
|
||||
- ADO API rate limits → Retry with exponential backoff
|
||||
- Authentication failed → Notify user, check PAT
|
||||
- Work item not found → Create if export, skip if import
|
||||
- Network errors → Queue for retry
|
||||
- Area Path invalid → Use default or notify user
|
||||
|
||||
## Testing
|
||||
|
||||
**Test scenarios**:
|
||||
1. Create increment → Creates ADO work items
|
||||
2. Update ADO → Updates SpecWeave
|
||||
3. Update SpecWeave → Updates ADO
|
||||
4. Area Path mapping
|
||||
5. Iteration mapping
|
||||
6. Conflict resolution
|
||||
7. Service hook handling
|
||||
8. Custom fields sync
|
||||
|
||||
## Integration with Other Skills
|
||||
|
||||
- **task-builder**: Reads ADO structure from spec.md
|
||||
- **increment-planner**: Can specify structure: ado
|
||||
|
||||
## Comparison: JIRA vs ADO
|
||||
|
||||
| Feature | JIRA (jira-sync) | Azure DevOps (ado-sync) |
|
||||
|---------|------------------|-------------------------|
|
||||
| **Epic level** | Epic | Feature |
|
||||
| **Story level** | Story | User Story |
|
||||
| **Task level** | Sub-task | Task |
|
||||
| **Organization** | Components, Labels | Area Paths |
|
||||
| **Sprints** | Sprints (board-based) | Iterations (path-based) |
|
||||
| **API** | JIRA REST API v3 | Azure DevOps REST API v7.0 |
|
||||
| **Auth** | API Token | PAT or OAuth |
|
||||
| **Webhooks** | JIRA Webhooks | Service Hooks |
|
||||
| **Custom fields** | Custom fields | Work item fields |
|
||||
|
||||
## Future Enhancements
|
||||
|
||||
- Support for ADO Boards/Backlogs
|
||||
- Sprint burndown sync
|
||||
- Test case sync (ADO Test Plans)
|
||||
- Build/release pipeline integration
|
||||
- Wiki sync
|
||||
- Git repo integration (link commits to work items)
|
||||
|
||||
---
|
||||
|
||||
**To implement**: See task in .specweave/increments/
|
||||
|
||||
**See also**: `jira-sync` skill for JIRA integration
|
||||
406
skills/ado-sync/SKILL.md
Normal file
406
skills/ado-sync/SKILL.md
Normal file
@@ -0,0 +1,406 @@
|
||||
---
|
||||
name: ado-sync
|
||||
description: Bidirectional synchronization between SpecWeave increments and Azure DevOps work items (two-way sync by default). Activates ONLY when user asks questions about Azure DevOps integration or needs help configuring ADO sync. Does NOT activate for slash commands. For syncing, use /specweave-ado:sync command instead.
|
||||
---
|
||||
|
||||
# Azure DevOps Sync Skill
|
||||
|
||||
**Purpose**: Seamlessly sync SpecWeave increments with Azure DevOps work items for unified project tracking.
|
||||
|
||||
**Default Behavior**: **Bidirectional (two-way) sync** - Changes in either system are automatically synchronized
|
||||
|
||||
**⚠️ IMPORTANT**: This skill provides HELP and GUIDANCE about Azure DevOps sync. For actual syncing, users should use the `/specweave-ado:sync` command directly. This skill should NOT auto-activate when the command is being invoked.
|
||||
|
||||
**Capabilities**:
|
||||
- Bidirectional sync: SpecWeave ↔ ADO (default)
|
||||
- Create ADO work items from increments
|
||||
- Sync task progress → ADO comments
|
||||
- Update increment status ← ADO state changes
|
||||
- Pull ADO comments and field updates → SpecWeave
|
||||
- Close work items when increments complete
|
||||
- Support for Epics, Features, User Stories
|
||||
|
||||
---
|
||||
|
||||
## When This Skill Activates
|
||||
|
||||
✅ **Do activate when**:
|
||||
- User asks: "How do I set up Azure DevOps sync?"
|
||||
- User asks: "What ADO credentials do I need?"
|
||||
- User asks: "How does ADO integration work?"
|
||||
- User needs help configuring Azure DevOps integration
|
||||
|
||||
❌ **Do NOT activate when**:
|
||||
- User invokes `/specweave-ado:sync` command (command handles it)
|
||||
- Command is already running (avoid duplicate invocation)
|
||||
- Task completion hook is syncing (automatic process)
|
||||
- "Close ADO work item when done"
|
||||
|
||||
---
|
||||
|
||||
## Prerequisites
|
||||
|
||||
### 1. ADO Plugin Installed
|
||||
|
||||
```bash
|
||||
# Check if installed
|
||||
/plugin list --installed | grep specweave-ado
|
||||
|
||||
# Install if needed
|
||||
/plugin install specweave-ado
|
||||
```
|
||||
|
||||
### 2. Azure DevOps Personal Access Token (PAT)
|
||||
|
||||
**Create PAT**:
|
||||
1. Go to https://dev.azure.com/{organization}/_usersSettings/tokens
|
||||
2. Click "New Token"
|
||||
3. Name: "SpecWeave Sync"
|
||||
4. Scopes: Work Items (Read & Write), Comments (Read & Write)
|
||||
5. Copy token → Set environment variable
|
||||
|
||||
**Set Token**:
|
||||
```bash
|
||||
export AZURE_DEVOPS_PAT="your-token-here"
|
||||
```
|
||||
|
||||
### 3. ADO Configuration
|
||||
|
||||
Add to `.specweave/config.json`:
|
||||
```json
|
||||
{
|
||||
"externalPM": {
|
||||
"tool": "ado",
|
||||
"enabled": true,
|
||||
"config": {
|
||||
"organization": "myorg",
|
||||
"project": "MyProject",
|
||||
"workItemType": "Epic",
|
||||
"areaPath": "MyProject\\Team A",
|
||||
"syncOnTaskComplete": true
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Commands Available
|
||||
|
||||
### `/specweave-ado:create-workitem <increment-id>`
|
||||
|
||||
**Purpose**: Create ADO work item from increment
|
||||
|
||||
**Example**:
|
||||
```bash
|
||||
/specweave-ado:create-workitem 0005
|
||||
```
|
||||
|
||||
**Result**:
|
||||
- Creates Epic/Feature/User Story in ADO
|
||||
- Links work item to increment (metadata)
|
||||
- Adds initial comment with spec summary
|
||||
- Sets tags: `specweave`, `increment-0005`
|
||||
|
||||
---
|
||||
|
||||
### `/specweave-ado:sync <increment-id>`
|
||||
|
||||
**Purpose**: Sync increment progress with ADO work item
|
||||
|
||||
**Example**:
|
||||
```bash
|
||||
/specweave-ado:sync 0005
|
||||
```
|
||||
|
||||
**Result**:
|
||||
- Calculates task completion (%)
|
||||
- Updates work item description
|
||||
- Adds comment with progress update
|
||||
- Updates state (New → Active → Resolved)
|
||||
|
||||
---
|
||||
|
||||
### `/specweave-ado:close-workitem <increment-id>`
|
||||
|
||||
**Purpose**: Close ADO work item when increment complete
|
||||
|
||||
**Example**:
|
||||
```bash
|
||||
/specweave-ado:close-workitem 0005
|
||||
```
|
||||
|
||||
**Result**:
|
||||
- Updates work item state → Closed
|
||||
- Adds completion comment with summary
|
||||
- Marks work item as resolved
|
||||
|
||||
---
|
||||
|
||||
### `/specweave-ado:status <increment-id>`
|
||||
|
||||
**Purpose**: Check ADO sync status for increment
|
||||
|
||||
**Example**:
|
||||
```bash
|
||||
/specweave-ado:status 0005
|
||||
```
|
||||
|
||||
**Result**:
|
||||
```
|
||||
ADO Sync Status
|
||||
===============
|
||||
Increment: 0005-payment-integration
|
||||
Work Item: #12345
|
||||
URL: https://dev.azure.com/myorg/MyProject/_workitems/edit/12345
|
||||
State: Active
|
||||
Completion: 60% (6/10 tasks)
|
||||
Last Synced: 2025-11-04 10:30:00
|
||||
Sync Enabled: ✅
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Automatic Sync
|
||||
|
||||
### When Task Completes
|
||||
|
||||
**Trigger**: Post-task-completion hook fires
|
||||
|
||||
**Flow**:
|
||||
1. User marks task complete: `[x] T-005: Add payment tests`
|
||||
2. Hook detects ADO sync enabled
|
||||
3. Calculate new completion %
|
||||
4. Update ADO work item comment:
|
||||
```markdown
|
||||
## Progress Update
|
||||
|
||||
**Increment**: 0005-payment-integration
|
||||
**Status**: 60% complete (6/10 tasks)
|
||||
|
||||
### Recently Completed
|
||||
- [x] T-005: Add payment tests
|
||||
|
||||
### Remaining
|
||||
- [ ] T-007: Add refund functionality
|
||||
- [ ] T-008: Implement subscriptions
|
||||
- [ ] T-009: Add analytics
|
||||
- [ ] T-010: Security audit
|
||||
|
||||
---
|
||||
🤖 Auto-updated by SpecWeave
|
||||
```
|
||||
|
||||
### When Increment Completes
|
||||
|
||||
**Trigger**: `/specweave:done` command
|
||||
|
||||
**Flow**:
|
||||
1. User runs `/specweave:done 0005`
|
||||
2. Validate all tasks complete
|
||||
3. Close ADO work item automatically
|
||||
4. Add completion comment with summary
|
||||
|
||||
---
|
||||
|
||||
## Work Item Types
|
||||
|
||||
### Epic (Recommended)
|
||||
|
||||
**Use When**: Large feature spanning multiple sprints
|
||||
|
||||
**Mapping**:
|
||||
- SpecWeave increment → ADO Epic
|
||||
- Tasks → Epic description (checklist)
|
||||
- Progress → Epic comments
|
||||
|
||||
---
|
||||
|
||||
### Feature
|
||||
|
||||
**Use When**: Medium-sized feature within a sprint
|
||||
|
||||
**Mapping**:
|
||||
- SpecWeave increment → ADO Feature
|
||||
- Tasks → Feature description (checklist)
|
||||
- Progress → Feature comments
|
||||
|
||||
---
|
||||
|
||||
### User Story
|
||||
|
||||
**Use When**: Small, single-sprint work
|
||||
|
||||
**Mapping**:
|
||||
- SpecWeave increment → ADO User Story
|
||||
- Tasks → User Story description (checklist)
|
||||
- Progress → User Story comments
|
||||
|
||||
---
|
||||
|
||||
## Bidirectional Sync (Optional)
|
||||
|
||||
**Enable**: Set `bidirectional: true` in config
|
||||
|
||||
**Flow**: ADO → SpecWeave
|
||||
1. User updates work item state in ADO (Active → Resolved)
|
||||
2. SpecWeave detects change (polling or webhook)
|
||||
3. Updates increment status locally
|
||||
4. Notifies user: "Work item #12345 resolved → Increment 0005 marked complete"
|
||||
|
||||
**Note**: Bidirectional sync requires webhook or polling setup
|
||||
|
||||
---
|
||||
|
||||
## Configuration Options
|
||||
|
||||
**`.specweave/config.json`**:
|
||||
```json
|
||||
{
|
||||
"externalPM": {
|
||||
"tool": "ado",
|
||||
"enabled": true,
|
||||
"config": {
|
||||
"organization": "myorg",
|
||||
"project": "MyProject",
|
||||
"personalAccessToken": "${AZURE_DEVOPS_PAT}",
|
||||
"workItemType": "Epic",
|
||||
"areaPath": "MyProject\\Team A",
|
||||
"iterationPath": "MyProject\\Sprint 1",
|
||||
"syncOnTaskComplete": true,
|
||||
"syncOnIncrementComplete": true,
|
||||
"createWorkItemsAutomatically": true,
|
||||
"bidirectional": false,
|
||||
"tags": ["specweave", "increment"],
|
||||
"customFields": {
|
||||
"incrementId": "Custom.IncrementId"
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### Error: "Personal Access Token invalid"
|
||||
|
||||
**Solution**:
|
||||
1. Verify token is set: `echo $AZURE_DEVOPS_PAT`
|
||||
2. Check token scopes: Work Items (Read & Write)
|
||||
3. Ensure token not expired
|
||||
4. Regenerate token if needed
|
||||
|
||||
---
|
||||
|
||||
### Error: "Work item not found"
|
||||
|
||||
**Solution**:
|
||||
1. Check work item ID is correct
|
||||
2. Verify you have access to the project
|
||||
3. Ensure work item not deleted
|
||||
|
||||
---
|
||||
|
||||
### Error: "Organization or project not found"
|
||||
|
||||
**Solution**:
|
||||
1. Verify organization name: https://dev.azure.com/{organization}
|
||||
2. Check project name (case-sensitive)
|
||||
3. Ensure you have access to the project
|
||||
|
||||
---
|
||||
|
||||
## API Rate Limits
|
||||
|
||||
**Azure DevOps**:
|
||||
- Rate limit: 200 requests per minute per PAT
|
||||
- Burst limit: 5000 requests per hour
|
||||
- Recommendation: Enable rate limiting in config
|
||||
|
||||
**Config**:
|
||||
```json
|
||||
{
|
||||
"externalPM": {
|
||||
"config": {
|
||||
"rateLimiting": {
|
||||
"enabled": true,
|
||||
"maxRequestsPerMinute": 150
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Security Best Practices
|
||||
|
||||
### DO:
|
||||
- ✅ Store PAT in environment variable (`AZURE_DEVOPS_PAT`)
|
||||
- ✅ Use `.env` file (gitignored)
|
||||
- ✅ Set minimum required scopes
|
||||
- ✅ Rotate PAT every 90 days
|
||||
|
||||
### DON'T:
|
||||
- ❌ Commit PAT to git
|
||||
- ❌ Share PAT via Slack/email
|
||||
- ❌ Use PAT with excessive permissions
|
||||
- ❌ Log PAT to console/files
|
||||
|
||||
---
|
||||
|
||||
## Related Commands
|
||||
|
||||
- `/specweave:inc` - Create increment (auto-creates ADO work item if enabled)
|
||||
- `/specweave:do` - Execute tasks (auto-syncs progress to ADO)
|
||||
- `/specweave:done` - Complete increment (auto-closes ADO work item)
|
||||
- `/specweave:status` - Show increment status (includes ADO sync status)
|
||||
|
||||
---
|
||||
|
||||
## Examples
|
||||
|
||||
### Example 1: Create Increment with ADO Sync
|
||||
|
||||
```bash
|
||||
# User
|
||||
"Create increment for payment integration"
|
||||
|
||||
# SpecWeave (if ADO enabled)
|
||||
1. PM agent generates spec.md
|
||||
2. Auto-create ADO Epic #12345
|
||||
3. Link Epic to increment metadata
|
||||
4. Display: "Created increment 0005 → ADO Epic #12345"
|
||||
```
|
||||
|
||||
### Example 2: Manual Sync
|
||||
|
||||
```bash
|
||||
# User completed 3 tasks manually
|
||||
# Now sync to ADO
|
||||
|
||||
/specweave-ado:sync 0005
|
||||
|
||||
# Result: ADO Epic #12345 updated with 30% progress
|
||||
```
|
||||
|
||||
### Example 3: Check Sync Status
|
||||
|
||||
```bash
|
||||
/specweave-ado:status 0005
|
||||
|
||||
# Output:
|
||||
# Work Item: #12345
|
||||
# URL: https://dev.azure.com/myorg/MyProject/_workitems/edit/12345
|
||||
# State: Active
|
||||
# Completion: 60%
|
||||
# Last Synced: 5 minutes ago
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
**Status**: Ready to use
|
||||
**Version**: 0.1.0
|
||||
**Plugin**: specweave-ado
|
||||
Reference in New Issue
Block a user