# GitHub ↔ SpecWeave Concept Mapping

**Purpose**: Quick reference for mapping GitHub concepts to SpecWeave architecture

**Source of Truth**: this file (the 1.x `tool-concept-mapping.md` guide was removed in 2.0)

**Last Synced**: 2025-11-04

---

## 🚨 CRITICAL: Agents MUST Follow This Mapping

When syncing between GitHub and SpecWeave, you **MUST** use these exact mappings. Do not deviate or create custom mappings.

---

## Core Concept Mapping

| GitHub Concept | SpecWeave Concept | Location | Mapping Rule |
|----------------|-------------------|----------|--------------|
| **Milestone** | Release Plan | `.specweave/docs/internal/delivery/release-v{version}.md` | 1 Milestone = 1 Release Plan |
| **Project** | Increment or Release | Context-dependent | Board scope determines mapping |
| **Issue (feature)** | RFC | `.specweave/docs/internal/architecture/rfc/####-{name}.md` | Feature request = Technical RFC |
| **Issue (bug)** | Incident | `.specweave/docs/internal/operations/incidents/{id}.md` | Bug = Operational incident |
| **Issue (task)** | Task | `.specweave/increments/####-{name}/tasks.md` | Implementation task |
| **Pull Request** | Implementation | Code + increment link | PR references increment/task |
| **Label** | Tag | `metadata.json` → tags | Filtering/categorization |
| **Assignee** | Owner | Task ownership | Person responsible |
| **Comment** | Progress Update | Task notes, discussions | Async collaboration |

---

## Status Mapping (MUST BE EXACT)

| GitHub State | SpecWeave Status | Notes |
|--------------|------------------|-------|
| `open` (no assignee) | `planned` | Not started, no owner |
| `open` (with assignee) | `in_progress` | Active development |
| `closed` (completed) | `completed` | Successfully delivered |
| `closed` (not planned) | `cancelled` | Won't do, out of scope |

**Rule**: Check assignee and close reason to determine SpecWeave status

---

## Priority Mapping

| GitHub Label | SpecWeave Priority | Description |
|--------------|-------------------|-------------|
| `priority: critical` | `P1` | Critical, must do now |
| `priority: high` | `P2` | High priority |
| `priority: medium` | `P3` | Medium priority |
| `priority: low` | `P4` | Low priority, nice-to-have |
| (no label) | `P3` | Default to medium |

---

## Issue Type Detection

**How to classify GitHub issues** (use labels, title prefixes, or body content):

```
Is the issue...
├─ A new feature request?
│  → Create RFC: .specweave/docs/internal/architecture/rfc/####-{name}.md
│
├─ A bug/incident?
│  → Create Incident: .specweave/docs/internal/operations/incidents/{id}.md
│
├─ An implementation task?
│  → Add to tasks.md: .specweave/increments/####-{name}/tasks.md
│
└─ An architecture decision?
   → Create ADR: .specweave/docs/internal/architecture/adr/####-{decision}.md
```

**Detection Rules**:
1. **Feature Request**: Labels include `enhancement`, `feature`, OR title starts with `[Feature]`, `[RFC]`
2. **Bug/Incident**: Labels include `bug`, `incident`, OR title starts with `[Bug]`, `[Incident]`
3. **Task**: Labels include `task`, `chore`, OR title starts with `[Task]`, `T-###`
4. **ADR**: Title starts with `[ADR]`, `[Decision]`, OR body contains "We need to decide"

---

## Milestone → Release Plan Mapping

**Mapping Rule**: 1 GitHub Milestone = 1 SpecWeave Release Plan

**Example**:
```
GitHub: Milestone "v1.0 - User Authentication" (Due: Jan 31)
  ↓
SpecWeave: .specweave/docs/internal/delivery/release-v1.0.md
```

**Release Plan Contents**:
- What increments are included (list of increment IDs)
- What features ship (user-facing)
- Testing strategy (E2E, integration, unit)
- Rollout plan (blue-green, canary, phased)
- Rollback plan (how to revert if issues)
- Success metrics (DORA, test coverage, uptime)

---

## Issue → Increment Mapping

**Use Case**: Import GitHub issue as SpecWeave increment

**Mapping Logic**:
1. **Read GitHub Issue**:
   - Title → Increment title
   - Body → Spec.md executive summary
   - Labels → Priority (P1/P2/P3/P4)
   - Assignee → Increment owner

2. **Create Increment**:
   ```bash
   .specweave/increments/####-{kebab-case-title}/
   ├── spec.md          # From issue body
   ├── plan.md          # Generated by architect agent
   ├── tasks.md         # Parsed from issue checklist OR generated
   └── metadata.json    # Links back to GitHub issue
   ```

3. **Store Bidirectional Link**:
   ```json
   {
     "github": {
       "issue_number": 123,
       "issue_url": "https://github.com/owner/repo/issues/123",
       "milestone": "v1.0",
       "labels": ["enhancement", "P1"],
       "synced_at": "2025-11-04T10:30:00Z"
     }
   }
   ```

---

## Pull Request → Task Linking

**Mapping Rule**: Each PR should reference the increment and task it implements

**PR Title Format**:
```
T-007: Implement Claude plugin installer (#130)
```

**PR Body Template**:
```markdown
## Increment

Implements: #130 (Increment 0004: Plugin Architecture)
Task: T-007 - Implement Claude plugin installer

## Changes

- Added plugin installer CLI
- Updated plugin loader to auto-install core plugin
- Added tests for installer

## Testing

- ✅ Unit tests: `npm test src/cli/install.test.ts`
- ✅ E2E tests: `npm run test:e2e`

## Checklist

- [x] Tests pass
- [x] Documentation updated
- [x] CHANGELOG.md updated
- [x] Increment metadata updated

Closes #130 (when all tasks done)
```

**Linking Rules**:
- PR title starts with `T-###:` (task ID)
- PR body includes `Implements: #issue-number`
- Use `Closes #issue-number` ONLY when increment is 100% complete

---

## Comment → Progress Update Mapping

**Trigger**: After task completion (post-task-completion hook)

**Format** (posted to GitHub issue):
```markdown
## Progress Update

**Increment**: 0004-plugin-architecture
**Status**: 15% complete (7/48 tasks)
**Last Updated**: 2025-11-04 10:30:00

### Recently Completed
- [x] T-007: Implement Claude plugin installer

### Next Up
- [ ] T-008: Add plugin validation
- [ ] T-009: Test plugin loading

### Files Changed
- `src/cli/install.ts` (+127 lines)
- `src/core/plugin-loader.ts` (+45 lines)
- `tests/integration/install.test.ts` (+89 lines)

---
🤖 Auto-updated by SpecWeave GitHub Plugin
```

---

## Label Conventions

**SpecWeave Standard Labels** (auto-add these):
- `specweave` - All SpecWeave-synced issues
- `increment` - Increment tracking issue
- `P1`, `P2`, `P3`, `P4` - Priority labels
- `in-progress` - Active development
- `testing` - Implementation done, testing phase
- `ready-for-review` - All tasks complete, awaiting review
- `blocked` - Blocked by external dependency

**Project-Specific Labels** (respect existing):
- Keep existing labels (don't remove them)
- Add SpecWeave labels (don't replace)
- Example: Issue has `frontend` + `enhancement` → Add `specweave` + `P2`

---

## Conflict Resolution Rules

**Scenario**: Both GitHub issue and SpecWeave increment changed

**Resolution Priority** (Source of Truth):
1. **Status changes** → SpecWeave wins (local is source of truth)
2. **Content changes** → GitHub wins (team collaboration via GitHub)
3. **Task completion** → SpecWeave wins (local task tracking)
4. **Assignee changes** → GitHub wins (team management via GitHub)

**Conflict Handling**:
```
IF GitHub issue closed BUT SpecWeave increment not done
  → Prompt user: "GitHub issue closed but increment not complete. Action?"
    1) Close increment (trust GitHub)
    2) Reopen issue (trust SpecWeave)
    3) Manual resolution

IF SpecWeave increment done BUT GitHub issue still open
  → Auto-close GitHub issue (SpecWeave is source of truth for completion)

IF Both changed status simultaneously
  → Log conflict, prompt user for resolution
```

---

## Examples

### Example 1: Import GitHub Issue as Increment

**GitHub Issue #123**:
```
Title: Add user authentication with OAuth2
Labels: enhancement, P1
Body: We need OAuth2 authentication with Google and GitHub providers...
```

**SpecWeave Result**:
```
.specweave/increments/0005-user-authentication/
├── spec.md           # "Add user authentication with OAuth2"
├── plan.md           # Architect generates implementation plan
├── tasks.md          # PM generates 12 tasks
└── metadata.json     # Links to GitHub issue #123
```

### Example 2: Sync Task Completion to GitHub

**SpecWeave**: Complete T-007 (7/48 tasks, 15%)

**GitHub**: Post comment to issue #130:
```markdown
## Progress Update
**Status**: 15% complete (7/48 tasks)

### Recently Completed
- [x] T-007: Implement Claude plugin installer

---
🤖 Auto-updated by SpecWeave
```

### Example 3: Close Increment → Close Issue

**SpecWeave**: `sw:done 0004` (all 48 tasks complete)

**GitHub**: Close issue #130 with comment:
```markdown
✅ **Increment Completed**

**Final Stats**:
- 48/48 tasks completed (100%)
- 127 test cases passing
- Duration: 4 weeks

**Deliverables**:
- Plugin architecture implemented
- 15 plugins migrated
- Documentation updated

Closing this issue as the increment is complete.

---
🤖 Auto-closed by SpecWeave
```

---

## Traceability

**From GitHub Issue to Code**:
```
GitHub Issue #123 "User Authentication"
  ↓
SpecWeave Increment: 0005-user-authentication
  ↓
spec.md → plan.md → tasks.md
  ↓
Code: src/services/auth/
  ↓
Tests: tests/e2e/auth.spec.ts
  ↓
Pull Requests: #45, #46, #47
  ↓
Deployment: production
```

**From Code to GitHub Issue**:
```
File: src/services/auth/oauth.ts
  ↓
Increment: 0005-user-authentication (via git blame or folder structure)
  ↓
GitHub Issue: #123 (via metadata.json)
  ↓
Milestone: v1.0 (release plan)
```

---

## Validation Checklist

**Before syncing, verify**:
- [ ] GitHub issue exists and is accessible
- [ ] Increment metadata has valid GitHub link
- [ ] Status mapping follows rules above (no custom mappings)
- [ ] Priority mapped correctly (P1/P2/P3/P4)
- [ ] Labels follow SpecWeave conventions
- [ ] Comments include increment context
- [ ] Bidirectional links are valid

---

## Related Documentation

- **Sync Skill**: [../../skills/sync/SKILL.md](../../skills/sync/SKILL.md)
- **CLI**: `specweave sync push | pull | status | setup`

---

**Last Updated**: 2025-11-04
**Version**: 1.0.0
**Plugin**: specweave-github
