specweave 0.34.20 → 0.34.22

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

@@ -49,6 +49,54 @@ Automates creation of increment structure for ANY type of work:
 
 ## Critical Rules
 
+### 0. **Project**: Field is MANDATORY (v0.35.0+ - HIGHEST PRIORITY!)
+
+**⛔ EVERY User Story MUST have `**Project**:` field - NO EXCEPTIONS!**
+
+This applies to BOTH single-project AND multi-project modes:
+- **Single-project**: Use `config.project.name` value (e.g., `**Project**: my-app`)
+- **Multi-project**: Use one of `multiProject.projects` keys (e.g., `**Project**: frontend-app`)
+
+**HOW TO GET THE PROJECT VALUE:**
+1. Run `specweave context projects`
+2. Use project ID from output
+
+**Single-project output:**
+```json
+{ "level": 1, "projects": [{"id": "my-app"}] }
+→ Use: **Project**: my-app
+```
+
+**Multi-project output:**
+```json
+{ "level": 1, "projects": [{"id": "frontend"}, {"id": "backend"}] }
+→ Pick appropriate project per US
+```
+
+**2-level output (ADO/JIRA):**
+```json
+{ "level": 2, "projects": [...], "boardsByProject": {"corp": [{"id": "digital-ops"}]} }
+→ ALSO add: **Board**: digital-ops
+```
+
+**EXAMPLE (v0.35.0+):**
+```markdown
+### US-001: Show Last 2 Git Commits
+**Project**: aac              # ← MANDATORY! Value from config
+**As a** developer, I want to see the last 2 git commits...
+```
+
+**⛔ NEVER GENERATE:**
+```markdown
+### US-001: Feature Name
+**As a** user, I want...      # ← MISSING **Project**: = INVALID!
+```
+
+**EDGE CASES:**
+- **Empty config.project.name**: Run `specweave init` to configure
+- **Empty multiProject.projects**: Invalid config - ask user to configure projects
+- **Project name with special chars**: Only `a-z`, `0-9`, `-` allowed
+
 ### 1. Increment Naming (MANDATORY)
 
 **Format**: `####-descriptive-kebab-case-name`
@@ -182,8 +230,22 @@ echo "Using coverageTarget: $coverageTarget"
 
 **🚨 FAILURE TO COMPLETE THIS STEP = spec.md WILL BE BLOCKED BY VALIDATION HOOK!**
 
+**🧠 ULTRATHINK REQUIRED - ANALYZE ALL AVAILABLE CONTEXT FIRST!**
+
 Before generating ANY spec.md content, you MUST:
 
+**0. ULTRATHINK - Gather context BEFORE running API:**
+```bash
+# 1. Check existing project folders in living docs
+ls .specweave/docs/internal/specs/
+
+# 2. Check how recent increments assigned projects
+grep -r "^\*\*Project\*\*:" .specweave/increments/*/spec.md | tail -10
+
+# 3. Read config.json for project.name or multiProject.projects
+cat .specweave/config.json | jq '.project.name, .multiProject'
+```
+
 **1. RUN THE CONTEXT API (via Bash tool):**
 ```bash
 specweave context projects
@@ -214,7 +276,37 @@ For 2-level structures (ADO/JIRA boards):
 }
 ```
 
-**3. RESOLVE PROJECT/BOARD FOR EACH USER STORY:**
+**3. 🧠 ULTRATHINK - SMART PROJECT RESOLUTION (v0.35.0+ CRITICAL!):**
+
+**RESOLUTION PRIORITY (MUST FOLLOW THIS ORDER!):**
+```
+1. ✅ EXACT MATCH: config.project.name or multiProject.projects key → USE IT
+2. ✅ LIVING DOCS: Existing folder in specs/ → USE THAT PROJECT ID
+3. ✅ RECENT PATTERNS: Same feature type in past increments → USE SAME PROJECT
+4. ⚠️  UNCERTAIN: Multiple valid options OR no clear match → ASK USER!
+5. 🔄 FALLBACK: If all else fails → USE "default" (NEVER "specweave"!)
+```
+
+**⚠️ CRITICAL: IF UNCERTAIN - YOU MUST ASK THE USER!**
+```
+I found multiple potential projects for this feature:
+- frontend-app (keywords: UI, form, React)
+- backend-api (keywords: API, endpoint)
+
+Which project should I assign to this feature?
+```
+
+**❌ NEVER DO THIS:**
+- Silently assign to "specweave" (that's the framework name, not user's project!)
+- Guess without analyzing context
+- Skip asking when genuinely uncertain
+
+**✅ CORRECT FALLBACK (when no projects configured):**
+```
+**Project**: default
+```
+
+**4. RESOLVE PROJECT/BOARD FOR EACH USER STORY:**
 
 ```
 CONTEXT_OUTPUT = <output from specweave context projects>
@@ -228,7 +320,7 @@ For each US you will generate:
     US.board = select from CONTEXT_OUTPUT.boardsByProject[project][].id
 ```
 
-**4. NOW PROCEED TO STEP 1 (with resolved values stored)**
+**5. NOW PROCEED TO STEP 1 (with resolved values stored)**
 
 ---
 
@@ -240,13 +332,16 @@ For each US you will generate:
 ✅ REQUIRED: project field MUST match one of projects[].id from output
 ✅ REQUIRED: board field (2-level) MUST match one of boardsByProject[project][].id
 ✅ REQUIRED: Each US has **Project**: and **Board**: (2-level) with RESOLVED values
+✅ REQUIRED: ASK USER when uncertain (multiple valid options or no clear match)
 
 ❌ FORBIDDEN: Skipping this step and generating spec.md directly
 ❌ FORBIDDEN: Inventing project names not in the API output
+❌ FORBIDDEN: Using "specweave" as project name (it's the framework, not user's project!)
 ❌ FORBIDDEN: Using folder names as project (e.g., "my-project-folder")
 ❌ FORBIDDEN: Using {{PROJECT_ID}} or {{BOARD_ID}} placeholders
 ❌ FORBIDDEN: Creating spec.md for 2-level without board: field
 ❌ FORBIDDEN: Generating spec.md without running context API first
+❌ FORBIDDEN: Silently guessing project without analyzing context
 ```
 
 **WHY THIS IS BLOCKING:**

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

@@ -27,7 +27,7 @@ description: Generates comprehensive specifications (spec.md, plan.md, tasks.md
 - **Bug Fix**: Problem statement, root cause, solution, impact analysis
 - **Refactoring**: Current state, proposed changes, benefits, migration plan
 
-**YAML Frontmatter** (v0.31.0+ MANDATORY):
+**YAML Frontmatter** (v0.35.0+ simplified):
 ```yaml
 ---
 increment: 0001-feature-name
@@ -36,14 +36,14 @@ type: feature
 priority: P1
 status: planned
 created: 2025-12-04
-project: my-project          # REQUIRED - target project for living docs sync
-board: my-board              # REQUIRED for 2-level structures (ADO area paths, JIRA boards)
+# NOTE: project: and board: fields REMOVED from frontmatter!
+# Use per-US **Project**: and **Board**: fields instead (see below)
 ---
 ```
 
-**Detect Structure Level First** (see `src/utils/structure-level-detector.ts`):
-- 1-level: `project:` field REQUIRED
-- 2-level: `project:` AND `board:` fields REQUIRED
+**⛔ CRITICAL RULE: Every User Story MUST have `**Project**:` field!**
+
+This is MANDATORY in BOTH single-project AND multi-project modes.
 
 **Core Sections** (Always Present):
 ```markdown
@@ -66,14 +66,15 @@ board: my-board              # REQUIRED for 2-level structures (ADO area paths,
 ## User Stories & Acceptance Criteria
 
 <!--
-⚠️ PER-US PROJECT TARGETING (v0.33.0+):
-Each user story MUST have **Project**: (and **Board**: for 2-level) fields.
-The LLM MUST resolve these from context - see RULE 0 in increment-planner.
+⛔ MANDATORY: **Project**: field on EVERY User Story (v0.35.0+)
+- Single-project: Use config.project.name value
+- Multi-project: Use one of multiProject.projects keys
+NEVER generate a User Story without **Project**: field!
 -->
 
 ### US-001: [Title]
-**Project**: [resolved-from-context]    <!-- REQUIRED - actual project ID from config/folders -->
-**Board**: [resolved-from-context]      <!-- REQUIRED for 2-level structures -->
+**Project**: [MANDATORY - use config.project.name or multiProject.projects key]
+**Board**: [MANDATORY for 2-level structures only]
 
 **As a** [user type]
 **I want** [goal]
@@ -91,6 +92,14 @@ The LLM MUST resolve these from context - see RULE 0 in increment-planner.
 
 **This step is BLOCKING - do not proceed until you have actual project/board IDs.**
 
+**🧠 ULTRATHINK REQUIRED - ANALYZE ALL AVAILABLE CONTEXT FIRST!**
+
+Before assigning ANY project, you MUST analyze:
+1. **Living docs structure**: `ls .specweave/docs/internal/specs/` - what project folders exist?
+2. **Recent increments**: `grep -r "^\*\*Project\*\*:" .specweave/increments/*/spec.md | tail -10`
+3. **config.json**: Read `project.name` (single-project) or `multiProject.projects` (multi-project)
+4. **Feature description**: What does the user want to build? Match to existing projects.
+
 **1. Run the context API command:**
 ```bash
 specweave context projects
@@ -118,13 +127,43 @@ For 2-level:
 }
 ```
 
-**3. STORE the actual IDs for use in spec.md:**
+**3. 🧠 ULTRATHINK - SMART PROJECT RESOLUTION (v0.35.0+ CRITICAL!):**
+
+**RESOLUTION PRIORITY (MUST FOLLOW THIS ORDER!):**
+```
+1. ✅ EXACT MATCH: config.project.name or multiProject.projects key → USE IT
+2. ✅ LIVING DOCS: Existing folder in specs/ → USE THAT PROJECT ID
+3. ✅ RECENT PATTERNS: Same feature type in past increments → USE SAME PROJECT
+4. ⚠️  UNCERTAIN: Multiple valid options OR no clear match → ASK USER!
+5. 🔄 FALLBACK: If all else fails → USE "default" (NEVER "specweave"!)
+```
+
+**⚠️ CRITICAL: IF UNCERTAIN - YOU MUST ASK THE USER!**
+```
+I found multiple potential projects for this feature:
+- frontend-app (keywords: UI, form, React)
+- backend-api (keywords: API, endpoint)
+
+Which project should I assign to this feature?
+```
+
+**❌ NEVER DO THIS:**
+- Silently assign to "specweave" (that's the framework name, not user's project!)
+- Guess without analyzing context
+- Skip asking when genuinely uncertain
+
+**✅ CORRECT FALLBACK (when no projects configured):**
+```
+**Project**: default
+```
+
+**4. 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!)**
+**5. Now generate spec.md using RESOLVED values (NEVER placeholders!)**
 
 ---
 
@@ -522,63 +561,31 @@ spec_generator:
 - Living docs auto-grouped by project
 - External tools (GitHub/JIRA/ADO) receive issues in correct project
 
-### Legacy Project-Scoped User Story Format (Pre-v0.33.0)
+### Multi-Project User Story Format (with **Project**: per US)
 
-**❌ LEGACY (Project prefixes - still works but per-US targeting preferred):**
+**✅ CORRECT Format - Every US has `**Project**:`:**
 ```markdown
 ## User Stories
 
 ### US-001: Thumbnail Upload
-As a content creator, I want to upload thumbnails...
-
-### US-002: CTR Prediction API
-As a system, I want to predict click-through rates...
-```
-
-**✅ LEGACY (Multi-Project Format with prefixes - use per-US targeting instead):**
-```markdown
-## User Stories by Project
-
-### Frontend (sw-thumbnail-ab-fe)
-
-#### US-FE-001: Thumbnail Upload & Comparison (P1)
-**Related Repo**: sw-thumbnail-ab-fe
+**Project**: frontend-app       # ← MANDATORY!
 **As a** content creator
-**I want** to upload multiple thumbnail variants and compare them side-by-side
-**So that** I can visually evaluate my options before testing
+**I want** to upload thumbnails
+**So that** I can test different versions
 
 **Acceptance Criteria**:
-- [ ] **AC-FE-US1-01**: User can drag-and-drop up to 5 thumbnail images (JPG, PNG, WebP)
-- [ ] **AC-FE-US1-02**: Images are validated for YouTube specs (1280x720 min, <2MB)
-- [ ] **AC-FE-US1-03**: Side-by-side comparison view displays all variants
-
----
-
-### Backend (sw-thumbnail-ab-be)
+- [ ] **AC-US1-01**: User can drag-and-drop images
+- [ ] **AC-US1-02**: Images validated for YouTube specs
 
-#### US-BE-001: Thumbnail Analysis API (P1)
-**Related Repo**: sw-thumbnail-ab-be
+### US-002: Thumbnail Analysis API
+**Project**: backend-api        # ← MANDATORY! Different project = different folder
 **As a** frontend application
 **I want** to call POST /predict-ctr endpoint
-**So that** I can get AI-powered click-through rate predictions
-
-**Acceptance Criteria**:
-- [ ] **AC-BE-US1-01**: POST /predict-ctr endpoint accepts thumbnail image
-- [ ] **AC-BE-US1-02**: ML model analyzes: face detection, text readability, color psychology
-
----
-
-### Shared Library (sw-thumbnail-ab-shared)
-
-#### US-SHARED-001: Common Types & Validators (P1)
-**Related Repo**: sw-thumbnail-ab-shared
-**As a** developer in FE or BE repos
-**I want** shared TypeScript types and validators
-**So that** API contracts are consistent across projects
+**So that** I can get AI-powered predictions
 
 **Acceptance Criteria**:
-- [ ] **AC-SHARED-US1-01**: ThumbnailMetadata type exported
-- [ ] **AC-SHARED-US1-02**: Validation schemas for image specs
+- [ ] **AC-US2-01**: POST /predict-ctr endpoint accepts thumbnail image
+- [ ] **AC-US2-02**: ML model returns prediction score
 ```
 
 ### Project Classification Rules