specweave 1.0.593 → 2.0.3

package/plugins/specweave/skills/ado-sync/SKILL.md

@@ -1,449 +0,0 @@
----
-description: "[DEPRECATED] Help and guidance for Azure DevOps synchronization with SpecWeave increments. Use when asking how to set up ADO sync, configure credentials, or troubleshoot integration issues. For actual syncing, use sw-ado:push or sw-ado:pull command."
-version: 1.0.0
-user-invokable: false
-deprecated: true
----
-
-> ⚠️ DEPRECATED: Use `sw-ado:push` / `sw-ado:pull` instead. This skill will be removed in v1.3.0.
-
-## Migration
-
-This skill has been deprecated as part of the Opus 4.7 framework alignment (increment 0669).
-
-- **Use instead**: `sw-ado:push` (content SpecWeave→ADO) and `sw-ado:pull` (status ADO→SpecWeave)
-- **Removal**: Scheduled for v1.3.0 (2 minor releases after v1.1.0)
-- **Why**: Consolidated sync logic moved to the `sw-ado:*` command family.
-
-For the migration policy, see `.specweave/docs/internal/specs/skill-deprecation-policy.md`.
-
----
-
-# Azure DevOps Sync Skill
-
-**Purpose**: Seamlessly sync SpecWeave increments with Azure DevOps work items for unified project tracking.
-
-**Default Behavior**: **Bidirectional (two-way) sync** - Changes in either system are automatically synchronized
-
-**⚠️ IMPORTANT**: This skill provides HELP and GUIDANCE about Azure DevOps sync. For actual syncing, users should use the `sw-ado:sync` command directly. This skill should NOT auto-activate when the command is being invoked.
-
-**Capabilities**:
-- Bidirectional sync: SpecWeave ↔ ADO (default)
-- Create ADO work items from increments
-- Sync task progress → ADO comments
-- Update increment status ← ADO state changes
-- Pull ADO comments and field updates → SpecWeave
-- Close work items when increments complete
-- Support for Epics, Features, User Stories
-
----
-
-## When This Skill Activates
-
-✅ **Do activate when**:
-- User asks: "How do I set up Azure DevOps sync?"
-- User asks: "What ADO credentials do I need?"
-- User asks: "How does ADO integration work?"
-- User needs help configuring Azure DevOps integration
-
-❌ **Do NOT activate when**:
-- User invokes `sw-ado:sync` command (command handles it)
-- Command is already running (avoid duplicate invocation)
-- Task completion hook is syncing (automatic process)
-- "Close ADO work item when done"
-
----
-
-## Prerequisites
-
-### 1. ADO Plugin Installed
-
-```bash
-# Check if installed
-/plugin list --installed | grep sw-ado
-
-# Install if needed
-/plugin install sw-ado@specweave
-```
-
-### 2. Azure DevOps Personal Access Token (PAT)
-
-**Create PAT**:
-1. Go to https://dev.azure.com/{organization}/_usersSettings/tokens
-2. Click "New Token"
-3. Name: "SpecWeave Sync"
-4. Scopes: Work Items (Read & Write), Comments (Read & Write)
-5. Copy token → Set environment variable
-
-**Set Token**:
-```bash
-export AZURE_DEVOPS_PAT="your-token-here"
-```
-
-### 3. ADO Configuration
-
-Add to `.specweave/config.json`:
-```json
-{
-  "sync": {
-    "enabled": true,
-    "preset": "bidirectional",
-    "activeProfile": "default",
-    "profiles": {
-      "default": {
-        "provider": "ado",
-        "config": {
-          "organization": "myorg",
-          "project": "MyProject",
-          "workItemType": "Epic",
-          "areaPath": "MyProject\\Team A",
-          "syncOnTaskComplete": true
-        }
-      }
-    }
-  }
-}
-```
-
-**Credentials** (in `.env`, gitignored):
-```bash
-AZURE_DEVOPS_PAT=your-token-here
-# Or org-specific: AZURE_DEVOPS_PAT_MYORG=your-token
-```
-
----
-
-## Commands Available
-
-### `sw-ado:create-workitem <increment-id>`
-
-**Purpose**: Create ADO work item from increment
-
-**Example**:
-```bash
-sw-ado:create-workitem 0005
-```
-
-**Result**:
-- Creates Epic/Feature/User Story in ADO
-- Links work item to increment (metadata)
-- Adds initial comment with spec summary
-- Sets tags: `specweave`, `increment-0005`
-
----
-
-### `sw-ado:sync <increment-id>`
-
-**Purpose**: Sync increment progress with ADO work item
-
-**Example**:
-```bash
-sw-ado:sync 0005
-```
-
-**Result**:
-- Calculates task completion (%)
-- Updates work item description
-- Adds comment with progress update
-- Updates state (New → Active → Resolved)
-
----
-
-### `sw-ado:close-workitem <increment-id>`
-
-**Purpose**: Close ADO work item when increment complete
-
-**Example**:
-```bash
-sw-ado:close-workitem 0005
-```
-
-**Result**:
-- Updates work item state → Closed
-- Adds completion comment with summary
-- Marks work item as resolved
-
----
-
-### `sw-ado:status <increment-id>`
-
-**Purpose**: Check ADO sync status for increment
-
-**Example**:
-```bash
-sw-ado:status 0005
-```
-
-**Result**:
-```
-ADO Sync Status
-===============
-Increment: 0005-payment-integration
-Work Item: #12345
-URL: https://dev.azure.com/myorg/MyProject/_workitems/edit/12345
-State: Active
-Completion: 60% (6/10 tasks)
-Last Synced: 2025-11-04 10:30:00
-Sync Enabled: ✅
-```
-
----
-
-## Automatic Sync
-
-### When Task Completes
-
-**Trigger**: Post-task-completion hook fires
-
-**Flow**:
-1. User marks task complete: `[x] T-005: Add payment tests`
-2. Hook detects ADO sync enabled
-3. Calculate new completion %
-4. Update ADO work item comment:
-   ```markdown
-   ## Progress Update
-   
-   **Increment**: 0005-payment-integration
-   **Status**: 60% complete (6/10 tasks)
-   
-   ### Recently Completed
-   - [x] T-005: Add payment tests
-   
-   ### Remaining
-   - [ ] T-007: Add refund functionality
-   - [ ] T-008: Implement subscriptions
-   - [ ] T-009: Add analytics
-   - [ ] T-010: Security audit
-   
-   ---
-   🤖 Auto-updated by SpecWeave
-   ```
-
-### When Increment Completes
-
-**Trigger**: `sw:done` command
-
-**Flow**:
-1. User runs `sw:done 0005`
-2. Validate all tasks complete
-3. Close ADO work item automatically
-4. Add completion comment with summary
-
----
-
-## Work Item Types
-
-### Epic (Recommended)
-
-**Use When**: Large feature spanning multiple sprints
-
-**Mapping**:
-- SpecWeave increment → ADO Epic
-- Tasks → Epic description (checklist)
-- Progress → Epic comments
-
----
-
-### Feature
-
-**Use When**: Medium-sized feature within a sprint
-
-**Mapping**:
-- SpecWeave increment → ADO Feature
-- Tasks → Feature description (checklist)
-- Progress → Feature comments
-
----
-
-### User Story
-
-**Use When**: Small, single-sprint work
-
-**Mapping**:
-- SpecWeave increment → ADO User Story
-- Tasks → User Story description (checklist)
-- Progress → User Story comments
-
----
-
-## Bidirectional Sync (Optional)
-
-**Enable**: Set `bidirectional: true` in config
-
-**Flow**: ADO → SpecWeave
-1. User updates work item state in ADO (Active → Resolved)
-2. SpecWeave detects change (polling or webhook)
-3. Updates increment status locally
-4. Notifies user: "Work item #12345 resolved → Increment 0005 marked complete"
-
-**Note**: Bidirectional sync requires webhook or polling setup
-
----
-
-## Configuration Options
-
-**`.specweave/config.json`**:
-```json
-{
-  "sync": {
-    "enabled": true,
-    "preset": "bidirectional",
-    "activeProfile": "default",
-    "profiles": {
-      "default": {
-        "provider": "ado",
-        "config": {
-          "organization": "myorg",
-          "project": "MyProject",
-          "workItemType": "Epic",
-          "areaPath": "MyProject\\Team A",
-          "iterationPath": "MyProject\\Sprint 1",
-          "syncOnTaskComplete": true,
-          "syncOnIncrementComplete": true,
-          "createWorkItemsAutomatically": true,
-          "bidirectional": false,
-          "tags": ["specweave", "increment"],
-          "customFields": {
-            "incrementId": "Custom.IncrementId"
-          }
-        }
-      }
-    }
-  }
-}
-```
-
-**Credentials** (in `.env`, gitignored — never commit tokens):
-```bash
-AZURE_DEVOPS_PAT=your-token-here
-```
-
----
-
-## Troubleshooting
-
-### Error: "Personal Access Token invalid"
-
-**Solution**:
-1. Verify token is set: `echo $AZURE_DEVOPS_PAT`
-2. Check token scopes: Work Items (Read & Write)
-3. Ensure token not expired
-4. Regenerate token if needed
-
----
-
-### Error: "Work item not found"
-
-**Solution**:
-1. Check work item ID is correct
-2. Verify you have access to the project
-3. Ensure work item not deleted
-
----
-
-### Error: "Organization or project not found"
-
-**Solution**:
-1. Verify organization name: https://dev.azure.com/{organization}
-2. Check project name (case-sensitive)
-3. Ensure you have access to the project
-
----
-
-## API Rate Limits
-
-**Azure DevOps**:
-- Rate limit: 200 requests per minute per PAT
-- Burst limit: 5000 requests per hour
-- Recommendation: Enable rate limiting in config
-
-**Config** (add to your profile's `config` block):
-```json
-{
-  "sync": {
-    "profiles": {
-      "default": {
-        "provider": "ado",
-        "config": {
-          "rateLimiting": {
-            "enabled": true,
-            "maxRequestsPerMinute": 150
-          }
-        }
-      }
-    }
-  }
-}
-```
-
----
-
-## Security Best Practices
-
-### DO:
-- ✅ Store PAT in environment variable (`AZURE_DEVOPS_PAT`)
-- ✅ Use `.env` file (gitignored)
-- ✅ Set minimum required scopes
-- ✅ Rotate PAT every 90 days
-
-### DON'T:
-- ❌ Commit PAT to git
-- ❌ Share PAT via Slack/email
-- ❌ Use PAT with excessive permissions
-- ❌ Log PAT to console/files
-
----
-
-## Related Commands
-
-- `sw:inc` - Create increment (auto-creates ADO work item if enabled)
-- `sw:do` - Execute tasks (auto-syncs progress to ADO)
-- `sw:done` - Complete increment (auto-closes ADO work item)
-- `sw:status` - Show increment status (includes ADO sync status)
-
----
-
-## Examples
-
-### Example 1: Create Increment with ADO Sync
-
-```bash
-# User
-"Create increment for payment integration"
-
-# SpecWeave (if ADO enabled)
-1. PM agent generates spec.md
-2. Auto-create ADO Epic #12345
-3. Link Epic to increment metadata
-4. Display: "Created increment 0005 → ADO Epic #12345"
-```
-
-### Example 2: Manual Sync
-
-```bash
-# User completed 3 tasks manually
-# Now sync to ADO
-
-sw-ado:sync 0005
-
-# Result: ADO Epic #12345 updated with 30% progress
-```
-
-### Example 3: Check Sync Status
-
-```bash
-sw-ado:status 0005
-
-# Output:
-# Work Item: #12345
-# URL: https://dev.azure.com/myorg/MyProject/_workitems/edit/12345
-# State: Active
-# Completion: 60%
-# Last Synced: 5 minutes ago
-```
-
----
-
-**Status**: Ready to use
-**Version**: 0.1.0
-**Plugin**: specweave-ado

package/plugins/specweave/skills/analytics/SKILL.md

@@ -1,46 +0,0 @@
----
-name: sw/analytics
-description: "Analytics and metrics for SpecWeave usage — token consumption, cache efficiency, agent spawn counts."
-version: 1.0.0
-allowed-tools: Read, Bash
----
-
-## Tool-Use Rationale
-
-- **Read**: Load metrics snapshots, increment history, and config to compute analytics.
-- **Bash**: Run `specweave metrics` CLI commands to gather live telemetry data.
-
-## Usage
-
-```
-sw:analytics [--cache-stats] [--spawn-count] [--token-usage]
-```
-
-## --cache-stats
-
-Displays prompt cache hit rates per skill for the current session.
-
-**Output format**:
-```
-Cache Statistics (current session)
-───────────────────────────────────
-sw/grill         hit rate: 78% (1,240 tokens from cache)
-sw/judge-llm     hit rate: 65% (980 tokens from cache)
-sw/code-reviewer hit rate: 82% (1,560 tokens from cache)
-───────────────────────────────────
-Overall:         hit rate: 75%
-```
-
-**Requirements**:
-- Cache must be enabled (`cache.staticContextFiles` non-empty in config)
-- Minimum 2 invocations per skill for meaningful hit rate
-
-**Enable persistent metrics**: Set `analytics.cacheMetrics.enabled: true` in `.specweave/config.json`.
-
-## --spawn-count
-
-Reports agent spawn counts per team session. Use to verify that Opus 4.7 fan-out reduction is working (target: ≤ 50% of pre-1.1.0 baseline).
-
-## --token-usage
-
-Reports total token consumption per skill across the session.

package/plugins/specweave/skills/architect/SKILL.md

@@ -1,113 +0,0 @@
----
-description: System architect for scalable technical designs and ADRs. Use for system architecture, microservices, database design, trade-off analysis, component diagrams, tech selection.
-version: 1.0.0
-context: fork
-model: opus
----
-
-# Architect
-
-## Tool-Use Rationale
-
-- **Read**: Load the increment's `spec.md`, existing ADRs under `.specweave/docs/internal/architecture/adr/`, and any living-docs referenced by the spec.
-- **Glob**: Discover repo layout, existing services, and interface files that inform component boundaries.
-- **Grep**: Locate existing types, APIs, and data models so the plan builds on reality instead of reinventing.
-- **Write**: Produce `plan.md` and new ADR files where design decisions warrant a record.
-
-## Project Overrides
-
-**Skill Memories**: If `.specweave/skill-memories/architect.md` exists, read and apply its learnings.
-
-## Design Approach
-
-Design system architecture with focus on:
-
-1. **ADRs** — Write Architecture Decision Records in `.specweave/docs/internal/architecture/adr/`
-2. **Component design** — Define boundaries, APIs, data flow
-3. **Trade-off analysis** — Evaluate options with clear pros/cons
-4. **Technology selection** — Choose stack based on project constraints
-
-## Key Architectural Patterns
-
-### Code Mode for API-Heavy Services (ADR-0140)
-
-When a service exposes 50+ API endpoints to AI agents, avoid exposing each as a separate MCP tool. Instead, use the **Code Mode pattern**: expose a typed schema (OpenAPI/JSON Schema) and let the agent write code to discover and call endpoints. This follows Cloudflare's proven approach (2,500+ endpoints → 2 tools, 99.9% token reduction) and SpecWeave's own "Code First, Tools Second" architecture.
-
-**Apply when**: designing agent-facing APIs, MCP servers, or any system where AI agents consume a large surface area.
-
-**Reference**: ADR-0140 (Code Execution Over Direct MCP Tool Calls) in `.specweave/docs/internal/architecture/adr/`
-
-## Markdown Preview Guidelines
-
-When presenting **2+ architectural approaches** for the user to choose between, use `AskUserQuestion` with the `markdown` preview field to show ASCII diagrams. This lets the user visually compare structural trade-offs in a side-by-side panel.
-
-**When to use**: Any decision point with 2+ options that have structural differences (service layout, schema design, component boundaries, data flow).
-
-**When NOT to use**: Simple yes/no questions, single-option confirmations, or text-only trade-offs without structural implications.
-
-### Example 1: Service Architecture Decision (Box Diagrams)
-
-```
-AskUserQuestion({
-  questions: [{
-    question: "Which service architecture should we use for the payment system?",
-    header: "Architecture",
-    multiSelect: false,
-    options: [
-      {
-        label: "Gateway Pattern (Recommended)",
-        description: "Single API gateway routes to microservices. Centralized auth, rate limiting.",
-        markdown: "┌─────────────┐     ┌─────────────┐\n│  Frontend   │────►│ API Gateway │\n│  (Next.js)  │     │  (Workers)  │\n└─────────────┘     └──────┬──────┘\n                      ┌────┴────┐\n                ┌─────▼───┐ ┌───▼───────┐\n                │ Payment │ │  Billing  │\n                │ Service │ │  Service  │\n                └─────────┘ └───────────┘"
-      },
-      {
-        label: "Direct Service Mesh",
-        description: "Services communicate directly via mesh. More resilient but complex.",
-        markdown: "┌─────────────┐     ┌───────────┐\n│  Frontend   │────►│  Payment  │\n│  (Next.js)  │  ┌─►│  Service  │\n└──────┬──────┘  │  └─────┬─────┘\n       │         │        │\n       │    ┌────┴────┐   │\n       └───►│ Billing │◄──┘\n            │ Service │\n            └─────────┘"
-      }
-    ]
-  }]
-})
-```
-
-### Example 2: Database Schema Decision (ASCII Tables)
-
-```
-AskUserQuestion({
-  questions: [{
-    question: "Which schema design should we use for user sessions?",
-    header: "Schema",
-    multiSelect: false,
-    options: [
-      {
-        label: "Normalized (Recommended)",
-        description: "Separate tables with foreign keys. Strict integrity, standard JOINs.",
-        markdown: "users                sessions\n────────────────     ────────────────────\nid     UUID PK       id       UUID PK\nemail  TEXT UNIQUE    user_id  UUID FK ──► users.id\nname   TEXT           token    TEXT UNIQUE\n                     expires  TIMESTAMP\n\nIndexes: users(email), sessions(token, user_id)"
-      },
-      {
-        label: "Denormalized",
-        description: "Single table with embedded session data. Faster reads, no JOINs.",
-        markdown: "user_sessions\n──────────────────────────────\nid            UUID PK\nemail         TEXT UNIQUE\nname          TEXT\nsession_token TEXT UNIQUE\nsession_exp   TIMESTAMP\nmetadata      JSONB\n\nIndexes: user_sessions(email, session_token)"
-      }
-    ]
-  }]
-})
-```
-
-## Project Field (Mandatory on Every Component)
-
-Every component/module block in plan.md MUST include `**Project**: <repo-id>`. This is unconditionally required — no conditional guards based on workspace size or flags.
-
-- **Multi-repo**: Each component specifies which repo owns it via `**Project**:`
-- **Single-repo**: All components get `**Project**: <workspace.name>`
-
-## Delegation
-
-After architecture is ready, delegate to domain skills:
-- Frontend: `sw:architect` (implement UI directly)
-- Backend: `sw:architect` (implement API/services directly)
-
-Output: `plan.md` with architecture decisions and component breakdown.
-
-## Resources
-
-- [Official Documentation](https://verified-skill.com/docs/reference/skills#architect)

package/plugins/specweave/skills/close-all/SKILL.md

@@ -1,51 +0,0 @@
----
-name: close-all
-description: Batch-close all complete increments by delegating each one to `sw:done`. Discovers active/ready-for-review increments with zero pending tasks, then iterates and calls `sw:done` per increment. Use when saying "close all", "close stuck increments", or "batch close".
-version: 1.0.0
-argument-hint: "[--dry-run]"
----
-
-# Batch Close All Complete Increments
-
-Closes all active increments that have reached 100% task completion by delegating each one to `sw:done`. This skill is a thin batch-discovery loop; all actual closure logic (gates, reports, sync) lives in `sw:done`.
-
-## Step 1: Discover Closeable Increments
-
-```bash
-for meta in $(find .specweave/increments -maxdepth 2 -name "metadata.json" | sort); do
-  st=$(jq -r '.status' "$meta" 2>/dev/null)
-  [ "$st" != "active" ] && [ "$st" != "in-progress" ] && [ "$st" != "ready_for_review" ] && continue
-  d=$(dirname "$meta"); id=$(basename "$d"); tasks="$d/tasks.md"
-  [ ! -f "$tasks" ] && continue
-  pending=$(grep -c '\[ \]' "$tasks" 2>/dev/null || echo 0)
-  done_count=$(grep -c '\[x\]' "$tasks" 2>/dev/null || echo 0)
-  if [ "$pending" -eq 0 ] && [ "$done_count" -gt 0 ]; then
-    echo "CLOSEABLE: $id"
-  fi
-done
-```
-
-If no closeable increments are found, report "No increments ready for closure" and stop.
-
-## Step 2: Dry-run
-
-If the user passed `--dry-run`, print the discovered list and stop without closing anything.
-
-## Step 3: Delegate each to `sw:done`
-
-Iterate the discovered list sequentially. For each `<ID>`:
-
-```
-Skill({ skill: "sw:done", args: "<ID>" })
-```
-
-`sw:done` owns the actual closure workflow: code-review, simplify, grill, judge-llm, PM validation, external sync, and final status transition. Close sequentially to respect dependency order; if `sw:done` fails for an increment, log the failure and continue with the next.
-
-## Step 4: Summary
-
-Print a final summary with CLOSED / FAILED counts per increment. Failures are not retried here — the user re-runs `sw:done <ID>` individually once blockers are resolved.
-
-## Notes
-
-- All gate logic lives in `sw:done`. This skill MUST NOT duplicate closure behaviour.
-- Parallel closure is intentionally not supported — race conditions on shared living docs are a real hazard.