specweave 0.30.19 → 0.32.2

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

@@ -1,6 +1,6 @@
 ---
 name: specweave:import-external
-description: Pull external work items from GitHub, JIRA, or Azure DevOps into living docs as READ-ONLY REFERENCES (not increments). To implement imported items, manually create an increment. Supports time range filtering and dry-run mode.
+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.
 ---
 
 # Import External Work Items (Reference Import)
@@ -9,6 +9,29 @@ Import work items from GitHub (issues/milestones), JIRA (epics/stories), or Azur
 
 > **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 `/specweave: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
@@ -25,10 +48,10 @@ Import work items from GitHub (issues/milestones), JIRA (epics/stories), or Azur
 /specweave:import-external [options]
 ```
 
-### Options
+### Options (ALL OPTIONAL - defaults work without them)
 
 - `--since=<range>` - Time range filter (default: since last import)
-  - `last` - Since last import (uses sync metadata)
+  - `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)
@@ -39,25 +62,28 @@ Import work items from GitHub (issues/milestones), JIRA (epics/stories), or Azur
 
 ## Examples
 
-### Example 1: Import New Items (Default)
+### Example 1: Import New Items (Default - NO PROMPTS!)
 
 ```bash
 /specweave:import-external
 
-# Uses default behavior:
-# - Imports from ALL configured platforms (GitHub, JIRA, ADO)
-# - Since last import timestamp (from .specweave/sync-metadata.json)
-# - Creates living docs files
-# - Updates sync metadata
+# IMMEDIATELY executes with defaults:
+# - Since last import (or 1 month if first import)
+# - All configured platforms
 
-# Result:
-# 🔄 Importing from GitHub... [30/30] ✓
-# 🔄 Importing from JIRA... [12/12] ✓
+# 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: 42 items
-#    - GitHub: 30 items (US-201E to US-230E)
-#    - JIRA: 12 items (US-231E to US-242E)
-#    Duplicates skipped: 5 items
+#    Total imported: 15 items
+#    🔗 GITHUB: 15 items
 # ✅ Import complete!
 ```
 
@@ -359,10 +385,11 @@ No tasks defined.
 | Feature | `specweave init` | `/specweave:import-external` |
 |---------|------------------|------------------------------|
 | When to use | First-time setup | Ongoing imports after init |
-| User prompts | Interactive setup | Minimal prompts (confirmation only) |
-| Time range | Configurable (default: 1 month) | Since last import (default) |
+| 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
 

package/plugins/specweave/commands/specweave-increment.md

@@ -395,53 +395,265 @@ const structureConfig = detectStructureLevel(projectRoot);
 6. Multi-project config (`multiProject.enabled`)
 7. Existing folder structure (fallback)
 
-**For 1-Level Structure** (projects only):
+**Project/Board Selection - ULTRA-SMART LOGIC:**
+
+**⚠️ 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 RULES
+
+**RULE 1: NO QUESTION IF ONLY 1 OPTION**
+```
+IF 1-level AND only 1 project → AUTO-SELECT silently, NO question
+IF 2-level AND only 1 project AND only 1 board → AUTO-SELECT silently, NO question
+```
+
+**RULE 2: KEYWORD-BASED AUTO-DETECTION**
+
+Analyze feature description for keywords before asking:
+
+**Project-Level Keywords (1-level and 2-level):**
+```
+Frontend (FE): UI, form, button, page, component, React, Vue, Angular,
+               Next.js, CSS, style, responsive, chart, dashboard, view,
+               modal, widget, Tailwind, Material-UI, Recharts
+
+Backend (BE): API, endpoint, REST, GraphQL, database, query, migration,
+              service, controller, authentication, JWT, session, middleware,
+              CRUD, Redis, PostgreSQL, MongoDB, microservice
+
+Mobile: mobile, iOS, Android, React Native, Flutter, Expo, app, native,
+        push notification, offline, AsyncStorage, screen, touch, gesture
+
+Infrastructure: deploy, CI/CD, Docker, Kubernetes, terraform, monitoring,
+                logging, pipeline, AWS, Azure, GCP, nginx, Helm, ArgoCD
+
+Shared: 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 listed
+```
+
+**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
 ```
-📁 Structure Level: 1 (projects only)
-   Available projects: web-app, mobile-app, platform-infra
 
-Which project should this increment target?
-> web-app
+---
+
+#### DECISION FLOWCHART
+
+```
+START
+  │
+  ▼
+┌─────────────────────────────────────┐
+│ 1. Detect structure level (1 or 2) │
+│ 2. Count available projects/boards │
+└─────────────────────────────────────┘
+  │
+  ▼
+┌─────────────────────────────────────┐
+│ ONLY 1 OPTION?                      │
+│ (1-level: 1 project)                │
+│ (2-level: 1 project + 1 board)      │
+└─────────────────────────────────────┘
+  │
+  ├── YES ──► AUTO-SELECT SILENTLY
+  │           "✅ Project: {name} (auto-selected)"
+  │           NO QUESTION ASKED
+  │
+  ▼ NO
+┌─────────────────────────────────────┐
+│ ANALYZE KEYWORDS in feature desc    │
+│ Calculate confidence per project    │
+└─────────────────────────────────────┘
+  │
+  ├── HIGH (>80% single) ──► AUTO-SELECT + NOTIFY
+  │   "✅ Detected: {project} (keywords: React, form)"
+  │
+  ├── MULTI-PROJECT (within 15%) ──► AUTO-SPLIT USs
+  │   "🔀 Multi-project detected:
+  │    • US-001 (Login UI) → web-app (60%)
+  │    • US-002 (Auth API) → api-service (55%)
+  │    Proceed? (Y/n)"
+  │
+  ├── MEDIUM (50-80%) ──► SUGGEST + CONFIRM
+  │   "📍 Suggested: {project}. Confirm? (Y/n)"
+  │
+  ▼ LOW (<50%)
+┌─────────────────────────────────────┐
+│ ASK with ALL options (multiSelect)  │
+│ Never truncate, never hide options  │
+└─────────────────────────────────────┘
+```
+
+---
+
+#### PER-USER-STORY ASSIGNMENT
+
+**CRITICAL: Assignment is at USER STORY level, not increment level!**
+
+Each US has its own project (and board for 2-level):
+```markdown
+### US-001: Login Form UI
+**Project**: web-app
+**Board**: frontend  <!-- 2-level only -->
+
+### US-002: Auth API Endpoints
+**Project**: api-service
+**Board**: backend  <!-- 2-level only -->
+
+### US-003: Mobile Login
+**Project**: mobile-app
+**Board**: mobile-team  <!-- 2-level only -->
+```
+
+**User can manually edit project/board per US in spec.md anytime!**
 
-✅ spec.md will include: project: web-app
-✅ Sync path: internal/specs/web-app/FS-XXX/
+---
+
+#### EXAMPLE SCENARIOS
+
+**Scenario 1: Single Project (NO QUESTION)**
 ```
+Config: 1 project (my-app)
+Feature: "Add dark mode toggle"
 
-**For 2-Level Structure** (projects + boards):
+→ AUTO-SELECT: my-app
+→ Output: "✅ Project: my-app (single project - auto-selected)"
+→ NO question asked
 ```
-📁 Structure Level: 2 (projects + boards)
-   Available projects: acme-corp
 
-   📁 Project: acme-corp
-      Boards: clinical-insights, platform-engineering, digital-operations
+**Scenario 2: Multiple Projects, Clear Keywords (AUTO-DETECT)**
+```
+Config: 3 projects (web-app, api-service, mobile-app)
+Feature: "Add React dashboard with charts"
 
-Which board should this increment sync to?
-> clinical-insights
+→ Keywords: "React" (FE), "dashboard" (FE), "charts" (FE)
+→ Confidence: 95% → web-app
+→ Output: "✅ Detected: web-app (keywords: React, dashboard, charts)"
+→ NO question (high confidence)
+```
 
-✅ spec.md will include:
-   project: acme-corp
-   board: clinical-insights
-✅ Sync path: internal/specs/acme-corp/clinical-insights/FS-XXX/
+**Scenario 3: Multi-Area Feature (SMART SPLIT)**
 ```
+Config: 3 projects (web-app, api-service, shared-lib)
+Feature: "User authentication with JWT"
+
+→ This spans FE (login form) + BE (auth API) + shared (types)
+→ Output:
+  "🔍 This feature spans multiple projects. Auto-assigning:
+   • US-001: Login UI → web-app
+   • US-002: Auth API → api-service
+   • US-003: Auth types → shared-lib
 
-**Multi-Project User Stories** (if umbrella detected):
+   ✅ Proceed? You can modify per-US in spec.md"
 ```
-📁 Multi-Project Mode Detected!
 
-Child Repos:
-  • FE: sw-thumbnail-ab-fe
-  • BE: sw-thumbnail-ab-be
-  • SHARED: sw-thumbnail-ab-shared
+**Scenario 4: 2-Level, Single Project, Multiple Boards**
+```
+Config: 1 project (enterprise-corp), 5 boards
+Feature: "Add reporting dashboard"
+
+→ Project: AUTO-SELECT (only 1)
+→ Board keywords: "reporting" + "dashboard"
+→ Output:
+  "✅ Project: enterprise-corp (auto-selected)
+   📍 Suggested board: analytics (keyword: reporting)
+   Confirm or select: [1] analytics [2] frontend [3] backend..."
+```
 
-User stories will be generated with project prefixes:
-  • US-FE-001, US-FE-002 (Frontend stories)
-  • US-BE-001, US-BE-002 (Backend stories)
-  • US-SHARED-001 (Shared library stories)
+**Scenario 5: Ambiguous (ASK WITH ALL OPTIONS)**
+```
+Config: 4 projects
+Feature: "Improve system performance"
 
-Each story will include "Related Repo" field for clarity.
+→ No clear keyword match
+→ ASK with ALL options listed (multiSelect: true)
+→ Never hide behind "see all"
 ```
 
-**Pass project/board values to increment-planner skill!**
+---
+
+#### VALIDATION RULES
+
+```
+❌ FORBIDDEN: Asking when only 1 project/board exists
+❌ FORBIDDEN: Hiding options behind "Let me see all"
+❌ FORBIDDEN: Truncating project/board lists
+❌ FORBIDDEN: Assigning ALL USs to same project when content differs
+✅ REQUIRED: Auto-select when only 1 option
+✅ REQUIRED: Use keyword matching before asking
+✅ REQUIRED: Each US has explicit project/board assignment
+✅ REQUIRED: When asking, show ALL options with descriptions
+✅ REQUIRED: Allow user to modify per-US in spec.md
+```
+
+---
+
+#### SPEC.MD YAML FORMAT
+
+**1-Level Structure:**
+```yaml
+---
+increment: 0045-user-auth
+title: "User Authentication"
+default_project: web-app  # Optional default for USs that don't specify
+---
+```
+
+**2-Level Structure:**
+```yaml
+---
+increment: 0045-user-auth
+title: "User Authentication"
+default_project: enterprise-corp
+default_board: backend  # Optional defaults
+---
+```
+
+**Pass detected/selected values to increment-planner skill!**
 
 ### Step 2: Detect tech stack (CRITICAL - framework-agnostic)
    - Settings auto-detected
@@ -659,12 +871,98 @@ This will:
 
 ```
 ✅ Strategic documentation synchronized!
+```
+
+### Step 10: Trigger Living Docs & External Tool Sync (v0.32.2+)
+
+**🔄 CRITICAL: After increment files are created, sync to living docs AND external tools:**
+
+```
+🔄 Syncing increment to living docs...
+📡 Syncing to external tools (GitHub/JIRA/ADO)...
+```
+
+**This step uses the existing sync infrastructure:**
+
+Run `/specweave:sync-specs {increment-id}` to trigger the full sync cascade:
+
+```bash
+/specweave:sync-specs {increment-id}
+```
+
+OR call LivingDocsSync directly in TypeScript implementations:
+
+```typescript
+import { LivingDocsSync } from './src/core/living-docs/living-docs-sync.js';
+
+const sync = new LivingDocsSync(projectRoot);
+const result = await sync.syncIncrement(incrementId, { dryRun: false });
+
+if (result.success) {
+  console.log(`✅ Living docs synced: ${result.featureId}`);
+  console.log(`   Created: ${result.filesCreated.length} files`);
+} else {
+  console.log(`⚠️  Living docs sync had errors (non-blocking): ${result.errors.join(', ')}`);
+}
+```
+
+**What `syncIncrement()` does automatically (Step 7 in the sync flow):**
+
+1. Creates living docs (FS-XXX folder with FEATURE.md and us-*.md files)
+2. Calls `syncToExternalTools()` which detects GitHub/JIRA/ADO from config
+3. Checks permissions (`canUpsertInternalItems`) before creating issues
+4. Creates issues in external tools via existing sync infrastructure:
+   - GitHub: `GitHubFeatureSync.syncFeatureToGitHub(featureId)`
+   - JIRA: `JiraFeatureSync.syncFeatureToJira(featureId)`
+   - ADO: `ADOFeatureSync.syncFeatureToADO(featureId)`
+
+**Expected output:**
+
+```
+🔄 Syncing increment to living docs...
+✅ Living docs synced: FS-118E
+   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-aware sync (v0.32.2+):**
+
+Before calling external sync, `syncToExternalTools()` checks permissions from `.specweave/config.json`:
+
+| Permission | Controls | When Required |
+|------------|----------|---------------|
+| `canUpsertInternalItems` | CREATE new issues for SpecWeave-created items | Creating increment issues |
+| `canUpdateExternalItems` | UPDATE issues imported from external tools | Updating imported items |
+| `canUpdateStatus` | UPDATE issue status (open/closed) | Closing completed items |
+
+If `canUpsertInternalItems: false`:
+```
+⚠️ Skipping external sync - canUpsertInternalItems is disabled in config
+💡 Enable in .specweave/config.json: sync.settings.canUpsertInternalItems: true
+```
+
+**Error handling:**
+
+External tool sync failures are **NON-BLOCKING** (increment creation succeeds):
+
+```
+⚠️ External sync failed: Rate limit exceeded
+💡 Run /specweave:sync-specs {increment-id} to retry
+```
+
+**After Step 10 completes:**
+
+```
+✅ Increment created and synced!
 
 Next steps:
 1. Review the increment plan and strategic docs
-2. Start implementation: /specweave:do 0003
-3. (Optional) Sync to GitHub: /sync-github
-    ```
+2. Start implementation: /specweave:do {increment-id}
+3. Monitor external tool status: /specweave:status {increment-id}
+```
 
 ## Frontmatter Format (spec.md):
 

package/plugins/specweave/commands/specweave-jobs.md

@@ -1,7 +1,7 @@
 ---
 name: specweave:jobs
-description: Monitor background jobs (repo cloning, issue import). Shows progress, allows pause/resume/kill.
-usage: /specweave:jobs [--active|--all|--id <job-id>] [--resume <job-id>] [--kill <job-id>] [--follow <job-id>] [--logs <job-id>]
+description: Show current work status (active increments, progress) and background jobs (imports, cloning). Even with no jobs, shows increment summary and helpful context.
+usage: /specweave:jobs [--all] [--id <job-id>] [--resume <job-id>] [--kill <job-id>] [--follow <job-id>] [--logs <job-id>]
 ---
 
 # Background Jobs Monitor

package/plugins/specweave/commands/specweave-progress.md

@@ -18,12 +18,12 @@ Simple, fast progress check for all active increments.
 ```bash
 #!/bin/bash
 #
-# Enhanced progress tracking with User Story grouping (v0.23.0+)
-# Uses TypeScript script for accurate task parsing and US-level progress
+# Instant progress tracking (v0.32.0+)
+# Uses pre-computed dashboard cache for <10ms response time
 #
 
-# Call TypeScript progress script
-npx tsx "$(dirname "${BASH_SOURCE[0]}")"/../../../scripts/show-progress.ts "$@"
+# Call instant bash script (reads from cache, no Node.js needed)
+bash "$(dirname "${BASH_SOURCE[0]}")"/../scripts/read-progress.sh "$@"
 ```
 
 ## Example Output

package/plugins/specweave/commands/specweave-restore-feature.md

@@ -25,10 +25,11 @@ Restore an archived feature or epic back to its active location. This also resto
 
 ## What Gets Restored
 
-### For Features:
-1. `_features/_archive/FS-XXX/` → `_features/FS-XXX/`
-2. `{project}/_archive/FS-XXX/` → `{project}/FS-XXX/` (all projects)
-3. All links updated from archive paths back to active paths
+### For Features (v5.0.0+):
+1. `{project}/_archive/FS-XXX/` → `{project}/FS-XXX/`
+2. All links updated from archive paths back to active paths
+
+**Note**: The `_features/` folder is OBSOLETE. Features live in `{project}/FS-XXX/`.
 
 ### For Epics:
 1. `_epics/_archive/EPIC-XXX/` → `_epics/EPIC-XXX/`

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

@@ -597,7 +597,7 @@ Status: {status} → Documentation Updated
 ✅ User Stories: {count} created/updated in .specweave/docs/internal/specs/
 ✅ Acceptance Criteria: Synchronized with completion status from spec.md
 ✅ Tasks: Linked to user stories with completion tracking
-✅ Feature Files: Created/updated in .specweave/docs/internal/specs/_features/
+✅ Feature Files: Created/updated in .specweave/docs/internal/specs/{project}/
 
 ───────────────────────────────────────────────────────
 📊 STRATEGIC DOCS CHANGES (Steps 1-5)