specweave 0.32.0 → 0.32.3

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

@@ -176,78 +176,362 @@ echo "Using coverageTarget: $coverageTarget"
 
 **Store these values for use in STEP 4 and STEP 7!**
 
-### STEP 0B: Detect Structure Level & Select Project/Board (MANDATORY!)
+### STEP 0B: Get Project Context (MANDATORY - BLOCKING!)
 
-**⚠️ CRITICAL: Before generating spec.md, you MUST know the target project (and board for 2-level structures)!**
+**⛔ DO NOT PROCEED TO STEP 1 WITHOUT COMPLETING THIS STEP!**
+
+Before generating ANY spec.md content, you MUST run this CLI command:
+
+```bash
+specweave context projects
+```
+
+This returns JSON with available projects and structure level:
+
+```json
+{
+  "level": 1,
+  "projects": [{"id": "my-app", "name": "My App"}],
+  "detectionReason": "multiProject configuration",
+  "source": "multi-project"
+}
+```
+
+**For 2-level structures**, output includes boards:
+```json
+{
+  "level": 2,
+  "projects": [{"id": "acme-corp", "name": "ACME Corporation"}],
+  "boardsByProject": {
+    "acme-corp": [
+      {"id": "digital-ops", "name": "Digital Operations"},
+      {"id": "mobile-team", "name": "Mobile Team"}
+    ]
+  },
+  "detectionReason": "ADO area path mapping configured",
+  "source": "ado-area-path"
+}
+```
+
+**VALIDATION RULES:**
+
+```
+✅ REQUIRED: Parse the JSON output and use ONLY those project/board values
+✅ REQUIRED: project field MUST match one of the returned projects[].id
+✅ REQUIRED: board field (2-level) MUST match one of boardsByProject[project].id
+❌ FORBIDDEN: Inventing or guessing project names
+❌ FORBIDDEN: Using folder name as project (e.g., "sw-olysense")
+❌ FORBIDDEN: Creating spec.md with {{PROJECT_ID}} placeholder
+❌ FORBIDDEN: Creating spec.md for 2-level without board: field
+```
 
 **Structure Levels:**
 - **1-Level**: `internal/specs/{project}/FS-XXX/` - requires `project` in spec.md
 - **2-Level**: `internal/specs/{project}/{board}/FS-XXX/` - requires BOTH `project` AND `board`
 
-**Detection Logic** (use `src/utils/structure-level-detector.ts`):
+**Alternative: Interactive Selection:**
+```bash
+specweave context select
+# Returns auto-selected or prompts for selection
+```
 
-```typescript
-import { detectStructureLevel, getRequiredSpecFields } from './utils/structure-level-detector.js';
+**Get boards for a specific project (2-level):**
+```bash
+specweave context boards --project=acme-corp
+```
 
-const structureConfig = detectStructureLevel(projectRoot);
-console.log(`Structure level: ${structureConfig.level}`);
-console.log(`Detection reason: ${structureConfig.detectionReason}`);
-console.log(`Available projects: ${structureConfig.projects.map(p => p.id).join(', ')}`);
+**Project/Board Selection - ULTRA-SMART LOGIC (MANDATORY BEFORE STEP 4!):**
 
-if (structureConfig.level === 2 && structureConfig.boardsByProject) {
-  console.log('Available boards by project:');
-  for (const [projectId, boards] of Object.entries(structureConfig.boardsByProject)) {
-    console.log(`  ${projectId}: ${boards.map(b => b.id).join(', ')}`);
-  }
-}
+**⚠️ CORE PRINCIPLE: Each User Story belongs to exactly ONE project (1-level) or ONE project+board (2-level). An increment can contain USs spanning MULTIPLE projects/boards.**
+
+---
+
+### SMART SELECTION DECISION TREE
+
+**RULE 1: NO QUESTION IF ONLY 1 OPTION**
+```
+IF 1-level AND only 1 project → AUTO-SELECT silently
+IF 2-level AND only 1 project AND only 1 board → AUTO-SELECT silently
 ```
 
-**Manual Detection:**
-```bash
-# Check if 2-level (ADO area paths or JIRA boards)
-jq '.sync.profiles | to_entries[] | select(.value.provider == "ado") | .value.config.areaPathMapping' .specweave/config.json
+**RULE 2: KEYWORD-BASED AUTO-DETECTION**
+
+Analyze feature description and US content for keywords:
+
+**Project-Level Keywords (1-level and 2-level):**
+```
+Frontend (FE) keywords:
+  UI, form, button, page, component, React, Vue, Angular, Next.js,
+  CSS, style, responsive, chart, dashboard, view, modal, widget,
+  Tailwind, Material-UI, Recharts
+
+Backend (BE) keywords:
+  API, endpoint, REST, GraphQL, database, query, migration, service,
+  controller, authentication, JWT, session, middleware, CRUD,
+  Redis, PostgreSQL, MongoDB, microservice
+
+Mobile keywords:
+  mobile, iOS, Android, React Native, Flutter, Expo, app, native,
+  push notification, offline, AsyncStorage, screen, touch, gesture
+
+Infrastructure (INFRA) keywords:
+  deploy, CI/CD, Docker, Kubernetes, terraform, monitoring,
+  logging, pipeline, AWS, Azure, GCP, nginx, Helm, ArgoCD
+
+Shared (SHARED) keywords:
+  types, interfaces, utilities, validators, shared, common, library,
+  SDK, models, constants, helpers
+```
+
+**Board-Level Keywords (2-level structures only):**
+```
+When project has multiple boards, also match board-specific keywords:
+
+analytics/reporting: analytics, metrics, KPI, dashboard, report, chart, graph
+user-management: user, auth, login, registration, profile, permissions, roles
+integrations: integration, webhook, API, third-party, sync, import, export
+payments: payment, billing, subscription, invoice, stripe, checkout
+notifications: notification, alert, email, SMS, push, messaging
+devops/platform: deploy, infrastructure, monitoring, CI/CD, pipeline
+```
+
+**RULE 3: CONFIDENCE CALCULATION FORMULA**
+```
+confidence = (matched_keywords / total_feature_keywords) × 100
+
+Example: "Add React login form with JWT authentication"
+  Keywords found: React (FE), login (FE), form (FE), JWT (BE), authentication (BE)
+  FE matches: 3, BE matches: 2
+  FE confidence: 3/5 = 60%
+  BE confidence: 2/5 = 40%
+  → Primary: FE (60%), Secondary: BE (40%)
+  → SUGGEST: "Frontend (60%), but also touches Backend (40%)"
+
+If multiple projects have similar confidence (within 15%):
+  → Treat as MULTI-PROJECT feature
+  → Auto-split USs by detected keywords
+```
+
+**RULE 4: CONFIDENCE-BASED DECISION**
+```
+>80% single project → AUTO-SELECT with notification (no question)
+50-80% single project → SUGGEST with quick confirm option
+Multiple projects within 15% → AUTO-SPLIT across projects
+<50% OR ambiguous → ASK user with all options
+```
+
+**RULE 5: FALLBACK TO DEFAULTS**
+```
+IF US has explicit **Project**: field → USE IT
+ELSE IF frontmatter has default_project → USE default_project
+ELSE → ASK user (should not happen if flow followed correctly)
+
+Same logic applies to **Board**: and default_board for 2-level
+```
+
+---
+
+### DECISION FLOWCHART
+
+```
+START
+  │
+  ▼
+┌─────────────────────────────────────┐
+│ 1. Detect structure level (1 or 2) │
+│ 2. Count available projects/boards │
+└─────────────────────────────────────┘
+  │
+  ▼
+┌─────────────────────────────────────┐
+│ ONLY 1 PROJECT?                     │
+│ (1-level: 1 project)                │
+│ (2-level: 1 project + 1 board)      │
+└─────────────────────────────────────┘
+  │
+  ├── YES ──► AUTO-SELECT SILENTLY
+  │           Output: "✅ Project: {name} (auto-selected)"
+  │           NO QUESTION ASKED
+  │
+  ▼ NO
+┌─────────────────────────────────────┐
+│ ANALYZE KEYWORDS in feature desc   │
+│ Calculate confidence per project   │
+└─────────────────────────────────────┘
+  │
+  ├── HIGH CONFIDENCE (>80% single) ──► AUTO-SELECT + NOTIFY
+  │   Output: "✅ Detected: {project} (keywords: form, React)"
+  │
+  ├── MULTI-PROJECT (within 15%) ──► AUTO-SPLIT USs
+  │   Output: "🔀 Multi-project detected:
+  │            • US-001 (Login UI) → web-app (60%)
+  │            • US-002 (Auth API) → api-service (55%)
+  │            Proceed? (Y/n)"
+  │
+  ├── MEDIUM CONFIDENCE (50-80%) ──► SUGGEST + CONFIRM
+  │   Output: "📍 Suggested: {project}. Confirm? (Y/n)"
+  │
+  ▼ LOW CONFIDENCE (<50%)
+┌─────────────────────────────────────┐
+│ ASK USER with ALL options listed   │
+│ multiSelect: true                  │
+│ Show complete list (never truncate)│
+└─────────────────────────────────────┘
+```
+
+---
+
+### PER-USER-STORY ASSIGNMENT MODEL
+
+**CRITICAL: Assignment is at USER STORY level, not increment level!**
+
+Each US in spec.md has its own project (and board for 2-level):
+
+```markdown
+## User Stories
 
-# Check existing folder structure
-ls -la .specweave/docs/internal/specs/*/  # If sub-folders exist (not FS-XXX) → 2-level
+### US-001: Login Form UI
+**Project**: web-app
+**Board**: frontend  <!-- 2-level only -->
+**As a** user...
+
+### US-002: Auth API Endpoints
+**Project**: api-service
+**Board**: backend  <!-- 2-level only -->
+**As a** developer...
+
+### US-003: Mobile Login Screen
+**Project**: mobile-app
+**Board**: mobile-team  <!-- 2-level only -->
+**As a** mobile user...
+```
+
+**User can manually change project/board per US at any time by editing spec.md!**
+
+---
+
+### EXAMPLE SCENARIOS
+
+**Scenario 1: Single Project (NO QUESTION)**
+```
+Config: 1 project (my-app)
+Feature: "Add user authentication"
+
+→ AUTO-SELECT: my-app
+→ Output: "✅ Project: my-app (single project - auto-selected)"
+→ NO question asked
+```
+
+**Scenario 2: Multiple Projects, Clear Keywords (AUTO-DETECT)**
+```
+Config: 3 projects (web-app, api-service, mobile-app)
+Feature: "Add React dashboard with charts"
+
+→ Keyword analysis: "React" (FE), "dashboard" (FE), "charts" (FE)
+→ Confidence: 95% → web-app
+→ Output: "✅ Detected project: web-app (keywords: React, dashboard, charts)"
+→ NO question asked (high confidence)
+```
+
+**Scenario 3: Multiple Projects, Multi-Area Feature (SMART SPLIT)**
 ```
+Config: 3 projects (web-app, api-service, shared-lib)
+Feature: "User authentication with JWT"
 
-**Project/Board Selection (MANDATORY BEFORE STEP 4!):**
+→ Analyze: This spans FE (login form) + BE (auth API) + possibly shared (types)
+→ Output:
+  "🔍 This feature likely spans multiple projects:
 
-1. **For 1-level structure:**
-   - ASK user: "Which project should this increment sync to?"
-   - Options: List from `structureConfig.projects`
-   - Store selected `PROJECT_ID`
+   Based on 'user authentication with JWT', I'll create:
+   • US-001: Login/Register UI → web-app (keywords: UI, form)
+   • US-002: Auth API endpoints → api-service (keywords: API, JWT)
+   • US-003: Auth types/validators → shared-lib (keywords: types, shared)
 
-2. **For 2-level structure:**
-   - ASK user: "Which project should this increment sync to?"
-   - Then ASK: "Which board/area path within {project}?"
-   - Options: List from `structureConfig.boardsByProject[selectedProject]`
-   - Store BOTH `PROJECT_ID` and `BOARD_ID`
+   ✅ Proceed with this assignment? (Y/n)
+   💡 You can modify project per US in spec.md anytime"
+```
+
+**Scenario 4: 2-Level, Single Project, Auto-Detect Board**
+```
+Config: 1 project (enterprise-corp), 5 boards (analytics, frontend, backend, mobile, devops)
+Feature: "Add reporting dashboard"
+
+→ Project: AUTO-SELECT enterprise-corp (only option)
+→ Board keywords: "reporting" → analytics, "dashboard" → frontend
+→ Confidence: 70% analytics, 60% frontend
+→ Output:
+  "✅ Project: enterprise-corp (auto-selected)
+   📍 Suggested board: analytics (keyword: reporting)
 
-**VALIDATION RULE:**
+   Confirm or select different board:
+   1. analytics (suggested)
+   2. frontend
+   3. backend
+   4. mobile
+   5. devops"
 ```
-❌ FORBIDDEN: Creating spec.md without PROJECT_ID set
-❌ FORBIDDEN: Creating spec.md for 2-level without BOARD_ID set
-❌ FORBIDDEN: Vague increments like "show last git commits" without project context
-✅ REQUIRED: Always know WHERE this increment will sync BEFORE creating spec.md
+
+**Scenario 5: Completely Ambiguous (ASK WITH ALL OPTIONS)**
+```
+Config: 4 projects (proj-a, proj-b, proj-c, proj-d)
+Feature: "Improve system performance"
+
+→ Keyword analysis: No clear project match
+→ Output:
+  "❓ Which project(s) should this increment target?
+
+   Available projects:
+   • proj-a - E-commerce frontend
+   • proj-b - Order processing API
+   • proj-c - Mobile shopping app
+   • proj-d - Infrastructure/DevOps
+
+   Select one or more (comma-separated, e.g., '1,2' or 'proj-a,proj-b'):"
 ```
 
-**Example User Interaction:**
+---
+
+### VALIDATION RULES
 
 ```
-🔍 Detected 2-level structure (ADO area path mapping)
-   Available projects: acme-corp
+❌ FORBIDDEN: Asking project question when only 1 project exists
+❌ FORBIDDEN: Asking board question when only 1 board exists in project
+❌ FORBIDDEN: Hiding options behind "Let me see all" - ALWAYS show complete list
+❌ FORBIDDEN: Truncating project/board lists
+❌ FORBIDDEN: Assigning ALL USs to same project when content clearly differs
+✅ REQUIRED: Auto-select when only 1 option available
+✅ REQUIRED: Use keyword matching before asking user
+✅ REQUIRED: Each US has explicit project (and board for 2-level) assignment
+✅ REQUIRED: Allow user to modify assignments per-US in spec.md
+✅ REQUIRED: When asking, show ALL options with descriptions
+```
 
-   📁 Project: acme-corp
-      Boards: clinical-insights, platform-engineering, digital-operations
+---
+
+### SPEC.MD YAML FORMAT
 
-Which board should this increment sync to?
-> digital-operations
+**1-Level Structure:**
+```yaml
+---
+increment: 0045-user-auth
+title: "User Authentication"
+# Optional default (used if US doesn't specify)
+default_project: web-app
+---
+```
 
-✅ Increment will sync to: internal/specs/acme-corp/digital-operations/FS-XXX/
+**2-Level Structure:**
+```yaml
+---
+increment: 0045-user-auth
+title: "User Authentication"
+# Optional defaults (used if US doesn't specify)
+default_project: enterprise-corp
+default_board: backend
+---
 ```
 
-**Store PROJECT_ID and BOARD_ID for use in STEP 4!**
+**Store detected/selected values for use in STEP 4!**
 
 ---
 
@@ -445,6 +729,60 @@ const metadata = {
 
 **DO NOT invoke Task() tool to spawn agents from this skill!**
 
+### STEP 9: Trigger Living Docs & External Tool Sync (v0.32.2+)
+
+**🔄 CRITICAL: After increment files are created, trigger sync to living docs AND external tools!**
+
+This step uses the existing sync infrastructure to:
+1. Create living docs (FS-XXX folder with FEATURE.md and us-*.md files)
+2. Check permissions (`canUpsertInternalItems`) from `.specweave/config.json`
+3. Sync to external tools (GitHub/JIRA/ADO) if configured and permitted
+
+**Run the sync-specs command:**
+
+```bash
+/specweave:sync-specs {increment-id}
+```
+
+**Expected output:**
+
+```
+🔄 Syncing increment to living docs...
+✅ Living docs synced: FS-021
+   Created: 4 files (FEATURE.md, us-001.md, us-002.md, us-003.md)
+
+📡 Syncing to external tools: github
+   📋 Permissions: upsert=true, update=true, status=true
+   ✅ Synced to GitHub: 0 updated, 3 created
+```
+
+**Permission handling (v0.32.2+):**
+
+If `canUpsertInternalItems: false` in config:
+```
+⚠️ Skipping external sync - canUpsertInternalItems is disabled
+💡 Enable in .specweave/config.json: sync.settings.canUpsertInternalItems: true
+```
+
+**Error handling:**
+
+External tool sync failures are NON-BLOCKING:
+```
+⚠️ External sync failed: Rate limit exceeded
+💡 Run /specweave:sync-specs {increment-id} to retry
+```
+
+**Output after sync:**
+
+```
+✅ Increment created and synced!
+
+Next steps:
+1. Review the increment plan and docs
+2. Start implementation: /specweave:do {increment-id}
+3. Monitor status: /specweave:status {increment-id}
+```
+
 ---
 
 ## Model Selection for Tasks
@@ -457,19 +795,21 @@ When creating tasks, assign optimal models:
 - Simple CRUD, configuration, setup
 - Mechanical work with defined approach
 
-**🧠 Sonnet** (thinking, balanced):
+**💎 Opus** (best quality, default):
 - Architecture decisions
 - Multiple valid approaches
 - Integration between components
 - Complex business logic
 - Error handling strategies
-
-**💎 Opus** (critical, expensive):
 - Critical system architecture
 - Security-critical decisions
 - Performance-critical algorithms
 - Novel problem-solving
 
+**🧠 Sonnet** (legacy, rarely needed):
+- Use only for backwards compatibility
+- Prefer Opus or Haiku instead
+
 ---
 
 ## Validation Checklist

package/plugins/specweave/skills/increment-planner/templates/spec-multi-project.md

@@ -8,6 +8,8 @@ created: {{DATE}}
 structure: user-stories
 test_mode: {{TEST_MODE}}
 coverage_target: {{COVERAGE_TARGET}}
+# MANDATORY: Run "specweave context projects" to get valid project/board IDs
+# For 2-level structures: BOTH project AND board are REQUIRED
 project: {{PROJECT_ID}}
 board: {{BOARD_ID}}
 multi_project: true
@@ -26,12 +28,16 @@ projects:
 
 [High-level description - WHAT this feature does and WHY it's needed]
 
-## User Stories by Project
+## User Stories
 
-### Frontend ({{PROJECT_FE_ID}})
+<!-- Each US has its own **Project** and **Board** fields. User can modify per-US anytime. -->
+
+### Frontend Stories
 
 #### US-FE-001: [Story Title] (P1)
-**Related Repo**: {{PROJECT_FE_ID}}
+**Project**: {{PROJECT_ID}}
+**Board**: {{BOARD_FE_ID}}
+
 **As a** [user type]
 **I want** [goal]
 **So that** [benefit]
@@ -42,10 +48,12 @@ projects:
 
 ---
 
-### Backend ({{PROJECT_BE_ID}})
+### Backend Stories
 
 #### US-BE-001: [Story Title] (P1)
-**Related Repo**: {{PROJECT_BE_ID}}
+**Project**: {{PROJECT_ID}}
+**Board**: {{BOARD_BE_ID}}
+
 **As a** [system/frontend application]
 **I want** [API endpoint/service goal]
 **So that** [benefit]
@@ -56,10 +64,12 @@ projects:
 
 ---
 
-### Shared Library ({{PROJECT_SHARED_ID}})
+### Shared Library Stories
 
 #### US-SHARED-001: [Story Title] (P1)
-**Related Repo**: {{PROJECT_SHARED_ID}}
+**Project**: {{PROJECT_ID}}
+**Board**: {{BOARD_SHARED_ID}}
+
 **As a** developer in FE or BE repos
 **I want** [shared types/utilities/validators]
 **So that** [consistency across projects]

package/plugins/specweave/skills/increment-planner/templates/spec-single-project.md

@@ -8,6 +8,7 @@ created: {{DATE}}
 structure: user-stories
 test_mode: {{TEST_MODE}}
 coverage_target: {{COVERAGE_TARGET}}
+# MANDATORY: Run "specweave context projects" to get valid project ID
 project: {{PROJECT_ID}}
 ---
 
@@ -19,7 +20,10 @@ project: {{PROJECT_ID}}
 
 ## User Stories
 
+<!-- Each US can have its own **Project** field. If omitted, uses default_project from frontmatter -->
+
 ### US-001: [Story Title] (P1)
+**Project**: {{PROJECT_ID}}
 
 **As a** [user type]
 **I want** [goal]
@@ -30,8 +34,9 @@ project: {{PROJECT_ID}}
 - [ ] **AC-US1-02**: [Another criterion]
 
 ### US-002: [Story Title] (P2)
+**Project**: {{PROJECT_ID}}
 
-[Repeat structure]
+[Repeat structure - change Project per US if spanning multiple projects]
 
 ## Functional Requirements
 

package/plugins/specweave/skills/increment-planner/templates/tasks-multi-project.md

@@ -6,7 +6,7 @@
 - `[P]`: Parallelizable
 - `[ ]`: Not started
 - `[x]`: Completed
-- Model hints: ⚡ haiku, 🧠 sonnet, 💎 opus
+- Model hints: ⚡ haiku (simple), 💎 opus (default)
 
 ## Phase 1: Foundation & Setup
 

package/plugins/specweave/skills/increment-planner/templates/tasks-single-project.md

@@ -6,7 +6,7 @@
 - `[P]`: Parallelizable
 - `[ ]`: Not started
 - `[x]`: Completed
-- Model hints: ⚡ haiku, 🧠 sonnet, 💎 opus
+- Model hints: ⚡ haiku (simple), 💎 opus (default)
 
 ## Phase 1: Setup
 

package/plugins/specweave/skills/instant-status/SKILL.md

@@ -0,0 +1,70 @@
+---
+name: instant-status
+description: Instant status commands that bypass LLM processing. Execute scripts directly for /specweave:status, /specweave:progress, /specweave:jobs. Activates for specweave status, specweave progress, specweave jobs, increment status, show status, show progress, background jobs, job status.
+---
+
+# Instant Status Commands
+
+These commands need **NO LLM reasoning** - execute scripts directly for instant results.
+
+## Commands and Scripts
+
+| Command | Script | Purpose |
+|---------|--------|---------|
+| `/specweave:status` | `bash plugins/specweave/scripts/read-status.sh` | Increment status overview |
+| `/specweave:progress` | `bash plugins/specweave/scripts/read-progress.sh` | Task completion progress |
+| `/specweave:jobs` | `bash plugins/specweave/scripts/read-jobs.sh` | Background job status |
+
+## CRITICAL: Direct Execution Required
+
+When user requests these commands:
+
+1. **DO NOT** process as natural language
+2. **DO NOT** expand slash command markdown
+3. **RUN** the bash script via Bash tool (NOT node!)
+4. **SHOW** output directly to user
+
+### Example Execution
+
+```bash
+# User types: /specweave:status
+# You execute:
+bash plugins/specweave/scripts/read-status.sh
+
+# User types: /specweave:progress
+# You execute:
+bash plugins/specweave/scripts/read-progress.sh
+
+# User types: /specweave:jobs
+# You execute:
+bash plugins/specweave/scripts/read-jobs.sh
+```
+
+## Three Execution Paths
+
+| Layer | Context | Speed | When Used |
+|-------|---------|-------|-----------|
+| **Hook** | Claude Code | <100ms | Automatic (UserPromptSubmit intercepts) |
+| **Skill** | Any LLM | ~2s | When hook not available (you are here) |
+| **CLI** | Terminal | ~500ms | Direct `specweave status` command |
+
+## CLI Alternative
+
+Users can also run directly in terminal:
+```bash
+specweave status    # Full CLI command
+specweave jobs      # Background jobs
+```
+
+## Script Arguments
+
+```bash
+bash plugins/specweave/scripts/read-status.sh 0045    # Specific increment
+bash plugins/specweave/scripts/read-jobs.sh --all     # All jobs
+```
+
+## Why This Matters
+
+- **3+ minutes** to **<100ms**: Status commands were expanding as prompts
+- **Zero LLM tokens**: Pure filesystem reads, no AI needed
+- **Universal**: Works in Claude Code, Cursor, Copilot, CLI