specweave 1.0.593 → 2.0.3

package/plugins/specweave/commands/state.md

@@ -1,209 +0,0 @@
----
-description: |
-  Unified increment state management. Change increment status: pause, resume, backlog, or reopen.
-  Use when changing increment lifecycle state (blocked, deprioritized, ready to start, bug found).
-argument-hint: <increment-id> <pause|resume|backlog|reopen> [--reason="reason"] [--task T-XXX] [--force]
-disable-model-invocation: true
----
-
-# State Management Command
-
-**Unified command for all increment state transitions.**
-
-## Usage
-
-```bash
-sw:state <id> pause   [--reason="reason"]      # Pause active increment
-sw:state <id> resume                            # Resume paused/backlog increment
-sw:state <id> backlog [--reason="reason"]      # Move to backlog (planned, not started)
-sw:state <id> reopen  [--reason="reason"]      # Reopen completed work
-sw:state <id> reopen  --task T-003 [--reason]  # Reopen specific task
-sw:state <id> reopen  --user-story US-001      # Reopen user story + related tasks
-sw:state <id> reopen  --force                  # Bypass WIP limit checks
-```
-
-## Actions
-
-### `pause` - Pause Active Increment
-
-When blocked by external dependency, waiting for review, or deprioritized.
-
-**Valid transitions**: active → paused
-
-**Behavior:**
-1. Normalize increment ID (supports `0153` or `0153-feature-name`)
-2. Validate increment exists and is "active"
-3. Prompt for reason if not provided via --reason
-4. Update metadata.json: status → "paused", pausedReason, pausedAt
-5. Display confirmation, suggest `sw:state <id> resume` to continue
-
-**Examples:**
-```bash
-sw:state 0006 pause --reason="Waiting for Stripe API keys"
-
-# Interactive (prompts for reason)
-sw:state 0006 pause
-```
-
-**Edge cases:**
-- Already paused → offer to update reason
-- Completed/abandoned → error with guidance
-
-### `resume` - Resume Paused/Backlog Increment
-
-When blocker resolved, ready to start backlog work, or reviving abandoned work.
-
-**Valid transitions**: paused → active, backlog → active, abandoned → active (with confirmation)
-
-**Behavior:**
-1. Normalize increment ID
-2. Validate increment is "paused", "backlog", or "abandoned"
-3. Calculate pause/backlog duration
-4. Update metadata.json: status → "active", clear pause/backlog fields
-5. Show context recovery (progress %, last activity, duration)
-6. Suggest `sw:do` to continue work
-
-**Examples:**
-```bash
-sw:state 0006 resume
-# → Increment 0006 resumed. Was paused for: 3 days, 4 hours
-# → Continue with: sw:do
-
-sw:state 0032 resume
-# → Increment 0032 activated from backlog. Was in backlog for: 5 days
-# → Start work with: sw:do
-```
-
-**Edge cases:**
-- Already active → no action needed
-- Completed → error
-- Abandoned → requires confirmation
-
-### `backlog` - Move to Backlog
-
-For planned work not ready to start. Does NOT count toward WIP limits.
-
-**Valid transitions**: active → backlog
-
-**Key difference**: Backlog = never started (future work). Paused = started but blocked.
-
-**Behavior:**
-1. Validate increment is "active"
-2. Prompt for reason if not provided
-3. Update metadata.json: status → "backlog", backlogReason, backlogAt
-4. Display confirmation
-
-**Examples:**
-```bash
-sw:state 0032 backlog --reason="Low priority, focus on 0031 first"
-```
-
-**Edge cases:**
-- Already in backlog → offer to update reason
-- Paused → error (resume or abandon instead)
-- Completed → error
-
-### `reopen` - Reopen Completed Work
-
-When issues discovered after completion. Supports reopening entire increment, specific task, or user story.
-
-**Valid transitions**: completed → active
-
-**Behavior:**
-1. Validate increment is "completed"
-2. Check WIP limits (unless --force)
-3. Update metadata.json: status → "active", add to reopened history
-4. Reopen tasks: [x] → [ ]
-5. Sync to external tools (GitHub/JIRA/ADO)
-6. Create audit trail
-
-**Parameters:**
-
-| Parameter | Description |
-|-----------|-------------|
-| `--reason` | Why reopening (for audit trail). Natural language also works. |
-| `--task T-XXX` | Reopen specific task only |
-| `--user-story US-XXX` | Reopen user story + all related tasks |
-| `--force` | Bypass WIP limit checks (emergencies only) |
-
-**Examples:**
-```bash
-# Reopen entire increment
-sw:state 0031 reopen --reason="GitHub sync failing in production"
-
-# Natural language (everything after action is the reason)
-sw:state 0043 reopen Bug found in AC sync implementation
-
-# Reopen specific task
-sw:state 0031 reopen --task T-003 --reason="API rate limiting not handled"
-
-# Reopen user story
-sw:state 0025 reopen --user-story US-002 --reason="Security requirements not satisfied"
-
-# Force reopen (bypass WIP limits)
-sw:state 0031 reopen --force --reason="Production down"
-```
-
-**WIP Limit Validation:**
-```
-WIP LIMIT WARNING:
-  Current active: 2 features
-  Limit: 2 features
-  Reopening 0031 will EXCEED the limit (3/2)!
-
-Options:
-1. Pause another feature: sw:state 0030 pause --reason="Paused for fix"
-2. Complete another feature: sw:done 0029
-3. Force reopen: sw:state 0031 reopen --force --reason="Critical"
-```
-
-**Audit Trail** (metadata.json):
-```json
-{
-  "reopened": {
-    "count": 1,
-    "history": [{
-      "date": "2025-11-14T15:30:00Z",
-      "reason": "GitHub sync failing",
-      "previousStatus": "completed"
-    }]
-  }
-}
-```
-
-**External Tool Sync:**
-- GitHub: Reopens closed issue, adds `reopened` label
-- JIRA: Transitions Done → In Progress
-- ADO: Updates state Closed → Active
-
-## Status Flow
-
-```
-active ──pause──→ paused ──resume──→ active
-  │                                     ↑
-  ├──backlog──→ backlog ──resume────────┘
-  │                                     ↑
-  └──────────→ completed ──reopen───────┘
-                    │
-               abandoned ──resume──→ active (with confirmation)
-```
-
-## Stale Increment Warnings
-
-Increments paused/backlog for 7+ days trigger warnings in `sw:status`:
-
-```
-Paused (1):
-  0007-stripe-integration [feature]
-     Paused: 10 days ago
-     Reason: Waiting for Stripe API keys
-     STALE! Review or abandon?
-```
-
-## Best Practices
-
-- Always provide a reason (audit trail)
-- Review paused/backlog items weekly
-- Use `reopen --task` for surgical fixes (don't reopen entire increment)
-- Don't abuse `--force` (respect WIP limits)
-- After `resume`, review spec.md first (context may have changed)

package/plugins/specweave/commands/sync-setup.md

@@ -1,161 +0,0 @@
----
-description: Interactive sync setup wizard that configures GitHub, JIRA, and/or ADO integration in one guided flow. Use when saying "setup sync", "configure sync", "connect to jira", "connect to github", or "sync-setup".
----
-
-# Sync Setup Wizard
-
-Interactive skill that configures SpecWeave's external sync in one guided flow.
-
-## Workflow
-
-### Step 1: Provider Selection
-
-Ask the user which providers to enable:
-
-```
-AskUserQuestion: "Which external platforms do you want to sync with?"
-Options: GitHub, JIRA, Azure DevOps (multiSelect: true)
-```
-
-### Step 2: Credentials (per provider)
-
-**GitHub**:
-1. Check `gh auth status` — if authenticated, use existing token
-2. If not, ask for GITHUB_TOKEN
-3. Ask for owner/repo (or auto-detect from git remote)
-
-**JIRA**:
-1. Ask for JIRA domain (e.g., `company.atlassian.net`)
-2. Ask for email
-3. Ask for API token (from https://id.atlassian.com/manage/api-tokens)
-4. Ask for project key
-5. Validate: `curl -u email:token https://domain/rest/api/3/myself`
-
-**Azure DevOps**:
-1. Ask for organization name
-2. Ask for project name
-3. Ask for PAT (from https://dev.azure.com/org/_usersSettings/tokens)
-4. Validate: `curl -u :PAT https://dev.azure.com/org/_apis/projects/project?api-version=7.1`
-
-### Step 3: Permission Preset
-
-```
-AskUserQuestion: "What sync permissions do you want?"
-Options:
-- read-only: Only pull changes from external tools
-- push-only: Only push SpecWeave changes to external tools
-- bidirectional (Recommended): Both push and pull
-- full-control: Everything including delete
-```
-
-### Step 4: Hierarchy Detection (JIRA/ADO only)
-
-For JIRA and ADO, auto-detect the hierarchy:
-
-```typescript
-// Use the new SyncEngine to detect hierarchy
-const engine = new SyncEngine({ permissions: resolvePermissions('read-only') });
-engine.registerProvider(adapter);
-const hierarchy = await engine.detectHierarchy(platform);
-```
-
-Show detected mapping and ask for confirmation:
-
-```
-AskUserQuestion: "Detected hierarchy pattern: [pattern]. Is this correct?"
-Options: Yes, use detected mapping | No, let me customize | Use flat mapping
-```
-
-### Step 5: GitHub Projects v2 (GitHub only)
-
-```
-AskUserQuestion: "Do you want to sync with a GitHub Project board?"
-Options: Yes, select a project | No, just Issues + Labels
-```
-
-If yes, list available projects and ask which one.
-
-### Step 5b: Umbrella Per-Repo Sync Targets (Umbrella projects only)
-
-If the project has `umbrella.enabled: true` and `umbrella.childRepos[]`:
-
-1. Read `config.umbrella.childRepos` to list all child repos
-2. For JIRA: Show the global JIRA projectKey and ask if ALL child repos should use it, or if specific repos need different project keys:
-
-```
-AskUserQuestion: "Your umbrella has [N] child repos. Should all sync to JIRA project [KEY]?"
-Options:
-- Yes, use [KEY] for all child repos (default)
-- No, let me assign per-repo JIRA project keys
-```
-
-If "No", for each child repo ask:
-```
-AskUserQuestion: "Which JIRA project key for child repo '[repoName]'?"
-Default: [global projectKey]
-```
-
-3. Write `childRepo.sync.jira.projectKey` for each child repo in config.json
-4. For GitHub: Each child repo should already have `sync.github` from init. If missing, auto-populate from the repo's git remote.
-
-**IMPORTANT**: Never leave child repos without `sync` config — they fall back to global defaults which may route to the wrong external project.
-
-### Step 6: Write Config
-
-Write the following:
-
-1. **`.env`** — Add credentials (JIRA_API_TOKEN, JIRA_EMAIL, AZURE_DEVOPS_PAT, etc.)
-2. **`.specweave/config.json`** — Update sync section:
-
-```json
-{
-  "sync": {
-    "enabled": true,
-    "preset": "bidirectional",
-    "github": { "enabled": true, "owner": "...", "repo": "..." },
-    "jira": { "enabled": true, "domain": "...", "projectKey": "..." },
-    "ado": { "enabled": true, "organization": "...", "project": "..." }
-  }
-}
-```
-
-### Step 7: Integration Health Check
-
-After credentials are validated, run a deeper health check to catch misconfigurations early (e.g., wrong issue types, missing permissions, unavailable integrations):
-
-```typescript
-// Import and run health checks for each enabled provider
-import { checkJiraIntegration, checkAdoIntegration, checkGitHubIntegration, formatHealthCheckResults } from '../../src/sync/integration-health-check.js';
-
-const results = [];
-if (jiraEnabled) results.push(await checkJiraIntegration({ domain, projectKey, email, apiToken }));
-if (adoEnabled)  results.push(await checkAdoIntegration({ organization, project, pat }));
-if (githubEnabled) results.push(await checkGitHubIntegration());
-
-console.log(formatHealthCheckResults(results));
-```
-
-This checks:
-- **JIRA**: API auth, project access, issue type availability (catches "The issue type selected is invalid"), edit permissions for remote links
-- **ADO**: API auth, work item type availability
-- **GitHub**: gh CLI authentication
-
-Warnings are advisory — they don't block setup but alert the user to fix issues before they hit them at increment closure.
-
-### Step 8: Dry Run
-
-Run a test sync (read-only) to verify configuration:
-
-```bash
-# Test each enabled provider with dry-run
-specweave sync-progress --dry-run
-```
-
-Report results and confirm setup is complete.
-
-## Key Principles
-
-- **Never commit secrets**: Credentials go in `.env` only
-- **Validate before saving**: Test API calls before writing config
-- **Safe defaults**: Default to `bidirectional` preset (no delete)
-- **User confirmation**: Always confirm detected hierarchy