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:

Direction	What Syncs	Example
SpecWeave → External	Content (specs, tasks, ACs)	Create JIRA Story from US-001
External → SpecWeave	Status only	JIRA "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:

SpecWeave	GitHub	JIRA	Azure DevOps
Feature (FS-XXX)	Milestone	Epic	Feature
User Story (US-XXX)	Issue	Story	User Story
Task (T-XXX)	Checkbox	Sub-task	Task

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

Feature	GitHub	JIRA	Azure DevOps
Setup Complexity	Simple	Medium	Medium
Auth Method	gh CLI	API Token	PAT
Hierarchy	Milestone → Issue → Checkbox	Epic → Story → Sub-task	Feature → US → Task
Team Support	Repos	Boards	Area Paths
Sprint Support	Milestones	Sprints	Iterations
Best For	Open source, startups	Enterprise Atlassian	Microsoft ecosystem

---

Quick Setup Guides

GitHub (Recommended for Most)

# 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:

"I want to create my feature"

"Sync progress"

Full GitHub Guide →

JIRA (Enterprise Atlassian)

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

# 2. Configure credentials
cat >> .env << EOF
[email protected]
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:

"I want to add user authentication"

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

2. Sync to external (happens automatically or manually):

"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:

"Import issues from external tools"

SpecWeave creates read-only references (FS-001E, US-001E-github-issue-42).

2. Work on tasks locally:

"Start implementing"

3. Status syncs back (if Gate 2 enabled):

"Sync progress"

Workflow 3: Complete Increment → Close External

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

1. Check all tasks completed:

"What's the status?"

2. Close increment with quality gates:

"We're done, close increment 0042"

SpecWeave validates (all tasks complete, test coverage >= 60%, living docs updated) and closes all external items if Gate 3 is enabled (GitHub closes issues, 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=[email protected]
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:

• GitHub Integration Guide - Full GitHub setup with Projects integration
• JIRA Integration Guide - 1-level and 2-level board mapping
• Azure DevOps Integration Guide - Area paths and iteration support

Or learn about specific workflows:

• Multi-Project Setup - Configure multiple repos/teams
• Sync Strategies - Intelligent vs custom queries
• Hierarchy Mapping - Map any external hierarchy

---

SpecWeave 1.0 - Enterprise-grade external tool integration