specweave 0.30.13 → 0.30.16

package/plugins/specweave-github/commands/pull.md

@@ -0,0 +1,142 @@
+---
+name: specweave-github:pull
+description: Pull latest changes from GitHub Issues (like git pull). Imports comments, labels, and status changes.
+---
+
+# GitHub Pull Command
+
+**Usage**: `/specweave-github:pull [increment-id]`
+
+**Purpose**: Pull latest changes from GitHub Issues to your local increment (like `git pull`)
+
+---
+
+## Quick Start
+
+```bash
+# Pull for current/active increment
+/specweave-github:pull
+
+# Pull for specific increment
+/specweave-github:pull 0005
+```
+
+---
+
+## What Gets Pulled
+
+| Field | Behavior |
+|-------|----------|
+| **Status** | Issue state (open/closed) -> increment status |
+| **Labels** | Priority labels imported |
+| **Comments** | New team comments imported to notes |
+| **Assignees** | Updated if changed |
+| **Milestone** | Iteration/sprint mapping |
+
+---
+
+## Command Behavior
+
+When user runs this command:
+
+### 1. Resolve Increment
+
+```typescript
+const incrementId = args.incrementId || await findActiveIncrement();
+
+const metadata = JSON.parse(await fs.readFile(
+  `.specweave/increments/${incrementId}/metadata.json`, 'utf-8'
+));
+
+const issueNumber = metadata?.external_sync?.github?.issue;
+if (!issueNumber) {
+  console.log(`Not linked to GitHub. Run: /specweave-github:create ${incrementId}`);
+  return;
+}
+```
+
+### 2. Fetch and Compare
+
+```
+Use Task tool with subagent_type: "specweave-github:github-manager:AGENT"
+
+Prompt: "Pull changes from GitHub for increment {increment-id}.
+
+Issue: #{issueNumber}
+
+Steps:
+1. Fetch issue #{issueNumber} via gh api
+2. Compare GitHub state vs local status
+3. Apply conflict resolution (external wins for status)
+4. Import new comments to increment notes
+5. Update labels/assignees in metadata
+6. Display what changed"
+```
+
+### 3. Display Changes
+
+```
+Pulled from GitHub
+
+Issue: #123
+Repository: owner/repo
+
+Changes Applied:
+  Status: open -> closed (mapped to: completed)
+  Labels: +bug, +priority-high
+  Comments: 2 new imported
+
+Last synced: 2025-12-04 10:30:00
+URL: https://github.com/owner/repo/issues/123
+```
+
+---
+
+## Status Mapping
+
+| GitHub State | SpecWeave Status |
+|--------------|------------------|
+| `open` | in-progress |
+| `closed` | completed |
+
+---
+
+## Examples
+
+### Example 1: Simple Pull
+
+```
+User: /specweave-github:pull
+
+Claude:
+Pulling from GitHub...
+  Increment: 0005-payment-integration
+  Issue: #123
+
+Changes Applied:
+  Status: open -> closed (completed)
+
+Pull complete!
+```
+
+### Example 2: Not Linked
+
+```
+User: /specweave-github:pull 0005
+
+Claude:
+Increment 0005 not linked to GitHub yet.
+
+To link: /specweave-github:create 0005
+```
+
+---
+
+## Related Commands
+
+| Command | Purpose |
+|---------|---------|
+| `/specweave-github:push` | Push local changes to GitHub |
+| `/specweave-github:sync` | Two-way sync (pull + push) |
+| `/specweave-github:status` | Check sync status |
+| `/specweave-github:create` | Create GitHub issue |

package/plugins/specweave-github/commands/push.md

@@ -0,0 +1,154 @@
+---
+name: specweave-github:push
+description: Push local progress to GitHub Issues (like git push). Updates issue with task completion checklist.
+---
+
+# GitHub Push Command
+
+**Usage**: `/specweave-github:push [increment-id]`
+
+**Purpose**: Push local progress to GitHub Issues (like `git push`)
+
+---
+
+## Quick Start
+
+```bash
+# Push current/active increment
+/specweave-github:push
+
+# Push specific increment
+/specweave-github:push 0005
+```
+
+---
+
+## What Gets Pushed
+
+| Field | Source |
+|-------|--------|
+| **Task Checklist** | Updated from tasks.md completion |
+| **Comment** | Auto-generated progress update |
+| **Labels** | Status labels updated |
+| **State** | Closed if 100% complete |
+
+---
+
+## Command Behavior
+
+When user runs this command:
+
+### 1. Check Permission Gate
+
+```typescript
+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: GitHub writes disabled
+
+To enable: Set sync.settings.canUpdateExternalItems = true
+
+Or use read-only: /specweave-github:pull ${incrementId}
+`);
+  return;
+}
+```
+
+### 2. Calculate Progress
+
+```typescript
+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);
+```
+
+### 3. Invoke Push Sync
+
+```
+Use Task tool with subagent_type: "specweave-github:github-manager:AGENT"
+
+Prompt: "Push progress to GitHub for increment {increment-id}.
+
+Issue: #{issueNumber}
+Progress: {completedTasks}/{totalTasks} ({percentage}%)
+
+Steps:
+1. Update issue body task checklist
+2. Add progress comment
+3. Update labels if needed
+4. Close issue if 100% complete (if canUpdateStatus)
+5. Update sync timestamp"
+```
+
+### 4. Display Result
+
+```
+Pushed to GitHub
+
+Issue: #123
+Repository: owner/repo
+
+Progress: 6/10 tasks (60%)
+
+Updates:
+  Task checklist: 6/10 checked
+  Comment: Progress update posted
+  Labels: +in-progress
+
+URL: https://github.com/owner/repo/issues/123
+```
+
+---
+
+## Examples
+
+### Example 1: Simple Push
+
+```
+User: /specweave-github:push
+
+Claude:
+Pushing to GitHub...
+  Increment: 0005-payment-integration
+  Issue: #123
+
+Progress: 8/10 tasks (80%)
+Checklist updated, comment posted.
+
+Push complete!
+```
+
+### Example 2: 100% Complete
+
+```
+User: /specweave-github:push 0005
+
+Claude:
+Pushing to GitHub...
+
+Progress: 10/10 tasks (100%)
+
+Updates:
+  Task checklist: 10/10 checked
+  Comment: "All tasks complete!"
+  Issue: CLOSED
+
+Ready for next: /specweave:done 0005
+```
+
+---
+
+## Related Commands
+
+| Command | Purpose |
+|---------|---------|
+| `/specweave-github:pull` | Pull changes from GitHub |
+| `/specweave-github:sync` | Two-way sync (pull + push) |
+| `/specweave-github:status` | Check sync status |
+| `/specweave-github:close` | Close issue with summary |

package/plugins/specweave-github/commands/{specweave-github-sync.md → sync.md}

@@ -547,13 +547,27 @@ If automatic profile creation fails:
    /specweave-github:sync 0004
    ```
 
+## Simpler Alternatives
+
+For most use cases, use the git-style commands:
+
+| Command | Purpose |
+|---------|---------|
+| `/specweave-github:pull` | Pull changes from GitHub (read-only) |
+| `/specweave-github:push` | Push progress to GitHub |
+
+Use `/specweave-github:sync` for advanced operations with time ranges and rate limit control.
+
 ## Related Commands
 
-- `/specweave-github:create-issue <increment-id>`: Create issue with profile selection
-- `/specweave-github:close-issue <increment-id>`: Close issue
-- `/specweave-github:status <increment-id>`: Check sync status
-- `/specweave:sync-profile create`: Create new sync profile
-- `/specweave:sync-profile list`: List all profiles
+| Command | Purpose |
+|---------|---------|
+| `/specweave-github:pull` | Pull from GitHub (git-style) |
+| `/specweave-github:push` | Push to GitHub (git-style) |
+| `/specweave-github:create` | Create GitHub issue |
+| `/specweave-github:close` | Close GitHub issue |
+| `/specweave-github:status` | Check sync status |
+| `/specweave:sync-profile create` | Create new sync profile |
 
 ## Tips & Best Practices
 

package/plugins/specweave-github/commands/{specweave-github-update-user-story.md → update-user-story.md}

@@ -1,5 +1,5 @@
 ---
-name: specweave-github-update-user-story
+name: specweave-github:update-user-story
 description: Update GitHub issue for user story with proper ACs and tasks
 ---
 

package/plugins/specweave-github/hooks/README.md

@@ -281,7 +281,7 @@ If upgrading from SpecWeave v0.12.x or earlier:
 - **Core Plugin Hooks**: `plugins/specweave/hooks/README.md`
 - **Architecture Analysis**: `.specweave/increments/0018-strict-increment-discipline-enforcement/reports/HOOKS-ARCHITECTURE-ANALYSIS.md`
 - **Claude Code Hooks Guide**: https://code.claude.com/docs/en/hooks-guide
-- **GitHub Sync Command**: `plugins/specweave-github/commands/specweave-github-sync.md`
+- **GitHub Sync Command**: `plugins/specweave-github/commands/sync.md`
 
 ---
 

package/plugins/specweave-jira/agents/jira-manager/AGENT.md

@@ -46,6 +46,36 @@ Task({
 
 ---
 
+## 🔐 CRITICAL: Authentication (DO NOT HALLUCINATE)
+
+**EXACT environment variable names - use ONLY these:**
+
+| Service | Env Var | Example |
+|---------|---------|---------|
+| **Jira Token** | `JIRA_API_TOKEN` | `JIRA_API_TOKEN=abc123xyz...` |
+| **Jira Email** | `JIRA_EMAIL` | `JIRA_EMAIL=user@example.com` |
+| **Jira Domain** | `JIRA_DOMAIN` | `JIRA_DOMAIN=company.atlassian.net` |
+
+⚠️ **NEVER USE OR SUGGEST these non-existent env vars:**
+- ❌ `JIRA_TOKEN` ← DOES NOT EXIST (use `JIRA_API_TOKEN`)
+- ❌ `JIRA_PAT` ← DOES NOT EXIST
+- ❌ `ATLASSIAN_TOKEN` ← DOES NOT EXIST
+
+**When auth fails, display this EXACT message:**
+```
+Jira Authentication Required
+
+Set in .env file:
+  JIRA_API_TOKEN=your-api-token
+  JIRA_EMAIL=your-email@example.com
+  JIRA_DOMAIN=your-domain.atlassian.net
+
+Generate token at:
+  https://id.atlassian.com/manage-profile/security/api-tokens
+```
+
+---
+
 ## Capabilities
 
 As the Jira Manager agent, I specialize in:

package/plugins/specweave-jira/commands/pull.md

@@ -0,0 +1,164 @@
+---
+name: specweave-jira:pull
+description: Pull latest changes from Jira (like git pull). Imports status, priority, sprint, and comments.
+---
+
+# Jira Pull Command
+
+**Usage**: `/specweave-jira:pull [increment-id]`
+
+**Purpose**: Pull latest changes from Jira to your local increment (like `git pull`)
+
+---
+
+## Quick Start
+
+```bash
+# Pull for current/active increment
+/specweave-jira:pull
+
+# Pull for specific increment
+/specweave-jira:pull 0005
+```
+
+---
+
+## What Gets Pulled
+
+| Field | Behavior |
+|-------|----------|
+| **Status** | External ALWAYS wins (QA/stakeholder decisions) |
+| **Priority** | External wins (stakeholder prioritization) |
+| **Sprint** | Updated if changed in Jira |
+| **Comments** | New team comments imported to notes |
+| **Assignee** | Updated if changed |
+| **Story Points** | Imported if set |
+
+---
+
+## Status Mapping
+
+| Jira Status | SpecWeave Status |
+|-------------|------------------|
+| To Do | draft |
+| In Progress | in-progress |
+| Code Review | implemented |
+| In Review | implemented |
+| QA / Testing | in-qa |
+| Done / Closed | completed |
+| Blocked | blocked |
+| Cancelled | cancelled |
+
+---
+
+## Command Behavior
+
+When user runs this command:
+
+### 1. Resolve Increment
+
+```typescript
+const incrementId = args.incrementId || await findActiveIncrement();
+
+const metadata = JSON.parse(await fs.readFile(
+  `.specweave/increments/${incrementId}/metadata.json`, 'utf-8'
+));
+
+const jiraIssueKey = metadata?.external_sync?.jira?.issueKey;
+if (!jiraIssueKey) {
+  console.log(`Not linked to Jira. Link manually or use: /specweave-jira:sync ${incrementId}`);
+  return;
+}
+```
+
+### 2. Fetch and Apply
+
+```
+Use Task tool with subagent_type: "specweave-jira:jira-manager:jira-manager"
+
+Prompt: "Pull changes from Jira for increment {increment-id}.
+
+Issue: {jiraIssueKey}
+
+Steps:
+1. Fetch issue {jiraIssueKey} via Jira REST API
+2. Compare Jira status vs local status
+3. Apply conflict resolution (EXTERNAL WINS for status/priority)
+4. Import new comments to increment notes
+5. Update sprint/assignee in metadata
+6. Display what changed"
+```
+
+### 3. Display Changes
+
+```
+Pulled from Jira
+
+Issue: PROJ-123
+Project: My Project
+
+Changes Applied:
+  Status: In Progress -> Done (mapped to: completed)
+  Priority: Medium -> High
+  Sprint: Sprint 23 -> Sprint 24
+  Comments: 3 new imported
+
+Last synced: 2025-12-04 10:30:00
+URL: https://mycompany.atlassian.net/browse/PROJ-123
+```
+
+---
+
+## Conflict Resolution
+
+**CRITICAL**: External tool status ALWAYS wins.
+
+| Scenario | Winner | Reason |
+|----------|--------|--------|
+| Status differs | **External** | QA/stakeholder decisions |
+| Priority differs | **External** | Stakeholder prioritization |
+| Sprint differs | **External** | Sprint planning decisions |
+
+---
+
+## Examples
+
+### Example 1: Simple Pull
+
+```
+User: /specweave-jira:pull
+
+Claude:
+Pulling from Jira...
+  Increment: 0005-payment-integration
+  Issue: PROJ-123
+
+Changes Applied:
+  Status: In Progress -> Done (completed)
+
+Pull complete!
+```
+
+### Example 2: Already Up to Date
+
+```
+User: /specweave-jira:pull 0005
+
+Claude:
+Pulling from Jira...
+  Increment: 0005-payment-integration
+  Issue: PROJ-123
+
+Already up to date!
+Last synced: 5 minutes ago
+```
+
+---
+
+## Related Commands
+
+| Command | Purpose |
+|---------|---------|
+| `/specweave-jira:push` | Push local changes to Jira |
+| `/specweave-jira:sync` | Two-way sync (pull + push) |
+| `/specweave-jira:import-boards` | Import Jira boards |

package/plugins/specweave-jira/commands/push.md

@@ -0,0 +1,170 @@
+---
+name: specweave-jira:push
+description: Push local progress to Jira (like git push). Updates epic/story with task completion and comments.
+---
+
+# Jira Push Command
+
+**Usage**: `/specweave-jira:push [increment-id]`
+
+**Purpose**: Push local progress to Jira (like `git push`)
+
+---
+
+## Quick Start
+
+```bash
+# Push current/active increment
+/specweave-jira:push
+
+# Push specific increment
+/specweave-jira:push 0005
+```
+
+---
+
+## What Gets Pushed
+
+| Field | Source |
+|-------|--------|
+| **Progress** | Calculated from tasks.md (X/Y tasks, Z%) |
+| **Comment** | Auto-generated with completed tasks list |
+| **Status** | Transition if threshold crossed |
+| **Custom Fields** | Completion % if field exists |
+
+---
+
+## Command Behavior
+
+When user runs this command:
+
+### 1. Check Permission Gate
+
+```typescript
+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: Jira writes disabled
+
+To enable: Set sync.settings.canUpdateExternalItems = true
+
+Or use read-only: /specweave-jira:pull ${incrementId}
+`);
+  return;
+}
+```
+
+### 2. Calculate Progress
+
+```typescript
+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);
+```
+
+### 3. Invoke Push Sync
+
+```
+Use Task tool with subagent_type: "specweave-jira:jira-manager:jira-manager"
+
+Prompt: "Push progress to Jira for increment {increment-id}.
+
+Issue: {jiraIssueKey}
+Progress: {completedTasks}/{totalTasks} ({percentage}%)
+
+Steps:
+1. Format progress comment with task list
+2. POST comment to Jira issue
+3. Update custom fields if available
+4. Transition status if threshold crossed:
+   - 100% completed -> Done (if canUpdateStatus)
+5. Update sync timestamp in metadata
+6. Display push summary"
+```
+
+### 4. Display Result
+
+```
+Pushed to Jira
+
+Issue: PROJ-123
+Project: 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://mycompany.atlassian.net/browse/PROJ-123
+```
+
+---
+
+## Permission Requirements
+
+| Permission | Required | Purpose |
+|------------|----------|---------|
+| `canUpdateExternalItems` | **true** | Write to Jira |
+| `canUpdateStatus` | optional | Transition issue status |
+
+---
+
+## Examples
+
+### Example 1: Simple Push
+
+```
+User: /specweave-jira:push
+
+Claude:
+Pushing to Jira...
+  Increment: 0005-payment-integration
+  Issue: PROJ-123
+
+Progress: 8/10 tasks (80%)
+Comment posted.
+
+Push complete!
+```
+
+### Example 2: 100% Complete
+
+```
+User: /specweave-jira:push 0005
+
+Claude:
+Pushing to Jira...
+
+Progress: 10/10 tasks (100%)
+
+Comment posted:
+  "All tasks complete!"
+
+Status transitioned:
+  In Progress -> Done (canUpdateStatus = true)
+
+Ready to close: /specweave:done 0005
+```
+
+---
+
+## Related Commands
+
+| Command | Purpose |
+|---------|---------|
+| `/specweave-jira:pull` | Pull changes from Jira |
+| `/specweave-jira:sync` | Two-way sync (pull + push) |
+| `/specweave-jira:import-boards` | Import Jira boards |