Skip to main content

External Tools Integration Overview

SpecWeave 1.0 provides enterprise-grade bidirectional synchronization with the three major project management platforms:

  • GitHub Issues - Native integration for GitHub-centric teams
  • JIRA - Enterprise Atlassian integration with board support
  • Azure DevOps - Microsoft ecosystem with area path mapping

Architecture Overview​

Key Concepts​

1. Split-Source Sync (Not True Bidirectional)​

SpecWeave uses split-source synchronization:

DirectionWhat SyncsExample
SpecWeave → ExternalContent (specs, tasks, ACs)Create JIRA Story from US-001
External → SpecWeaveStatus onlyJIRA "Done" → task completed

Why split-source?

  • SpecWeave remains the source of truth for what to build
  • External tools track status for team visibility
  • No merge conflicts between systems
  • Clear ownership boundaries

2. Three Permission Gates​

Every sync operation passes through three permission gates:

┌─────────────────────────────────────────────────────────────┐
│                    PERMISSION GATES                          │
├─────────────────────────────────────────────────────────────┤
│                                                              │
│  Gate 1: canUpsertInternalItems                             │
│  └─ Can create/update items that originated in SpecWeave?   │
│     Example: Push US-001 to create JIRA story               │
│                                                              │
│  Gate 2: canUpdateExternalItems                             │
│  └─ Can update items that were imported from external?      │
│     Example: Update GitHub issue that was imported          │
│                                                              │
│  Gate 3: canUpdateStatus                                    │
│  └─ Can change status fields in external tools?             │
│     Example: Close JIRA issue when increment completes      │
│                                                              │
└─────────────────────────────────────────────────────────────┘

Default: All gates are OFF (safe mode). Enable explicitly in config.

3. Hierarchy Mapping​

SpecWeave maps its 3-level hierarchy to each platform:

SpecWeaveGitHubJIRAAzure DevOps
Feature (FS-XXX)MilestoneEpicFeature
User Story (US-XXX)IssueStoryUser Story
Task (T-XXX)CheckboxSub-taskTask

4. Project Structure Levels​

SpecWeave supports two folder structure levels:

1-Level Structure (Simple)​

.specweave/docs/internal/specs/
├── my-project/
│   ├── FS-001/
│   │   ├── FEATURE.md
│   │   └── us-001-login.md
│   └── FS-002/
│       └── ...

Use when: Single team, simple organization

2-Level Structure (Team-Based)​

.specweave/docs/internal/specs/
├── my-project/
│   ├── frontend-team/
│   │   ├── FS-001/
│   │   └── FS-002/
│   ├── backend-team/
│   │   ├── FS-003/
│   │   └── FS-004/
│   └── mobile-team/
│       └── FS-005/

Use when: Multiple teams, JIRA boards, or ADO area paths

Platform Comparison​

FeatureGitHubJIRAAzure DevOps
Setup ComplexitySimpleMediumMedium
Auth Methodgh CLIAPI TokenPAT
HierarchyMilestone → Issue → CheckboxEpic → Story → Sub-taskFeature → US → Task
Team SupportReposBoardsArea Paths
Sprint SupportMilestonesSprintsIterations
Best ForOpen source, startupsEnterprise AtlassianMicrosoft ecosystem

Quick Setup Guides​

# 1. Install and authenticate GitHub CLI
brew install gh
gh auth login

# 2. Initialize SpecWeave with GitHub
specweave init .
# Select: "Yes, GitHub Issues"

# 3. Create and sync increment
/sw:increment "my feature"
/sw:sync-progress

Full GitHub Guide →

JIRA (Enterprise Atlassian)​

# 1. Create API token at id.atlassian.com

# 2. Configure credentials
cat >> .env << EOF
JIRA_EMAIL=your-email@company.com
JIRA_API_TOKEN=your-token
EOF

# 3. Configure domain in config.json
specweave config set issueTracker.domain "company.atlassian.net"

# 4. Initialize with JIRA
specweave init .
# Select: "Yes, JIRA"

Full JIRA Guide →

Azure DevOps (Microsoft Ecosystem)​

# 1. Create PAT at dev.azure.com

# 2. Configure credentials
cat >> .env << EOF
AZURE_DEVOPS_PAT=your-pat
EOF

# 3. Configure org in config.json
specweave config set issueTracker.organization_ado "your-org"

# 4. Initialize with ADO
specweave init .
# Select: "Yes, Azure DevOps Work Items"

Full Azure DevOps Guide →

Sync Workflows​

Workflow 1: Create Internal → Push to External​

When you create an increment locally and want it visible in external tools:

# 1. Create increment
/sw:increment "User authentication feature"

# 2. AI generates spec.md, plan.md, tasks.md

# 3. Sync to external (happens automatically or manually)
/sw:sync-progress

# Result:
# - GitHub: Creates milestone + issues
# - JIRA: Creates Epic + Stories + Sub-tasks
# - ADO: Creates Feature + User Stories + Tasks

Workflow 2: Import External → Work Locally​

When work items exist in external tools and you want to implement them:

# 1. Import from external tool
/sw:import-external

# 2. SpecWeave creates read-only references
# Result:
# - FS-001E (E = external)
# - US-001E-github-issue-42
# - Frontmatter includes: external_ref, external_url

# 3. Work on tasks locally
/sw:do

# 4. Status syncs back (if Gate 2 enabled)
/sw:sync-progress

Workflow 3: Complete Increment → Close External​

When an increment completes and you want to close all related external items:

# 1. All tasks completed
/sw:progress
# → "15/15 tasks complete"

# 2. Close increment with quality gates
/sw:done 0042

# 3. SpecWeave validates:
# - All tasks complete ✓
# - Test coverage >= 60% ✓
# - Living docs updated ✓

# 4. Closes all external items (if Gate 3 enabled)
# - GitHub: Closes issues, updates milestone
# - JIRA: Transitions to "Done"
# - ADO: Sets state to "Closed"

Configuration Reference​

config.json Structure​

{
  "sync": {
    "enabled": true,
    "autoSync": false,
    "providers": {
      "github": {
        "enabled": true,
        "owner": "your-org",
        "repo": "your-repo"
      },
      "jira": {
        "enabled": true,
        "projectKey": "PROJ"
      },
      "ado": {
        "enabled": true,
        "project": "your-project"
      }
    },
    "permissions": {
      "canUpsertInternalItems": true,
      "canUpdateExternalItems": false,
      "canUpdateStatus": true
    },
    "profiles": {
      "default": {
        "strategy": "intelligent",
        "hierarchyMapping": {
          "featureLevelTypes": ["Epic", "Feature"],
          "userStoryTypes": ["Story", "User Story", "PBI"]
        }
      }
    }
  },
  "issueTracker": {
    "domain": "company.atlassian.net",
    "organization_ado": "your-org"
  }
}

.env Secrets (Never Commit!)​

# GitHub (via gh CLI, usually not needed in .env)
GITHUB_TOKEN=ghp_xxxxxxxxxxxx

# JIRA
JIRA_EMAIL=your-email@company.com
JIRA_API_TOKEN=xxxxxxxxxxxxxxxxxxxxxx

# Azure DevOps
AZURE_DEVOPS_PAT=xxxxxxxxxxxxxxxxxxxx

Troubleshooting​

"Permission denied" errors​

Cause: Gate permissions not enabled

Fix:

# Check current permissions
specweave config get sync.permissions

# Enable needed gates
specweave config set sync.permissions.canUpsertInternalItems true

"Project not found" errors​

Cause: Config mismatch or authentication issue

Fix:

# Verify config
specweave context projects

# Check authentication
gh auth status          # GitHub
/sw-jira:status         # JIRA
/sw-ado:status          # ADO

"Duplicate issues" created​

Cause: Running sync multiple times without idempotency

Fix: SpecWeave uses 3-layer idempotency (frontmatter → metadata.json → API). If duplicates occur:

  1. Check frontmatter for existing IDs
  2. Use --dry-run first to preview
  3. Never use --force unless testing

"Status not syncing back"​

Cause: Gate 3 (canUpdateStatus) is OFF

Fix:

specweave config set sync.permissions.canUpdateStatus true

Best Practices​

1. Start with Gates OFF​

Begin with all gates OFF, enable incrementally:

  1. First enable Gate 1 (push specs out)
  2. Test thoroughly
  3. Then enable Gate 3 (status sync)
  4. Only enable Gate 2 if you import external items

2. Use Intelligent Strategy​

The intelligent sync strategy auto-maps user stories to projects:

{
  "sync": {
    "profiles": {
      "default": {
        "strategy": "intelligent"
      }
    }
  }
}

3. Prefer Per-US Project Field​

Always specify project per user story in spec.md:

### US-001: Login Form
**Project**: frontend-app
**As a** user, I want...

4. Keep External as Read-Only References​

When importing external items:

  • Don't modify the spec content
  • Only track status changes
  • Use FS-XXXE naming (E = external)

5. Monitor Sync Health​

Regular health checks:

# Check sync status
/sw:workflow

# View external items dashboard
/sw:external

# Check for drift
/sw:sync-diagnostics

Next Steps​

Choose your platform guide:

Or learn about specific workflows:

SpecWeave 1.0 - Enterprise-grade external tool integration