specweave 0.33.3 → 0.33.5

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

@@ -8,17 +8,18 @@ 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}}
+# MANDATORY: Must be RESOLVED values from "specweave context projects" output
+# ⛔ NEVER use {{PROJECT_ID}} or {{BOARD_ID}} placeholders!
+# For 2-level structures: BOTH project AND board are REQUIRED per US
+project: {{RESOLVED_PROJECT}}
+board: {{RESOLVED_BOARD}}
 multi_project: true
 projects:
-  - id: {{PROJECT_FE_ID}}
+  - id: {{RESOLVED_PROJECT_FE}}
     prefix: FE
-  - id: {{PROJECT_BE_ID}}
+  - id: {{RESOLVED_PROJECT_BE}}
     prefix: BE
-  - id: {{PROJECT_SHARED_ID}}
+  - id: {{RESOLVED_PROJECT_SHARED}}
     prefix: SHARED
 ---
 
@@ -30,13 +31,25 @@ projects:
 
 ## User Stories
 
-<!-- Each US has its own **Project** and **Board** fields. User can modify per-US anytime. -->
+<!--
+⚠️ MANDATORY RESOLUTION (v0.34.0+):
+1. Run: specweave context projects
+2. Parse JSON output:
+   - level 1: projects[].id gives valid project IDs
+   - level 2: projects[].id + boardsByProject[project][].id gives project AND board IDs
+3. Replace ALL placeholders with actual IDs from step 2
+4. Each US MUST have **Project**: (and **Board**: for 2-level) with RESOLVED values
+
+❌ FORBIDDEN: Using {{PROJECT_ID}}, {{BOARD_ID}} placeholders
+❌ FORBIDDEN: Inventing project/board names
+✅ REQUIRED: Use ONLY IDs from "specweave context projects" output
+-->
 
 ### Frontend Stories
 
 #### US-FE-001: [Story Title] (P1)
-**Project**: {{PROJECT_ID}}
-**Board**: {{BOARD_FE_ID}}
+**Project**: {{RESOLVED_PROJECT}}
+**Board**: {{RESOLVED_BOARD_FE}}
 
 **As a** [user type]
 **I want** [goal]
@@ -51,8 +64,8 @@ projects:
 ### Backend Stories
 
 #### US-BE-001: [Story Title] (P1)
-**Project**: {{PROJECT_ID}}
-**Board**: {{BOARD_BE_ID}}
+**Project**: {{RESOLVED_PROJECT}}
+**Board**: {{RESOLVED_BOARD_BE}}
 
 **As a** [system/frontend application]
 **I want** [API endpoint/service goal]
@@ -67,8 +80,8 @@ projects:
 ### Shared Library Stories
 
 #### US-SHARED-001: [Story Title] (P1)
-**Project**: {{PROJECT_ID}}
-**Board**: {{BOARD_SHARED_ID}}
+**Project**: {{RESOLVED_PROJECT}}
+**Board**: {{RESOLVED_BOARD_SHARED}}
 
 **As a** developer in FE or BE repos
 **I want** [shared types/utilities/validators]

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

@@ -8,8 +8,9 @@ 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}}
+# MANDATORY: Must be a RESOLVED value from "specweave context projects" output
+# ⛔ NEVER use {{PROJECT_ID}} placeholder - always resolve BEFORE creating spec.md!
+project: {{RESOLVED_PROJECT}}
 ---
 
 # Feature: {{FEATURE_TITLE}}
@@ -20,10 +21,20 @@ project: {{PROJECT_ID}}
 
 ## User Stories
 
-<!-- Each US can have its own **Project** field. If omitted, uses default_project from frontmatter -->
+<!--
+⚠️ MANDATORY RESOLUTION (v0.34.0+):
+1. Run: specweave context projects
+2. Parse JSON: projects[].id gives valid project IDs
+3. Replace {{RESOLVED_PROJECT}} with actual ID from step 2
+4. Each US MUST have **Project**: field with RESOLVED value
+
+❌ FORBIDDEN: Using {{PROJECT_ID}} placeholder
+❌ FORBIDDEN: Inventing project names
+✅ REQUIRED: Use ONLY IDs from "specweave context projects" output
+-->
 
 ### US-001: [Story Title] (P1)
-**Project**: {{PROJECT_ID}}
+**Project**: {{RESOLVED_PROJECT}}
 
 **As a** [user type]
 **I want** [goal]
@@ -34,7 +45,7 @@ project: {{PROJECT_ID}}
 - [ ] **AC-US1-02**: [Another criterion]
 
 ### US-002: [Story Title] (P2)
-**Project**: {{PROJECT_ID}}
+**Project**: {{RESOLVED_PROJECT}}
 
 [Repeat structure - change Project per US if spanning multiple projects]
 

package/plugins/specweave/skills/spec-generator/SKILL.md

@@ -85,34 +85,93 @@ The LLM MUST resolve these from context - see RULE 0 in increment-planner.
 
 ---
 
+### MANDATORY STEP 0: Get Project Context FIRST (v0.34.0+ BLOCKING!)
+
+**⛔ YOU CANNOT GENERATE spec.md UNTIL YOU COMPLETE THIS STEP!**
+
+**This step is BLOCKING - do not proceed until you have actual project/board IDs.**
+
+**1. Run the context API command:**
+```bash
+specweave context projects
+```
+
+**2. Parse the JSON output:**
+```json
+{
+  "level": 1,
+  "projects": [{"id": "frontend-app", "name": "Frontend App"}],
+  "detectionReason": "multiProject configuration"
+}
+```
+For 2-level:
+```json
+{
+  "level": 2,
+  "projects": [{"id": "acme-corp", "name": "ACME Corp"}],
+  "boardsByProject": {
+    "acme-corp": [
+      {"id": "digital-ops", "name": "Digital Operations"},
+      {"id": "mobile-team", "name": "Mobile Team"}
+    ]
+  }
+}
+```
+
+**3. STORE the actual IDs for use in spec.md:**
+```
+RESOLVED_PROJECT = "frontend-app"  // from projects[].id
+RESOLVED_BOARD = "digital-ops"     // from boardsByProject (2-level only)
+```
+
+**4. Now generate spec.md using RESOLVED values (NEVER placeholders!)**
+
+---
+
 ### Per-US Project Resolution (v0.33.0+ MANDATORY)
 
-**🧠 USE ALL AVAILABLE CONTEXT TO RESOLVE PROJECT/BOARD:**
+**🧠 USE CONTEXT API OUTPUT + LIVING DOCS TO RESOLVE PROJECT/BOARD:**
 
-Before generating spec.md, analyze:
-1. **Living docs folders**: `ls .specweave/docs/internal/specs/` → actual project IDs
-2. **Recent increment patterns**: `grep "**Project**:" .specweave/increments/*/spec.md`
-3. **Config projectMappings**: Exact project IDs from config
-4. **Feature keywords**: Map to actual projects (not generic terms)
+After running `specweave context projects`, you have the valid project/board IDs.
+Now map each user story to the correct project:
+
+**Resolution Flow:**
+```
+1. Get valid projects from context API: ["frontend-app", "backend-api", "shared"]
+2. Analyze feature description for keywords
+3. Map keywords to ACTUAL project IDs (from step 1, NOT generic terms!)
+4. Assign each US to its project
+```
 
 **Resolution Example:**
 ```
+Context API returned: projects = ["frontend-app", "backend-api", "shared"]
+
 Feature: "Add OAuth login to React frontend"
-Detected: "React", "frontend", "login"
+Detected keywords: "React", "frontend", "login"
 
-Step 1: Check living docs → folders: frontend-app/, backend-api/, shared/
-Step 2: "frontend" keyword → matches "frontend-app" folder
-Step 3: Assign **Project**: frontend-app (NOT "frontend"!)
+Mapping:
+- "frontend" keyword → matches "frontend-app" (from context API)
+- "login" spans frontend + backend
 
-If cross-cutting ("OAuth" = both frontend + backend):
+Result:
   US-001 (Login UI) → **Project**: frontend-app
   US-002 (Auth API) → **Project**: backend-api
 ```
 
-**NEVER:**
-- ❌ Use generic keywords as project names ("frontend", "backend")
-- ❌ Ask user when context provides the answer
-- ❌ Leave `{{PROJECT_ID}}` placeholders
+**VALIDATION RULES:**
+
+```
+✅ REQUIRED: Run "specweave context projects" BEFORE generating spec.md
+✅ REQUIRED: Use ONLY project IDs from the API response
+✅ REQUIRED: Each US has explicit **Project**: field with resolved value
+✅ REQUIRED: For 2-level, each US has explicit **Board**: field with resolved value
+
+❌ FORBIDDEN: Generating spec.md without running context API first
+❌ FORBIDDEN: Using {{PROJECT_ID}} or {{BOARD_ID}} placeholders
+❌ FORBIDDEN: Using generic keywords as project names ("frontend" vs "frontend-app")
+❌ FORBIDDEN: Inventing project names not in the API response
+```
 
 ## Success Metrics
 [How we'll measure success]

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

@@ -52,7 +52,7 @@ if [ ! -d ".specweave/cache/docs-site/node_modules" ]; then
 fi
 ```
 
-If not set up, follow the same setup steps as `/specweave-docs:preview` (Step 3 in preview.md).
+If not set up, follow the same setup steps as `/specweave-docs:view` (Step 3 in view.md).
 
 ### Step 3: Run Build
 
@@ -131,8 +131,8 @@ git commit -m "docs: update documentation site"
 
 ### Build fails with broken links
 ```bash
-# Preview first to find errors
-/specweave-docs:preview
+# View docs first to find errors
+/specweave-docs:view
 # Fix broken links, then build
 /specweave-docs:build
 ```
@@ -155,6 +155,6 @@ rm -rf .specweave/cache/docs-site
 
 ## See Also
 
-- `/specweave-docs:preview` - Preview docs locally with hot reload
+- `/specweave-docs:view` - View docs locally with hot reload
 - `/specweave-docs:organize` - Organize large folders with themed indexes
 - `/specweave-docs:health` - Documentation health report

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

@@ -408,7 +408,7 @@ cat ./docs/api/index.md ./docs/specs/index.md > ./docs/complete-reference.md
 ## Related Commands
 
 - `/specweave-docs:init` - Initialize Docusaurus documentation site
-- `/specweave-docs:preview` - Preview generated documentation
+- `/specweave-docs:view` - View generated documentation
 - `/specweave-docs:build` - Build static site from generated docs
 
 ## Requirements

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

@@ -264,5 +264,5 @@ jobs:
 ## See Also
 
 - `/specweave-docs:organize` - Organize large folders with themed indexes
-- `/specweave-docs:preview` - Preview documentation with Docusaurus
+- `/specweave-docs:view` - View documentation with Docusaurus
 - `/specweave-docs:generate` - Generate docs from code

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

@@ -309,7 +309,7 @@ themeConfig: {
 ## Related Commands
 
 - `/specweave-docs:generate` - Generate docs from code/specs
-- `/specweave-docs:preview` - Launch documentation preview server
+- `/specweave-docs:view` - Launch documentation server
 - `/specweave-docs:build` - Build static documentation site
 
 ## Requirements

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

@@ -161,7 +161,7 @@ Generated 9 index files:
 After running this command, use:
 
 ```bash
-/specweave-docs:preview
+/specweave-docs:view
 ```
 
 The generated indexes will appear in the sidebar:
@@ -179,6 +179,6 @@ The generated indexes will appear in the sidebar:
 
 ## See Also
 
-- `/specweave-docs:preview` - Preview documentation with Docusaurus
+- `/specweave-docs:view` - View documentation with Docusaurus
 - `/specweave-docs:build` - Build static documentation site
 - `/specweave-docs:health` - Documentation health report

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

@@ -245,6 +245,6 @@ onBrokenMarkdownLinks: 'warn',
 
 ## See Also
 
-- `/specweave-docs:preview` - Preview docs (runs validation first)
+- `/specweave-docs:view` - View docs (runs validation first)
 - `/specweave-docs:build` - Build docs (runs validation first)
 - `/specweave-docs:health` - Full documentation health report