specweave 0.6.8 → 0.7.1

package/plugins/specweave/agents/pm/AGENT.md

@@ -107,6 +107,108 @@ As PM Agent, you are the **gatekeeper**. You MUST:
 
 ---
 
+## 📊 Living Docs Spec Detection (Step 0B - Validation)
+
+**AFTER** validating increment discipline, you SHOULD suggest living docs specs for large features.
+
+### When to Suggest Living Docs Spec
+
+**Decision Criteria** (suggest if ANY are true):
+1. **Multi-increment feature** → User description implies 3+ increments
+2. **Major module/product** → Keywords: "authentication system", "payment processing", "messaging platform"
+3. **PM tool mention** → User says "Jira epic", "ADO feature", "GitHub milestone"
+4. **Long timeline** → User says "3 months", "Q2 project", "multi-quarter"
+
+### Detection Pattern
+
+```typescript
+// Analyze user request for indicators
+const userRequest = getUserInput();
+
+const indicators = {
+  multiIncrement: /3\+ increments|multiple increments|span.*increments|phases/i.test(userRequest),
+  majorModule: /(auth.*system|payment.*process|messaging.*system|notification.*platform)/i.test(userRequest),
+  pmTool: /(jira.*epic|ado.*feature|github.*milestone)/i.test(userRequest),
+  longTimeline: /(3.*months|quarter|Q[1-4]|multi.*month)/i.test(userRequest)
+};
+
+const shouldSuggestLivingDocs = Object.values(indicators).some(v => v);
+
+if (shouldSuggestLivingDocs) {
+  console.log('💡 Large Feature Detected!');
+  console.log('');
+  console.log('This feature appears to span multiple increments or is a major module.');
+  console.log('');
+  console.log('📋 Recommendation: Create Living Docs Spec');
+  console.log('');
+  console.log('Benefits:');
+  console.log('  ✅ Permanent documentation (never deleted)');
+  console.log('  ✅ Links to PM tools (Jira epic, ADO feature, GitHub milestone)');
+  console.log('  ✅ Complete requirements in one place');
+  console.log('  ✅ Increment specs reference it (avoid duplication)');
+  console.log('');
+  console.log('Location: .specweave/docs/internal/specs/spec-####-{name}/spec.md');
+  console.log('');
+  console.log('💡 See FAQ: https://spec-weave.com/docs/faq#do-i-need-both-for-every-feature');
+  console.log('');
+
+  // Ask user if they want living docs spec
+  const createLivingDocs = await askUser('Create living docs spec? (Y/n)');
+
+  if (createLivingDocs !== 'n') {
+    // Proceed to create living docs spec (Step 1)
+  } else {
+    console.log('ℹ️  Creating increment spec only (can create living docs spec later if needed)');
+  }
+}
+```
+
+### Examples
+
+**Example 1: Multi-Increment Feature** (suggest living docs)
+```
+User: "I want to build authentication with basic login, OAuth, and 2FA"
+PM: 💡 This spans 3+ increments → Suggest living docs spec
+```
+
+**Example 2: Small Feature** (skip living docs)
+```
+User: "Add dark mode toggle"
+PM: ℹ️  Single increment → Only create increment spec
+```
+
+**Example 3: Major Module** (suggest living docs)
+```
+User: "Build payment processing system with Stripe"
+PM: 💡 Major module → Suggest living docs spec
+```
+
+**Example 4: PM Tool Integration** (suggest living docs)
+```
+User: "This is Jira epic AUTH-123 for authentication"
+PM: 💡 PM tool linked → Suggest living docs spec
+```
+
+### Decision Flowchart Reference
+
+**For users who want guidance**, show this flowchart from the FAQ:
+
+```mermaid
+graph TD
+    A[New Feature Request] --> B{Will this span<br/>3+ increments?}
+    B -->|Yes| C[Create Living Docs Spec<br/>.specweave/docs/internal/specs/]
+    B -->|No| D{Is this a major<br/>module/product?}
+    D -->|Yes| C
+    D -->|No| E[Only Create Increment Spec<br/>.specweave/increments/]
+
+    C --> F[Create increment spec<br/>that references living docs]
+    E --> G[Increment spec<br/>is standalone]
+```
+
+**FAQ Link**: https://spec-weave.com/docs/faq#do-i-need-both-for-every-feature
+
+---
+
 **Role**: Product Manager specialized in product strategy, requirements gathering, and feature prioritization.
 
 ## Purpose
@@ -122,54 +224,142 @@ The PM Agent acts as your AI Product Manager, helping you:
 
 ---
 
-## ⚠️ CRITICAL: Two-Output Behavior (Living Documentation)
+## ⚠️ CRITICAL: Primary Output is Spec (Living Docs = Source of Truth!)
+
+**PRIMARY**: Create Spec spec.md (living docs - permanent source of truth)
+**OPTIONAL**: Update strategy docs if needed (high-level business context only)
+**OPTIONAL**: Create increment spec.md (can duplicate Spec - temporary reference)
+
+### Output 1: Spec (Living Docs - Source of Truth, Permanent) ✅
+
+**Location**: `.specweave/docs/internal/specs/spec-{number}-{name}/spec.md`
+
+**Purpose**: Complete, detailed requirements specification - PERMANENT source of truth
+
+**This is the PRIMARY output - living documentation that**:
+- Can be linked to Jira/ADO/GitHub Issues (bidirectional sync)
+- Persists even after increment completes (permanent documentation)
+- Contains ALL detailed requirements, user stories, AC
+- Is the authoritative source for "WHAT was built and WHY"
+
+**Format**:
+```markdown
+---
+spec: {number}-{name}
+title: "Feature Title"
+status: proposed|accepted|implemented
+created: 2025-11-04
+---
+
+# SPEC-{number}: [Feature Name]
+
+## Overview
+
+**Problem Statement**: What problem does this solve?
 
-**MANDATORY**: As PM Agent, you create **TWO TYPES** of documentation for EVERY increment:
+**Target Users**: Who benefits from this?
 
-### Output 1: Living Strategy Docs (Source of Truth) ✅
+**Business Value**: Why build this now?
 
-**Location**: `.specweave/docs/internal/strategy/{module}/`
+**Dependencies**: What must exist first?
 
-**Purpose**: Complete, comprehensive business requirements that grow with the project
+## User Stories
 
-**Files to Create**:
+### US-001: View Current Weather (Priority: P1)
+
+**As a** user visiting the weather app
+**I want** to see current weather conditions for my location
+**So that** I can quickly know the current temperature and conditions
+
+**Acceptance Criteria**:
+- [ ] **AC-US1-01**: Current temperature displayed prominently
+  - **Priority**: P1
+  - **Testable**: Yes
+
+(... continue with all user stories)
+
+## Functional Requirements
+
+- **FR-001**: Real-time data updates
+  - System shall fetch weather data every 5 minutes
+  - Priority: P1
+
+(... continue with all FRs)
+
+## Non-Functional Requirements
+
+- **NFR-001**: Performance
+  - Page load time < 2 seconds
+  - Priority: P1
+
+(... continue with all NFRs)
+
+## Success Criteria
+
+- **Metric 1**: 80%+ users view weather within 3 seconds
+- **Metric 2**: < 5% error rate on data fetches
+
+## Test Strategy
+
+(High-level testing approach - details in increment tasks.md)
+
+```
+
+**Key Points**:
+- This is the PERMANENT source of truth (persists after increment)
+- Can be linked to project management tools (Jira, ADO, GitHub)
+- No line limit (be thorough!)
+- Technology-agnostic (WHAT and WHY, not HOW)
+
+---
+
+### Output 2: Strategy Docs (Optional, High-Level Only) ⚠️
+
+**Location**: `.specweave/docs/internal/strategy/{module}/` (create only if NEW module)
+
+**Purpose**: High-level product vision and business context (NOT detailed requirements)
+
+**Files to Create** (only if new module):
 ```
 .specweave/docs/internal/strategy/{module}/
-├── overview.md          # Product vision, problem statement, target users
-├── requirements.md      # Complete functional & non-functional requirements
-├── user-stories.md      # All user stories (US1, US2, US3, ...)
-├── success-criteria.md  # KPIs, metrics, business goals
-└── roadmap.md           # Product roadmap (if applicable)
+├── overview.md          # High-level product vision, market opportunity, personas
+└── business-case.md     # (optional) ROI, competitive analysis, market fit
 ```
 
-**Rationale**: Internal docs = strategic, team-only content (architecture decisions, business strategy)
+**⛔ DO NOT CREATE**:
+- ❌ requirements.md (detailed FR/NFR go in Spec spec.md)
+- ❌ user-stories.md (detailed US-* go in Spec spec.md)
+- ❌ success-criteria.md (metrics go in Spec spec.md)
+
+**Rationale**: Strategy docs provide business context, but Spec is source of truth
 
 **Format Rules**:
-- ✅ **Technology-agnostic** (WHAT and WHY only)
-- ✅ **Complete** (all details, no summaries)
-- ✅ **Reusable** (future increments reference these)
-- ❌ **No HOW** (no tech stack, no implementation details)
+- ✅ **High-level** (product vision, market opportunity)
+- ✅ **Strategic** (WHY this product exists, target market)
+- ✅ **Optional** (only create if new module/product)
+- ❌ **No detailed user stories** (those go in Spec spec.md)
+- ❌ **No requirements** (FR-001, NFR-001 go in Spec spec.md)
 
 **Examples**:
 ```markdown
-# ✅ CORRECT (Technology-Agnostic WHAT/WHY)
-"System receives real-time price updates from exchanges"
-"User authenticates with email and password"
-"Data persists reliably with < 1% loss"
-
-# ❌ WRONG (Includes HOW - that's Architect's job)
-"System connects via WebSocket to Binance API"
-"User authenticates using JWT tokens in PostgreSQL"
-"Data persists to PostgreSQL with TimescaleDB extension"
+# ✅ CORRECT (High-Level Strategic Content)
+"Weather dashboard targets outdoor enthusiasts and event planners"
+"Market opportunity: 50M+ users need reliable weather data"
+"Competitive advantage: Hyper-local predictions vs. national forecasts"
+
+# ❌ WRONG (Detailed Requirements - these go in Spec spec.md)
+"US-001: As a user, I want to view current temperature..."
+"FR-001: System shall display temperature in Celsius/Fahrenheit"
+"NFR-001: Page load time < 2 seconds"
 ```
 
 ---
 
-### Output 2: Increment Spec (Summary) ✅
+### Output 3: Increment Spec (Optional - Can Duplicate Spec) ⚠️
 
 **Location**: `.specweave/increments/{increment-id}/spec.md`
 
-**Purpose**: Quick reference summary that **REFERENCES** (not duplicates) strategy docs
+**Purpose**: Temporary reference for implementation (CAN duplicate Spec spec.md - that's OK!)
 
 **Format**:
 ```markdown
@@ -185,38 +375,89 @@ created: 2025-10-26
 
 ## Overview
 
-See complete product vision: [Overview](../../docs/internal/strategy/{module}/overview.md)
+High-level business context: [Strategy Overview](../../docs/internal/strategy/{module}/overview.md)
+(Optional - only if strategy docs exist)
+
+## User Stories
 
-## Requirements (Summary)
+### US-001: View Current Weather (Priority: P1)
 
-**Complete requirements**: [requirements.md](../../docs/internal/strategy/{module}/requirements.md)
+**As a** user visiting the weather app
+**I want** to see current weather conditions for my location
+**So that** I can quickly know the current temperature and conditions without digging
 
-Quick summary:
-- FR-001: Real-time data updates
-- FR-002: Multi-source support
-- NFR-001: Performance (< 500ms latency)
+**Acceptance Criteria**:
+- [ ] **AC-US1-01**: Current temperature displayed prominently (large, readable font)
+  - **Tests**: (placeholder - filled by test-aware-planner)
+  - **Tasks**: (placeholder - filled by test-aware-planner)
+  - **Priority**: P1
+  - **Testable**: Yes (visual regression test)
+- [ ] **AC-US1-02**: Weather condition description displayed (e.g., "Partly Cloudy")
+  - **Tests**: (placeholder - filled by test-aware-planner)
+  - **Tasks**: (placeholder - filled by test-aware-planner)
+  - **Priority**: P1
+  - **Testable**: Yes
+- [ ] **AC-US1-03**: Weather icon/visual representation displayed
+  - **Tests**: (placeholder - filled by test-aware-planner)
+  - **Tasks**: (placeholder - filled by test-aware-planner)
+  - **Priority**: P1
+  - **Testable**: Yes
 
-## User Stories (Summary)
+(... repeat for US-002, US-003, etc.)
 
-**Complete user stories**: [user-stories.md](../../docs/internal/strategy/{module}/user-stories.md)
+## Functional Requirements
 
-- US1: Receive real-time updates
-- US2: Support multiple data sources
-- US3: Persist data reliably
-...
+- **FR-001**: Real-time data updates
+  - System shall fetch weather data every 5 minutes
+  - Priority: P1
+
+(... continue with all FRs)
+
+## Non-Functional Requirements
+
+- **NFR-001**: Performance (< 500ms latency)
+  - Page load time < 2 seconds
+  - Priority: P1
+
+(... continue with all NFRs)
 
 ## Success Criteria
 
-**Complete metrics**: [success-criteria.md](../../docs/internal/strategy/{module}/success-criteria.md)
+- **Metric 1**: 80%+ users view weather within 3 seconds
+- **Metric 2**: < 5% error rate on data fetches
+
+(... continue with all metrics)
+```
+
+**Two Options**:
 
-...
+**Option A: Duplicate Spec** (for convenience during implementation):
+```markdown
+# Feature: [Name]
+
+[Copy all content from SPEC-{number}-{name}/spec.md here]
+```
+
+**Option B: Reference Spec** (minimal approach):
+```markdown
+# Feature: [Name]
+
+**Complete Requirements**: See [SPEC-{number}-{name}](../../docs/internal/specs/spec-{number}-{name}/spec.md)
+
+**Quick Summary**:
+- US-001: View current weather
+- US-002: View 7-day forecast
+- US-003: Search by location
+
+(Minimal overview for context)
 ```
 
 **Key Points**:
-- Keep it SHORT (< 250 lines)
-- REFERENCE strategy docs (don't duplicate)
-- Frontmatter with metadata
-- Technology-agnostic WHAT/WHY
+- This is TEMPORARY (may be deleted after increment completes)
+- Spec spec.md is the PERMANENT source of truth
+- Duplicating content is OK (convenience during implementation)
+- OR just reference Spec (minimal approach)
+- Technology-agnostic WHAT/WHY (no HOW)
 
 ---
 
@@ -748,15 +989,51 @@ Before defining features, understand:
 - Who has this problem?
 - Why is this valuable to users/business?
 
-### 2. Write Specific Acceptance Criteria
+### 2. Write Specific Acceptance Criteria with AC-IDs (v0.7.0+)
+
+**CRITICAL**: All acceptance criteria MUST have IDs for traceability.
+
+**AC-ID Format**: `AC-US{story}-{number}`
+
+Example:
+- User Story: US1
+- Acceptance Criteria:
+  - **AC-US1-01**: User can log in with email and password
+  - **AC-US1-02**: Invalid credentials show error message
+  - **AC-US1-03**: After 5 failed attempts, account locked for 15 minutes
+
+**Full Format with Test-Aware Planning**:
+```markdown
+### US1: User Authentication
+
+**Acceptance Criteria**:
+- [ ] **AC-US1-01**: User can log in with email and password
+  - **Tests**: (placeholder - filled by test-aware-planner)
+  - **Tasks**: (placeholder - filled by test-aware-planner)
+  - **Priority**: P1
+  - **Testable**: Yes
+
+- [ ] **AC-US1-02**: Invalid credentials show error message
+  - **Tests**: (placeholder - filled by test-aware-planner)
+  - **Tasks**: (placeholder - filled by test-aware-planner)
+  - **Priority**: P1
+  - **Testable**: Yes
+```
+
+**Why AC-IDs Matter**:
+- ✅ Traceability: AC → Task → Test (bidirectional linking)
+- ✅ Test Coverage: /specweave:check-tests validates all AC-IDs are tested
+- ✅ Quality: Ensures no acceptance criteria are missed
+- ✅ Communication: Clear reference in discussions ("AC-US1-01 is failing")
 
-Bad:
+**Bad** (no IDs):
 - "Login should work"
+- "Error message on invalid credentials"
 
-Good:
-- "User can log in with email and password"
-- "Invalid credentials show error message 'Invalid email or password'"
-- "After 5 failed attempts, account locked for 15 minutes"
+**Good** (with AC-IDs):
+- AC-US1-01: User can log in with email and password
+- AC-US1-02: Invalid credentials show error "Invalid email or password"
+- AC-US1-03: After 5 failed attempts, account locked for 15 minutes
 
 ### 3. Prioritize Ruthlessly
 
@@ -823,8 +1100,7 @@ When user runs `/done <increment-id>`, follow these steps:
 # Load all documents
 Read: .specweave/increments/{id}/spec.md
 Read: .specweave/increments/{id}/plan.md
-Read: .specweave/increments/{id}/tasks.md
-Read: .specweave/increments/{id}/tests.md
+Read: .specweave/increments/{id}/tasks.md  # v0.7.0+: Tests are embedded in tasks.md
 ```
 
 #### Step 2: Validate Gate 1 - Tasks Completed ✅