specweave 0.6.8 → 0.7.1

package/CLAUDE.md

@@ -31,10 +31,9 @@ Users receive a different CLAUDE.md via the template system.
 
 ✅ CORRECT - INCREMENT FOLDERS:
 .specweave/increments/0004-plugin-architecture/
-├── spec.md                            # Spec files (core 4)
+├── spec.md                            # Spec files (core 3)
 ├── plan.md
-├── tasks.md
-├── tests.md
+├── tasks.md                           # Tasks with embedded tests
 ├── reports/                           # ✅ PUT REPORTS HERE!
 │   ├── PLUGIN-MIGRATION-COMPLETE.md   # ✅ Completion reports
 │   ├── SESSION-SUMMARY.md             # ✅ Session summaries
@@ -137,11 +136,11 @@ Claude Code isn't just another AI coding assistant - **Anthropic defines the ind
 **When Creating Increments**:
 ```bash
 # ❌ Wrong
-/specweave:inc "0004"
+/specweave:increment "0004"
 
 # ✅ Correct
-/specweave:inc "0004-cost-optimization"
-/specweave:inc "0005-github-sync-enhancements"
+/specweave:increment "0004-cost-optimization"
+/specweave:increment "0005-github-sync-enhancements"
 ```
 
 **Enforcement**:
@@ -157,7 +156,79 @@ Claude Code isn't just another AI coding assistant - **Anthropic defines the ind
 
 ---
 
-## Increment Discipline (v0.6.0+ MANDATORY)
+## Increment Discipline
+
+### Core Philosophy: **ONE Active Increment = Maximum Focus**
+
+Simplified from complex per-type limits to **focus-first architecture**:
+- ✅ **Default**: 1 active increment (maximum productivity)
+- ✅ **Emergency ceiling**: 2 active max (hotfix/bug can interrupt)
+- ✅ **Hard cap**: Never >2 active (enforced)
+
+**Why 1?** Research shows:
+- 1 task = 100% productivity
+- 2 tasks = 20% slower (context switching cost)
+- 3+ tasks = 40% slower + more bugs
+
+### What is an Increment?
+
+**An increment can be any type of work**, not just features. SpecWeave supports six increment types:
+
+| Type | Description | Use When | Can Interrupt? | Examples |
+|------|-------------|----------|----------------|----------|
+| **feature** | Standard feature development | Adding new functionality | No | User authentication, payment integration, real-time chat |
+| **hotfix** | Critical production fixes | Production is broken | ✅ Yes (emergency) | Security patch, critical bug causing downtime |
+| **bug** | Production bugs with SRE investigation | Bug requires root cause analysis | ✅ Yes (emergency) | Memory leak investigation, performance degradation |
+| **change-request** | Stakeholder requests | Business requirements change | No | UI redesign per stakeholder feedback, API contract changes |
+| **refactor** | Code improvement | Technical debt, code quality | No | Extract service layer, migrate to TypeScript, improve test coverage |
+| **experiment** | POC/spike work | Exploring options, prototypes | No* | Evaluate GraphQL vs REST, test new library, architecture spike |
+
+**Notes**:
+- **Experiments auto-abandon** after 14 days of inactivity (prevents accumulation of stale POCs)
+- **Types are for tracking**, not separate limits (git log shows hotfixes vs features)
+- **Single simple rule**: 1 active, allow 2 for emergencies only
+
+**Key Insight**: The increment structure (spec.md, plan.md, tasks.md) works for ALL types. A bug investigation still needs:
+- **spec.md**: What's broken? Why? What's the expected behavior?
+- **plan.md**: How to investigate? What tools? What hypothesis?
+- **tasks.md**: Investigation steps, fix implementation, verification tests
+
+### WIP Limits
+
+**Configuration** (`.specweave/config.json`):
+```json
+{
+  "limits": {
+    "maxActiveIncrements": 1,  // Default: 1 active (focus)
+    "hardCap": 2,               // Emergency ceiling (never exceeded)
+    "allowEmergencyInterrupt": true, // hotfix/bug can interrupt
+    "typeBehaviors": {
+      "canInterrupt": ["hotfix", "bug"], // Emergency types
+      "autoAbandonDays": {
+        "experiment": 14  // Auto-abandon stale experiments
+      }
+    }
+  }
+}
+```
+
+**Enforcement**:
+- **0 active** → Create new (no warnings)
+- **1 active** → Warn about context switching (allow with confirmation)
+- **2 active** → HARD BLOCK (must complete or pause one first)
+
+**Exception**: Hotfix/bug can interrupt to start 2nd active (emergency only)
+
+**Multiple hotfixes?** Combine into ONE increment:
+```bash
+# ❌ Wrong: Multiple hotfix increments
+0009-sql-injection-fix
+0010-xss-vulnerability-fix
+0011-csrf-token-fix
+
+# ✅ Right: Combined hotfix increment
+0009-security-fixes (SQL + XSS + CSRF)
+```
 
 **⛔ THE IRON RULE: You CANNOT start increment N+1 until increment N is DONE**
 
@@ -165,14 +236,14 @@ This is **NOT negotiable**. It is a **hard enforcement** to prevent chaos, scope
 
 ### Why This Rule Exists
 
-**The Problem (before v0.6.0)**:
+**The Problem**:
 - Multiple incomplete increments piling up (0002, 0003, 0006 all in progress)
 - No clear source of truth ("which increment are we working on?")
 - Living docs become stale (sync doesn't know what's current)
 - Scope creep (jumping between features without finishing)
 - Quality degradation (tests not run, docs not updated)
 
-**The Solution (v0.6.0+)**:
+**The Solution**:
 - ✅ **Hard block** on `/specweave:inc` if previous increments incomplete
 - ✅ **Helper commands** to close increments properly
 - ✅ **Clear guidance** on how to resolve incomplete work
@@ -191,7 +262,7 @@ An increment is DONE if **ONE** of the following is true:
 **When you try to start a new increment**:
 
 ```bash
-/specweave:inc "new feature"
+/specweave:increment "new feature"
 ```
 
 **If previous increments are incomplete, you'll see**:
@@ -241,7 +312,7 @@ Previous increments are incomplete:
 /specweave:do
 
 # Once all tasks done, it's automatically complete
-/specweave:inc "new feature"  # ✅ Now works!
+/specweave:increment "new feature"  # ✅ Now works!
 ```
 
 #### Option 2: Close Interactively
@@ -274,7 +345,7 @@ Previous increments are incomplete:
 
 ```bash
 # Bypass the check (USE SPARINGLY!)
-/specweave:inc "urgent-hotfix" --force
+/specweave:increment "urgent-hotfix" --force
 
 # This is logged and should be explained in the next standup/PR
 ```
@@ -291,7 +362,7 @@ Remove parts from `spec.md`, regenerate `plan.md` and `tasks.md` to match reduce
 # 1. Edit spec.md - remove features you're not doing
 # 2. Delete plan.md and tasks.md
 # 3. Regenerate from spec
-/specweave:inc "same increment" --regenerate
+/specweave:increment "same increment" --regenerate
 
 # Now tasks match reduced scope → 100% complete!
 ```
@@ -363,16 +434,16 @@ Result: Clean increments, clear progress, shipping regularly
 
 **Scenario**: You have 0002 at 73% complete, want to start 0006.
 
-**Before v0.6.0** (broken):
+**Old approach** (broken):
 ```bash
-/specweave:inc "0006-i18n"
+/specweave:increment "0006-i18n"
 # ✅ Creates 0006 (no check)
 # Result: 0002, 0003, 0006 all incomplete
 ```
 
-**After v0.6.0** (disciplined):
+**Current approach** (disciplined):
 ```bash
-/specweave:inc "0006-i18n"
+/specweave:increment "0006-i18n"
 # ❌ Blocked! "Close 0002 and 0003 first"
 
 # Check status
@@ -385,7 +456,7 @@ Result: Clean increments, clear progress, shipping regularly
 # Select 0003 → Move tasks to 0007 (defer work)
 
 # Now can proceed
-/specweave:inc "0006-i18n"
+/specweave:increment "0006-i18n"
 # ✅ Works! Clean slate, disciplined workflow
 ```
 
@@ -394,7 +465,7 @@ Result: Clean increments, clear progress, shipping regularly
 For **emergencies only** (hotfixes, urgent features):
 
 ```bash
-/specweave:inc "urgent-security-fix" --force
+/specweave:increment "urgent-security-fix" --force
 ```
 
 **This bypasses the check** but:
@@ -411,6 +482,164 @@ For **emergencies only** (hotfixes, urgent features):
 
 ---
 
+## Test-Aware Planning
+
+**MAJOR ARCHITECTURE CHANGE**: Tests are now embedded in tasks.md instead of separate tests.md file.
+
+### Why the Change?
+
+**OLD Format**:
+- ❌ Separate tests.md file (duplication, sync issues)
+- ❌ Manual TC-ID management (TC-001, TC-002, etc.)
+- ❌ No BDD format (hard to understand test intent)
+- ❌ Tests disconnected from tasks (traceability gaps)
+
+**NEW Format**:
+- ✅ Tests embedded in tasks.md (single source of truth)
+- ✅ BDD format (Given/When/Then - clear intent)
+- ✅ AC-ID traceability (spec.md → tasks.md → tests)
+- ✅ Test-first workflow (TDD supported naturally)
+- ✅ Coverage targets per task (realistic 80-90%, not 100%)
+
+### Quick Workflow Example
+
+**Step 1: Create increment** → PM agent generates spec.md with user stories and AC-IDs:
+
+```bash
+/specweave:increment "Add user authentication"  # → generates spec.md with AC-US1-01, AC-US1-02, etc.
+```
+
+**spec.md excerpt** (acceptance criteria with AC-IDs):
+
+### US1: Basic Login Flow
+**Acceptance Criteria**:
+- [ ] **AC-US1-01**: User can log in with valid email/password (P1, testable)
+- [ ] **AC-US1-02**: Invalid credentials show error (P1, testable)
+- [ ] **AC-US1-03**: 5 failed attempts lock account 15min (P2, testable)
+```
+
+**Step 2: Architect creates plan.md** with architecture and test strategy (85% unit, 80% integration, 100% E2E critical path)
+
+**Step 3: test-aware-planner generates tasks.md** with embedded tests:
+
+```markdown
+---
+increment: 0008-user-authentication
+total_tasks: 5
+test_mode: TDD
+coverage_target: 85%
+---
+
+# Tasks for Increment 0008: User Authentication
+
+## T-001: Implement Authentication Service (FULL EXAMPLE)
+
+**AC**: AC-US1-01, AC-US1-02, AC-US1-03
+
+**Test Plan** (BDD format):
+- **Given** user with valid credentials → **When** login → **Then** receive JWT token + timestamp update
+
+**Test Cases**:
+- Unit (`auth.test.ts`): validLogin, invalidPassword, nonexistentUser, rateLimiting → 90% coverage
+- Integration (`auth-flow.test.ts`): loginEndpoint, lockedAccount → 85% coverage
+- **Overall: 87% coverage**
+
+**Implementation**: AuthService.ts, password hashing (bcrypt), JWT generation, rate limiting (Redis), TDD tests
+
+---
+
+## T-002 through T-005 (Abbreviated)
+
+- **T-002**: Session Manager (AC-US2-01, AC-US2-02) - session persistence, "Remember Me", 85% coverage, deps: T-001
+- **T-003**: Login API Endpoint (AC-US1-01, AC-US1-02) - REST API, validation, rate limiting, 85% coverage, deps: T-001, T-002
+- **T-004**: Update Documentation - API docs, flow diagram, user guide (validation: manual review, link checker, build check)
+- **T-005**: Security Audit (AC-US1-03) - OWASP scan, password/JWT verification, 90% coverage, deps: T-001, T-002, T-003
+```
+
+**Step 4: Validate** → `/specweave:check-tests 0008` shows per-task coverage, AC-ID coverage, missing tests, recommendations
+
+**AC-ID Format**: `AC-US{story}-{number}` (e.g., AC-US1-01) enables traceability from spec.md → tasks.md → tests
+
+### Agent Invocation (increment-planner skill)
+
+The `increment-planner` skill automatically invokes the `test-aware-planner` agent:
+
+```markdown
+STEP 4: Invoke Test-Aware Planner Agent (🚨 MANDATORY - USE TASK TOOL)
+
+Task(
+  subagent_type: "test-aware-planner",
+  description: "Generate tasks with embedded tests",
+  prompt: "Create tasks.md with embedded test plans for: [user feature description]
+
+  FIRST, read the increment files:
+  - .specweave/increments/0008-user-authentication/spec.md
+  - .specweave/increments/0008-user-authentication/plan.md
+
+  Generate tasks.md with:
+  - Test Plan (Given/When/Then in BDD format)
+  - Test Cases (unit/integration/E2E with file paths)
+  - Coverage Targets (80-90% overall)
+  - Implementation steps
+  - Ensure all AC-IDs from spec.md are covered"
+)
+```
+
+### TDD Workflow Mode
+
+When `test_mode: TDD` in tasks.md frontmatter:
+
+**Red → Green → Refactor**:
+1. **Red**: Write failing test first
+2. **Green**: Implement minimal code to pass test
+3. **Refactor**: Improve code while keeping tests green
+
+**Example**:
+```bash
+# 1. RED - Write failing test
+vim tests/unit/services/auth.test.ts
+npm test  # ❌ Fails (expected)
+
+# 2. GREEN - Implement feature
+vim src/services/auth/AuthService.ts
+npm test  # ✅ Passes
+
+# 3. REFACTOR - Improve code
+vim src/services/auth/AuthService.ts
+npm test  # ✅ Still passes
+```
+
+### Migration from OLD Format
+
+**If you have increments with tests.md**:
+
+```bash
+# Option 1: Keep old format (works, but deprecated)
+# No action needed - old increments continue to work
+
+# Option 2: Migrate to new format (recommended)
+# 1. Extract tests from tests.md
+# 2. Embed them in tasks.md for each task
+# 3. Delete tests.md
+# 4. Run /specweave:check-tests to validate
+```
+
+**Note**: New increments ONLY use tasks.md format. Backward compatibility removed per user feedback (greenfield product).
+
+### Quick Reference
+
+| Aspect | OLD (tests.md) | NEW (tasks.md) |
+|--------|---------------|----------------|
+| **File** | Separate tests.md | Embedded in tasks.md |
+| **Format** | TC-IDs (TC-001) | Function names + BDD |
+| **Traceability** | Manual | Automatic (AC-IDs) |
+| **BDD** | No | Yes (Given/When/Then) |
+| **Sync Issues** | Yes (tasks ↔ tests) | No (single file) |
+| **Coverage** | Per test case | Per task + overall |
+| **TDD Support** | Limited | Native (test_mode: TDD) |
+
+---
+
 ## Root-Level .specweave/ Folder (MANDATORY)
 
 **CRITICAL ARCHITECTURE RULE**: SpecWeave ONLY supports root-level `.specweave/` folders. Nested `.specweave/` folders are NOT supported and MUST be prevented.
@@ -527,7 +756,7 @@ git init && npx specweave init .
 mkdir -p services/{user,order,payment}
 
 # Work normally - SpecWeave sees all services
-/specweave:inc "0001-add-service-mesh"
+/specweave:increment "0001-add-service-mesh"
 # Creates: .specweave/increments/0001-add-service-mesh/
 # Can reference: services/user-service/, infrastructure/k8s/, etc.
 ```
@@ -594,16 +823,16 @@ if (parentSpecweave) {
 
 ---
 
-## Project Scale (v0.4.0 - Plugin Architecture)
+## Project Scale - Plugin Architecture
 
 ### Core Plugin (Always Auto-Loaded)
 
 **Plugin**: `specweave` - The essential SpecWeave plugin loaded in every project:
-- **Skills**: 9 skills (increment-planner, tdd-workflow, rfc-generator, context-loader, project-kickstarter, brownfield-analyzer, brownfield-onboarder, increment-quality-judge, context-optimizer)
+- **Skills**: 9 skills (increment-planner, tdd-workflow, spec-generator, context-loader, project-kickstarter, brownfield-analyzer, brownfield-onboarder, increment-quality-judge, context-optimizer)
 - **Agents**: 22 agents (PM, Architect, Tech Lead, + 19 specialized including tdd-orchestrator)
 - **Commands**: 22 commands (/specweave:inc, /specweave:do, /specweave:next, /specweave:done, /specweave:progress, /specweave:validate, /specweave:sync-docs, + 15 specialized)
 - **Hooks**: 8 lifecycle hooks
-- **Size**: ~12K tokens (vs. 50K in v0.3.7)
+- **Size**: ~12K tokens
 
 **Result**: **75%+ context reduction** out of the box!
 
@@ -615,7 +844,7 @@ if (parentSpecweave) {
 
 ### Available Plugins (Opt-In)
 
-**Implemented Plugins** (v0.4.0):
+**Implemented Plugins**:
 
 | Plugin | Skills | Agents | Commands | Status |
 |--------|--------|--------|----------|--------|
@@ -664,12 +893,12 @@ if (parentSpecweave) {
 
 ### Context Efficiency Examples
 
-**Before (v0.3.7)** - Monolithic:
+**Before** - Monolithic approach:
 - Simple React app: Loads ALL 44 skills + 20 agents ≈ **50K tokens**
 - Backend API: Loads ALL 44 skills + 20 agents ≈ **50K tokens**
 - ML pipeline: Loads ALL 44 skills + 20 agents ≈ **50K tokens**
 
-**After (v0.4.0)** - Modular:
+**After** - Modular plugin architecture:
 - Simple React app: Core + frontend-stack + github ≈ **16K tokens** (68% reduction!)
 - Backend API: Core + nodejs-backend + github ≈ **15K tokens** (70% reduction!)
 - ML pipeline: Core + ml-ops + github ≈ **18K tokens** (64% reduction!)
@@ -683,7 +912,7 @@ if (parentSpecweave) {
 
 When you run `specweave init`:
 
-1. ✅ **GitHub Marketplace Registration** (v0.6.7+)
+1. ✅ **GitHub Marketplace Registration**
    - Creates `.claude/settings.json` with GitHub marketplace reference
    - **No local copying** - plugins fetched from GitHub on-demand
    - Settings.json structure:
@@ -703,7 +932,7 @@ When you run `specweave init`:
    - Claude Code automatically discovers plugins from GitHub
    - No manual `/plugin marketplace add` needed!
 
-2. ✅ **Core Plugin Auto-Installation** (v0.6.1+)
+2. ✅ **Core Plugin Auto-Installation**
    - Automatically runs: `claude plugin marketplace add` and `claude plugin install specweave@specweave`
    - Works via CLI during init (uses user's shell to access `claude` command)
    - Slash commands available IMMEDIATELY - no manual install!
@@ -714,13 +943,13 @@ When you run `specweave init`:
    - Based on project detection (Git, package.json, etc.)
    - User can install now or later
 
-**Key Architectural Change (v0.6.7)**:
+**Key Architectural Change**:
 - ❌ Old: Copied `.claude-plugin/` + `plugins/` to every project (~2MB bloat)
 - ✅ New: Reference GitHub marketplace (~2KB settings.json, always up-to-date)
 
 #### Phase 2: Increment Planning (On-Demand Loading)
 
-When you create increments (e.g., `/specweave:inc "Add Stripe billing"`):
+When you create increments (e.g., `/specweave:increment "Add Stripe billing"`):
 
 1. **Spec Analysis** (NEW! v0.6.0+)
    - increment-planner skill scans spec.md content
@@ -791,7 +1020,7 @@ All plugin management happens through Claude Code's native commands:
 ```
 specweave/  (GitHub repo - Contributors)
 ├── .claude/
-│   └── settings.json              # Local path reference
+│   └── settings.json              # Empty or minimal (no local paths supported)
 ├── .claude-plugin/
 │   └── marketplace.json           # Marketplace definition
 └── plugins/
@@ -799,20 +1028,20 @@ specweave/  (GitHub repo - Contributors)
     └── specweave-github/          # Plugin SOURCE CODE
 ```
 
-**Settings.json for development** (.claude/settings.json):
-```json
-{
-  "extraKnownMarketplaces": {
-    "specweave": "../.claude-plugin"
-  }
-}
-```
+**Marketplace setup for development** (use CLI, NOT settings.json):
+
+Local paths are **NOT supported** in `extraKnownMarketplaces` in settings.json. Use CLI instead:
 
-**OR use CLI** (recommended for contributors):
 ```bash
+# Add local marketplace (only way for development)
 /plugin marketplace add ./.claude-plugin
+
+# Then install plugins
+/plugin install specweave@specweave
 ```
 
+**Why CLI-only?** Claude Code's `extraKnownMarketplaces` in settings.json only supports remote sources (GitHub, Git). Local paths must be added via CLI commands.
+
 #### User Projects (Production)
 
 ```
@@ -842,8 +1071,8 @@ my-saas-app/  (User's project)
 **Key Differences**:
 - ✅ **Development**: Local `.claude-plugin/` and `plugins/` in repo (for editing)
 - ✅ **Production**: GitHub reference only (no local plugin copies)
-- ✅ **Development**: Use string path `"../​.claude-plugin"`
-- ✅ **Production**: Use GitHub object `{"source": "github", ...}`
+- ✅ **Development**: Use CLI `/plugin marketplace add ./.claude-plugin` (settings.json cannot reference local paths)
+- ✅ **Production**: Use GitHub object in settings.json: `{"source": {"source": "github", ...}}`
 
 No per-project installation needed!
 
@@ -873,7 +1102,7 @@ plugins/                        ← ROOT: All plugins (version controlled)
 ├── specweave/             ← CORE PLUGIN (framework essentials)
 │   ├── .claude-plugin/         ← plugin.json (Claude native)
 │   ├── skills/                 ← Core skills (9 total)
-│   │   ├── rfc-generator/
+│   │   ├── spec-generator/
 │   │   ├── increment-planner/
 │   │   ├── tdd-workflow/
 │   │   └── ...
@@ -913,16 +1142,15 @@ plugins/                        ← ROOT: All plugins (version controlled)
 
 **Rules**:
 - ✅ `src/` = TypeScript code ONLY (compiled to `dist/`)
-- ✅ ALL skills/agents/commands/hooks = Inside plugins (including core!)
+- ✅ ALL skills/agents/commands/hooks = Inside `plugins/` (including core!)
 - ✅ `plugins/specweave/` = Core framework plugin (always loaded)
-- ✅ `.claude/` = Installed from all enabled plugins
+- ✅ `.claude/` = Plugin settings only (settings.json references marketplace)
 - ❌ NEVER mix `*.ts` and `SKILL.md` in the same directory
-- ❌ NEVER edit files in `.claude/` directly (they get overwritten)
 - ❌ NEVER create new files in project root (use increment folders)
 
 **Key Architectural Principle**:
 - TypeScript code (`*.ts`) goes in `src/` → compiled to `dist/`
-- Claude-native files (`SKILL.md`, `AGENT.md`, `*.md`) go in `plugins/` → copied to `.claude/`
+- Claude-native files (`SKILL.md`, `AGENT.md`, `*.md`) stay in `plugins/` → loaded directly by Claude Code
 - Even "core" framework components are in `plugins/specweave/` (everything is a plugin!)
 - This separation ensures clean builds and prevents mixing compiled code with runtime files
 
@@ -988,7 +1216,7 @@ specweave/
 │   │   ├── .claude-plugin/
 │   │   │   └── plugin.json     # Claude native manifest
 │   │   ├── skills/             # Core skills (9 total)
-│   │   │   ├── rfc-generator/          # RFC generation for increments
+│   │   │   ├── spec-generator/         # Specification generation for increments
 │   │   │   ├── increment-planner/      # Increment planning and spec generation
 │   │   │   ├── context-loader/         # Context loading optimization
 │   │   │   ├── tdd-workflow/           # Test-driven development workflow
@@ -1046,23 +1274,22 @@ specweave/
 │   │   ├── 0002-core-enhancements/
 │   │   │   ├── spec.md
 │   │   │   ├── plan.md
-│   │   │   ├── tasks.md
-│   │   │   ├── tests.md
+│   │   │   ├── tasks.md        # Tasks with embedded tests (v0.7.0+)
 │   │   │   ├── logs/           # ✅ Session logs go here
 │   │   │   ├── scripts/        # ✅ Helper scripts
 │   │   │   └── reports/        # ✅ Analysis files
 │   │   └── _backlog/
 │   ├── docs/
-│   │   ├── internal/           # Strategic docs (NEVER published)
-│   │   │   ├── strategy/       # Business strategy, market analysis
-│   │   │   ├── rfc/            # ✅ Request for Comments (proposals at all stages)
-│   │   │   ├── architecture/   # Technical architecture (accepted designs)
-│   │   │   │   ├── adr/        # Architecture Decision Records
-│   │   │   │   ├── diagrams/   # Mermaid + SVG
-│   │   │   │   └── hld-system.md # High-Level Design
-│   │   │   ├── delivery/       # Implementation notes, runbooks
-│   │   │   ├── operations/     # Runbooks, SLOs
-│   │   │   └── governance/     # Security, compliance
+│   │   ├── internal/           # Strategic docs (NEVER published) - 6 core folders
+│   │   │   ├── strategy/       # Business rationale, vision, PRDs, OKRs
+│   │   │   ├── rfc/            # Feature specifications (detailed requirements, project history)
+│   │   │   │   └── rfc-####-{name}.md  # User stories, AC, implementation plans
+│   │   │   ├── architecture/   # Technical design (HLD, LLD, ADR, diagrams)
+│   │   │   │   ├── adr/        # Architecture Decision Records (why we chose X over Y)
+│   │   │   │   └── diagrams/   # Mermaid + SVG (C4 model diagrams)
+│   │   │   ├── delivery/       # Build & release processes (roadmap, DORA, branching)
+│   │   │   ├── operations/     # Production operations (runbooks, SLOs, incidents)
+│   │   │   └── governance/     # Policies (security, compliance, coding standards)
 │   │   └── public/             # User-facing docs (can publish)
 │   │       ├── guides/
 │   │       └── api/
@@ -1137,6 +1364,395 @@ specweave/
 
 ---
 
+## Internal Documentation Structure
+
+**Location**: `.specweave/docs/internal/` - Six core folders for engineering playbook
+
+**Quick Reference**:
+
+| Folder | Purpose | Use When | Examples |
+|--------|---------|----------|----------|
+| **strategy/** | Business rationale (Why?) | Defining business case for features | `prd-user-auth.md` |
+| **specs/** | Feature specifications (What?) | Detailed requirements with user stories | `spec-0007-smart-discipline.md` |
+| **architecture/** | Technical design (How?) | System architecture, decisions | `hld-system.md`, `adr/0001-postgres.md` |
+| **delivery/** | Build & release (How we build) | Git workflow, DORA metrics, CI/CD | `branch-strategy.md`, `dora-metrics.md` |
+| **operations/** | Production ops (How we run) | Runbooks, incidents, performance | `runbook-api.md`, `performance-tuning.md` |
+| **governance/** | Policies (Guardrails) | Security, compliance, coding standards | `security-policy.md`, `coding-standards.md` |
+
+**Document Flow**: `PRD → Spec → Architecture → Delivery → Operations`
+
+**See**: [Internal Docs README](.specweave/docs/internal/README.md) for complete guidance
+
+---
+
+## Specs Architecture: Two Locations Explained
+
+**CRITICAL ARCHITECTURAL CONCEPT**: SpecWeave uses specs in TWO locations for different purposes. Understanding this distinction is essential.
+
+### The Core Question: Why Two Locations?
+
+1. **Living Docs Specs**: `.specweave/docs/internal/specs/spec-NNN-feature-area.md` - **Permanent, feature-level knowledge base**
+2. **Increment Specs**: `.specweave/increments/####-name/spec.md` - **Temporary, focused implementation snapshot**
+
+**Key Difference**: Specs use **3-digit numbers** (001, 002, 003) for **feature areas**, increments use **4-digit numbers** (0001, 0002, 0003) for **implementations**.
+
+### The Answer: Permanent vs Temporary
+
+**Living Docs Specs = Permanent, Feature-Level Knowledge Base**
+
+- **Location**: `.specweave/docs/internal/specs/spec-001-core-framework-architecture.md`
+- **Purpose**: COMPLETE, PERMANENT source of truth for entire feature area
+- **Lifecycle**: Created once, updated over time, NEVER deleted
+- **Scope**: Comprehensive feature area (e.g., "Core Framework", 10-50 user stories)
+- **Contains**:
+  - ✅ ALL user stories for the feature area (across multiple increments)
+  - ✅ ALL acceptance criteria for those user stories
+  - ✅ Implementation history (which increments implemented which parts)
+  - ✅ Links to brownfield documentation (existing project docs)
+  - ✅ External PM tool links (GitHub Project, Jira Epic, ADO Feature)
+  - ✅ Architecture decisions rationale (ADRs)
+  - ✅ Success criteria & metrics for the feature area
+
+**Increment Specs = Temporary, Focused Implementation Snapshot**
+
+- **Location**: `.specweave/increments/0001-core-framework/spec.md`
+- **Purpose**: TEMPORARY implementation reference (what am I building THIS iteration?)
+- **Lifecycle**: Created per increment, can be deleted after completion
+- **Scope**: Focused subset (3-5 user stories for this increment only)
+- **Contains**:
+  - ✅ Reference to living docs: `"See: SPEC-001-core-framework-architecture"`
+  - ✅ Subset of user stories: `"Implements: US-001, US-002, US-003 only"`
+  - ✅ What's being implemented RIGHT NOW (this iteration)
+  - ✅ Out of scope: Lists what's NOT in this increment (deferred to future increments)
+
+### Real-World Example: SpecWeave Core Framework
+
+**Living Docs Spec** (Permanent, Feature-Level):
+```
+File: .specweave/docs/internal/specs/spec-001-core-framework-architecture.md
+
+# SPEC-001: Core Framework & Architecture
+Foundation framework with CLI, plugin system, cross-platform support
+
+## Increments (Implementation History)
+- 0001-core-framework: MVP CLI, skills, agents (Complete)
+- 0002-core-enhancements: Context optimization, PM agent (Complete)
+- 0004-plugin-architecture: Claude native plugins (Complete)
+- 0005-cross-platform-cli: Windows/Mac/Linux support (Complete)
+
+## User Stories (35 total across all 4 increments)
+- US-001: NPM installation (0001) ✅
+- US-003: Context optimization (0002) ✅
+- US-005: Plugin system (0004) ✅
+- US-007: Cross-platform CLI (0005) ✅
+... (31 more stories)
+
+## External References
+- GitHub Project: TBD (create for 1.0.0)
+```
+
+**Increment Spec** (Temporary, Implementation-Level):
+```
+File: .specweave/increments/0001-core-framework/spec.md
+
+# Increment 0001: Core Framework MVP
+**Implements**: SPEC-001-core-framework-architecture (US-001 to US-002 only)
+**Complete Specification**: See ../../docs/internal/specs/spec-001-core-framework-architecture.md
+
+## What We're Implementing (This Increment Only)
+- US-001: NPM installation + CLI basics ✅
+- US-002: Plugin system foundation ✅
+
+## Out of Scope (For This Increment)
+- ❌ Context optimization (US-003) → Increment 0002
+- ❌ Claude native plugins (US-005) → Increment 0004
+- ❌ Cross-platform support (US-007) → Increment 0005
+```
+
+### Key Benefits
+
+**Why This Architecture?**
+
+1. **Permanent Knowledge Base**: Living docs = long-term memory. Answer: "How did we build authentication?"
+2. **Focused Implementation**: Increment specs = short-term focus. Answer: "What am I building RIGHT NOW?"
+3. **Brownfield Integration**: Living docs link to existing project documentation, increment specs don't need this complexity
+4. **Clean After Completion**: Delete increment specs (optional), living docs remain as knowledge base
+5. **External PM Tool Integration**: Jira epic → Living docs spec (permanent link), increment specs don't need external links
+
+### When to Use Which?
+
+**Create Living Docs Spec When**:
+- ✅ Planning a major feature (authentication, payments, messaging)
+- ✅ Feature spans multiple increments (will take weeks/months)
+- ✅ Need brownfield integration (link to existing project docs)
+- ✅ Want permanent historical record (how did we build this?)
+- ✅ Need external PM tool link (Jira epic, ADO feature, GitHub milestone)
+
+**Create Increment Spec When**:
+- ✅ Starting implementation of one increment
+- ✅ Want quick reference (what am I building right now?)
+- ✅ Need focused scope (just 3 user stories, not 20)
+
+### Comparison Table
+
+| Aspect | Living Docs Specs | Increment Specs |
+|--------|------------------|----------------|
+| **Location** | `.specweave/docs/internal/specs/` | `.specweave/increments/####/` |
+| **Lifecycle** | ✅ Permanent (never deleted) | ⏳ Temporary (optional deletion) |
+| **Scope** | 📚 Complete feature (20 US) | 🎯 Focused subset (3 US) |
+| **Size** | 500+ lines (comprehensive) | 50-100 lines (focused) |
+| **Purpose** | Knowledge base + history | Implementation tracker |
+| **Coverage** | ALL user stories | SUBSET of user stories |
+| **Brownfield** | ✅ Links to existing docs | ❌ Rarely needed |
+| **External Links** | ✅ Jira, ADO, GitHub | ❌ Rarely needed |
+| **Multiple Increments** | ✅ One spec → many increments | ❌ One increment → one spec |
+| **After Completion** | ✅ Remains forever | ⚠️ Can be deleted |
+
+### Analogy: Wikipedia vs Sticky Notes
+
+- **Living Docs Specs** = 📚 Wikipedia Article (permanent, comprehensive, updated over time)
+- **Increment Specs** = 📝 Sticky Note Reminder (temporary, focused, disposable after done)
+
+### Typical Workflow
+
+**Phase 1: Planning** (PM Agent)
+```
+User: "I want to build a plugin-based framework with CLI"
+PM Agent:
+1. Creates living docs spec:
+   → .specweave/docs/internal/specs/spec-001-core-framework-architecture.md
+   → Contains ALL 35 user stories (comprehensive, feature-level)
+   → Links to GitHub Project (TBD)
+   → Maps to 4 increments (0001, 0002, 0004, 0005)
+```
+
+**Phase 2: Increment 1** (Core MVP)
+```
+User: "/specweave:increment 0001-core-framework"
+PM Agent:
+1. Creates increment spec:
+   → .specweave/increments/0001-core-framework/spec.md
+   → References living docs: "See SPEC-001"
+   → Contains ONLY US-001 to US-002 (focused, this iteration only)
+2. Implementation happens...
+3. Increment completes ✅
+4. Increment spec stays for history (or can be deleted)
+```
+
+**Phase 3: Increment 2** (Enhancements)
+```
+User: "/specweave:increment 0002-core-enhancements"
+PM Agent:
+1. Creates increment spec:
+   → .specweave/increments/0002-core-enhancements/spec.md
+   → References SAME living docs: "See SPEC-001"
+   → Contains ONLY US-003 to US-004 (focused, this iteration only)
+2. Implementation happens...
+3. Increment completes ✅
+```
+
+**Phase 4: All Increments Done!**
+```
+After ALL increments complete (0001, 0002, 0004, 0005):
+- ✅ Living docs spec REMAINS (permanent knowledge base)
+- ⏳ Increment specs can be deleted (optional cleanup)
+- ✅ Complete history preserved in spec-001
+- ✅ GitHub Project linked to SPEC-001 (not increments)
+```
+
+### Relationship
+
+**One living docs spec → Many increment specs**
+
+```
+SPEC-001: Core Framework & Architecture (Living Docs - Permanent, Feature-Level)
+├── 0001-core-framework (Increment - Temporary, Implementation-Level)
+├── 0002-core-enhancements (Increment - Temporary, Implementation-Level)
+├── 0004-plugin-architecture (Increment - Temporary, Implementation-Level)
+└── 0005-cross-platform-cli (Increment - Temporary, Implementation-Level)
+
+SPEC-002: Intelligent AI Capabilities (Living Docs - Permanent, Feature-Level)
+├── 0003-intelligent-model-selection (Increment - Temporary, Implementation-Level)
+├── 0007-smart-increment-discipline (Increment - Temporary, Implementation-Level)
+└── 0009-intelligent-reopen-logic (Increment - Temporary, Implementation-Level)
+```
+
+### Summary
+
+**Two Locations, Two Purposes**:
+
+1. **Living Docs Specs** (`.specweave/docs/internal/specs/`):
+   - ✅ Permanent knowledge base
+   - ✅ Complete feature specification
+   - ✅ Links to brownfield docs
+   - ✅ External PM tool integration
+   - ✅ Spans multiple increments
+
+2. **Increment Specs** (`.specweave/increments/####/`):
+   - ⏳ Temporary implementation tracker
+   - 🎯 Focused subset of work
+   - 📝 Quick reference: "What am I building?"
+   - 🗑️ Can be deleted after completion
+
+**Result**: Clean, focused implementation + permanent knowledge base
+
+**For comprehensive explanation**: See [SPECS-ARCHITECTURE-CLARIFICATION.md](.specweave/increments/0007-smart-increment-discipline/reports/SPECS-ARCHITECTURE-CLARIFICATION.md)
+
+---
+
+## Living Completion Reports
+
+### The Problem with Traditional Reports
+
+**Traditional approach** (report written at the end):
+```
+Start increment: Plan 10 user stories
+During work: Scope changes 5 times (not documented)
+End increment: Write report "Completed 8/10 stories"
+Future: "Why was Story 5 removed?" → No one remembers!
+```
+
+**Problems**:
+- ❌ No audit trail for scope changes
+- ❌ Decision rationale lost
+- ❌ Difficult for onboarding/compliance
+- ❌ Can't learn from past iterations
+
+### Living Reports Solution
+
+**SpecWeave approach** (report updated in real-time):
+```
+Start: Initialize completion report (v1.0)
+During work:
+  - 2025-11-06: Added US6 (dark mode) → /update-scope → v1.1
+  - 2025-11-07: Deferred US3 (CSV export) → /update-scope → v1.2
+  - 2025-11-08: WebSockets → Polling pivot → /update-scope → v1.3
+End: Finalize report with complete scope evolution history
+Future: "Why was Story 5 removed?" → Check report, find exact reason with WHO approved and WHY!
+```
+
+**Benefits**:
+- ✅ Complete audit trail (every scope change documented)
+- ✅ Real-time context (captured when decision is fresh)
+- ✅ Regulatory compliance (explains deviations from plan)
+- ✅ Learning for future increments
+- ✅ Onboarding new team members (understand project history)
+
+### Report Structure
+
+**Location**: `.specweave/increments/{id}/reports/COMPLETION-REPORT.md`
+
+**Sections**:
+1. **Original Scope**: What was planned at increment start
+2. **Scope Evolution**: Living log of changes (updated during increment)
+3. **Final Delivery**: What was actually delivered
+4. **What Changed and Why**: Rationale for scope changes
+5. **Lessons Learned**: What we learned for next time
+6. **Metrics**: Velocity, scope creep, test coverage, defects
+
+### Workflow
+
+**1. Initialize Report** (automatic when increment created):
+```bash
+/specweave:increment "User dashboard"
+# Creates: .specweave/increments/0008-user-dashboard/reports/COMPLETION-REPORT.md (v1.0)
+```
+
+**2. Update During Work** (whenever scope changes):
+```bash
+# Quick log
+/specweave:update-scope "Added dark mode toggle (stakeholder request from CMO, +16 hours)"
+
+# Or interactive
+/specweave:update-scope
+# Prompts:
+#   - What changed? (Added/Removed/Modified)
+#   - Why? (Business reason, technical blocker, etc.)
+#   - Impact? (+/- hours)
+#   - Who approved? (PM, stakeholder, etc.)
+#   - Documentation? (ADR, GitHub issue, etc.)
+```
+
+**3. Finalize at Completion** (via `/specweave:done`):
+```bash
+/specweave:done 0008
+# Validates report completeness
+# Prompts to fill any missing sections
+# Marks increment as complete
+```
+
+### Example Entry
+
+```markdown
+## Scope Evolution (Living Updates)
+
+### 2025-11-06: Added user story
+
+**Changed**: US6: Dark mode toggle
+**Reason**: Stakeholder request from CMO (high priority, blocks marketing launch)
+**Impact**: +16 hours
+**Decision**: PM + CMO
+**Documentation**: GitHub issue #45
+
+---
+
+### 2025-11-07: Removed/deferred user story
+
+**Changed**: US3: Data export to CSV
+**Reason**: Not critical for MVP, can be added later without breaking changes
+**Impact**: -8 hours (deferred to increment 0009)
+**Decision**: PM
+**Documentation**: None
+
+---
+
+### 2025-11-08: Technical pivot (architecture change)
+
+**Changed**: WebSockets → Long-polling
+**Reason**: WebSocket library had critical security vulnerability (CVE-2025-1234)
+**Impact**: -4 hours (simpler implementation)
+**Decision**: Architect + Security Lead
+**Documentation**: ADR-008: Why We Chose Polling Over WebSockets
+
+---
+```
+
+### When to Update
+
+✅ **DO update** when:
+- Adding new user story or task
+- Removing/deferring work
+- Modifying scope of existing story
+- Making architecture pivots (technical decisions)
+- Reducing/expanding scope
+- Blocking issues discovered
+
+❌ **DON'T update** for:
+- Bug fixes discovered during implementation (normal)
+- Minor implementation details
+- Code refactoring (unless scope-affecting)
+
+### Best Practices
+
+1. **Update in real-time**: Don't batch updates (capture context while fresh)
+2. **Be specific**: "Added US6: Dark mode" not "Added feature"
+3. **Include rationale**: Always answer WHY
+4. **Link to docs**: ADR, GitHub issue, Jira ticket
+5. **Track approvals**: Who made the decision
+6. **Quantify impact**: +/- hours for scope changes
+
+### Commands
+
+| Command | Purpose |
+|---------|---------|
+| `/specweave:increment "feature"` | Creates increment with initial completion report |
+| `/specweave:update-scope` | Log scope change during increment |
+| `/specweave:done <id>` | Finalize report and mark increment complete |
+
+**See**: [update-scope.md](plugins/specweave/commands/update-scope.md) for detailed documentation
+
+---
+
 ## Development Workflow
 
 ### Making Changes
@@ -1146,7 +1762,7 @@ specweave/
 **1. Editing Skills** (any plugin):
 ```bash
 # Core plugin (auto-loaded):
-vim plugins/specweave/skills/rfc-generator/SKILL.md
+vim plugins/specweave/skills/spec-generator/SKILL.md
 
 # Other plugins (opt-in):
 vim plugins/specweave-github/skills/github-sync/SKILL.md
@@ -1195,13 +1811,14 @@ npm run build && npm test
    - Acceptance criteria in PRDs
    - Manual validation
 
-2. **Feature Tests** (`.specweave/increments/####/tests.md`)
-   - Test coverage plans per increment
-   - TC-XXXX test case IDs
+2. **Embedded Tests** (`.specweave/increments/####/tasks.md`)
+   - Test plans embedded in tasks (BDD format, v0.7.0+)
+   - AC-ID traceability (AC-US1-01, AC-US1-02, etc.)
 
-3. **Skill Tests** (`tests/specs/{skill-name}/` or `tests/integration/{skill-name}/`)
-   - Test cases for skill functionality
-   - Minimum 3 test cases per skill
+3. **Integration Tests** (`tests/integration/{skill-name}/`)
+   - Tests for plugin and skill functionality
+   - Tool sync (github, ado, jira)
+   - Brownfield detection and other integrations
    - Run via: `npm run test:integration`
 
 4. **Code Tests** (`tests/`)
@@ -1222,7 +1839,7 @@ npm run build && npm test
 
 ### Hooks and Automation
 
-**Post-Task Completion Hook v2.0** (`.claude/hooks/post-task-completion.sh`):
+**Post-Task Completion Hook** (`.claude/hooks/post-task-completion.sh`):
 
 **Smart Session-End Detection**:
 - ✅ Tracks inactivity gaps between TodoWrite calls
@@ -1255,10 +1872,54 @@ Solution: Inactivity-based detection
 - Update `README.md` for user-facing changes
 - Update `CHANGELOG.md` for API changes
 
-**Living Docs Sync** (after `/specweave:do` completes):
-- Run `/specweave:sync-docs update`
-- Updates `.specweave/docs/` with implementation learnings
-- Updates ADRs from Proposed → Accepted
+**Living Docs Sync** (AUTOMATIC after task completion):
+
+**The Critical Problem**: `.specweave/docs/internal/specs/` is the **permanent source of truth** for ALL completed work across the entire enterprise. Without automatic sync, this documentation becomes stale and incomplete.
+
+**How It Works** (Automatic):
+1. **Hook Triggers**: After every task completion (TodoWrite), `post-task-completion.sh` fires
+2. **Sync Check**: Runs `dist/hooks/lib/sync-living-docs.js` to check if sync is needed
+3. **Automatic Sync**: If enabled in config, syncs increment specs to living docs
+4. **Result**: `.specweave/docs/internal/specs/spec-{id}.md` is always up-to-date
+
+**Configuration** (`.specweave/config.json`):
+```json
+{
+  "hooks": {
+    "post_task_completion": {
+      "sync_living_docs": true,        // ✅ MUST be true!
+      "sync_tasks_md": true,           // Updates tasks.md with completion status
+      "external_tracker_sync": true    // Syncs to GitHub/Jira/ADO
+    }
+  }
+}
+```
+
+**Manual Sync** (when automatic sync was disabled):
+```bash
+# Sync all completed increments to living docs
+/specweave:sync-docs update
+
+# Or copy manually (emergency only):
+cp .specweave/increments/0001-core-framework/spec.md \
+   .specweave/docs/internal/specs/spec-0001-core-framework.md
+```
+
+**Verify Sync**:
+```bash
+# Check all synced specs
+ls -1 .specweave/docs/internal/specs/spec-*.md
+
+# Should match number of completed increments
+ls -1 .specweave/increments/ | grep -E '^[0-9]{4}' | wc -l
+```
+
+**Why This Matters**:
+- ✅ **Enterprise-level traceability**: Every increment's spec is permanently archived
+- ✅ **Cross-increment history**: See all work completed across the entire project
+- ✅ **Onboarding new developers**: Read specs to understand what was built and why
+- ✅ **Compliance & auditing**: Complete audit trail of all product decisions
+- ✅ **Living documentation**: Specs stay up-to-date without manual intervention
 
 ---
 
@@ -1330,7 +1991,7 @@ plugins/specweave-{name}/
 ```
 Is this feature...
 ├─ Used by EVERY project? → specweave (auto-loaded)
-│  Examples: increment-planner, rfc-generator, tdd-workflow, PM/Architect agents
+│  Examples: increment-planner, spec-generator, tdd-workflow, PM/Architect agents
 │
 ├─ Part of increment lifecycle? → specweave (auto-loaded)
 │  Examples: /specweave:inc, /specweave:do, living docs hooks
@@ -1433,9 +2094,53 @@ vim .claude-plugin/marketplace.json
 
 ## Release Process
 
+### Versioning Strategy
+
+**IMPORTANT**: SpecWeave follows semantic versioning (semver), but version bumps are **MANUAL** and controlled:
+
+**The Rules**:
+- ✅ **Patch version** (0.7.X) - Increment ONLY when explicitly requested by maintainer
+- ✅ **Minor version** (0.X.0) - Increment ONLY when maintainer says to
+- ✅ **Major version** (X.0.0) - Increment ONLY when maintainer says to
+- ❌ **NEVER auto-increment** versions after each increment completion
+
+**Why Manual Control?**
+- Multiple increments may be part of the same release (e.g., 0.7.0 = increments 0006 + 0007 + 0008)
+- Version bumps signal user-facing releases, not internal development progress
+- Maintainer decides when features are ready to ship
+- Prevents version number inflation (e.g., jumping from 0.7.0 to 0.12.0 in one day)
+
+**When Completing Increments**:
+```bash
+# ❌ WRONG - Don't auto-bump version
+git commit -m "feat: complete increment 0008"
+npm version patch  # ❌ NO! Wait for maintainer approval
+
+# ✅ CORRECT - Just commit the work
+git commit -m "feat: complete increment 0008"
+# Version stays at 0.7.0 until maintainer says to bump
+```
+
+**When Maintainer Requests Version Bump**:
+```bash
+# Maintainer says: "Bump to 0.7.1"
+npm version patch  # ✅ Now bump
+npm publish        # ✅ And publish
+
+# Maintainer says: "Bump to 0.8.0"
+npm version minor  # ✅ New minor version
+npm publish
+```
+
+**Summary**: Complete increments → commit code → maintainer decides when to bump version and publish.
+
+---
+
+### NPM Publishing
+
 **NPM Publishing**:
 ```bash
-# 1. Update version
+# 1. Update version (ONLY when maintainer requests)
 npm version patch|minor|major
 
 # 2. Update CHANGELOG.md
@@ -1496,7 +2201,7 @@ Other tools simply can't match these capabilities. The adapters remain in the co
 - **Plugin components**: `plugins/specweave-{name}/{skills|agents|commands}/`
 - **Tests**: `tests/integration/{component-name}/` or `tests/unit/`
 
-**For detailed instructions**: See "Adding a New Plugin (Contributors)" section above (line ~1250)
+**For detailed instructions**: See "Adding a New Plugin (Contributors)" section above
 
 ### Update Documentation
 
@@ -1512,21 +2217,106 @@ vim docs-site/docs/guides/getting-started.md
 cd docs-site && npm run build
 ```
 
+### Translation Workflow (Multilingual Support)
+
+**SpecWeave supports multilingual development** via post-generation translation (Increment 0006).
+
+**Key Concept**: Users work in their native language (great UX), system auto-translates to English (maintainable docs).
+
+**Workflow**:
+
+```bash
+# 1. User creates increment in Russian
+/specweave:increment "Добавить пользовательскую аутентификацию"
+
+# 2. PM agent generates spec.md in Russian (natural, user-friendly)
+
+# 3. post-increment-planning hook fires automatically
+#    - Detects Russian content
+#    - Translates spec.md, plan.md, tasks.md to English (~$0.01 cost)
+#    - Files now in English (maintainable)
+
+# User sees:
+# ✅ Increment created
+# 🌐 Detected Russian content. Translating to English...
+#   📄 spec.md... ✅
+#   📄 plan.md... ✅
+#   📄 tasks.md... ✅
+# ✅ Translation complete! Cost: ~$0.01
+```
+
+**Configuration** (`.specweave/config.json`):
+
+```json
+{
+  "language": "ru",
+  "translation": {
+    "enabled": true,
+    "autoTranslateInternalDocs": true,
+    "autoTranslateLivingDocs": false,
+    "keepFrameworkTerms": true,
+    "keepTechnicalTerms": true,
+    "translationModel": "haiku"
+  }
+}
+```
+
+**Key Settings**:
+- `language`: Primary language (en, ru, es, zh, de, fr, ja, ko, pt)
+- `autoTranslateInternalDocs`: Auto-translate spec/plan/tasks to English (default: true)
+- `autoTranslateLivingDocs`: Auto-translate ADRs/HLDs after task completion (default: false)
+- `translationModel`: Model to use (haiku/sonnet/opus, default: haiku)
+
+**Supported Languages**:
+- English (en)
+- Russian (ru)
+- Spanish (es)
+- Chinese (zh)
+- German (de)
+- French (fr)
+- Japanese (ja)
+- Korean (ko)
+- Portuguese (pt)
+
+**Cost**: ~$0.01 per increment (3 files, Haiku model)
+
+**Implementation Details**:
+- Language detection: Heuristic-based (<1ms, zero cost)
+- Code preservation: Never translates code blocks, inline code, or links
+- Validation: Checks heading count, code block count, link count, YAML structure
+- See: `.specweave/increments/0006-llm-native-i18n/reports/IMPLEMENTATION-COMPLETE.md`
+
+**Testing Translation Utilities**:
+
+```bash
+# Run translation unit tests
+npm test -- tests/unit/i18n/translation.test.ts
+
+# Test result: 67/67 passing (100%)
+```
+
+**Files**:
+- Utilities: `src/utils/translation.ts` (673 lines, 11 languages)
+- CLI Script: `src/hooks/lib/translate-file.ts` (398 lines)
+- Hook: `plugins/specweave/hooks/post-increment-planning.sh` (307 lines)
+- Tests: `tests/unit/i18n/translation.test.ts` (705 lines, 67 tests)
+- Schema: `src/core/schemas/specweave-config.schema.json`
+
 ---
 
 ## Troubleshooting
 
 **Skills not activating?**
-1. Check YAML frontmatter in `SKILL.md`
-2. Verify installation: `ls ~/.claude/skills/skill-name/`
+1. Check plugin is installed: `/plugin list --installed`
+2. Verify YAML frontmatter in `plugins/{plugin}/skills/{skill}/SKILL.md`
 3. Restart Claude Code
 4. Check description has clear trigger keywords
 
 **Commands not working?**
-1. Verify file in `.claude/commands/`
-2. Check YAML frontmatter
-3. Restart Claude Code
-4. Check command name matches file name
+1. Check plugin is installed: `/plugin list --installed`
+2. Verify command exists: `plugins/{plugin}/commands/{command}.md`
+3. Check YAML frontmatter
+4. Restart Claude Code
 
 **Tests failing?**
 1. Run `npm run build` first
@@ -1563,36 +2353,50 @@ cd docs-site && npm run build
 
 **Commands (for SpecWeave development)**:
 
-*Convenient short forms (use daily)*:
-- `/inc "feature"` - Plan new increment
-- `/do` - Execute tasks (smart resume)
-- `/done 0002` - Close increment
-- `/validate 0002` - Validate increment
+**IMPORTANT**: All commands MUST use the `/specweave:*` namespace prefix to avoid conflicts with Claude Code's native commands.
 
-*Full namespace forms (explicit, avoids conflicts)*:
-- `/specweave:inc "feature"` - Plan new increment
+*Primary commands*:
+- `/specweave:increment "feature"` - Plan new increment
 - `/specweave:do` - Execute tasks (smart resume)
 - `/specweave:done 0002` - Close increment
 - `/specweave:validate 0002` - Validate increment
-- `/specweave:progress` - Check status
-- `/specweave:sync-docs update` - Sync living docs
+- `/specweave:qa 0002` - Quality assessment with risk scoring
+- `/specweave:status` - Show increment status overview
+- `/specweave:progress` - Check current increment progress
+- `/specweave:check-tests` - Validate test coverage (NEW format)
+
+*State management (mostly automatic)*:
+- `/specweave:pause 0002 --reason="..."` - Pause active increment
+- `/specweave:resume 0002` - Resume paused increment
+- `/specweave:abandon 0002 --reason="..."` - Abandon increment
+
+*Documentation sync*:
+- `/specweave:sync-docs update` - Sync living docs after implementation
+- `/specweave:sync-tasks` - Sync tasks with completion status
+
+*Other commands*:
+- `/specweave:costs` - Show AI cost dashboard
+- `/specweave:translate` - Translate content
+- `/specweave:update-scope` - Log scope changes
+- `/specweave:next` - Smart increment transition
+
+**NO SHORTCUTS**: Do NOT use shortcuts like `/inc`, `/do`, `/pause`, `/resume` etc. They conflict with Claude Code's native commands and will break functionality.
 
-**Both forms work identically** - use short forms for speed, namespace forms for clarity.
+**File naming**: All commands are `specweave-{name}.md` (e.g., `specweave-increment.md`)
 
 **Build & Test**:
 - `npm run build` - Compile TypeScript
-- `npm test` - Run all unit tests
+- `npm test` - Run unit tests (includes skill tests in `tests/unit/`, `tests/integration/`)
 - `npm run test:e2e` - Run Playwright E2E tests
 - `npm run test:integration` - Run integration tests
-- `npm run install:all` - Sync src/ to .claude/
 
 **File Structure**:
-- Source of truth: `src/`
-- Installed: `.claude/`
+- Source of truth: `src/` (TypeScript) and `plugins/` (skills/agents/commands)
+- Plugin settings: `.claude/settings.json` (marketplace references)
 - Increments: `.specweave/increments/`
-- Internal Docs (strategy, architecture): `.specweave/docs/internal/`
-- Public Docs (user guides): `.specweave/docs/public/` and `docs-site/`
-- Tests: `tests/`
+- Internal Docs: `.specweave/docs/internal/` (strategy, architecture, ADRs)
+- Public Docs: `.specweave/docs/public/` and `docs-site/` (user guides, API docs)
+- Tests: `tests/` (unit, integration, E2E, skill tests)
 
 ---
 
@@ -1604,4 +2408,4 @@ cd docs-site && npm run build
 5. Follow increment-based workflow
 
 **SpecWeave Documentation**: https://spec-weave.com
-**Last Updated**: 2025-10-28 (Increment 0002)
+**Last Updated**: 2025-11-04