specweave 1.0.256 → 1.0.259

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

@@ -1,5 +1,5 @@
 ---
-description: Expert on SpecWeave framework structure, rules, and spec-driven development conventions. Use when learning SpecWeave best practices, understanding increment lifecycle, or configuring hooks. Covers source-of-truth discipline, tasks.md/spec.md formats, living docs sync, and file organization patterns.
+description: SpecWeave framework expert for structure, rules, spec-driven conventions. Use for SpecWeave best practices, increment lifecycle, hooks, tasks.md/spec.md, living docs sync.
 allowed-tools: Read, Grep, Glob
 user-invocable: false
 ---

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

@@ -97,7 +97,7 @@ If detection fails, ask user.
 ```typescript
 Skill({
   skill: "sw:increment-planner",
-  args: "--id=XXXX-name --description=\"...\" --project=my-project"
+  args: "<user's feature description>"
 });
 ```
 

package/plugins/specweave/skills/increment-planner/SKILL.md

@@ -19,31 +19,39 @@ hooks:
 
 # Increment Planner Skill
 
+## CRITICAL: Plan Mode Required
+
+**Before executing this skill, you MUST be in plan mode.** If you are not currently in plan mode, call `EnterPlanMode` first. Increment planning is ALWAYS a planning activity — never skip straight to implementation.
+
 ## Project Overrides
 
 !`s="increment-planner"; for d in .specweave/skill-memories .claude/skill-memories "$HOME/.claude/skill-memories"; do p="$d/$s.md"; [ -f "$p" ] && awk '/^## Learnings$/{ok=1;next}/^## /{ok=0}ok' "$p" && break; done 2>/dev/null; true`
 
+## Project Context
+
+!`.specweave/scripts/skill-context.sh increment-planner 2>/dev/null; true`
+
 **Self-contained increment planning for ANY user project after `specweave init`.**
 
 ## Workflow Overview
 
 ```
-STEP 0: Pre-flight (TDD mode, multi-project, Deep Interview)
+STEP 1: Pre-flight (TDD mode, multi-project, Deep Interview)
         -> CHECK: Deep Interview Mode enabled?
 
-STEP 0.5: Deep Interview (if enabled)
-        -> PM skill loads phases/00-deep-interview.md
-        -> ASSESS complexity first, then ask right number of questions
-        -> Skip categories that don't apply to this feature
+STEP 1a: Deep Interview (if enabled)
+         -> PM skill loads phases/00-deep-interview.md
+         -> ASSESS complexity first, then ask right number of questions
+         -> Skip categories that don't apply to this feature
 
-STEP 1: Project Context (resolve project/board)
+STEP 2: Project Context (resolve project/board)
 
-STEP 2: Create Increment (via Template API)
+STEP 3: Create Increment (via Template API)
 
-STEP 3: Guide User (complete in main conversation)
+STEP 4: Guide User (complete in main conversation)
 ```
 
-## Step 0: Pre-flight Checks
+## Step 1: Pre-flight Checks
 
 ```bash
 # 1. Check TDD mode
@@ -59,7 +67,7 @@ jq -r '.planning.deepInterview.enabled // false' .specweave/config.json 2>/dev/n
 find .specweave/increments -maxdepth 2 -name "metadata.json" -exec grep -l '"status":"active"' {} \; 2>/dev/null | wc -l
 ```
 
-## Step 0.5: Deep Interview Mode (if enabled)
+## Step 1a: Deep Interview Mode (if enabled)
 
 **If deep interview is enabled, delegate to PM skill:**
 
@@ -70,7 +78,7 @@ Skill({ skill: "sw:pm", args: "Deep interview mode for: <user description>" })
 **THINK about complexity first** - assess before asking:
 - Trivial: 0-3 questions | Small: 4-8 | Medium: 9-18 | Large: 19-40+
 
-## Step 1: Project Context
+## Step 2: Project Context
 
 ```bash
 # Get project/board values for spec.md
@@ -79,9 +87,9 @@ specweave context projects
 
 Every US MUST have `**Project**:` field. For 2-level structures, also `**Board**:`.
 
-## Step 2: Create Increment
+## Step 3: Create Increment
 
-### 2a. Determine Increment Location
+### 3a. Determine Increment Location
 
 **CRITICAL for multi-repo setups:**
 
@@ -108,7 +116,7 @@ fi
 - Run `specweave init` in each repo if `.specweave/` doesn't exist
 - Repos MUST be at `repositories/{ORG}/{repo-name}/` — NEVER directly under `repositories/`
 
-### 2b. Get Unique ID
+### 3b. Get Unique ID
 
 ```bash
 # Check ALL folders for existing IDs
@@ -118,13 +126,15 @@ find .specweave/increments -maxdepth 2 -type d -name "[0-9]*" 2>/dev/null | grep
 find repositories -path "*/specweave/increments/*" -maxdepth 5 -type d -name "[0-9]*" 2>/dev/null | grep -oE '[0-9]{4}E?' | sort -u | tail -5
 ```
 
-### 2c. Create via CLI (preferred)
+### 3c. Create via CLI (preferred)
 
 ```bash
-specweave create-increment --id "XXXX-name" --project "my-app"
+specweave create-increment --id "XXXX-name" --title "Feature Title" --description "Brief description" --project "my-app"
 ```
 
-### 2d. Create manually (if CLI unavailable)
+**Optional flags**: `--type hotfix` | `--priority P1` | `--board "team-name"` | `--json`
+
+### 3d. Create manually (if CLI unavailable)
 
 ```bash
 mkdir -p .specweave/increments/XXXX-name
@@ -173,7 +183,7 @@ Create files in order: metadata.json FIRST, then spec.md, plan.md, tasks.md.
 ## Critical Rules
 
 1. **Project field is MANDATORY** - Every US MUST have `**Project**:` field
-2. **Use Template Creator API** when available: `specweave create-increment --id "XXXX-name" --project "my-app"`
+2. **Use Template Creator CLI** (REQUIRED): `specweave create-increment --id "XXXX-name" --title "Title" --description "Desc" --project "my-app"`
 3. **NO agent spawning** - Skills MUST NOT spawn Task() agents (causes crashes). Guide user in main conversation.
 4. **Increment naming** - Format: `####-descriptive-kebab-case`
 5. **Multi-repo** - In umbrella projects with `repositories/` folder, create increments in EACH repo's `.specweave/`, not the umbrella root
@@ -194,7 +204,7 @@ Skill({ skill: "sw:test-aware-planner", args: "Generate tasks for increment XXXX
 
 ```typescript
 // Called by hook system (primary path)
-Skill({ skill: "sw:increment-planner", args: "--description=\"Add auth\"" })
+Skill({ skill: "sw:increment-planner", args: "Add user authentication" })
 
 // Via command (handles pre-flight checks too)
 /sw:increment "Add user authentication"

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

@@ -0,0 +1,52 @@
+---
+description: View and manage background jobs (cloning, imports, living-docs). Shows job status, progress, and logs. Use when saying "check jobs", "job status", or "background tasks".
+argument-hint: "[--all] [--id job-id]"
+---
+
+# Background Jobs Monitor
+
+## Project Overrides
+
+!`s="jobs"; for d in .specweave/skill-memories .claude/skill-memories "$HOME/.claude/skill-memories"; do p="$d/$s.md"; [ -f "$p" ] && awk '/^## Learnings$/{ok=1;next}/^## /{ok=0}ok' "$p" && break; done 2>/dev/null; true`
+
+Shows background job information including:
+- **Clone jobs** — repository cloning progress and status
+- **Import jobs** — issue/epic import from GitHub, JIRA, ADO
+- **Living docs** — documentation builder progress
+- **Brownfield analysis** — code-spec gap detection
+
+## Hook Execution (Default)
+
+This command is intercepted by the **UserPromptSubmit hook** for instant execution (<100ms). The hook runs `read-jobs.sh` or `jobs.js` directly.
+
+**No action needed** — the hook output appears automatically in `<system-reminder>` tags.
+
+## CLI Fallback
+
+If hook output isn't displayed (rare), execute:
+
+```bash
+specweave jobs
+```
+
+## Arguments
+
+- `/sw:jobs` — Show active and recent jobs
+- `/sw:jobs --all` — Show all jobs including completed
+- `/sw:jobs --id <job-id>` — Show details for specific job
+
+## Data Shown
+
+| Field | Description |
+|-------|-------------|
+| Job ID | Short UUID identifier |
+| Type | clone-repos, import-issues, living-docs-builder, etc. |
+| Status | pending, running, completed, completed_with_warnings, failed |
+| Progress | `X/Y (Z%)` with progress bar |
+| Duration | Elapsed time since job started |
+
+## Related Commands
+
+- `/sw:progress` — Increment task/AC completion
+- `/sw-github:clone` — Trigger GitHub repo cloning
+- `/sw-ado:clone` — Trigger ADO repo cloning

package/plugins/specweave/skills/multi-project-spec-mapper/SKILL.md

@@ -1,5 +1,5 @@
 ---
-description: Intelligent multi-project specification splitting that maps user stories to correct projects (FE, BE, MOBILE, INFRA). Use when working with multiple JIRA/GitHub projects, microservices architecture, or brownfield projects with multiple teams. Analyzes content and tech stack for automatic classification.
+description: Multi-project spec splitting that maps user stories to correct projects (FE, BE, MOBILE, INFRA). Use for microservices, multiple JIRA/GitHub projects, multi-team setups.
 user-invocable: false
 ---