specweave 0.26.10 → 0.26.13

package/src/templates/CLAUDE.md.template

@@ -1,758 +1,190 @@
 # {PROJECT_NAME} - SpecWeave Quick Reference
 
-This project uses **SpecWeave** - a specification-first AI development framework where specs and docs are the SOURCE OF TRUTH.
+**Framework**: SpecWeave (spec-first development)
+**Source of Truth**: `spec.md` + `tasks.md` (not internal TODO)
 
 ---
 
-## 🚨 Meta-Rule: Thinking-Before-Acting (For Claude)
+## Critical Rules
 
-**If you identify a dependency in your reasoning, satisfy it BEFORE attempting the dependent operation.**
+### 1. File Organization
+**NEVER pollute project root!** All AI-generated files → increment folders.
 
 ```
-❌ Anti-pattern: node script.js → Error: file not compiled → npm run build
-✅ Correct: npm run build → node script.js → Success
+.specweave/increments/####-name/
+├── spec.md, plan.md, tasks.md    ← ONLY these at root
+├── reports/                       ← Reports, summaries, analysis
+├── scripts/                       ← Helper scripts, migrations
+└── logs/                          ← Execution logs, temp data
 ```
 
-**Why**: Avoids predictable failures when you already know what needs to happen first.
-
----
-
-## 🎯 Getting Started
-
-**Initial Increment Created**: `0001-project-setup` (`.specweave/increments/0001-project-setup/`)
-
-This increment was auto-generated by `specweave init` to give you a starting point.
-
-**Your Options**:
-1. **Start Fresh** (Recommended): Delete it and create your first real feature
-   ```bash
-   rm -rf .specweave/increments/0001-project-setup
-   /specweave:increment "your-feature-name"
-   ```
-2. **Customize It**: Edit the spec.md and use this increment for initial setup tasks
+### 2. Source of Truth
+After completing work, **IMMEDIATELY update both files**:
+```typescript
+TodoWrite([{task: "T-001", status: "completed"}]);
+Edit("tasks.md", "**Status**: [ ] pending", "**Status**: [x] completed");
+Edit("spec.md", "- [ ] **AC-US1-01**", "- [x] **AC-US1-01**");
+```
 
-**Note**: SpecWeave works best when each increment represents a single, focused feature or bugfix.
+### 3. Increment Numbers Must Be Unique
+**Format**: `####-descriptive-name` (e.g., `0001-user-auth`)
+**Check before creating**: `ls -1 .specweave/increments/ | grep -E "^[0-9]{4}-" | sort | tail -5`
 
 ---
 
-## 🚨 CRITICAL: NEVER POLLUTE PROJECT ROOT!
-
-**⛔ THIS IS THE #1 RULE - ALL AI-GENERATED FILES GO IN INCREMENT FOLDERS ⛔**
-
-### ❌ NEVER Create in Root
+## Core Workflow
 
 ```
-❌ WRONG - ROOT FILES (NOT ALLOWED!):
-/SESSION-SUMMARY.md                    # NO! Goes to increment reports/
-/ANALYSIS-REPORT.md                    # NO! Goes to increment reports/
-/migration-script.py                   # NO! Goes to increment scripts/
-/execution.log                         # NO! Goes to increment logs/
-/temp-data.json                        # NO! Goes to increment logs/
-
-✅ CORRECT - INCREMENT FOLDERS:
-.specweave/increments/0001-user-auth/
-├── spec.md                            # Core spec files
-├── plan.md
-├── tasks.md                           # Tasks with embedded tests (BDD format)
-├── reports/                           # ✅ PUT REPORTS HERE!
-│   ├── SESSION-SUMMARY.md
-│   └── ANALYSIS-REPORT.md
-├── scripts/                           # ✅ PUT SCRIPTS HERE!
-│   └── migration-script.py
-└── logs/                              # ✅ PUT LOGS HERE!
-    ├── execution.log
-    └── temp-data.json
+/specweave:increment "feature" → /specweave:do → /specweave:progress → /specweave:done 0001
 ```
 
-### What IS Allowed in Root?
-
-**ONLY these files**:
-- ✅ `CLAUDE.md` (this file)
-- ✅ Your project files (`src/`, `package.json`, etc.)
-- ✅ Standard config (`.env`, `.gitignore`, `tsconfig.json`)
+| Command | Purpose |
+|---------|---------|
+| `/specweave:increment "X"` | Plan new feature |
+| `/specweave:do` | Execute implementation |
+| `/specweave:progress` | Check status |
+| `/specweave:validate 0001` | Quality check |
+| `/specweave:done 0001` | Close increment |
 
-**Everything else → increment folders!**
-
-**Before asking me to commit, check**: `git status` - If you see unexpected `.md` files in root, STOP and move them!
+**Sync Commands** (if plugins installed):
+- `/specweave-github:sync` - Sync to GitHub Issues
+- `/specweave-jira:sync` - Sync to Jira
+- `/specweave-ado:sync` - Sync to Azure DevOps
 
 ---
 
-## 📋 Quick Reference Cards
-
-### Daily Workflow
-```
-┌────────────────────────────────────────────────────────────┐
-│ TASK                    → COMMAND                          │
-├────────────────────────────────────────────────────────────┤
-│ Plan new feature        → /specweave:increment "feature"   │
-│ Execute tasks           → /specweave:do                    │
-│ Check progress          → /specweave:progress              │
-│ Validate quality        → /specweave:validate 0001         │
-│ Close increment         → /specweave:done 0001             │
-│ Sync to GitHub          → /specweave:github:sync           │
-│ Sync to Jira            → /specweave:jira:sync             │
-└────────────────────────────────────────────────────────────┘
-```
+## Project Structure
 
-### When to Use Which Command
-| User Says...              | Use Command                        |
-|---------------------------|------------------------------------|
-| "Let's build X"           | `/specweave:increment "X"`         |
-| "Start implementing"      | `/specweave:do`                    |
-| "What's the status?"      | `/specweave:progress`              |
-| "Is this ready?"          | `/specweave:validate 0001`         |
-| "We're done"              | `/specweave:done 0001`             |
-| "Sync to GitHub"          | `/specweave:github:sync`           |
-| "Sync to Jira"            | `/specweave:jira:sync`             |
-
-### File Organization Rules
 ```
-┌────────────────────────────────────────────────────────────┐
-│ NEVER in Root           ↔ ALWAYS in Increment Folder      │
-├────────────────────────────────────────────────────────────┤
-│ ❌ analysis.md          ↔ ✅ .../0001/reports/analysis.md  │
-│ ❌ migration.py         ↔ ✅ .../0001/scripts/migration.py │
-│ ❌ execution.log        ↔ ✅ .../0001/logs/execution.log   │
-│ ❌ session-notes.md     ↔ ✅ .../0001/reports/session.md   │
-└────────────────────────────────────────────────────────────┘
+.specweave/
+├── increments/              # Feature increments (####-name/)
+│   └── 0001-feature/
+│       ├── spec.md          # WHAT & WHY
+│       ├── plan.md          # HOW
+│       ├── tasks.md         # Checklist with embedded tests
+│       └── context-manifest.yaml  # Selective loading
+├── docs/internal/
+│   ├── strategy/            # Business specs
+│   ├── specs/               # Living docs (post-completion)
+│   │   └── {project}/       # Project-specific specs
+│   ├── architecture/        # Technical design, ADRs
+│   └── operations/          # Runbooks, SLOs
+└── config.json              # Project configuration
 ```
 
 ---
 
-## SpecWeave Workflow (Use These Commands!)
+## Task Format (Mandatory)
 
-**How SpecWeave works**:
+```markdown
+### T-001: Task Title
+**User Story**: US-001           ← REQUIRED
+**Satisfies ACs**: AC-US1-01     ← REQUIRED
+**Status**: [x] completed
 
+**Test Plan** (BDD):
+- **Given** [context] → **When** [action] → **Then** [result]
 ```
-/specweave:increment "feature" → /specweave:do → /specweave:progress → /specweave:done → repeat
-```
-
-**1. Plan Feature** → `/specweave:increment "user authentication"`
-   - Creates spec.md (WHAT/WHY), plan.md (HOW), tasks.md (with embedded tests)
-   - PM-led process with architect/security/QA review
-   - **Use when**: Starting any new feature or increment
-
-**2. Execute Tasks** → `/specweave:do` or `/specweave:do 0001`
-   - Smart resume (picks up where you left off)
-   - Runs hooks after EVERY task completion
-   - **Use when**: Ready to implement planned work
-
-**3. Check Progress** → `/specweave:progress`
-   - Shows task completion %, next action
-   - **Use when**: Want to see status
-
-**4. Validate Quality** → `/specweave:validate 0001` or `/specweave:qa 0001`
-   - Rule-based validation (120 checks) or AI quality assessment with risk scoring
-   - Validates tasks, tests (embedded in tasks.md), and documentation
-   - **Use when**: Verify increment quality before completion
-
-**5. Close Increment** → `/specweave:done 0001`
-   - Validates all tasks complete
-   - **Use when**: Feature is finished
-
-**6. Sync to External** (Plugin Commands):
-   - `/specweave:github:sync` - Export to GitHub issues (github plugin)
-   - `/specweave:jira:sync` - Export to Jira (jira plugin)
-   - **Use when**: Need to sync with project management tools
-
-**All other functionality (agents, skills) activates automatically based on context.**
 
 ---
 
-## ⚠️ Increment Discipline (CRITICAL)
-
-### 🚨 INCREMENT NUMBERS MUST BE UNIQUE!
-
-**Duplicate numbers break everything** - sync, status line, git history.
-
-**Format**: `####-descriptive-name` (e.g., `0001-user-auth`)
-
-**Check before creating:**
-```bash
-ls -1 .specweave/increments/ | grep -E "^[0-9]{4}-" | sort | tail -5
-```
-
-### 📁 Folder Structure (MANDATORY)
-
-**Only 3 files in root:** `spec.md`, `plan.md`, `tasks.md`
+## Context Loading (Token Savings)
 
-**Everything else in subfolders:**
-- `reports/` - Analysis, summaries, session notes
-- `scripts/` - Helper scripts
-- `logs/` - Execution logs
+**ALWAYS read `context-manifest.yaml` first!** Load only files listed there.
+- Full specs: 50k tokens
+- Manifest files: 5k tokens
+- **Savings: 90%**
 
 ---
 
-## 🔗 Automatic Syncing (Living Docs + External Tools)
-
-**SpecWeave automatically syncs your work** after EVERY task completion via hooks:
-
-### What Gets Synced Automatically
-
-1. **Living Docs** → `.specweave/docs/internal/specs/`
-   - Increment specs sync to permanent knowledge base
-   - Ensures complete project history
-   - **Configurable**: Set `sync_living_docs: true` in `.specweave/config.json`
-
-2. **External Trackers** (if configured):
-   - GitHub Issues - Task checkboxes update automatically
-   - Jira - Issue status updates automatically
-   - Azure DevOps - Work item updates automatically
-   - **Configurable**: Set `external_tracker_sync: true` in `.specweave/config.json`
-
-### 🏷️ GitHub Sync Mapping (Universal Hierarchy)
-
-**SpecWeave follows strict hierarchy for GitHub sync:**
-
-| SpecWeave Entity | GitHub Mapping | Example |
-|------------------|----------------|---------|
-| **Feature** (FS-XXX) | **Milestone** | `FS-031: External Tool Status Sync` |
-| **User Story** (US-XXX) | **Issue** | `[FS-031][US-002] Task-Level Mapping` |
-| **Task** (T-XXX) | **Checkbox** | `- [ ] T-001: Implement validator` |
-
-**Key Principles**:
-- ✅ **Features → Milestones** (container for all User Stories)
-- ✅ **User Stories → Issues** (each US-* file = separate GitHub issue)
-- ✅ **Tasks → Checkboxes** (listed in User Story issue body)
-- ❌ **NEVER create Feature-level issues** (Features are Milestones!)
-
-**⛔ DEPRECATED**:
-- ❌ `[INC-XXXX]` - Old increment format (pre-v0.18.0)
-- ❌ `[FS-XXX] Feature Title` as issue - Feature-level issues (pre-v0.19.0, wrong!)
-
-3. **Sound Notifications**:
-   - Plays sound when tasks complete (helps you know when to review)
-   - Platform-specific: Glass.aiff (macOS), system sounds (Linux/Windows)
-
-### Configuration (`.specweave/config.json`)
+## Automatic Syncing (Hooks)
 
-Created automatically during `specweave init`, but you can customize:
+After **EVERY task completion**, hooks automatically:
+1. Update `tasks.md` status
+2. Sync to living docs (`.specweave/docs/internal/specs/`)
+3. Sync to external trackers (GitHub/Jira/ADO) if configured
 
+**Configuration** (`.specweave/config.json`):
 ```json
 {
   "hooks": {
     "post_task_completion": {
-      "sync_living_docs": true,        // Sync specs to living docs
-      "sync_tasks_md": true,           // Update tasks.md
-      "external_tracker_sync": true    // Sync to GitHub/Jira/ADO
+      "sync_living_docs": true,
+      "external_tracker_sync": true
     }
   }
 }
 ```
 
-**Just works!** No manual syncing needed - focus on implementation, SpecWeave handles the rest.
-
----
-
-## 🧠 Automatic Intent Detection (NEW in v0.3.8+)
-
-**SpecWeave now detects when you're describing a product/project and automatically helps you plan it!**
-
-### How It Works
-
-When working in a SpecWeave-initialized project (`.specweave/` exists), SpecWeave recognizes product descriptions by detecting these patterns:
-
-**Signals that trigger auto-detection:**
-1. ✅ **Project Name/Description** - "Project: RosterSync", "I want to build X"
-2. ✅ **Features List** - Bullet points or numbered list of features (3+ items)
-3. ✅ **Tech Stack** - Languages, frameworks, databases mentioned
-4. ✅ **Timeline/Scope** - "MVP", "2 weeks", "Phase 1", "Quick build"
-5. ✅ **Problem Statement** - "For teams...", "Helps users...", "Solves..."
-6. ✅ **Business Model** - "Freemium", "$X/mo", "B2B", "Consumer"
-
-**Confidence Levels:**
-- **High (5-6 signals + SpecWeave folder)**: Auto-route to `/specweave:increment` immediately
-- **Medium (3-4 signals + SpecWeave folder)**: Ask 1-2 clarifying questions, then route
-- **Low (<3 signals)**: Regular conversation (no auto-routing)
-
-### Example: Automatic Detection
-
-```
-You: Project: RosterSync - Team scheduling SaaS
-Core features:
-- Team roster management
-- Availability calendar
-- Event scheduling with notifications
-- Lineup builder
-Tech stack: .NET 8, Next.js 14+, PostgreSQL
-MVP: 2-3 weeks
-Monetization: Freemium ($10/mo)
-
-SpecWeave detects: ✅ Name ✅ Features ✅ Tech ✅ Timeline ✅ Problem ✅ Business
-→ Automatically recognizes this as a product description
-→ Guides you through increment planning
-→ Invokes /specweave:increment automatically
-
-No need to remember the full command!
-```
-
-### Opt-Out Options
-
-You can override automatic routing with explicit instructions:
-- **"Just brainstorm first"** → Uses spec-driven-brainstorming instead
-- **"Don't plan yet"** → Regular conversation
-- **"Quick discussion"** → No automatic routing
-- **"Let's explore ideas first"** → Exploratory mode
-
-### Two Ways to Use SpecWeave
-
-1. ✅ **Automatic** (NEW): Describe your product → SpecWeave detects it → Plans automatically
-2. ✅ **Explicit** (Classic): Type `/specweave:increment "feature"` → Works as before
-
-Both approaches work perfectly - use whichever feels more natural!
-
----
-
-## 🚨 CRITICAL: File Organization Rules
-
-**Keep project root CLEAN!** All AI-generated files MUST go into increment folders.
-
-### What Goes Where
-
-**✅ ALLOWED in Root**:
-- `CLAUDE.md` (this file)
-- Your existing project files (package.json, src/, etc.)
-- Standard config files (.env, .gitignore, tsconfig.json)
-
-**❌ NEVER Create in Root** (use increment folders):
-- Reports → `.specweave/increments/0001-feature-name/reports/`
-- Scripts → `.specweave/increments/0001-feature-name/scripts/`
-- Logs → `.specweave/increments/0001-feature-name/logs/`
-- Analysis files → `.specweave/increments/0001-feature-name/reports/`
-- Temp files → `.specweave/increments/0001-feature-name/logs/`
-
-### Increment Structure
-
-```
-.specweave/increments/0001-user-auth/   # ⚠️ ID must be unique!
-├── spec.md                      # WHAT & WHY
-├── plan.md                      # HOW
-├── tasks.md                     # Tasks with embedded test plans (BDD format)
-├── context-manifest.yaml        # Selective context loading
-├── logs/                        # ✅ Execution logs, errors, AI sessions
-├── scripts/                     # ✅ Helper scripts, migrations, setup
-└── reports/                     # ✅ Analysis, completion, performance
-```
-
-**Why?**
-- ✅ Complete traceability (know which increment created which files)
-- ✅ Easy cleanup (delete increment folder = delete all related files)
-- ✅ Clear context (all files for a feature in one place)
-- ✅ No root clutter
-
-**Example**:
-```
-❌ WRONG:
-project-root/
-├── analysis-report.md          # NO! Pollutes root
-├── migration-script.py         # NO! Pollutes root
-└── execution.log               # NO! Pollutes root
-
-✅ CORRECT:
-.specweave/increments/0001-user-auth/
-├── reports/analysis-report.md
-├── scripts/migration-script.py
-└── logs/execution.log
-```
-
 ---
 
-## 🔗 Bidirectional Task ↔ User Story Linking
-
-**AUTOMATIC FEATURE**: SpecWeave creates bidirectional links between tasks and user stories.
-
-### How It Works
-
-**When you complete an increment** (`/specweave:done`):
-1. User stories are extracted to `.specweave/docs/internal/specs/default/`
-2. Tasks.md is automatically updated with links back to user stories
-3. Complete bidirectional navigation is created!
-
-**Example Task** (WITH bidirectional link):
-```markdown
-### T-001: Implement User Login
-
-**User Story**: [US-001: User Authentication](../../docs/internal/specs/default/auth-service/us-001-user-authentication.md)
-
-**AC**: AC-US1-01, AC-US1-02, AC-US1-03
-
-**Test Plan** (BDD):
-- **Given** valid credentials → **When** login → **Then** receive JWT token
-```
-
-### Requirements
-
-**Your tasks.md MUST have AC-IDs** for bidirectional linking:
-
-```markdown
-## T-001: Implement User Login
-
-**AC**: AC-US1-01, AC-US1-02, AC-US1-03   ← CRITICAL for linking!
-```
-
-**AC-ID Format**: `AC-US{number}-{criteria}` (e.g., `AC-US1-01`, `AC-US2-03`)
-- Maps to user stories: `AC-US1-01` → `US-001`
-- Multiple AC-IDs allowed per task
-- Task links to FIRST user story found
-
-### Benefits
-
-- ✅ **Navigate both directions**: Tasks → User Stories → Tasks
-- ✅ **Automatic**: No manual linking needed
-- ✅ **Multi-project aware**: Works with backend, frontend, mobile, etc.
-- ✅ **Always in sync**: Links created during `/specweave:done`
-- ✅ **NEW (v0.18.3+)**: User stories include project-specific checkable task lists
+## GitHub Sync Mapping
 
-### Project-Specific Tasks (v0.18.3+)
-
-**NEW**: User stories now have their OWN checkable task lists, not just links!
-
-```markdown
-## Tasks
-
-- [ ] **T-001**: Setup API endpoint
-- [x] **T-003**: Add DB migration (completed)
-
-> **Note**: Tasks are project-specific. See increment tasks.md for full list
-```
+| SpecWeave | GitHub |
+|-----------|--------|
+| Feature (FS-XXX) | Milestone |
+| User Story (US-XXX) | Issue |
+| Task (T-XXX) | Checkbox |
 
-**Benefits**:
-- **Project Isolation**: Backend tasks ≠ Frontend tasks
-- **GitHub UX**: Checkable task lists in GitHub issues
-- **Traceability**: Each user story explicitly lists its tasks
-- **Completion Tracking**: Status synced from increment tasks.md
-
-**For complete details**: Ask me about "bidirectional linking" or check `.specweave/docs/internal/specs/default/README.md`
+**Issue Title Format**: `[FS-XXX][US-YYY] User Story Title`
 
 ---
 
 ## Tech Stack
 
-**Project Type**: {MONOREPO_OR_SINGLE}
+**Type**: {MONOREPO_OR_SINGLE}
 
 {#IF_SINGLE_STACK}
-**Stack**:
 - Language: {DETECTED_LANGUAGE}
 - Framework: {DETECTED_FRAMEWORK}
 - Database: {SPECIFIED_DATABASE}
-- Platform: {SPECIFIED_PLATFORM}
 {#ENDIF}
 
 {#IF_MONOREPO}
 **Services**:
-- {SERVICE_1_NAME}: {SERVICE_1_LANGUAGE} + {SERVICE_1_FRAMEWORK} ({SERVICE_1_PATH}/)
-- {SERVICE_2_NAME}: {SERVICE_2_LANGUAGE} + {SERVICE_2_FRAMEWORK} ({SERVICE_2_PATH}/)
-{#ENDIF}
-
-Config: Auto-detected from project files
-
----
-
-## Project Structure
-
-**IMPORTANT**: This project uses {MONOREPO_OR_SINGLE} mode.
-
-{#IF_SINGLE_PROJECT}
-### Single Project Structure
-
-```
-{PROJECT_NAME}/
-├── .specweave/
-│   ├── docs/                    # Strategic documentation
-│   │   ├── internal/
-│   │   │   ├── strategy/        # Business specs (WHAT, WHY)
-│   │   │   ├── specs/           # Feature specifications (living docs)
-│   │   │   │   └── default/     # ✅ All specs in default project
-│   │   │   ├── architecture/    # Technical design (HOW)
-│   │   │   ├── delivery/        # Guides, roadmap, CI/CD
-│   │   │   ├── operations/      # Runbooks, monitoring
-│   │   │   └── governance/      # Security, compliance
-│   │   └── public/              # Published docs
-│   ├── increments/              # Features (auto-numbered, UNIQUE IDs)
-│   │   └── 0001-feature-name/   # ⚠️ Each ID must be unique (0001-9999)
-│   │       ├── spec.md          # What we're building
-│   │       ├── plan.md          # How we'll build it
-│   │       ├── tasks.md         # Tasks with embedded tests
-│   │       ├── logs/            # ✅ Put logs here
-│   │       ├── scripts/         # ✅ Put scripts here
-│   │       └── reports/         # ✅ Put reports here
-│   └── tests/                   # Centralized test repository
-│
-├── .claude/                     # Pre-installed components
-│   ├── agents/                  # Core + plugin agents (auto-activate)
-│   ├── skills/                  # Core + plugin skills (auto-activate)
-│   └── commands/                # Core + plugin slash commands
-│
-├── CLAUDE.md                    # This file
-└── src/                         # Your source code
-```
-{#ENDIF}
-
-{#IF_MULTI_PROJECT}
-### Multi-Project Structure (v0.16.11+ Flattened)
-
-**CRITICAL**: Specs are organized by project with FLATTENED structure (v0.16.11+).
-
-```
-{PROJECT_NAME}/
-├── .specweave/
-│   ├── docs/internal/
-│   │   ├── strategy/            # Cross-project strategy
-│   │   ├── specs/               # ✅ FLATTENED structure (v0.16.11+)
-│   │   │   ├── backend/         # Backend project specs
-│   │   │   │   ├── spec-001-api-auth.md
-│   │   │   │   └── spec-002-data-layer.md
-│   │   │   ├── frontend/        # Frontend project specs
-│   │   │   │   ├── spec-001-user-dashboard.md
-│   │   │   │   └── spec-002-dark-mode.md
-│   │   │   ├── mobile/          # Mobile project specs (if applicable)
-│   │   │   │   └── spec-001-push-notifications.md
-│   │   │   └── _parent/         # Parent repo specs (multi-repo only)
-│   │   │       └── spec-001-system-architecture.md
-│   │   ├── architecture/        # System-wide technical design
-│   │   ├── delivery/            # Cross-project delivery
-│   │   ├── operations/          # Cross-project operations
-│   │   └── governance/          # Cross-project governance
-│   ├── increments/
-│   │   ├── 0001-backend-auth/   # Backend increment
-│   │   ├── 0002-frontend-ui/    # Frontend increment
-│   │   └── 0003-mobile-push/    # Mobile increment
-│   └── ...
-```
-
-**Living Docs Path Format**:
-- ✅ **CORRECT** (v0.16.11+): `.specweave/docs/internal/specs/{project-id}/spec-NNN-name.md`
-- ❌ **OLD** (v0.8.0-v0.16.10): `.specweave/docs/internal/projects/{project-id}/specs/...` (DEPRECATED)
-
-**Project Detection** (automatic):
-- **From increment name**: `0001-backend-auth` → project: `backend`
-- **From tech stack**: React/Next.js → `frontend`, ASP.NET/Node.js → `backend`
-- **From config**: `multiProject.activeProject` in `.specweave/config.json`
-- **Fallback**: Uses `default` project
-{#ENDIF}
-
----
-
-## Plugins
-
-SpecWeave uses Claude Code's native plugin system. All plugins auto-install during `specweave init`.
-
-**Enabled plugins**: {ENABLED_PLUGINS}
-
-**Plugin commands** (examples):
-- `/specweave:github:sync` - Sync to GitHub
-- `/specweave:jira:sync` - Sync to Jira
-
-Skills/agents activate automatically based on context.
-
----
-
-## Documentation Approach
-
-**You chose**: {DOCUMENTATION_APPROACH}
-
-{#IF_COMPREHENSIVE}
-**Comprehensive** - Detailed specs upfront, best for enterprise/regulated industries.
-{#ENDIF}
-
-{#IF_INCREMENTAL}
-**Incremental** - Build docs as you go, best for startups/MVPs.
+- {SERVICE_1_NAME}: {SERVICE_1_LANGUAGE} ({SERVICE_1_PATH}/)
+- {SERVICE_2_NAME}: {SERVICE_2_LANGUAGE} ({SERVICE_2_PATH}/)
 {#ENDIF}
 
 ---
 
-## Quick Reference
-
-**Need help?** [SpecWeave Docs](https://spec-weave.com/docs)
-- **Which spec is source of truth?** Living docs spec (when it exists), otherwise increment spec
-
-### Key Topics Covered
-- ✅ Two-spec architecture explained
-- ✅ When to create living docs specs
-- ✅ Increment spec lifecycle
-- ✅ Brownfield documentation linking
-- ✅ External PM tool integration (Jira, ADO, GitHub)
-- ✅ Small vs large feature decisions
-- ✅ Project structure and organization
-
-**[View Complete FAQ →](https://spec-weave.com/docs/faq)**
-
----
-
 ## Testing
 
-**Four Levels**:
-1. **Specification** (`.specweave/docs/internal/strategy/`) - Acceptance criteria (AC-IDs)
-2. **Feature** (`.specweave/increments/####/tasks.md`) - Test plans embedded in tasks (BDD format)
-3. **Integration** (`tests/integration/` or `tests/specs/`) - Component/module tests
-4. **Code** (`tests/`) - Automated tests (Unit, Integration, E2E)
-
-**Test-Aware Planning**: Tests are embedded in tasks.md using BDD format (Given/When/Then), with AC-ID traceability and realistic coverage targets (80-90%).
-
-**Requirements**:
-- E2E tests when UI exists
-- >80% coverage for critical paths
-- Tests MUST tell the truth
+**Test-Aware Planning**: Tests embedded in `tasks.md` (BDD format)
+- Unit tests: >80% coverage
+- Integration tests: Critical paths
+- E2E tests: When UI exists
 
-### Writing Modern Tests (Vitest)
+**Test Files**: `.test.ts` (Vitest), NOT `.spec.ts`
 
-**SpecWeave uses Vitest**. Key patterns:
+---
 
-```typescript
-// ✅ CORRECT: ES6 imports, Vitest API, type-safe mocks
-import { describe, it, expect, vi } from 'vitest';
-vi.mock('fs-extra', () => ({ default: { readFile: vi.fn() } }));
-import fs from 'fs-extra';
-
-describe('Feature', () => {
-  const mockReadFile = vi.mocked(fs.readFile);
-
-  beforeEach(() => {
-    vi.clearAllMocks();
-    mockReadFile.mockResolvedValue('data');
-  });
-
-  it('works', async () => {
-    const result = await MyModule.doSomething();
-    expect(mockReadFile).toHaveBeenCalled();
-  });
-});
-```
+## Troubleshooting
 
-**Common mistakes to avoid**:
-- ❌ `require()` → ✅ `import` (ES modules only)
-- ❌ `jest.fn()` → ✅ `vi.fn()` (Vitest API)
-- ❌ `fs as anyed<>` → ✅ `vi.mocked(fs.method)` (type-safe)
-- ❌ External variable in `vi.mock()` factory → ✅ Inline `vi.fn()`
+| Issue | Solution |
+|-------|----------|
+| Skills not activating | Restart Claude Code |
+| Commands not found | Check plugin: `/plugin list --installed` |
+| Root polluted | Move files to increment folders |
+| Tasks out of sync | `/specweave:sync-tasks` |
+| Can't find increment | `/specweave:status` |
 
 ---
 
-## Key SpecWeave Principles
+## Documentation
 
-1. **Specification-First**: Always start with `/specweave:increment` to create specs before coding
-2. **Documentation = Source of Truth**: Specs guide implementation, not the reverse
-3. **Incremental**: Work in small, measurable increments
-4. **Validated**: Every increment validated before closure
-5. **Traceable**: All work traces back to specs and requirements
-6. **Clean Organization**: All supporting files in increment folders, never root
-7. **No Duplicate Increments**: Each increment must have a unique 4-digit ID (0001-9999)
+- **Quick Reference**: This file
+- **Full Docs**: https://spec-weave.com
+- **Project Docs**: `.specweave/docs/internal/`
 
 ---
 
 ## Project-Specific Notes
 
 {#CUSTOM_NOTES}
-<!-- Add project-specific conventions, team workflows, deployment notes here -->
+<!-- Add project-specific conventions here -->
 {#ENDCUSTOM}
 
 ---
 
-## 🆘 Troubleshooting
-
-### Skills Not Activating
-
-**Symptoms**: Expected skill didn't load automatically
-
-**Solutions**:
-1. Restart Claude Code (skills loaded at startup)
-2. Check keywords: Skills activate based on description keywords
-3. Verify plugin installed: Use `/plugin list --installed`
-4. Manual check: Look in `.claude/skills/SKILLS-INDEX.md` for available skills
-
-### Commands Not Found
-
-**Symptoms**: `/specweave:increment` doesn't work
-
-**Solutions**:
-1. Verify plugin installed: `/plugin list --installed`
-2. Check installed commands: `ls .claude/commands/`
-3. Restart Claude Code
-4. Re-run: `specweave init` if plugins missing
-
-### Root Folder Polluted
-
-**Symptoms**: `git status` shows `.md` files in project root
-
-**Solutions**:
-1. **Immediate fix**: Move files to increment folder
-   ```bash
-   mv SESSION-NOTES.md .specweave/increments/0001/reports/
-   mv analysis.md .specweave/increments/0001/reports/
-   ```
-2. Check `.gitignore` is up to date
-3. Commit cleaned structure:
-   ```bash
-   git add .
-   git commit -m "fix: move reports to increment folder"
-   ```
-
-### Increment Numbers Not Unique
-
-**Symptoms**: Multiple increments with same number (0001, 0001, etc.)
-
-**Solutions**:
-1. Check existing: `ls -1 .specweave/increments/ | grep -E "^[0-9]{4}-"`
-2. Use next available number
-3. If duplicates exist, run: `/specweave:fix-duplicates`
-
-### External Tracker Not Syncing
-
-**Symptoms**: GitHub/Jira not updating after task completion
-
-**Solutions (Claude Code)**:
-1. Check config: `.specweave/config.json` has `external_tracker_sync: true`
-2. Verify hook exists: `ls plugins/specweave-github/hooks/post-task-completion.sh`
-3. Check credentials: `gh auth status` or `jira config list`
-4. Manual sync: `/specweave:github:sync 0001`
-
-### Tasks.md Out of Sync
-
-**Symptoms**: Progress shows 0/24 but many tasks done
-
-**Solutions**:
-1. Auto-sync from reality: `/specweave:sync-tasks`
-2. Manual update: Edit tasks.md, change `[ ]` to `[x]`
-3. Recalculate progress counters
-
-### Can't Find Increment
-
-**Symptoms**: Don't know which increment is active
-
-**Solutions**:
-1. Check status: `/specweave:status` (shows all increments)
-2. Check progress: `/specweave:progress` (shows active increment)
-3. View active: `cat .specweave/state/active-increment.json`
-
-### More Help
-
-**Documentation**: https://spec-weave.com/docs/troubleshooting
-**GitHub Issues**: https://github.com/anton-abyzov/specweave/issues
-**Discussions**: https://github.com/anton-abyzov/specweave/discussions
-
----
-
-## Getting Started
-
-**Create your first feature**:
-```bash
-/specweave:increment "your feature description"
-```
-
-**Typical Workflow**:
-1. `/specweave:increment "feature"` → SpecWeave creates specs
-2. Review specs (spec.md, plan.md, tasks.md)
-3. `/specweave:do` → Claude implements the code
-4. `/specweave:progress` → Check status anytime
-5. `/specweave:validate 0001` → Validate quality (optional)
-6. `/specweave:done 0001` → Close when complete
-
-**Remember**:
-- Type `/specweave:increment` first, THEN implement
-- Keep root clean (use increment folders)
-- All agents/skills activate automatically
-
-**SpecWeave Documentation**: https://spec-weave.com
-
----
-
-**Last Updated**: Auto-updated via SpecWeave hooks
+**SpecWeave**: Specification-first AI development framework