specweave 1.0.593 → 2.0.3

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

@@ -1,155 +0,0 @@
----
-description: Update GitHub issue for user story with proper ACs and tasks
----
-
-# Update User Story GitHub Issue
-
-**Purpose**: Update an existing GitHub issue for a user story to include:
-- ✅ Checkable acceptance criteria (GitHub task checkboxes)
-- ✅ Task connections (links to increment tasks)
-- ✅ Proper formatting and status
-
-**Usage**:
-```bash
-sw-github:update-user-story FS-031 US-004
-```
-
-**What It Does**:
-
-1. **Finds user story file**: `.specweave/docs/internal/specs/{project}/FS-031/us-004-*.md`
-2. **Parses content**:
-   - User story description (As a... I want... So that...)
-   - Acceptance criteria with completion status
-   - Tasks from increment tasks.md
-3. **Finds existing GitHub issue**: Searches for `[FS-031][US-004]` or `[FS-031 US-004]`
-4. **Updates issue body**: Replaces with properly formatted content including:
-   - Checkable ACs
-   - Task connections
-   - Status and progress
-
-**Arguments**:
-- `featureId` - Feature ID (e.g., `FS-031`)
-- `userStoryId` - User Story ID (e.g., `US-004`)
-
-**Example**:
-```bash
-# Update US-004 in FS-031
-sw-github:update-user-story FS-031 US-004
-
-# Output:
-# 🔍 Finding user story: FS-031/US-004
-#    📄 Found: .specweave/docs/internal/specs/default/FS-031/us-004-bidirectional-status-sync.md
-# 🔍 Searching for existing GitHub issue...
-#    🔗 Found issue #501: [FS-031][US-004] Bidirectional Status Sync
-# 📝 Building updated issue body...
-#    ✅ 6 acceptance criteria (4 completed)
-#    ✅ 6 tasks (3 completed)
-# 🚀 Updating GitHub issue #501...
-#    ✅ Updated successfully!
-#    🔗 https://github.com/owner/repo/issues/501
-```
-
-**What Gets Updated**:
-
-```markdown
-**Feature**: [FS-031](../../_features/_archive/FS-031/FEATURE.md)
-**Status**: complete
-**Priority**: P1
-**Project**: default
-
----
-
-## User Story
-
-**As a** PM
-**I want** status changes in external tools to sync back to SpecWeave
-**So that** both systems stay in sync without manual updates
-
-📄 View full story: [`us-004-bidirectional-status-sync.md`](...)
-
----
-
-## Acceptance Criteria
-
-Progress: 4/6 criteria met (67%)
-
-- [x] **AC-US4-01**: SpecWeave status change triggers external update (P1, testable)
-- [x] **AC-US4-02**: External issue close triggers SpecWeave prompt (P1, testable)
-- [x] **AC-US4-03**: External issue reopen triggers SpecWeave prompt (P2, testable)
-- [x] **AC-US4-04**: Sync logs include timestamp and reason (P2, testable)
-- [ ] **AC-US4-05**: Failed syncs retry with exponential backoff (P2, testable)
-- [ ] **AC-US4-06**: Sync works for GitHub, JIRA, and ADO (P1, testable)
-
----
-
-## Implementation Tasks
-
-Progress: 3/6 tasks complete (50%)
-
-**Increment**: [0031-external-tool-status-sync](../../increments/0031-external-tool-status-sync/)
-
-- [x] [T-008: Create Status Sync Engine (Core)](../../increments/0031/tasks.md#t-008-create-status-sync-engine-core)
-- [x] [T-009: Implement GitHub Status Sync](../../increments/0031/tasks.md#t-009-implement-github-status-sync)
-- [x] [T-010: Implement JIRA Status Sync](../../increments/0031/tasks.md#t-010-implement-jira-status-sync)
-- [ ] [T-011: Implement ADO Status Sync](../../increments/0031/tasks.md#t-011-implement-ado-status-sync)
-- [ ] [T-018: Add Sync Event Logging](../../increments/0031/tasks.md#t-018-add-sync-event-logging)
-- [ ] [T-021: Error Handling & Retry Logic](../../increments/0031/tasks.md#t-021-error-handling-retry-logic)
-
----
-
-🤖 Auto-synced by SpecWeave User Story Sync
-```
-
-**When to Use**:
-
-- ✅ After completing increment implementation (update task statuses)
-- ✅ After modifying acceptance criteria
-- ✅ When GitHub issue is missing proper formatting
-- ✅ When you want to refresh issue content from living docs
-
-**Related Commands**:
-- `sw-github:sync-epic FS-031` - Sync entire epic (all user stories)
-- `sw-github:create-issue 0031` - Create issue for increment
-- `sw-github:sync 0031` - Two-way sync for increment
-
----
-
-## Implementation
-
-**File**: `plugins/specweave-github/lib/user-story-content-builder.ts`
-
-**Workflow**:
-1. Parse user story file with `UserStoryContentBuilder`
-2. Search GitHub for existing issue (title pattern matching)
-3. Build rich issue body with checkable ACs and task links
-4. Update issue via `gh issue edit` with new body
-
-**Error Handling**:
-- ✅ Graceful fallback if user story file not found
-- ✅ Clear error if GitHub issue doesn't exist
-- ✅ Validation of required fields (epic, status, etc.)
-
----
-
-## Execution
-
-When user runs this command, the Claude Code assistant should:
-
-1. Extract `featureId` and `userStoryId` from command arguments
-2. Find user story file in living docs (search all projects)
-3. Use `UserStoryContentBuilder` to parse and build issue body
-4. Search for existing GitHub issue using `gh issue list --search`
-5. Update issue using `gh issue edit --body`
-6. Report success with issue URL
-
-**Tech Stack**:
-- TypeScript (UserStoryContentBuilder class)
-- GitHub CLI (`gh issue list`, `gh issue edit`)
-- YAML frontmatter parsing
-- Markdown formatting
-
-**Testing**:
-- Test with FS-031/US-004 (bidirectional status sync)
-- Verify ACs are checkable
-- Verify tasks link to correct increment tasks.md
-- Verify progress percentages are correct

package/plugins/specweave/commands/handoff.md

@@ -1,54 +0,0 @@
----
-description: Write a portable, secret-scrubbed work handoff doc so you can continue this work in any AI tool. Use when saying "handoff", "running out of tokens", "switch to Codex/OpenCode/Gemini/Cursor", "continue elsewhere", or "continue on another machine".
-argument-hint: "[incrementId] [--reason ...] [--summary ...] [--next ...] [--gotcha ...] [--decision ...] [--inline]"
----
-
-# Work Handoff (Cross-Tool)
-
-Assemble the current work state into one portable, self-contained handoff document so the work can be picked up in another AI coding tool — Claude Code, Codex, OpenCode, Gemini, Antigravity, Cursor, Aider — picking up exactly where you left off, uncommitted edits and all.
-
-The expensive, deterministic work (workspace detection, task/AC parsing, git capture, full-diff dump, secret scrub, rendering) is done by the `specweave handoff` CLI subcommand. This command is a thin wrapper that runs it and surfaces the output.
-
-## When to use
-
-- You are low on subscription tokens and want to continue in another tool.
-- You want a durable artifact that survives a context crash.
-- You are moving to another machine (`--inline` embeds the full doc in the paste-prompt).
-
-## Workflow
-
-### Step 1: Run the CLI
-
-Pass through whatever short context the agent can supply cheaply. All flags are optional — the CLI derives everything it can from disk.
-
-```bash
-specweave handoff $ARGUMENTS
-```
-
-`$ARGUMENTS` forwards `[incrementId]` plus any `--reason`, `--summary`, `--next`, `--gotcha`, `--decision`, and `--inline` flags the user (or agent) provided.
-
-- No `incrementId` and exactly one active increment → it is used automatically.
-- No active increment → a git + interview handoff is written (still portable).
-- 2+ active increments and no `incrementId` → the CLI errors listing the candidate ids; re-run with the chosen id.
-
-### Step 2: Surface the output VERBATIM, in order
-
-The CLI prints, in this exact order — present it to the user without reordering:
-
-1. **The absolute doc path as plain text** (so it is copyable/clickable in any terminal).
-2. A clickable markdown link to the doc.
-3. The `.diff` path holding the exact uncommitted edits.
-4. A fenced copy-paste **resume prompt** to drop into the next tool.
-5. Per-tool "find your source session" tips (Claude `claude -r <uuid>`, Codex `codex resume <uuid>`, OpenCode `opencode -s <id>`, etc.).
-
-Do NOT re-summarize or reformat the resume prompt — the user copies it as-is.
-
-### Step 3: Note the safety defaults
-
-The doc and diff are **secret-scrubbed and gitignored by default** (`.handoff/` or `.specweave/state/handoff-latest.*`). Scrubbing is heuristic — remind the user to review before sharing. Nothing is committed and no `git add` hint is printed.
-
-## Related
-
-- `sw:progress` — check increment status without writing a handoff.
-- `sw:next` — close the current increment and suggest next work.
-- The portable doc format and cross-tool resume matrix: see the `handoff` skill and `docs/guides/cross-tool-handoff.md`.

package/plugins/specweave/commands/import-external.md

@@ -1,461 +0,0 @@
----
-description: AUTO-EXECUTE import of external work items (GitHub/JIRA/ADO) since last import. NO PROMPTS - immediately runs with defaults. Creates READ-ONLY references in living docs. Options available but NOT required.
-disable-model-invocation: true
----
-
-# Import External Work Items (Reference Import)
-
-Import work items from GitHub (issues/milestones), JIRA (epics/stories), or Azure DevOps (work items) into SpecWeave living docs **as read-only references**.
-
-> **Important**: This command creates a **reference catalog**, NOT increments. Imported items have E-suffix IDs (US-001E, FS-042E). To implement an imported item, you must **manually create an increment** that references it.
-
-## CRITICAL: Default Behavior (NO PROMPTS!)
-
-**When user runs `sw:import-external` with NO arguments:**
-1. **IMMEDIATELY execute** with default settings - DO NOT show menus or ask questions
-2. **Default = "since last import"** - auto-detects from `.specweave/sync-metadata.json`
-3. **If first import ever** - defaults to last 1 month
-4. **Import from ALL configured platforms** (GitHub, JIRA, ADO - whichever are configured)
-
-**WRONG behavior** (DO NOT DO THIS):
-```
-❌ "What would you like to import?"
-❌ "Which option would you like?"
-❌ "Should I run a dry run first?"
-❌ Showing a menu of options
-```
-
-**CORRECT behavior**:
-```
-✅ Immediately start importing
-✅ Show progress: "🔄 Importing from GitHub... [25/150]"
-✅ Show summary when done
-```
-
-## What This Does
-
-1. **Detects configured external tools** (GitHub, JIRA, ADO) from environment/config
-2. **Fetches work items** based on time range filter (since last import by default)
-3. **Assigns IDs with E suffix and validation**
-   - IDs have E suffix to indicate external origin (US-001E, T-001E, FS-042E)
-   - **Validates FS (Feature) IDs** to avoid conflicts:
-     ```typescript
-     import { validateIncrementNumber, logValidationResult } from './src/core/increment-validator.js';
-
-     // Get all existing feature IDs (including E-suffix ones)
-     const existingFeatures = [
-       ...fs.readdirSync('.specweave/docs/internal/specs/'),
-       ...fs.readdirSync('.specweave/increments/').map(parseFeatureId),
-     ].filter(f => /^FS-\d{3}E?$/.test(f));
-
-     // For external feature FS-042E, validate base number 042
-     const baseNumber = featureId.replace('E', '').replace('FS-', '');
-     const result = validateIncrementNumber(baseNumber, existingFeatures);
-
-     // Log warnings if non-sequential
-     if (result.warnings.length > 0) {
-       console.log('ℹ️  External feature ID validation:');
-       logValidationResult(result);
-       console.log('   This is normal for external imports (IDs from external system)');
-     }
-     ```
-   - Note: External IDs may be non-sequential (they come from external systems)
-   - Validation ensures awareness of gaps, not enforcement
-
-4. **Creates living docs files** in `.specweave/docs/internal/specs/FS-XXXE/`
-5. **Updates sync metadata** (`.specweave/sync-metadata.json`) with import timestamp
-6. **Skips duplicates** automatically (checks existing external IDs)
-7. **Shows progress** indicator and summary report
-
-## Usage
-
-```bash
-sw:import-external [options]
-```
-
-### Options (ALL OPTIONAL - defaults work without them)
-
-- `--since=<range>` - Time range filter (default: since last import)
-  - `last` - Since last import (uses sync metadata) **← DEFAULT**
-  - `1m`, `3m`, `6m` - Last 1/3/6 months
-  - `all` - All items (no time filter)
-  - Custom: `2025-01-01` - Since specific date (ISO format)
-- `--github-only` - Import from GitHub only
-- `--jira-only` - Import from JIRA only
-- `--ado-only` - Import from Azure DevOps only
-- `--dry-run` - Preview what would be imported without creating files
-
-## Examples
-
-### Example 1: Import New Items (Default - NO PROMPTS!)
-
-```bash
-sw:import-external
-
-# IMMEDIATELY executes with defaults:
-# - Since last import (or 1 month if first import)
-# - All configured platforms
-
-# Output (NO QUESTIONS ASKED):
-# 📥 Import External Work Items
-#
-# 📋 Import Configuration:
-#   Platforms: GITHUB
-#   Time range: last
-#   Dry run: No
-#
-# 🔗 Imported from GITHUB: 15 items
-#
-# 📊 Import Summary:
-#    Total imported: 15 items
-#    🔗 GITHUB: 15 items
-# ✅ Import complete!
-```
-
-### Example 2: GitHub Only (Last 3 Months)
-
-```bash
-sw:import-external --github-only --since=3m
-
-# Imports only from GitHub
-# Items created in last 3 months
-```
-
-### Example 3: Dry Run (Preview)
-
-```bash
-sw:import-external --dry-run --since=1m
-
-# Shows what would be imported without creating files
-# Useful for checking item counts before actual import
-
-# Result:
-# 🔍 Dry run - no files will be created
-# 📊 Preview:
-#    GitHub: 25 items (5 duplicates skipped)
-#    JIRA: 10 items (2 duplicates skipped)
-#    Total: 35 new items, 7 existing
-# ⚠️  Remove --dry-run to perform actual import
-```
-
-### Example 4: JIRA Only (All Items)
-
-```bash
-sw:import-external --jira-only --since=all
-
-# Imports all JIRA items (no time filter)
-# ⚠️  Warning shown if > 100 items detected
-```
-
-## Time Range Filters
-
-### Since Last Import (Default)
-
-```bash
-sw:import-external
-
-# Reads last import timestamp from:
-# .specweave/sync-metadata.json
-# {
-#   "github": { "lastImport": "2025-11-15T10:30:00Z" },
-#   "jira": { "lastImport": "2025-11-10T14:20:00Z" }
-# }
-#
-# GitHub: imports items created after 2025-11-15T10:30:00Z
-# JIRA: imports items created after 2025-11-10T14:20:00Z
-```
-
-### Relative Time Ranges
-
-```bash
---since=1m   # Last 1 month
---since=3m   # Last 3 months
---since=6m   # Last 6 months
-```
-
-### Absolute Date
-
-```bash
---since=2025-01-01   # Since January 1, 2025 (ISO format: YYYY-MM-DD)
-```
-
-### All Items
-
-```bash
---since=all   # Import all items (no time filter)
-# ⚠️  Warning: May import hundreds of items
-```
-
-## Configured Platforms
-
-The command auto-detects configured platforms from:
-
-### GitHub
-- **Detection**: `.git/config` remote URL
-- **Auth**: `GITHUB_TOKEN` environment variable
-- **Format**: `github.com/{owner}/{repo}`
-
-### JIRA
-- **Detection**: `JIRA_HOST` environment variable
-- **Auth**: `JIRA_EMAIL` + `JIRA_API_TOKEN`
-- **Format**: `https://{company}.atlassian.net`
-
-### Azure DevOps
-- **Detection**: `ADO_ORG_URL` environment variable
-- **Auth**: `ADO_PAT` (Personal Access Token)
-- **Format**: `https://dev.azure.com/{org}` + `ADO_PROJECT`
-
-## Progress Indicator
-
-During import, you'll see real-time progress:
-
-```
-🔄 Importing from GitHub... [25/150] ⠋
-⚠️  GitHub rate limit low: 42/5000 remaining. Resets at 10:45 AM (in 300s).
-🔄 Importing from GitHub... [150/150] ✓
-
-🔄 Importing from JIRA... [12/12] ✓
-```
-
-- **Spinner**: Shows active import
-- **Counter**: `[current/total]` items processed
-- **Rate limit warnings**: Shown if remaining requests drop below threshold
-- **Checkmark**: `✓` when platform import completes
-
-## Summary Report
-
-After import, a detailed summary is shown:
-
-```
-📊 Import Summary:
-   Total imported: 162 items
-   - GitHub: 150 items (US-201E to US-350E)
-   - JIRA: 12 items (US-351E to US-362E)
-
-   Duplicates skipped: 8 items
-   - GitHub: 5 items (already imported)
-   - JIRA: 3 items (already imported)
-
-   Rate limit status:
-   - GitHub: 3842/5000 remaining (resets at 11:00 AM)
-   - JIRA: Estimated 950/1000 remaining
-
-✅ Import complete!
-   Living docs updated: .specweave/docs/internal/specs/
-   Sync metadata updated: .specweave/sync-metadata.json
-```
-
-## Duplicate Detection
-
-The command automatically skips items that have already been imported:
-
-- Scans all `us-*.md` files in living docs
-- Checks `external_id` frontmatter field
-- Skips if external ID already exists (e.g., `GH-#638`, `JIRA-PROJ-123`)
-- Reports skipped count in summary
-
-## Rate Limiting
-
-The command monitors API rate limits and handles them gracefully:
-
-### Warning Threshold (100 requests remaining)
-
-```
-⚠️  GitHub rate limit low: 42/5000 remaining. Resets at 10:45 AM (in 300s).
-```
-
-- Import continues normally
-- Warning shown to user
-
-### Pause Threshold (10 requests remaining)
-
-```
-⚠️  GitHub rate limit critically low. Waiting 60s before continuing...
-```
-
-- Import pauses automatically
-- Resumes after wait period
-- No user action required
-
-### Retry Suggestions (Rate limit exceeded)
-
-```
-❌ GitHub rate limit exceeded.
-   Remaining: 0/5000
-   Resets at: 10:45 AM (in 300 seconds)
-
-💡 Suggestions:
-   - Wait 5 minutes and retry
-   - Use --github-only next time to avoid hitting limit
-   - Increase time range to reduce item count (--since=1m instead of --since=all)
-```
-
-## Large Import Confirmation
-
-If import detects > 100 items, you'll be prompted:
-
-```
-⚠️  Found 250 items to import:
-   - GitHub: 200 items
-   - JIRA: 50 items
-
-   This may take 5-10 minutes and use significant API quota.
-
-Continue? (Y/n) _
-```
-
-- Press `Y` or `Enter` to proceed
-- Press `n` to cancel
-- Use `--since=1m` to reduce item count
-
-## Sync Metadata
-
-After successful import, sync metadata is updated:
-
-**File**: `.specweave/sync-metadata.json`
-
-```json
-{
-  "github": {
-    "lastImport": "2025-11-19T10:30:00Z",
-    "lastImportCount": 150,
-    "lastSkippedCount": 5,
-    "lastSyncResult": "success"
-  },
-  "jira": {
-    "lastImport": "2025-11-19T10:32:00Z",
-    "lastImportCount": 12,
-    "lastSkippedCount": 3,
-    "lastSyncResult": "success"
-  }
-}
-```
-
-- `lastImport`: Timestamp of most recent successful import
-- `lastImportCount`: Number of items imported in last sync
-- `lastSkippedCount`: Number of duplicates skipped
-- `lastSyncResult`: `success`, `partial`, or `failed`
-
-## Living Docs Structure
-
-Imported items create living docs files with E suffix:
-
-```
-.specweave/docs/internal/specs/
-├── FS-042E/                    ← Feature (external)
-│   ├── README.md               ← Feature metadata
-│   ├── us-001e-login.md        ← User Story (external)
-│   └── us-002e-signup.md       ← User Story (external)
-└── FS-043E/                    ← Feature (external)
-    └── us-001e-api-auth.md     ← User Story (external)
-```
-
-### User Story File Format
-
-```markdown
----
-us_id: US-001E
-title: "User Login"
-feature_id: FS-042E
-origin: external
-external_platform: github
-external_id: GH-#638
-external_url: https://github.com/owner/repo/issues/638
-imported_at: 2025-11-19T10:30:00Z
-status: open
----
-
-# US-001E: User Login
-
-**Origin**: 🔗 GitHub (GH-#638)
-
-## Description
-
-[Original GitHub issue description]
-
-## Acceptance Criteria
-
-[Parsed from GitHub issue body or comments]
-
-## Tasks
-
-No tasks defined.
-
-## Implementation Notes
-
-[Original labels, comments, metadata from GitHub]
-```
-
-## When to Use
-
-- **After initial setup**: Import new external items created after `specweave init`
-- **Periodic sync**: Weekly/monthly imports to stay in sync with external tools
-- **Brownfield onboarding**: Import historical items missed during initialization
-- **Cross-team collaboration**: Pull work items from other teams' external tools
-
-## Limitations
-
-- **NO automatic increment creation**: Imported items live in living docs ONLY
-  - User must manually create increment when ready to work on external item
-- **Read-only snapshot**: External items are imported as static snapshots
-  - No two-way sync (external tool → SpecWeave only)
-- **Pagination**: Large imports (500+ items) may take several minutes
-- **API quota**: Uses GitHub/JIRA/ADO API quota
-  - GitHub: 5000 requests/hour (authenticated)
-  - JIRA: ~1000 requests/hour (Cloud estimate)
-  - ADO: 200 requests/minute
-
-## Differences from `specweave init`
-
-| Feature | `specweave init` | `sw:import-external` |
-|---------|------------------|------------------------------|
-| When to use | First-time setup | Ongoing imports after init |
-| User prompts | Interactive setup | **NONE** (auto-execute with defaults) |
-| Time range | Configurable (default: 1 month) | Since last import (auto-detected) |
-| Config update | Creates `.specweave/config.json` | Uses existing config |
-| Primary use case | Brownfield onboarding | Stay in sync with external tools |
-| Execution | Step-by-step wizard | **Immediate** (no questions asked) |
-
-## Troubleshooting
-
-### Error: "No platforms configured"
-
-```
-❌ No external platforms configured.
-
-💡 Ensure one of these is set:
-   - GitHub: GITHUB_TOKEN + .git/config remote
-   - JIRA: JIRA_HOST + JIRA_EMAIL + JIRA_API_TOKEN
-   - Azure DevOps: ADO_ORG_URL + ADO_PROJECT + ADO_PAT
-```
-
-**Solution**: Set environment variables for at least one platform
-
-### Error: "Rate limit exceeded"
-
-```
-❌ GitHub rate limit exceeded (0/5000 remaining).
-   Resets at: 10:45 AM (in 300 seconds)
-```
-
-**Solution**: Wait for rate limit reset, or use platform filter (`--jira-only`) to avoid GitHub
-
-### Warning: "Found 0 items to import"
-
-```
-⚠️  No new items found since last import (2025-11-19T10:30:00Z).
-```
-
-**Solution**: This is expected if no new work items created since last import. Use `--since=all` to re-import all items (will skip duplicates).
-
-## See Also
-
-- `specweave init` - Initial project setup with external tool import
-- [External Import Guide](https://spec-weave.com/docs/guides/external-import)
-- [GitHub Integration](https://spec-weave.com/docs/integrations/github)
-- [JIRA Integration](https://spec-weave.com/docs/integrations/jira)
-- [Azure DevOps Integration](https://spec-weave.com/docs/integrations/ado)
-
----
-
-**Implementation**: `src/cli/commands/import-external.ts`