/ado-push

description: Push local changes to Azure DevOps (like git push). Supports increment, project, or full living docs sync.

ADO Push Command

**Usage**: `sw-ado:push [target] [options]`

**Purpose**: Push local changes to Azure DevOps (like `git push`)

---

Quick Start

# Push current/active increment (simple mode)
sw-ado:push

# Push specific increment
sw-ado:push 0005

# Push ALL local changes to ADO (living docs sync)
sw-ado:push --all

# Push specific project/board
sw-ado:push --project clinical-insights

# Push specific feature hierarchy
sw-ado:push --feature FS-042

---

Sync Modes

Mode 1: Increment Sync (Default)

Pushes task progress from ONE increment to its linked work item.

Mode 2: Living Docs Sync (--all)

Pushes ALL local spec changes to corresponding ADO items:

• Scans `.specweave/docs/internal/specs/` for modified specs
• Updates status, progress, comments on linked ADO items
• Respects multi-project folder structure

Mode 3: Project-Scoped Sync (--project)

Pushes changes only within a specific project folder.

Mode 4: Feature Hierarchy Sync (--feature)

Pushes a feature and all its child user stories.

---

What Gets Pushed

| Field | Source | |-------|--------| | **Progress** | Calculated from tasks.md (X/Y tasks, Z%) | | **Comment** | Auto-generated with completed tasks list | | **Completion %** | Updated on work item custom field | | **State** | Updated if threshold crossed (e.g., 100% -> Resolved) |

---

Command Behavior

When user runs this command:

0. Load Credentials from .env (MANDATORY FIRST)

**CRITICAL**: Read PAT from `.env` file, NOT from shell environment variables.

# Read PAT from .env file
ADO_PAT=$(grep '^AZURE_DEVOPS_PAT=' .env 2>/dev/null | cut -d'=' -f2)

if [ -z "$ADO_PAT" ]; then
  echo "ERROR: AZURE_DEVOPS_PAT not found in .env file"
  echo "Add to .env: AZURE_DEVOPS_PAT=your-pat-here"
  exit 1
fi

1. Check Permission Gate (MANDATORY)

const config = JSON.parse(await fs.readFile('.specweave/config.json', 'utf-8'));
const canUpdateExternal = config?.sync?.settings?.canUpdateExternalItems ?? false;

if (!canUpdateExternal) {
  console.log(`
Permission Denied: ADO writes disabled

Current: sync.settings.canUpdateExternalItems = false

To enable writes, update .specweave/config.json:
  "sync": { "settings": { "canUpdateExternalItems": true } }

Or use read-only mode:
  sw-ado:pull ${incrementId}
`);
  return;
}

2. Resolve Increment & Profile

const incrementId = args.incrementId || await findActiveIncrement();

const metadata = JSON.parse(await fs.readFile(
  `.specweave/increments/${incrementId}/metadata.json`, 'utf-8'
));

const adoWorkItemId = metadata?.external_sync?.ado?.workItemId;
if (!adoWorkItemId) {
  console.log(`Not linked to ADO. Run: sw-ado:create ${incrementId}`);
  return;
}

const profileName = metadata?.external_sync?.ado?.profile
  || config?.sync?.defaultProfile;

3. Calculate Progress

const tasksContent = await fs.readFile(
  `.specweave/increments/${incrementId}/tasks.md`, 'utf-8'
);

const totalTasks = (tasksContent.match(/### T-\d+/g) || []).length;
const completedTasks = (tasksContent.match(/\[x\] completed/gi) || []).length;
const percentage = Math.round((completedTasks / totalTasks) * 100);

// Find recently completed tasks (for comment)
const recentlyCompleted = parseRecentlyCompletedTasks(tasksContent);

4. Invoke Push Sync

Use Skill tool: Skill({ skill: "sw-ado:ado-sync", args: "Push progress to ADO for increment {increment-id}.

DIRECTION: to-ado
PERMISSION: canUpdateExternalItems = true (verified)

Profile: {profileName}
Work Item: #{workItemId}

Progress: {completedTasks}/{totalTasks} ({percentage}%)
Recently completed: {recentlyCompleted}

Steps:
1. Format progress comment with task list
2. POST comment to ADO work item
3. PATCH work item completion field
4. Update state if threshold crossed:
   - 100% completed -> Resolved (if canUpdateStatus)
5. Update sync timestamp in metadata
6. Display push summary"

5. Display Result

Pushed to ADO

Work Item: #12345
Profile: ado-my-project

Progress: 6/10 tasks (60%)

Comment posted:
  "Progress Update: 60% complete

   Recently completed:
   - T-005: Add payment validation
   - T-006: Implement refund flow"

Fields updated:
  Completion: 60%

URL: https://dev.azure.com/org/project/_workitems/edit/12345

---

Permission Requirements

| Permission | Required | Purpose | |------------|----------|---------| | `canUpdateExternalItems` | **true** | Write to ADO | | `canUpdateStatus` | optional | Change work item state |

If `canUpdateStatus` is false, progress is posted but state unchanged.

---

Examples

Example 1: Simple Push

User: sw-ado:push

Claude:
Checking permissions...
  canUpdateExternalItems: true

Pushing to ADO...
  Increment: 0005-payment-integration
  Work Item: #12345

Pushed to ADO

Progress: 8/10 tasks (80%)
Comment posted with 2 recently completed tasks

Push complete!

Example 2: Permission Denied

User: sw-ado:push 0005

Claude:
Checking permissions...
  canUpdateExternalItems: false

Permission Denied

To enable ADO writes:
1. Edit .specweave/config.json
2. Set sync.settings.canUpdateExternalItems = true

Or use read-only: sw-ado:pull 0005

Example 3: 100% Complete

User: sw-ado:push 0005

Claude:
Pushing to ADO...

Progress: 10/10 tasks (100%)

Comment posted:
  "Progress Update: 100% complete - All tasks done!"

State updated:
  Active -> Resolved (canUpdateStatus = true)

Ready to close: sw-ado:close 0005

---

Sync Brief (MANDATORY OUTPUT)

**After EVERY push operation, display a compact summary:**

Brief Format (Single Increment)

┌─────────────────────────────────────────────────────────┐
│  PUSH COMPLETE                                    ✓ ADO │
├─────────────────────────────────────────────────────────┤
│  Increment: 0005-payment-integration