specweave 0.3.7 → 0.3.9

package/src/skills/brownfield-onboarder/SKILL.md

@@ -92,15 +92,18 @@ When installing SpecWeave into an existing project:
 ```
 Project-specific content → SpecWeave folders:
 
-Domain knowledge        → specifications/modules/{domain}/
-Project conventions     → .specweave/docs/guides/project-conventions.md
-Team workflows          → .specweave/docs/guides/team-workflows.md
-Architecture details    → .specweave/docs/architecture/existing-system.md
-Business rules          → specifications/modules/business-rules/
-Technology stack        → .specweave/docs/architecture/tech-stack.md
-Deployment process      → .specweave/docs/guides/deployment.md
-API conventions         → .specweave/docs/guides/api-conventions.md
-Code style              → .specweave/docs/guides/code-style.md
+# Internal Documentation (strategic, team-only)
+Architecture details    → .specweave/docs/internal/architecture/existing-system.md
+Technology stack        → .specweave/docs/internal/architecture/tech-stack.md
+Business rules          → .specweave/docs/internal/strategy/business-rules.md
+Team workflows          → .specweave/docs/internal/processes/team-workflows.md
+Deployment process      → .specweave/docs/internal/processes/deployment.md
+Domain knowledge        → .specweave/increments/{####-name}/domain/{domain}.md
+
+# Public Documentation (user-facing, can be published)
+Project conventions     → .specweave/docs/public/guides/project-conventions.md
+API conventions         → .specweave/docs/public/guides/api-conventions.md
+Code style              → .specweave/docs/public/guides/code-style.md
 ```
 
 **Only add to CLAUDE.md**: High-level project summary (1-2 paragraphs max)
@@ -252,13 +255,13 @@ We use a microservices architecture:
 - Database (PostgreSQL) - shared across services
 ```
 
-**Destination**: `..specweave/docs/architecture/existing-system.md`
+**Destination**: `.specweave/docs/internal/architecture/existing-system.md`
 
 **CLAUDE.md addition**:
 ```markdown
 ## Project-Specific Architecture
 
-See [Existing System Architecture](.specweave/docs/architecture/existing-system.md) for complete microservices architecture.
+See [Existing System Architecture](.specweave/docs/internal/architecture/existing-system.md) for complete microservices architecture.
 ```
 
 ---
@@ -278,7 +281,7 @@ See [Existing System Architecture](.specweave/docs/architecture/existing-system.
 - React components: `{Name}Component.tsx` suffix
 ```
 
-**Destination**: `.specweave/docs/guides/project-conventions.md`
+**Destination**: `.specweave/docs/public/guides/project-conventions.md`
 
 **CLAUDE.md addition**: None (standard conventions, no need to clutter CLAUDE.md)
 
@@ -301,13 +304,13 @@ See [Existing System Architecture](.specweave/docs/architecture/existing-system.
 6. Rollback via GitHub Actions if needed
 ```
 
-**Destination**: `.specweave/docs/guides/deployment.md`
+**Destination**: `.specweave/docs/internal/processes/deployment.md`
 
 **CLAUDE.md addition**:
 ```markdown
 ## Deployment
 
-See [Deployment Guide](.specweave/docs/guides/deployment.md).
+See [Deployment Guide](.specweave/docs/internal/processes/deployment.md).
 ```
 
 ---
@@ -328,7 +331,7 @@ See [Deployment Guide](.specweave/docs/guides/deployment.md).
 - Insurance verification required before booking
 ```
 
-**Destination**: `specifications/modules/appointments/business-rules.md`
+**Destination**: `.specweave/docs/internal/strategy/appointments/business-rules.md`
 
 **CLAUDE.md addition**: None (specifications are source of truth)
 
@@ -352,7 +355,7 @@ See [Deployment Guide](.specweave/docs/guides/deployment.md).
 - Monitoring: Grafana, Prometheus
 ```
 
-**Destination**: `.specweave/docs/architecture/tech-stack.md`
+**Destination**: `.specweave/docs/internal/architecture/tech-stack.md`
 
 **CLAUDE.md addition**:
 ```markdown
@@ -360,7 +363,7 @@ See [Deployment Guide](.specweave/docs/guides/deployment.md).
 
 Next.js 14 + Node.js 20 + PostgreSQL 16 + Hetzner Cloud
 
-See [Tech Stack Details](.specweave/docs/architecture/tech-stack.md).
+See [Tech Stack Details](.specweave/docs/internal/architecture/tech-stack.md).
 ```
 
 ---
@@ -382,7 +385,7 @@ All APIs follow REST conventions:
 - Versioning: /api/v1, /api/v2
 ```
 
-**Destination**: `.specweave/docs/guides/api-conventions.md`
+**Destination**: `.specweave/docs/public/guides/api-conventions.md`
 
 **CLAUDE.md addition**: None (guide covers it)
 
@@ -418,7 +421,7 @@ function useCustomAuth() {
 }
 ```
 
-**Action**: Extract to `.specweave/docs/guides/authentication.md` (project-specific pattern)
+**Action**: Extract to `.specweave/docs/public/guides/authentication.md` (project-specific pattern)
 
 ---
 
@@ -435,12 +438,12 @@ function useCustomAuth() {
 **Domain**: Healthcare, Patient Management, Provider Scheduling
 
 ### Quick Links
-- [Domain Model](specifications/modules/appointments/domain-model.md)
-- [Existing System Architecture](.specweave/docs/architecture/existing-system.md)
-- [Tech Stack](.specweave/docs/architecture/tech-stack.md)
-- [Business Rules](specifications/modules/appointments/business-rules.md)
-- [Deployment Guide](.specweave/docs/guides/deployment.md)
-- [Project Conventions](.specweave/docs/guides/project-conventions.md)
+- [Domain Model](.specweave/increments/####-name/domain/appointments/domain-model.md)
+- [Existing System Architecture](.specweave/docs/internal/architecture/existing-system.md)
+- [Tech Stack](.specweave/docs/internal/architecture/tech-stack.md)
+- [Business Rules](.specweave/docs/internal/strategy/appointments/business-rules.md)
+- [Deployment Guide](.specweave/docs/internal/processes/deployment.md)
+- [Project Conventions](.specweave/docs/public/guides/project-conventions.md)
 
 **Note**: All project-specific details are in linked documents. This keeps CLAUDE.md concise.
 
@@ -505,22 +508,22 @@ if (exists("specifications/modules/appointments/domain-model.md")) {
 I found the following project-specific content in your backup CLAUDE.md:
 
 📦 Domain Model (Healthcare Appointments)
-   → specifications/modules/appointments/domain-model.md
+   → .specweave/increments/####-name/domain/appointments/domain-model.md
 
 🏗️ Microservices Architecture
-   → .specweave/docs/architecture/existing-system.md
+   → .specweave/docs/internal/architecture/existing-system.md
 
 🛠️ Tech Stack (Next.js + Node.js + PostgreSQL)
-   → .specweave/docs/architecture/tech-stack.md
+   → .specweave/docs/internal/architecture/tech-stack.md
 
 📋 Business Rules (Booking policies)
-   → specifications/modules/appointments/business-rules.md
+   → .specweave/docs/internal/strategy/appointments/business-rules.md
 
 🔧 Project Conventions (Naming, code style)
-   → .specweave/docs/guides/project-conventions.md
+   → .specweave/docs/public/guides/project-conventions.md
 
 🚀 Deployment Process (CI/CD workflow)
-   → .specweave/docs/guides/deployment.md
+   → .specweave/docs/internal/processes/deployment.md
 
 📝 CLAUDE.md Update
    → Add 12-line project summary with links
@@ -551,11 +554,11 @@ Proceed with merge? (y/n)
 
 ## Files Created (Essential Only)
 
-1. ✅ `.specweave/docs/architecture/core-architecture.md` (120 lines)
-2. ✅ `.specweave/docs/architecture/tech-stack.md` (80 lines)
-3. ✅ `.specweave/docs/architecture/critical-patterns.md` (100 lines)
-4. ✅ `.specweave/docs/guides/project-conventions.md` (90 lines)
-5. ✅ `.specweave/docs/guides/deployment.md` (70 lines)
+1. ✅ `.specweave/docs/internal/architecture/core-architecture.md` (120 lines)
+2. ✅ `.specweave/docs/internal/architecture/tech-stack.md` (80 lines)
+3. ✅ `.specweave/docs/internal/architecture/critical-patterns.md` (100 lines)
+4. ✅ `.specweave/docs/public/guides/project-conventions.md` (90 lines)
+5. ✅ `.specweave/docs/internal/processes/deployment.md` (70 lines)
 
 **Total**: 5 files, 460 lines (essential content)
 
@@ -573,11 +576,11 @@ Proceed with merge? (y/n)
 
 | Content Type | Lines | Status | Destination |
 |--------------|-------|--------|-------------|
-| Core Architecture | 120 | ✅ Merged | .specweave/docs/architecture/ |
-| Tech Stack | 80 | ✅ Merged | .specweave/docs/architecture/ |
-| Critical Patterns | 100 | ✅ Merged | .specweave/docs/architecture/ |
-| Conventions | 90 | ✅ Merged | .specweave/docs/guides/ |
-| Deployment | 70 | ✅ Merged | .specweave/docs/guides/ |
+| Core Architecture | 120 | ✅ Merged | .specweave/docs/internal/architecture/ |
+| Tech Stack | 80 | ✅ Merged | .specweave/docs/internal/architecture/ |
+| Critical Patterns | 100 | ✅ Merged | .specweave/docs/internal/architecture/ |
+| Conventions | 90 | ✅ Merged | .specweave/docs/public/guides/ |
+| Deployment | 70 | ✅ Merged | .specweave/docs/internal/processes/ |
 | **CLAUDE.md** | **10** | ✅ **Updated** | **Root** |
 | **Subtotal Merged** | **470** | | |
 | | | | |
@@ -662,12 +665,12 @@ The following content remains in the backup and will be extracted when you work
 
 ## Files Created
 
-1. ✅ `specifications/modules/appointments/domain-model.md` (450 lines)
-2. ✅ `.specweave/docs/architecture/existing-system.md` (320 lines)
-3. ✅ `.specweave/docs/architecture/tech-stack.md` (180 lines)
-4. ✅ `specifications/modules/appointments/business-rules.md` (280 lines)
-5. ✅ `.specweave/docs/guides/project-conventions.md` (200 lines)
-6. ✅ `.specweave/docs/guides/deployment.md` (150 lines)
+1. ✅ `.specweave/increments/####-name/domain/appointments/domain-model.md` (450 lines)
+2. ✅ `.specweave/docs/internal/architecture/existing-system.md` (320 lines)
+3. ✅ `.specweave/docs/internal/architecture/tech-stack.md` (180 lines)
+4. ✅ `.specweave/docs/internal/strategy/appointments/business-rules.md` (280 lines)
+5. ✅ `.specweave/docs/public/guides/project-conventions.md` (200 lines)
+6. ✅ `.specweave/docs/internal/processes/deployment.md` (150 lines)
 
 **Total**: 6 files, 1,580 lines
 
@@ -685,12 +688,12 @@ The following content remains in the backup and will be extracted when you work
 
 | Content Type | Lines | Destination |
 |--------------|-------|-------------|
-| Domain Model | 450 | specifications/ |
-| Architecture | 320 | .specweave/docs/architecture/ |
-| Tech Stack | 180 | .specweave/docs/architecture/ |
-| Business Rules | 280 | specifications/ |
-| Conventions | 200 | .specweave/docs/guides/ |
-| Deployment | 150 | .specweave/docs/guides/ |
+| Domain Model | 450 | .specweave/increments/####-name/domain/ |
+| Architecture | 320 | .specweave/docs/internal/architecture/ |
+| Tech Stack | 180 | .specweave/docs/internal/architecture/ |
+| Business Rules | 280 | .specweave/docs/internal/strategy/ |
+| Conventions | 200 | .specweave/docs/public/guides/ |
+| Deployment | 150 | .specweave/docs/internal/processes/ |
 | **CLAUDE.md** | **12** | **Root** |
 
 **Result**: 99.2% of content distributed to appropriate folders, not bloating CLAUDE.md
@@ -709,7 +712,7 @@ The following content remains in the backup and will be extracted when you work
 
 ## Next Steps
 
-1. ✅ Review generated files in `.specweave/docs/` and `specifications/`
+1. ✅ Review generated files in `.specweave/docs/internal/` and `.specweave/docs/public/`
 2. ✅ SpecWeave uses auto-detection
 3. ✅ Run `npm run docs:dev` to preview documentation
 4. ✅ Create features from specifications: `specweave plan-feature {name}`
@@ -779,12 +782,12 @@ Proceed with merge? (y/n)
 ✅ Merge complete!
 
 Created:
-1. specifications/modules/appointments/domain-model.md
-2. .specweave/docs/architecture/existing-system.md
-3. .specweave/docs/architecture/tech-stack.md
-4. specifications/modules/appointments/business-rules.md
-5. .specweave/docs/guides/project-conventions.md
-6. .specweave/docs/guides/deployment.md
+1. .specweave/increments/####-name/domain/appointments/domain-model.md
+2. .specweave/docs/internal/architecture/existing-system.md
+3. .specweave/docs/internal/architecture/tech-stack.md
+4. .specweave/docs/internal/strategy/appointments/business-rules.md
+5. .specweave/docs/public/guides/project-conventions.md
+6. .specweave/docs/internal/processes/deployment.md
 
 Updated:
 - CLAUDE.md (added 12-line project summary)

package/src/skills/increment-planner/SKILL.md

@@ -426,7 +426,12 @@ created: YYYY-MM-DD
 
 ### Step 7: Generate tasks.md
 
-**Purpose**: Break down implementation into executable steps.
+**Purpose**: Break down implementation into executable steps with intelligent model selection.
+
+**CRITICAL**: Use the model detection utility to assign optimal models to tasks:
+```typescript
+import { detectModelForTask, formatModelHint } from '../utils/model-selection';
+```
 
 **Structure**:
 ```markdown
@@ -439,27 +444,28 @@ created: YYYY-MM-DD
 - `[US#]`: User story reference
 - `[ ]`: Not started
 - `[x]`: Completed
+- Model hints: ⚡ haiku (fast), 🧠 sonnet (thinking), 💎 opus (critical)
 
 ## Phase 1: Setup and Foundation
 
-- [ ] [T001] [P] Initialize project structure
-- [ ] [T002] [P] Setup testing framework
-- [ ] [T003] Install dependencies
+- [ ] [T001] [P] ⚡ haiku - Initialize project structure
+- [ ] [T002] [P] ⚡ haiku - Setup testing framework
+- [ ] [T003] ⚡ haiku - Install dependencies
 
 ## Phase 2: Core Implementation
 
 ### US1: [User Story Title] (P1)
 
-- [ ] [T004] Write test for [component]
-- [ ] [T005] Implement [component] in src/path/file.ts
-- [ ] [T006] [P] Create [another component]
-- [ ] [T007] Integrate components
-- [ ] [T008] Verify US1 acceptance criteria
+- [ ] [T004] ⚡ haiku - Write test for [component]
+- [ ] [T005] ⚡ haiku - Implement [component] in src/path/file.ts
+- [ ] [T006] [P] ⚡ haiku - Create [another component]
+- [ ] [T007] 🧠 sonnet - Integrate components (requires decision-making)
+- [ ] [T008] ⚡ haiku - Verify US1 acceptance criteria
 
 ### US2: [User Story Title] (P2)
 
-- [ ] [T009] Write test for [feature]
-- [ ] [T010] Implement [feature]
+- [ ] [T009] ⚡ haiku - Write test for [feature]
+- [ ] [T010] 🧠 sonnet - Implement [feature] (complex logic)
 ...
 
 ## Phase 3: Testing and Validation
@@ -488,6 +494,30 @@ T051 depends on T050 (integration must pass first)
 - Exact file paths specified
 - Parallelizable tasks marked `[P]`
 - Dependencies explicitly stated
+- **Model hints for cost optimization**: Each task labeled with optimal model
+  - ⚡ haiku: Clear instructions, mechanical work (3x faster, 20x cheaper)
+  - 🧠 sonnet: Complex decisions, creative problem-solving
+  - 💎 opus: Critical architecture (rare, use sparingly)
+
+**Model Selection Guidelines**:
+1. **Use Haiku (⚡) when**:
+   - Task has specific file path (e.g., `src/components/LoginForm.tsx`)
+   - Acceptance criteria are detailed (3+ specific points)
+   - Implementation approach is defined in plan.md
+   - Simple CRUD operations, configuration, setup tasks
+
+2. **Use Sonnet (🧠) when**:
+   - Task requires architecture decisions
+   - Multiple valid approaches exist
+   - Integration between components
+   - Complex business logic
+   - Error handling strategies
+
+3. **Use Opus (💎) when**:
+   - Critical system architecture
+   - Security-critical decisions
+   - Performance-critical algorithms
+   - Novel problem-solving required
 
 ### Step 8: Generate tests.md
 

package/src/templates/AGENTS.md.template

@@ -70,6 +70,127 @@ SpecWeave uses role-based development. When working on tasks, adopt the appropri
 
 ---
 
+## 🎯 CRITICAL: Skills Are Your Expert Manuals (Read First!)
+
+**MANDATORY**: Before starting ANY implementation task, check for relevant skills.
+
+### What Are Skills?
+
+Skills are **specialized expert manuals** that contain:
+- Proven workflows for specific tasks
+- SpecWeave conventions and best practices
+- Required files to read and tools to use
+- Step-by-step instructions
+- Examples and test cases
+
+**There are 34+ skills available** organized into categories:
+- **Framework Core**: increment-planner, context-loader, context-optimizer
+- **External Integrations**: jira-sync, ado-sync, github-sync
+- **Architecture & Design**: diagrams-architect, design-system-architect
+- **Development**: frontend, nodejs-backend, python-backend, nextjs, dotnet-backend
+- **Quality & Testing**: increment-quality-judge, e2e-playwright
+- **Infrastructure**: hetzner-provisioner, cost-optimizer
+- **Documentation**: docusaurus, figma-to-code, figma-designer
+- **Orchestration**: role-orchestrator, skill-router, spec-driven-brainstorming
+
+### Progressive Disclosure Pattern (How to Use Skills)
+
+**STEP 1: Discovery (Always Start Here)**
+
+Before starting ANY task, read the skills index:
+
+```bash
+cat .claude/skills/SKILLS-INDEX.md
+```
+
+This single file contains ALL available skills with their activation keywords. **This is your first stop for every task.**
+
+**STEP 2: Matching**
+
+Look for skills whose "Activates for" keywords match your current task:
+
+| Your Task | Relevant Skill | Keywords |
+|-----------|---------------|----------|
+| "Plan a new feature for user auth" | `increment-planner` | "feature planning", "create increment" |
+| "Sync this to JIRA" | `jira-sync` | "JIRA sync", "create JIRA issue" |
+| "Create architecture diagram" | `diagrams-architect` | "architecture diagram", "C4 diagram" |
+| "Implement React component" | `frontend` | "React", "components", "UI" |
+| "Deploy to cloud" | `hetzner-provisioner` or `cost-optimizer` | "deploy", "hosting", "infrastructure" |
+| "Quality check" | `increment-quality-judge` | "validate quality", "quality check" |
+| "E2E test" | `e2e-playwright` | "E2E test", "browser automation" |
+| "Generate docs site" | `docusaurus` | "documentation site", "docs" |
+
+**STEP 3: Load Full Skill**
+
+Once you've identified 1-3 relevant skills, load their full documentation:
+
+```bash
+cat .claude/skills/{skill-name}/SKILL.md
+```
+
+**STEP 4: Execute Workflow**
+
+Follow the skill's instructions precisely:
+- Read required files listed in skill
+- Use recommended tools
+- Follow step-by-step workflow
+- Apply SpecWeave best practices
+
+### Why This Matters (Token Savings + Quality)
+
+**Scenario**: User asks to plan a new feature
+
+**Without skills** (bad):
+```
+❌ Read entire .specweave/docs/ folder (50k tokens)
+❌ Guess at SpecWeave conventions
+❌ Create inconsistent increment structure
+❌ Miss context-manifest.yaml (no token savings)
+❌ Reinvent workflow from scratch
+Result: High token cost, inconsistent output
+```
+
+**With skills** (good):
+```
+✅ Read SKILLS-INDEX.md (2k tokens)
+✅ Match "plan feature" → increment-planner skill
+✅ Load increment-planner SKILL.md (3k tokens)
+✅ Follow proven workflow with templates
+✅ Create proper context-manifest.yaml (70% token savings)
+Result: 5k tokens vs 50k = 90% savings + higher quality
+```
+
+### Skills vs Agents (What's the Difference?)
+
+**Skills = Capabilities (WHAT you can do)**
+- increment-planner: Creates feature plans
+- jira-sync: Syncs with external tools
+- diagrams-architect: Creates diagrams
+- **Use skills for workflows and procedures**
+
+**Agents = Roles (WHO you become)**
+- PM: Product manager perspective
+- Architect: Technical design perspective
+- DevOps: Infrastructure perspective
+- **Use agents when you need to adopt a specific role/perspective**
+
+### For Non-Claude Code Users
+
+**GitHub Copilot, Cursor, Windsurf, etc.:**
+
+Since these tools don't have native skill support, you MUST:
+
+1. **At session start**: Always read `SKILLS-INDEX.md` first
+2. **Before each task**: Check if relevant skills exist
+3. **During execution**: Follow skill workflows precisely
+4. **When stuck**: Re-read the relevant SKILL.md
+
+**Treat this as mandatory**, not optional. Skills are the difference between:
+- Inconsistent ad-hoc work ❌
+- Professional SpecWeave-compliant output ✅
+
+---
+
 ## Available Skills (Specialized Capabilities)
 
 SpecWeave has specialized capabilities for different tasks:
@@ -81,10 +202,14 @@ SpecWeave has specialized capabilities for different tasks:
 **In Claude Code** (automatic):
 - Skills activate based on keywords in your request
 - No manual invocation needed
+- Claude reads SKILLS-INDEX.md at startup
+- Full SKILL.md loaded when relevant
 
 **In other tools** (manual):
-- Read the skill file: `.claude/skills/{skill-name}/SKILL.md`
-- Follow the workflow described in that file
+- Read `.claude/skills/SKILLS-INDEX.md` first (mandatory)
+- Match task to activation keywords
+- Load full skill: `.claude/skills/{skill-name}/SKILL.md`
+- Follow the workflow precisely
 - Example: "Following increment-planner skill workflow..."
 
 ---
@@ -276,6 +401,152 @@ npm run lint
 
 ---
 
+## 📝 Documentation Updates (CRITICAL FOR NON-CLAUDE TOOLS)
+
+**IMPORTANT**: Claude Code has automatic hooks that remind you to update documentation. **GitHub Copilot, Cursor, and other tools DO NOT have these hooks!**
+
+### You MUST Manually Update Documentation After Every Task
+
+When you complete ANY task (implementation, bug fix, refactoring), you MUST update:
+
+#### 1. Living Docs (.specweave/docs/)
+
+After implementing features, update strategic documentation:
+
+**Strategy Docs** (`.specweave/docs/internal/strategy/`):
+- Update PRDs when requirements change
+- Add new user stories if scope expanded
+- Document discovered requirements
+
+**Architecture Docs** (`.specweave/docs/internal/architecture/`):
+- Update HLD (high-level design) when architecture changes
+- Update LLD (low-level design) when components change
+- Update ADRs from "Proposed" → "Accepted" after implementation
+- Add new ADRs for significant decisions made during implementation
+
+**Delivery Docs** (`.specweave/docs/internal/delivery/`):
+- Update deployment guides after infrastructure changes
+- Update CI/CD docs after pipeline modifications
+
+**Operations Docs** (`.specweave/docs/internal/operations/`):
+- Update runbooks after operational changes
+- Update monitoring/alerting docs
+
+#### 2. Increment Documentation
+
+**Always update these files in `.specweave/increments/{increment-id}/`**:
+
+```bash
+# Update implementation status
+vim .specweave/increments/0001-feature/plan.md
+# Add: "## Implementation Notes" section with learnings
+
+# Update task checklist
+vim .specweave/increments/0001-feature/tasks.md
+# Mark completed: - [x] T001: Task description
+
+# Document completion
+vim .specweave/increments/0001-feature/reports/completion-report.md
+# Add: Summary of what was implemented, challenges, solutions
+```
+
+#### 3. Project Documentation
+
+**CLAUDE.md or AGENTS.md** (this file):
+- Update when project structure changes
+- Add new workflows or commands
+- Update "Current Work" section
+
+**README.md** (user-facing):
+- Update when features are added
+- Update installation instructions if changed
+- Update usage examples
+
+**CHANGELOG.md** (version history):
+- Add entries for all user-facing changes
+- Format: `## [version] - date` with bullet points
+
+#### 4. Code Documentation
+
+**Inline comments**:
+- Add JSDoc/TSDoc for new functions
+- Update existing comments if behavior changes
+- Explain "why" not just "what"
+
+### When to Update (Checklist)
+
+After you:
+- ✅ Complete a task → Update increment tasks.md
+- ✅ Implement a feature → Update living docs (architecture, strategy)
+- ✅ Make architecture decision → Create or update ADR
+- ✅ Change project structure → Update CLAUDE.md/AGENTS.md
+- ✅ Add user-facing feature → Update README.md
+- ✅ Fix a bug → Update CHANGELOG.md
+- ✅ Change API → Update API documentation
+- ✅ Modify deployment → Update deployment guide
+
+### Example Workflow (GitHub Copilot/Cursor Users)
+
+```markdown
+# After completing "Implement user authentication" task:
+
+1. Update living docs:
+   echo "## Implementation Notes
+   - Used JWT for stateless authentication
+   - Password hashing with bcrypt
+   - Session timeout: 24 hours
+   " >> .specweave/increments/0001-auth/plan.md
+
+2. Update architecture:
+   vim .specweave/docs/internal/architecture/hld-system.md
+   # Add authentication component diagram
+
+3. Create ADR:
+   vim .specweave/docs/internal/architecture/adr-003-jwt-authentication.md
+
+4. Update README:
+   vim README.md
+   # Add authentication usage example
+
+5. Update CHANGELOG:
+   echo "### Added
+   - User authentication with JWT
+   - Password reset flow
+   " >> CHANGELOG.md
+
+6. Mark task complete:
+   vim .specweave/increments/0001-auth/tasks.md
+   # Change [ ] to [x] for completed tasks
+```
+
+### Why This Matters
+
+**Without documentation updates**:
+- ❌ Specs diverge from implementation (specs become useless)
+- ❌ Team members don't know what changed
+- ❌ Future AI sessions have outdated context
+- ❌ SpecWeave's core principle (living documentation) breaks down
+
+**With documentation updates**:
+- ✅ Specs stay synchronized with code
+- ✅ Clear audit trail of changes
+- ✅ AI agents have accurate context
+- ✅ Team members stay informed
+- ✅ SpecWeave philosophy is maintained
+
+### Tools That Need Manual Updates
+
+These tools **DO NOT** have automatic documentation hooks:
+- GitHub Copilot (all versions)
+- Cursor
+- Windsurf
+- Gemini CLI
+- Generic AI tools (ChatGPT, Claude web, etc.)
+
+Only **Claude Code** has automatic hooks that remind you to update docs.
+
+---
+
 ## Security Considerations
 
 - Never commit secrets (use `.env` files, gitignored)
@@ -317,6 +588,7 @@ When you encounter a new task:
 5. ✅ **Technology-specific in plan.md** (HOW with details)
 6. ✅ **Use checkboxes in tasks.md** for tracking
 7. ✅ **All supporting files in increment folders** (never in root)
+8. 🔴 **UPDATE DOCUMENTATION AFTER EVERY TASK** (see "Documentation Updates" section above - CRITICAL for non-Claude tools!)
 
 ---