Living Documentation

Living Documentation is documentation that stays automatically synchronized with your codebase and project state. Unlike traditional static documentation that becomes outdated, living docs are updated automatically through hooks, automation, and bidirectional sync with external systems.

The Problem with Traditional Documentation

Traditional documentation has a fatal flaw: it dies the moment you write it.

Why traditional docs fail:

❌ Manual updates required (often forgotten)
❌ No validation (docs can lie)
❌ Drift from code (code changes, docs don't)
❌ No source of truth (multiple versions)
❌ Low trust (team knows docs are stale)

Living Documentation: The Solution

Living docs stay alive through three key mechanisms:

1. Auto-Update After Tasks

SpecWeave's post-task-completion hook automatically updates living docs:

# Complete any task
# → Hook fires automatically
# → Living docs sync in background
# → Zero manual intervention

2. Bidirectional Sync

Changes flow both ways:

Local (.specweave/) ↔ External (GitHub/JIRA/ADO)

Example:

Task completed in SpecWeave → GitHub issue updated
GitHub issue closed → SpecWeave increment updated

3. Validation

Living docs are validated on every sync:

AC-ID coverage (all acceptance criteria documented)
Test coverage targets (85-90%)
Link integrity (no broken references)
Content classification (correct folder placement)

Living Docs Structure in SpecWeave

Permanent Knowledge Base

Location: .specweave/docs/internal/

.specweave/docs/internal/
├── strategy/              # Business rationale (PRDs, vision)
├── specs/                 # Feature specifications (permanent)
│   └── spec-001-auth.md   # ALL user stories for authentication
├── architecture/          # Technical design (HLD, ADR)
│   ├── adr/               # Architecture Decision Records
│   └── diagrams/          # System diagrams
├── delivery/              # Build & release (roadmap, DORA)
├── operations/            # Production ops (runbooks, SLOs)
└── governance/            # Policies (security, compliance)

Key Principle: Specs use 3-digit numbers (spec-001, spec-002) for feature areas.

Temporary Implementation Tracker

Location: .specweave/increments/####-name/

.specweave/increments/0008-user-authentication/
├── spec.md                # Subset of work (this iteration only)
├── plan.md                # Implementation approach
└── tasks.md               # Task checklist with tests

Key Principle: Increments use 4-digit numbers (0001, 0002) for implementations.

Living Docs Sync Flow

Step-by-Step Example

1. Complete Task:

# Developer marks task complete in tasks.md
- [x] T-001: Implement password hashing (AC-US1-02)

2. Hook Fires Automatically:

# Hook: plugins/specweave/hooks/post-task-completion.sh
# Runs sync-living-docs.js automatically

3. Living Docs Updated:

# Before (living docs):
.specweave/docs/internal/specs/spec-001-authentication.md
## US-001: User Login
Status: Planning

# After (living docs):
.specweave/docs/internal/specs/spec-001-authentication.md
## US-001: User Login
Status: Complete ✅
Implemented: Increment 0008
Test Coverage: 90% (target: 85%)

4. External Tracker Synced:

# GitHub issue updated automatically:
- [x] T-001: Implement password hashing

Progress: 1/5 tasks (20%)

Intelligent Living Docs Sync (v0.18.0+)

NEW in v0.18.0: Intelligent mode automatically classifies and distributes content to correct folders.

Simple Mode vs Intelligent Mode

Aspect	Simple Mode	Intelligent Mode
Output	One file (spec-001.md)	Multiple files (9 categories)
Classification	None	9-category system
Project Detection	None	Auto-detects (backend/frontend)
Cross-Linking	Manual	Automatic
Docusaurus	Manual frontmatter	Auto-generated
Size	5,000+ lines	200-500 lines per file

9-Category Classification

Example: Before/After Intelligent Sync

Before (Simple Mode):

.specweave/docs/internal/specs/spec-001-authentication.md (5,000 lines)
- User stories
- Architecture diagrams
- ADRs
- Runbooks
- Test strategy
- Business requirements
(All mixed together)

After (Intelligent Mode):

.specweave/docs/internal/
├── specs/backend/
│   ├── us-001-user-login.md              (User Story)
│   ├── us-002-session-management.md      (User Story)
│   └── _archive/spec-001-authentication.md (Original preserved)
├── architecture/
│   ├── authentication-flow.md            (HLD)
│   └── adr/0001-oauth-vs-jwt.md          (ADR)
├── operations/
│   ├── runbook-auth-service.md           (Runbook)
│   └── slo-auth-availability.md          (SLO)
├── delivery/
│   └── test-strategy-authentication.md   (Test Strategy)
└── strategy/
    └── auth-business-requirements.md     (Business Requirements)

Configuration

Enable Living Docs Sync (.specweave/config.json):

{
  "hooks": {
    "post_task_completion": {
      "sync_living_docs": true,        // ✅ Enable auto-sync
      "sync_tasks_md": true,           // ✅ Update tasks.md
      "external_tracker_sync": true    // ✅ Sync to GitHub/JIRA/ADO
    }
  },
  "livingDocs": {
    "intelligent": {
      "enabled": true,                 // ✅ Use intelligent mode
      "splitByCategory": true,         // ✅ Classify content
      "generateCrossLinks": true,      // ✅ Auto-link related docs
      "preserveOriginal": true,        // ✅ Keep original spec
      "classificationConfidenceThreshold": 0.6,
      "fallbackProject": "default"
    }
  }
}

Project Detection (Multi-Project Support)

Intelligent sync auto-detects which project (backend/frontend/mobile) content belongs to:

Detection Signals

Signal	Score	Example
Frontmatter	+20	`project: backend`
Increment ID	+10	`0016-backend-auth`
Team Name	+5	`team: backend-team`
Keywords	+3 each	`backend`, `api`, `service`
Tech Stack	+2 each	`Node.js`, `PostgreSQL`

Example Detection:

---
title: User Authentication
project: backend    # ← +20 points (explicit)
---

# User Authentication

Implement OAuth for **backend services** using Node.js...
# Keywords: backend (+3), service (+3), Node.js (+2) = +8
# Total: 20 + 8 = 28 points → 100% confidence → "backend" project

Docusaurus Frontmatter (Auto-Generated)

Every distributed file gets rich frontmatter for LLM context:

---
id: us-001-user-login
title: "US-001: User Login"
sidebar_label: "User Login"
description: "User can log in with email and password"
tags: ["user-story", "backend", "authentication"]
increment: "0016-authentication"
project: "backend"                    # ← LLM knows which project
category: "user-story"                # ← LLM knows document type
last_updated: "2025-11-10"
status: "planning"
priority: "P1"
---

Benefits:

✅ LLM Context: AI assistants understand project/category
✅ Docusaurus Ready: Works out-of-the-box
✅ Navigation: Sidebar generation
✅ Search: Better search results
✅ Traceability: Links to increment

Cross-Linking (Bidirectional)

Intelligent sync generates automatic cross-links between related documents:

## Related Documents

### Implements
- [Authentication Architecture](../../architecture/auth-flow.md)

### References
- [ADR-001: OAuth vs JWT](../../architecture/adr/0001-oauth-vs-jwt.md)

### Defined In
- [Business Requirements](../../strategy/auth-requirements.md)

### Related To
- [US-002: Session Management](./us-002-session-management.md)

Link Types:

Implements: User story implements architecture
References: References ADR or design doc
Defined In: Defined in PRD or strategy doc
Related To: Related to other user stories

Specs vs Increments (Two Locations Explained)

The Core Question: Why does SpecWeave have specs in TWO locations?

Living Docs Specs = Permanent Knowledge Base

Location: .specweave/docs/internal/specs/default/spec-001-core-framework.md

Purpose: COMPLETE, PERMANENT source of truth for entire feature area

Lifecycle: Created once, updated over time, NEVER deleted

Scope: Comprehensive feature area (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 Implementation Tracker

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"
✅ 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)

Real-World Example

Living Docs Spec (Permanent):

File: .specweave/docs/internal/specs/default/spec-001-core-framework.md

# SPEC-001: Core Framework & Architecture

## Increments (Implementation History)
- 0001-core-framework: MVP CLI (Complete)
- 0002-core-enhancements: Context optimization (Complete)
- 0004-plugin-architecture: Claude native plugins (Complete)

## User Stories (35 total across all increments)
- US-001: NPM installation (0001) ✅
- US-003: Context optimization (0002) ✅
- US-005: Plugin system (0004) ✅
... (32 more stories)

Increment Spec (Temporary):

File: .specweave/increments/0001-core-framework/spec.md

# Increment 0001: Core Framework MVP

**Implements**: SPEC-001 (US-001 to US-002 only)
**Complete Specification**: See ../../docs/internal/specs/default/spec-001.md

## What We're Implementing (This Increment Only)
- US-001: NPM installation + CLI basics ✅

## Out of Scope (For This Increment)
- ❌ Context optimization (US-003) → Increment 0002
- ❌ Plugin system (US-005) → Increment 0004

Analogy: Wikipedia vs Sticky Notes

Living Docs Specs = 📚 Wikipedia Article (permanent, comprehensive)
Increment Specs = 📝 Sticky Note Reminder (temporary, focused, disposable)

Benefits of Living Documentation

1. Always Accurate

Traditional docs are often outdated. Living docs are always accurate because they're auto-synced:

# Traditional docs (manual):
Code changes → Developer forgets to update docs → Docs outdated

# Living docs (automatic):
Code changes → Hook fires → Docs synced automatically → Always accurate

2. Zero Manual Work

Developers never manually update living docs:

# Complete task
- [x] T-001: Implement password hashing

# Hook fires automatically:
# ✅ Living docs synced
# ✅ GitHub issue updated
# ✅ Test coverage validated
# ✅ AC-IDs checked

# Developer: Zero manual work!

3. Single Source of Truth

Living docs are the permanent source of truth:

SpecWeave (.specweave/docs/internal/) = Source of Truth
External tools (GitHub, JIRA, ADO) = Mirrors

4. Complete History

Living docs preserve complete implementation history:

## SPEC-001: Core Framework

## Implementation History
- 2025-09-01: 0001-core-framework (US-001 to US-002) ✅
- 2025-09-15: 0002-core-enhancements (US-003 to US-004) ✅
- 2025-10-01: 0004-plugin-architecture (US-005 to US-006) ✅

## What Was Built
- US-001: NPM installation (Increment 0001) ✅
- US-002: CLI basics (Increment 0001) ✅
- US-003: Context optimization (Increment 0002) ✅
- US-004: Smart caching (Increment 0002) ✅
- US-005: Plugin marketplace (Increment 0004) ✅
- US-006: Plugin loader (Increment 0004) ✅

5. Onboarding New Developers

New developers can read living docs to understand the project:

# New developer joins team
# Reads: .specweave/docs/internal/specs/spec-001-core-framework.md

# Learns:
# - What was built (35 user stories)
# - Why decisions were made (ADRs)
# - How to use the system (architecture docs)
# - What tests exist (test coverage)

# Result: Productive in hours, not weeks

Manual Sync (When Automatic Sync Disabled)

If automatic sync is disabled, you can manually sync:

# 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-001-core-framework.md

Verification

Check Living Docs Are Synced:

# List 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

# Check intelligent sync distribution
ls -1 .specweave/docs/internal/specs/*/us-*.md
ls -1 .specweave/docs/internal/architecture/adr/*.md

When to Use Living Docs

✅ Good Fits for Living Docs

Feature specifications: Complete user story documentation
Architecture decisions: ADRs that evolve over time
API contracts: Endpoints, schemas, versioning
Runbooks: Production operations procedures
Test strategies: Coverage targets, test plans
Business requirements: PRDs, vision statements

❌ Not Suitable for Living Docs

Temporary notes: Session summaries, scratch work
Prototypes: Throwaway exploration
Draft content: Not-yet-approved specifications
Meeting notes: Unstructured discussions

Living Docs Anti-Patterns

1. Manual Updates

# ❌ Bad: Manual updates to living docs
vim .specweave/docs/internal/specs/spec-001.md
# (Changes get overwritten by next sync)

# ✅ Good: Update increment spec, let sync handle it
vim .specweave/increments/0001-core-framework/spec.md
# Hook syncs automatically to living docs

2. Duplicate Content

# ❌ Bad: Same content in multiple places
.specweave/increments/0001/spec.md (5,000 lines)
.specweave/docs/internal/specs/spec-001.md (5,000 lines, duplicate)

# ✅ Good: Increment references living docs
.specweave/increments/0001/spec.md (500 lines, focused)
.specweave/docs/internal/specs/spec-001.md (5,000 lines, complete)

3. Outdated External Links

# ❌ Bad: Manual links that break
GitHub: https://github.com/owner/repo/issues/123 (closed)
Living docs: Still references old issue

# ✅ Good: Bidirectional sync keeps links fresh
GitHub issue closed → Hook updates living docs → Link removed

Specs - Specifications (permanent knowledge base)
Increments - Temporary implementation tracker
Split-Source Sync - Content out, status in
Intelligent Living Docs Sync - Content classification
Source of Truth - Single source of truth principle
User Stories - User story format
AC-ID - Acceptance criteria identifiers

Summary

Living Documentation stays synchronized automatically through:

Auto-update hooks (post-task-completion)
Bidirectional sync (Local ↔ External)
Validation (AC-IDs, test coverage, links)

Two Locations:

Living docs (.specweave/docs/internal/specs/) = Permanent knowledge base
Increment specs (.specweave/increments/####/) = Temporary implementation tracker

Intelligent Mode (v0.18.0+):

9-category classification
Project detection (backend/frontend)
Auto-generated frontmatter
Cross-linking

Result: Documentation that never dies because it's always alive.

The Problem with Traditional Documentation​

Living Documentation: The Solution​

1. Auto-Update After Tasks​

2. Bidirectional Sync​

3. Validation​

Living Docs Structure in SpecWeave​

Permanent Knowledge Base​

Temporary Implementation Tracker​

Living Docs Sync Flow​

Step-by-Step Example​

Intelligent Living Docs Sync (v0.18.0+)​

Simple Mode vs Intelligent Mode​

9-Category Classification​

Configuration​

Project Detection (Multi-Project Support)​

Detection Signals​

Docusaurus Frontmatter (Auto-Generated)​

Cross-Linking (Bidirectional)​

Specs vs Increments (Two Locations Explained)​

Living Docs Specs = Permanent Knowledge Base​

Increment Specs = Temporary Implementation Tracker​

Real-World Example​

Analogy: Wikipedia vs Sticky Notes​

Benefits of Living Documentation​

1. Always Accurate​

2. Zero Manual Work​

3. Single Source of Truth​

4. Complete History​

5. Onboarding New Developers​

Manual Sync (When Automatic Sync Disabled)​

Verification​

When to Use Living Docs​

✅ Good Fits for Living Docs​

❌ Not Suitable for Living Docs​

Living Docs Anti-Patterns​

1. Manual Updates​

2. Duplicate Content​

3. Outdated External Links​

Related Terms​

Summary​