specweave 0.30.12 → 0.30.14

package/plugins/specweave-docs/skills/preview/SKILL.md

@@ -0,0 +1,105 @@
+---
+name: preview
+description: Documentation preview expert for Docusaurus integration. Launches interactive preview server for SpecWeave living documentation with hot reload, auto-generated sidebar, and Mermaid diagrams. Activates for preview docs, view documentation, Docusaurus server, docs UI, documentation website, local docs server, hot reload docs, static site build.
+---
+
+# Documentation Preview Skill
+
+Expert in launching and managing Docusaurus documentation preview for SpecWeave projects.
+
+## What I Do
+
+I help you preview and build your SpecWeave living documentation with Docusaurus:
+
+### 1. Interactive Preview
+- Launch local development server (default port: 3016)
+- Auto-generate sidebar from folder structure
+- Hot reload - edit markdown, see changes instantly
+- Mermaid diagram rendering
+- Mobile-responsive UI
+- Search functionality
+
+### 2. Static Site Building
+- Build production-ready static site
+- Output to `.specweave/docs-site-internal/build/`
+- Ready for deployment to any static host
+- Optimized for performance
+
+### 3. Smart Setup
+- Lazy installation (only installs when first used)
+- Checks Node.js version (18+ required)
+- Installs Docusaurus dependencies automatically
+- Configures from `.specweave/config.json` settings
+
+## Available Commands
+
+### Preview Documentation
+```bash
+/specweave-docs:preview
+```
+
+**What it does:**
+1. Checks if Docusaurus is installed (installs if needed)
+2. Generates sidebar from `.specweave/docs/internal/` structure
+3. Starts development server on port 3016 (configurable)
+4. Opens browser automatically
+5. Enables hot reload
+
+### Build Static Site
+```bash
+/specweave-docs:build
+```
+
+**What it does:**
+1. Checks if Docusaurus is installed
+2. Runs production build
+3. Outputs to `.specweave/docs-site-internal/build/`
+4. Shows build stats and output path
+
+## When to Use This Skill
+
+### Activate for questions like:
+- "How do I preview my documentation?"
+- "Show me my docs in a UI"
+- "Launch Docusaurus server"
+- "View my living documentation"
+- "Start docs preview"
+- "Build static docs site"
+
+### Common workflows:
+
+**1. First-time preview:**
+```
+User: "I want to preview my docs"
+You: "I'll set up the documentation preview with Docusaurus."
+     [Run: /specweave-docs:preview]
+```
+
+**2. Build for deployment:**
+```
+User: "I need to deploy my docs"
+You: "I'll build the static site for deployment."
+     [Run: /specweave-docs:build]
+```
+
+## Configuration
+
+```json
+{
+  "documentation": {
+    "preview": {
+      "enabled": true,
+      "autoInstall": true,
+      "port": 3016,
+      "openBrowser": true,
+      "theme": "default"
+    }
+  }
+}
+```
+
+## See Also
+
+- `/specweave-docs:organize` - Organize large folders with themed indexes
+- `/specweave-docs:health` - Documentation health report
+- `/specweave-docs:generate` - Generate docs from code

package/plugins/specweave-github/agents/user-story-updater/AGENT.md

@@ -161,7 +161,7 @@ Agent: "I'll update GitHub issue #501 for US-004 to include checkable ACs and ta
 
 **Related Files**:
 - `plugins/specweave-github/lib/user-story-content-builder.ts` - Core builder class
-- `plugins/specweave-github/commands/specweave-github-update-user-story.md` - Command spec
+- `plugins/specweave-github/commands/update-user-story.md` - Command spec
 - `.specweave/docs/internal/specs/{project}/FS-*/us-*.md` - User story files
 
 **Testing**:

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

@@ -1,5 +1,5 @@
 ---
-name: specweave-github:close-issue
+name: specweave-github:close
 description: Close GitHub issue for completed SpecWeave increment. Posts completion summary with final stats, deliverables, and closes the issue. Links closure in increment metadata.
 ---
 
@@ -7,7 +7,7 @@ description: Close GitHub issue for completed SpecWeave increment. Posts complet
 
 Close the GitHub issue associated with a completed SpecWeave increment.
 
-## Usage
+**Usage**: `/specweave-github:close <increment-id>`
 
 ```bash
 /specweave:github:close-issue <increment-id> [options]

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

@@ -1,5 +1,5 @@
 ---
-name: specweave-github:create-issue
+name: specweave-github:create
 description: Create a GitHub issue for a SpecWeave increment. Generates issue from increment specs with task checklist, labels, and milestone. Links issue to increment metadata.
 ---
 
@@ -7,7 +7,7 @@ description: Create a GitHub issue for a SpecWeave increment. Generates issue fr
 
 Create a GitHub issue for the specified SpecWeave increment.
 
-## Usage
+**Usage**: `/specweave-github:create <increment-id>`
 
 ```bash
 /specweave:github:create-issue <increment-id> [options]

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/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 |