Initial commit
This commit is contained in:
Zhongwei Li
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
|
||||
Reference in New Issue
Block a user