specweave 0.4.1 → 0.6.3

package/CLAUDE.md

@@ -1,7 +1,6 @@
 # SpecWeave - Development Guide
 
 **Project**: SpecWeave - Spec-Driven Development Framework
-**Version**: 0.4.0 (Plugin Architecture Complete!)
 **Type**: Open Source NPM Package (TypeScript CLI)
 **Repository**: https://github.com/anton-abyzov/specweave
 **Website**: https://spec-weave.com
@@ -11,26 +10,72 @@ Users receive a different CLAUDE.md via the template system.
 
 ---
 
-## Quick Start for Contributors
+## 🚨 CRITICAL: NEVER POLLUTE PROJECT ROOT!
 
-**Current Work**: Increment 0004 - Plugin Architecture ✅ COMPLETE
-**Active Branch**: `develop` → merges to `features/001-core-feature`
-**Latest**: v0.4.0 - Plugin Architecture with GitHub plugin (priority #1)
-**Next**: v0.5.0 - Additional plugins (Jira, Kubernetes, Frontend/Backend stacks)
+**⛔ THIS IS THE #1 RULE - VIOLATING THIS WILL GET YOUR PR REJECTED ⛔**
 
-**Typical Workflow**:
-```bash
-# 1. Make changes to source files in src/
-# 2. Test locally
-npm run build && npm test
+**ALL AI-generated files MUST go into the CURRENT INCREMENT folder**, NOT in the project root!
 
-# 3. Use SpecWeave commands for managing work
-/specweave.do                   # Execute next task
-/specweave.progress             # Check status
+### ❌ NEVER Create in Root (Pollutes Repository)
 
-# 4. Commit with hooks (auto-validates)
-git add . && git commit -m "feat: description"
 ```
+❌ WRONG - ROOT FILES (REJECTED!):
+/PLUGIN-MIGRATION-COMPLETE.md          # NO! Goes to increment reports/
+/SESSION-SUMMARY-2025-10-28.md         # NO! Goes to increment reports/
+/ADR-006-DEEP-ANALYSIS.md              # NO! Goes to .specweave/docs/internal/architecture/adr/
+/ANALYSIS-MULTI-TOOL-COMPARISON.md     # NO! Goes to increment reports/
+/migration-helper.sh                   # NO! Goes to increment scripts/
+/execution.log                         # NO! Goes to increment logs/
+/specweave-0.5.1.tgz                   # NO! Build artifact, should be in .gitignore
+/yolov8n.pt                            # NO! ML model, should be in .gitignore
+
+✅ CORRECT - INCREMENT FOLDERS:
+.specweave/increments/0004-plugin-architecture/
+├── spec.md                            # Spec files (core 4)
+├── plan.md
+├── tasks.md
+├── tests.md
+├── reports/                           # ✅ PUT REPORTS HERE!
+│   ├── PLUGIN-MIGRATION-COMPLETE.md   # ✅ Completion reports
+│   ├── SESSION-SUMMARY.md             # ✅ Session summaries
+│   └── ANALYSIS-*.md                  # ✅ Analysis files
+├── scripts/                           # ✅ PUT SCRIPTS HERE!
+│   └── migration-helper.sh            # ✅ Helper scripts
+└── logs/                              # ✅ PUT LOGS HERE!
+    └── execution.log                  # ✅ Execution logs
+
+.specweave/docs/internal/architecture/ # ✅ PUT ADRS/DIAGRAMS HERE!
+└── adr/
+    └── 0006-deep-analysis.md          # ✅ Architecture decisions
+```
+
+### Why This Matters
+
+- ✅ **Complete traceability** - Know which increment created which files
+- ✅ **Easy cleanup** - Delete increment folder = delete all files
+- ✅ **Clear context** - All files for a feature in one place
+- ✅ **No root clutter** - Project root stays clean and professional
+- ✅ **Better git history** - Changes grouped by increment
+
+### What IS Allowed in Root?
+
+**ONLY these files belong in root**:
+- ✅ `CLAUDE.md` (this file - contributor guide)
+- ✅ `README.md`, `CHANGELOG.md`, `LICENSE` (project documentation)
+- ✅ `package.json`, `tsconfig.json`, `.gitignore` (config files)
+- ✅ Directories: `src/`, `tests/`, `plugins/`, `.specweave/`, etc. (source code)
+
+**Everything else goes in increment folders or `.gitignore`!**
+
+### Build Artifacts (Add to .gitignore)
+
+These should NEVER be committed:
+- ❌ `*.tgz`, `*.tar.gz` - NPM package archives
+- ❌ `*.pt`, `*.pth` - ML model files (download on demand)
+- ❌ `dist/`, `build/` - Compiled outputs (already in .gitignore)
+- ❌ `*.log` - Log files (already in .gitignore)
+
+**Before committing, ALWAYS check**: `git status` - If you see `.md` files in root, MOVE THEM!
 
 ---
 
@@ -49,83 +94,24 @@ Claude Code isn't just another AI coding assistant - **Anthropic defines the ind
 
 ### Why SpecWeave + Claude Code = 10x Better
 
-| Feature | SpecWeave + Claude Code | Competitors (Kiro, Cursor, Copilot) |
-|---------|------------------------|-------------------------------------|
-| **Living Docs (Automated)** | ✅ Native hooks update docs on EVERY task | ❌ Manual sync required (Kiro, Cursor, Copilot) |
-| **Auto-Activation** | ✅ Skills auto-fire based on context | ❌ Must manually invoke (all competitors) |
-| **Multi-Agent Isolation** | ✅ Separate contexts per agent | 🟡 Cursor: shared context; Others: none |
-| **Slash Commands** | ✅ Native `/specweave.*` commands | 🟡 Cursor: team commands; Others: none |
-| **Hooks (Pre/Post)** | ✅ Native lifecycle automation | ❌ No hooks (all competitors) |
-| **MCP Protocol** | ✅ Native context management | ❌ Proprietary or none |
-| **Context Efficiency** | ✅ 60-80% reduction with plugins | 🟡 Cursor: @ shortcuts; Others: limited |
-| **Spec-Driven Workflow** | ✅ Core framework feature | ❌ Not supported |
-
-### The Living Docs Advantage: SpecWeave vs. Kiro
-
-**Kiro's Pitch**: "Automated living documentation"
-**Reality**: Kiro requires **manual sync** - you must remember to update docs.
-
-**SpecWeave + Claude Code**:
-- **100% automated** via native hooks
-- After EVERY task, hooks fire automatically
-- Docs update without user intervention
-- No manual sync needed, EVER
-
-**Why?** Claude Code's native hooks system. Kiro doesn't have this - they rely on manual triggers.
-
-### Cursor 2.0: Good, But Not Native
-
-Cursor 2.0 (released Oct 29, 2025) has impressive features:
-- ✅ 8 parallel agents
-- ✅ Team-defined custom commands
-- ✅ In-app browser
-- ✅ @ context shortcuts
-
-**But Cursor still lacks**:
-- ❌ Native hooks (no automated doc updates)
-- ❌ Skill auto-activation (must explicitly request)
-- ❌ Agent isolation (all 8 agents share context)
-- ❌ MCP protocol (proprietary context management)
-
-**SpecWeave on Cursor** = ~85% of Claude Code experience (still very good!)
+| Feature | Claude Code (Native) | Cursor 2.0 | Copilot | Generic |
+|---------|---------------------|------------|---------|---------|
+| **Living Docs** | ✅ Auto-sync via hooks | ❌ Manual | ❌ Manual | ❌ Manual |
+| **Skills** | ✅ Auto-activate | 🟡 Must @mention | ❌ None | ❌ None |
+| **Commands** | ✅ Plugin-based `/specweave:*` | 🟡 Team commands | ❌ None | ❌ None |
+| **Hooks** | ✅ Pre/Post lifecycle | ❌ No hooks | ❌ No hooks | ❌ No hooks |
+| **Agents** | ✅ Isolated contexts | 🟡 Shared (8 parallel) | ❌ None | ❌ None |
+| **Context** | ✅ MCP + 60-80% reduction | 🟡 @ shortcuts | ❌ Limited | ❌ None |
+| **Quality** | ⭐⭐⭐⭐⭐ 100% | ⭐⭐⭐⭐ 85% | ⭐⭐⭐ 60% | ⭐⭐ 40% |
 
-### GitHub Copilot: Basic Automation
+**Quick Comparison**:
 
-Copilot provides:
-- ✅ Workspace instructions
-- ✅ Code suggestions
+**Claude Code** - Full automation with native hooks, MCP protocol, plugin system, isolated agent contexts
+**Cursor 2.0** - Good multi-tool support (AGENTS.md compilation, team commands, @ shortcuts) but no hooks or agent isolation
+**Copilot** - Basic instructions.md support, no automation features
+**Generic** - Manual copy-paste workflow
 
-**But Copilot lacks**:
-- ❌ Native hooks
-- ❌ Skills/agents
-- ❌ Slash commands
-- ❌ Living docs
-
-**SpecWeave on Copilot** = ~60% of Claude Code experience (basic automation only)
-
-### Generic Tools (ChatGPT, Gemini): Manual Workflow
-
-Generic AI tools:
-- ✅ Conversational AI
-- ✅ Code generation
-
-**But they lack**:
-- ❌ ALL automation features
-- ❌ Project integration
-- ❌ Persistent state
-
-**SpecWeave on Generic** = ~40% of Claude Code experience (copy-paste manual)
-
-### The Bottom Line
-
-**SpecWeave works with any tool**, but for the **BEST experience**:
-
-1. **Claude Code** (⭐⭐⭐⭐⭐ 100%) - Full automation, native hooks, MCP, isolated agents
-2. **Cursor 2.0** (⭐⭐⭐⭐ 85%) - Semi-automation, AGENTS.md, team commands
-3. **Copilot** (⭐⭐⭐ 60%) - Basic automation, instructions.md
-4. **Generic** (⭐⭐ 40%) - Manual workflow, copy-paste
-
-**Recommendation**: Use Claude Code for SpecWeave. Other tools work, but you'll miss the magic.
+**The Key Differentiator**: Only Claude Code supports **automated living docs** via native hooks. After EVERY task completion, docs sync automatically - zero manual intervention. This is why SpecWeave is designed Claude Code-first, though it gracefully degrades to other tools.
 
 ---
 
@@ -152,15 +138,15 @@ Generic AI tools:
 **When Creating Increments**:
 ```bash
 # ❌ Wrong
-/specweave.inc "0004"
+/specweave:inc "0004"
 
 # ✅ Correct
-/specweave.inc "0004-cost-optimization"
-/specweave.inc "0005-github-sync-enhancements"
+/specweave:inc "0004-cost-optimization"
+/specweave:inc "0005-github-sync-enhancements"
 ```
 
 **Enforcement**:
-- `/specweave.inc` command validates naming (rejects bare numbers)
+- `/specweave:inc` command validates naming (rejects bare numbers)
 - Code review requirement (descriptive names mandatory)
 - This document serves as the source of truth
 
@@ -172,23 +158,461 @@ Generic AI tools:
 
 ---
 
+## Increment Discipline (v0.6.0+ MANDATORY)
+
+**⛔ THE IRON RULE: You CANNOT start increment N+1 until increment N is DONE**
+
+This is **NOT negotiable**. It is a **hard enforcement** to prevent chaos, scope creep, and stale documentation.
+
+### Why This Rule Exists
+
+**The Problem (before v0.6.0)**:
+- 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+)**:
+- ✅ **Hard block** on `/specweave:inc` if previous increments incomplete
+- ✅ **Helper commands** to close increments properly
+- ✅ **Clear guidance** on how to resolve incomplete work
+- ✅ **Force discipline** = force quality
+
+### What "DONE" Means
+
+An increment is DONE if **ONE** of the following is true:
+
+1. **All tasks completed**: All tasks in `tasks.md` marked `[x] Completed`
+2. **Completion report exists**: `COMPLETION-SUMMARY.md` with "✅ COMPLETE" status
+3. **Explicit closure**: Closed via `/specweave:close` with documentation
+
+### The Enforcement
+
+**When you try to start a new increment**:
+
+```bash
+/specweave:inc "new feature"
+```
+
+**If previous increments are incomplete, you'll see**:
+
+```
+❌ Cannot create new increment!
+
+Previous increments are incomplete:
+
+📋 Increment 0002-core-enhancements
+   Status: 73% complete (11/15 tasks)
+   Pending:
+     - T-008: Migrate DIAGRAM-CONVENTIONS.md content
+     - T-010: Create context-manifest.yaml
+     - T-012: Test agent invocation manually
+     - T-013: Run skill test suite
+     - T-015: Create PR when increment complete
+
+📋 Increment 0003-intelligent-model-selection
+   Status: 50% complete (11/22 tasks)
+   Pending: 11 tasks
+
+💡 What would you like to do?
+
+1️⃣  Close incomplete increments:
+   /specweave:close
+
+2️⃣  Check status:
+   /specweave:status
+
+3️⃣  Force create (DANGEROUS - violates discipline!):
+   Add --force flag to bypass this check
+
+⚠️  The discipline exists for a reason:
+   - Prevents scope creep
+   - Ensures completions are tracked
+   - Maintains living docs accuracy
+   - Keeps work focused
+```
+
+### How to Resolve Incomplete Increments
+
+#### Option 1: Complete the Work (Recommended)
+
+```bash
+# Continue working on incomplete increment
+/specweave:do
+
+# Once all tasks done, it's automatically complete
+/specweave:inc "new feature"  # ✅ Now works!
+```
+
+#### Option 2: Close Interactively
+
+```bash
+# Interactive closure with options
+/specweave:close
+
+# You'll be asked to choose:
+# - Force complete (mark all tasks done)
+# - Move tasks to next increment (defer work)
+# - Reduce scope (mark tasks as won't-do)
+# - Create completion report (manual close)
+```
+
+#### Option 3: Check Status First
+
+```bash
+# See all incomplete increments
+/specweave:status
+
+# Output shows:
+# ✅ 0001-core-framework
+# ✅ 0004-plugin-architecture
+# ⏳ 0002-core-enhancements (73% complete)
+# ⏳ 0003-intelligent-model-selection (50% complete)
+```
+
+#### Option 4: Force Create (Emergency Only!)
+
+```bash
+# Bypass the check (USE SPARINGLY!)
+/specweave:inc "urgent-hotfix" --force
+
+# This is logged and should be explained in the next standup/PR
+```
+
+### The Three Options for Closing
+
+When using `/specweave:close`, you get **THREE options**:
+
+#### 1. **Adjust Scope** (Simplest - Recommended)
+
+Remove parts from `spec.md`, regenerate `plan.md` and `tasks.md` to match reduced scope:
+
+```bash
+# 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
+
+# Now tasks match reduced scope → 100% complete!
+```
+
+#### 2. **Move Scope to Next Increment**
+
+Transfer incomplete tasks to the new increment:
+
+```bash
+# Via /specweave:close
+# Select "Move tasks to next increment"
+# Tasks are migrated with documentation
+# Old increment closed, new increment gets the work
+```
+
+#### 3. **Extend Existing Increment** (Merge Work)
+
+Simplest option: **Don't start a new increment**. Just extend the current one:
+
+```bash
+# Instead of creating 0003, extend 0002:
+# 1. Update spec.md to include new features
+# 2. Update plan.md with new implementation details
+# 3. Add new tasks to tasks.md
+# 4. Minimize tests if needed (focus on critical paths)
+
+# Work on combined scope in ONE increment
+/specweave:do
+```
+
+### Helper Commands
+
+| Command | Purpose |
+|---------|---------|
+| `/specweave:status` | Show all increments and their completion status |
+| `/specweave:close` | Interactive closure of incomplete increments |
+| `/specweave:force-close <id>` | Mark all tasks complete (dangerous!) |
+
+### Enforcement Points
+
+1. **`/specweave:inc` command** - Hard block (Step 0A)
+2. **PM agent** - Pre-flight validation before planning
+3. **CI/CD** (future) - Prevent PR merges with incomplete increments
+
+### Philosophy: Discipline = Quality
+
+**Why enforce this strictly?**
+
+- **Focus**: Work on ONE thing at a time
+- **Completion**: Finish before starting new
+- **Quality**: Tests run, docs updated, code reviewed
+- **Clarity**: Everyone knows what's current
+- **Velocity**: Actually shipping > endless WIP
+
+**Old Way (suggest)**:
+```
+User: "Just let me start the new feature, I'll come back to this"
+Result: 5 incomplete increments, nothing ships
+```
+
+**New Way (enforce)**:
+```
+Framework: "Close this first, then start new"
+User: *closes increment properly*
+Result: Clean increments, clear progress, shipping regularly
+```
+
+### Real-World Example
+
+**Scenario**: You have 0002 at 73% complete, want to start 0006.
+
+**Before v0.6.0** (broken):
+```bash
+/specweave:inc "0006-i18n"
+# ✅ Creates 0006 (no check)
+# Result: 0002, 0003, 0006 all incomplete
+```
+
+**After v0.6.0** (disciplined):
+```bash
+/specweave:inc "0006-i18n"
+# ❌ Blocked! "Close 0002 and 0003 first"
+
+# Check status
+/specweave:status
+# Shows: 0002 (73%), 0003 (50%) incomplete
+
+# Close them
+/specweave:close
+# Select 0002 → Force complete (work was done, just not marked)
+# Select 0003 → Move tasks to 0007 (defer work)
+
+# Now can proceed
+/specweave:inc "0006-i18n"
+# ✅ Works! Clean slate, disciplined workflow
+```
+
+### Exception: The `--force` Flag
+
+For **emergencies only** (hotfixes, urgent features):
+
+```bash
+/specweave:inc "urgent-security-fix" --force
+```
+
+**This bypasses the check** but:
+- ✅ Logs the force creation
+- ✅ Warns in CLI output
+- ✅ Should be explained in PR/standup
+- ✅ Should close previous increments ASAP
+
+**Use sparingly!** The discipline exists for a reason.
+
+---
+
+**Summary**: Close previous increments before starting new ones. Use `/specweave:status` and `/specweave:close` to maintain discipline. This isn't bureaucracy—it's quality enforcement.
+
+---
+
+## 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.
+
+### The Rule: ONE Source of Truth
+
+```
+✅ CORRECT - Root-level only:
+my-project/
+├── .specweave/              ← ONE source of truth
+│   ├── increments/
+│   ├── docs/
+│   └── logs/
+├── frontend/
+├── backend/
+└── infrastructure/
+
+❌ WRONG - Nested .specweave/ (NOT SUPPORTED):
+my-project/
+├── .specweave/              ← Root level
+│   └── ...
+├── backend/
+│   └── .specweave/          ← ❌ NESTED - PREVENTS THIS!
+└── frontend/
+    └── .specweave/          ← ❌ NESTED - PREVENTS THIS!
+```
+
+### Why Root-Level Only?
+
+**Single Source of Truth**:
+- ✅ One central location for all specs, increments, architecture
+- ✅ No duplication or fragmentation
+- ✅ Clear ownership and responsibility
+- ✅ Simplified living docs sync (one place to update)
+
+**Cross-Cutting Features**:
+- ✅ Increments often span multiple modules (frontend + backend + infra)
+- ✅ Architecture decisions (ADRs) apply system-wide
+- ✅ Strategy docs are project-level, not module-level
+- ✅ Living docs sync works best with one central location
+
+**Plugin Detection**:
+- ✅ Four-phase detection assumes one `.specweave/` folder
+- ✅ Auto-detection scans from root only
+- ✅ No ambiguity about where plugins are enabled
+
+**Prevents Chaos**:
+- ❌ Nested folders cause: Which is the source of truth?
+- ❌ Duplication: Same increment in multiple places?
+- ❌ Conflicts: Different modules with same increment numbers?
+- ❌ Complexity: Where do cross-cutting features live?
+
+### Multi-Repo & Microservices Pattern
+
+**Problem**: "My project has multiple repos, microservices, or complex architecture"
+
+**Solution**: Create a **parent folder** with ONE root-level `.specweave/`
+
+The pattern is the same whether you have:
+- Multiple git repos (polyrepo architecture)
+- Microservices (separate service directories)
+- Monorepo with multiple modules
+
+```
+microservices-project/       ← Create parent folder
+├── .specweave/              ← ONE source of truth for entire system
+│   ├── increments/
+│   │   ├── 0001-add-service-mesh/      ← Cross-cutting
+│   │   ├── 0002-user-svc-v2/           ← Single service
+│   │   └── 0003-checkout-flow/         ← Multi-service
+│   ├── docs/
+│   │   ├── internal/
+│   │   │   ├── strategy/               ← System-wide strategy
+│   │   │   ├── architecture/
+│   │   │   │   ├── service-mesh.md     ← System-wide
+│   │   │   │   ├── api-contracts.md    ← Cross-service
+│   │   │   │   └── adr/
+│   │   │   │       └── 0001-service-mesh-choice.md
+│   │   │   └── ...
+│   │   └── public/
+│   └── logs/
+│
+├── services/
+│   ├── user-service/        ← Can be separate git repos
+│   ├── order-service/       ← Or monorepo subdirectories
+│   ├── payment-service/
+│   └── notification-service/
+│
+├── infrastructure/
+│   ├── k8s/
+│   └── terraform/
+│
+└── shared/
+    └── api-contracts/
+```
+
+**How to Set Up**:
+
+```bash
+# Option 1: Multiple repos (clone as subdirectories)
+mkdir microservices-project && cd microservices-project
+npx specweave init .
+git clone https://github.com/myorg/user-service.git services/user-service
+git clone https://github.com/myorg/order-service.git services/order-service
+
+# Option 2: Git submodules (advanced)
+mkdir microservices-project && cd microservices-project
+git init && npx specweave init .
+git submodule add https://github.com/myorg/user-service.git services/user-service
+
+# Option 3: Monorepo (services in same repo)
+mkdir microservices-project && cd microservices-project
+git init && npx specweave init .
+mkdir -p services/{user,order,payment}
+
+# Work normally - SpecWeave sees all services
+/specweave:inc "0001-add-service-mesh"
+# Creates: .specweave/increments/0001-add-service-mesh/
+# Can reference: services/user-service/, infrastructure/k8s/, etc.
+```
+
+**Benefits**:
+- ✅ One `.specweave/` for entire system (no duplication)
+- ✅ Each repo maintains its own git history (if using polyrepo)
+- ✅ Cross-service increments are natural (e.g., checkout flow)
+- ✅ System-wide architecture docs in one place
+- ✅ Living docs cover all services
+
+### Enforcement
+
+**Validation in `init.ts`**:
+
+```typescript
+// Check for parent .specweave/
+function detectNestedSpecweave(targetDir: string): string | null {
+  let currentDir = path.dirname(targetDir);
+  const root = path.parse(currentDir).root;
+
+  while (currentDir !== root) {
+    const specweavePath = path.join(currentDir, '.specweave');
+    if (fs.existsSync(specweavePath)) {
+      return currentDir; // Found parent .specweave/
+    }
+    currentDir = path.dirname(currentDir);
+  }
+
+  return null;
+}
+
+// Prevent nested initialization
+const parentSpecweave = detectNestedSpecweave(targetDir);
+if (parentSpecweave) {
+  console.error('❌ Nested .specweave/ folders are not supported!');
+  console.error(`   Found parent .specweave/ at: ${parentSpecweave}`);
+  console.error(`   Use the parent folder for all increments.`);
+  process.exit(1);
+}
+```
+
+**Detection Rules**:
+- ❌ Prevent `specweave init` in subdirectories if parent `.specweave/` exists
+- ✅ Suggest using parent folder instead
+- ✅ Provide clear error messages with path to parent
+
+**Code Review**:
+- ❌ Reject PRs with nested `.specweave/` folders
+- ✅ Enforce via linting/validation scripts
+
+### Summary
+
+| Aspect | Root-Level Only | Nested (NOT Supported) |
+|--------|----------------|------------------------|
+| **Source of Truth** | ✅ One central location | ❌ Multiple conflicting sources |
+| **Cross-Cutting Features** | ✅ Natural | ❌ Complex coordination |
+| **Living Docs Sync** | ✅ Simple | ❌ Merge conflicts |
+| **Plugin Detection** | ✅ Works | ❌ Ambiguous |
+| **Multi-Repo** | ✅ Parent folder | ❌ Fragmented |
+| **Complexity** | ✅ Simple | ❌ High |
+
+**Bottom Line**: Root-level `.specweave/` only. For multi-repo projects, create a parent folder. No exceptions.
+
+---
+
 ## Project Scale (v0.4.0 - Plugin Architecture)
 
-### Core Framework (Always Loaded)
+### Core Plugin (Always Auto-Loaded)
 
-**The Essentials** - What every SpecWeave project gets:
-- **Skills**: 8 core (increment-planner, **rfc-generator**, context-loader, project-kickstarter, brownfield-analyzer, brownfield-onboarder, increment-quality-judge, context-optimizer)
-- **Agents**: 3 core (PM, Architect, Tech Lead)
-- **Commands**: 7 core (/specweave.inc, /specweave.do, /specweave.next, /specweave.done, /specweave.progress, /specweave.validate, /sync-docs)
+**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)
+- **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)
 
 **Result**: **75%+ context reduction** out of the box!
 
 **Why So Small?**
-- External sync (GitHub, Jira) = plugins
-- Tech stacks (React, K8s) = plugins
-- Domain expertise (ML, payments) = plugins
-- Only increment lifecycle + living docs in core
+- External sync (GitHub, Jira) = separate plugins
+- Tech stacks (React, K8s) = separate plugins
+- Domain expertise (ML, payments) = separate plugins
+- Core plugin = only increment lifecycle + living docs automation
 
 ### Available Plugins (Opt-In)
 
@@ -219,7 +643,7 @@ Generic AI tools:
 | **ml-ops** | 3 | 3 | 1 | Machine learning, TensorFlow, PyTorch |
 | **observability** | 4 | 4 | 2 | Prometheus, Grafana, monitoring |
 | **payment-processing** | 4 | 1 | 0 | Stripe, billing, subscriptions |
-| **e2e-testing** | 2 | 1 | 0 | Playwright, browser automation |
+| **e2e-testing** | 1 | 0 | 0 | Playwright, E2E browser automation, visual regression |
 | **figma-ecosystem** | 5 | 2 | 0 | Design integration, Figma API |
 | **security** | 3 | 1 | 0 | Security scanning, best practices |
 | **diagrams** | 2 | 1 | 0 | C4 diagrams, Mermaid |
@@ -252,26 +676,96 @@ Generic AI tools:
 - ML pipeline: Core + ml-ops + github ≈ **18K tokens** (64% reduction!)
 - SpecWeave itself: Core + github + diagrams ≈ **15K tokens** (70% reduction!)
 
-### How to Enable Plugins
+### How Plugins Are Loaded (Intelligent Auto-Loading)
 
-**Auto-Detection** (recommended):
-```bash
-specweave init  # Auto-detects and suggests plugins
-```
+**SpecWeave's plugin system is designed to be intelligent and non-intrusive:**
 
-**Manual**:
-```bash
-specweave plugin list           # See all available
-specweave plugin enable kubernetes
-specweave plugin disable figma-ecosystem
-```
+#### Phase 1: Initialize (FULLY AUTOMATED!)
+
+When you run `specweave init`:
+
+1. ✅ **Marketplace Auto-Registration**
+   - Creates `.claude/settings.json` with marketplace reference
+   - Claude Code automatically discovers plugins
+   - No manual `/plugin marketplace add` needed!
+
+2. ✅ **Core Plugin Auto-Installation** (NEW! v0.6.1+)
+   - 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!
+   - Success message: "✔ SpecWeave core plugin installed automatically!"
+   - Graceful fallback: If CLI unavailable, shows manual install instructions
+
+3. ℹ️  **Optional Plugins Suggested**
+   - Based on project detection (Git, package.json, etc.)
+   - User can install now or later
+
+#### Phase 2: Increment Planning (On-Demand Loading)
+
+When you create increments (e.g., `/specweave:inc "Add Stripe billing"`):
+
+1. **Spec Analysis** (NEW! v0.6.0+)
+   - increment-planner skill scans spec.md content
+   - Detects keywords: "Stripe", "GitHub", "Kubernetes", "React", etc.
+   - Maps keywords → required plugins (see Step 6 in increment-planner/SKILL.md)
+
+2. **Plugin Suggestion** (Non-Blocking)
+   ```
+   🔌 This increment requires additional plugins:
+
+   Required:
+   • specweave-payments - Stripe integration (detected: "billing", "Stripe")
+
+   📦 Install: /plugin install specweave-payments@specweave
+
+   Or continue without it (can install later)
+   ```
+
+3. **User Decision**
+   - Install now → Plugin activates immediately (after Claude Code restart)
+   - Install later → Skills won't be available until plugin installed
+   - Skip → Increment creation continues (not blocked)
+
+#### Phase 3: Implementation (Auto-Activation)
+
+When plugins are installed:
+
+1. **Skills Auto-Activate**
+   - Based on description keywords (Claude Code native behavior)
+   - No manual invocation needed
+   - Example: Mention "GitHub" → github-sync skill activates
+
+2. **Context Efficiency**
+   - Only loaded plugins consume tokens
+   - 70%+ reduction vs. monolithic approach
+   - Real-time: Simple React app = 16K tokens (was 50K in v0.3.7)
+
+### Manual Plugin Management
+
+All plugin management happens through Claude Code's native commands:
 
-**Spec-Based** (during increment planning):
 ```bash
-/specweave.inc "deploy to Kubernetes"
-# → Suggests kubernetes plugin before creating spec
+# List installed plugins
+/plugin list --installed
+
+# Install a specific plugin
+/plugin install specweave-kubernetes@specweave
+
+# Uninstall a plugin
+/plugin uninstall specweave-kubernetes
+
+# List all available plugins from marketplace
+/plugin list specweave
 ```
 
+**Key Insight**: SpecWeave uses **ONLY** Claude Code's native plugin system:
+- Plugins install globally via `/plugin install specweave-{name}@specweave`
+- Work across ALL projects (like VS Code extensions)
+- Auto-activate based on skills' description keywords
+- Managed by Claude Code (updates, uninstall, etc.)
+
+No per-project installation needed!
+
 ---
 
 ## Project Architecture
@@ -281,19 +775,54 @@ specweave plugin disable figma-ecosystem
 **CRITICAL**: SpecWeave follows a strict source-of-truth pattern:
 
 ```
-src/                            ← SOURCE OF TRUTH (version controlled)
-├── skills/                     ← Source for skills
-├── agents/                     ← Source for agents
-├── commands/                   ← Source for slash commands
-├── hooks/                      ← Source for hooks
-├── adapters/                   ← Tool adapters (Claude, Cursor, etc.)
-└── templates/                  ← Templates for user projects
+src/                            ← SOURCE OF TRUTH (TypeScript code only)
+├── core/                       ← Core framework logic (TypeScript utilities)
+│   ├── plugin-loader.ts
+│   ├── config-manager.ts
+│   ├── types/                  ← TypeScript type definitions
+│   └── schemas/                ← JSON schemas
+├── cli/                        ← CLI commands
+├── hooks/                      ← TypeScript utilities for hooks
+│   └── lib/                    ← Hook helper functions
+├── adapters/                   ← Tool adapters (legacy)
+├── templates/                  ← Templates for user projects
+└── utils/                      ← Utility functions
+
+plugins/                        ← ROOT: All plugins (version controlled)
+├── specweave/             ← CORE PLUGIN (framework essentials)
+│   ├── .claude-plugin/         ← plugin.json (Claude native)
+│   ├── skills/                 ← Core skills (9 total)
+│   │   ├── rfc-generator/
+│   │   ├── increment-planner/
+│   │   ├── tdd-workflow/
+│   │   └── ...
+│   ├── agents/                 ← Core agents (3 core + 19 specialized)
+│   │   ├── pm/
+│   │   ├── architect/
+│   │   ├── tech-lead/
+│   │   └── ...
+│   ├── commands/               ← Core commands (7 core + 15 specialized)
+│   │   ├── inc.md
+│   │   ├── do.md
+│   │   └── ...
+│   ├── hooks/                  ← Lifecycle hooks (8 total)
+│   │   ├── post-task-completion.sh
+│   │   ├── pre-implementation.sh
+│   │   └── ...
+│   └── lib/                    ← TypeScript utilities (optional)
+│
+└── specweave-{name}/           ← Other plugins (GitHub, Figma, etc.)
+    ├── .claude-plugin/         ← plugin.json (Claude native)
+    ├── skills/                 ← Plugin skills
+    ├── agents/                 ← Plugin agents
+    ├── commands/               ← Plugin commands
+    └── lib/                    ← TypeScript utilities (optional)
 
 .claude/                        ← INSTALLED (gitignored in user projects)
-├── skills/                     ← Installed from src/skills/
-├── agents/                     ← Installed from src/agents/
-├── commands/                   ← Installed from src/commands/
-└── hooks/                      ← Installed from src/hooks/
+├── agents/                     ← Installed from plugins/*/agents/
+├── commands/                   ← Installed from plugins/*/commands/
+├── hooks/                      ← Installed from plugins/*/hooks/
+└── skills/                     ← Installed from plugins/*/skills/
 
 .specweave/                     ← FRAMEWORK DATA (always present)
 ├── increments/                 ← Feature development
@@ -302,11 +831,20 @@ src/                            ← SOURCE OF TRUTH (version controlled)
 ```
 
 **Rules**:
-- ✅ ALWAYS edit files in `src/` (source of truth)
-- ✅ Run install scripts to sync changes to `.claude/`
+- ✅ `src/` = TypeScript code ONLY (compiled to `dist/`)
+- ✅ ALL skills/agents/commands/hooks = Inside plugins (including core!)
+- ✅ `plugins/specweave/` = Core framework plugin (always loaded)
+- ✅ `.claude/` = Installed from all enabled plugins
+- ❌ 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/`
+- 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
+
 ### Tech Stack
 
 **Core**:
@@ -336,67 +874,91 @@ src/                            ← SOURCE OF TRUTH (version controlled)
 
 ```
 specweave/
-├── src/                        # SOURCE OF TRUTH
+├── src/                        # SOURCE OF TRUTH (TypeScript code ONLY)
 │   ├── cli/                    # CLI commands (init, version)
 │   │   └── commands/
 │   │       └── init.ts         # Main installation logic
-│   ├── core/                   # Core framework logic
-│   │   ├── plugin-loader.ts    # ✅ NEW: Load plugins from disk
-│   │   ├── plugin-manager.ts   # ✅ NEW: Plugin lifecycle management
-│   │   ├── plugin-detector.ts  # ✅ NEW: Auto-detect plugins (4 phases)
+│   ├── core/                   # Core framework logic (TypeScript only)
+│   │   ├── plugin-loader.ts    # Load plugins from disk
+│   │   ├── plugin-manager.ts   # Plugin lifecycle management
+│   │   ├── plugin-detector.ts  # Auto-detect plugins (4 phases)
 │   │   ├── config-manager.ts   # Config loading/validation
 │   │   ├── types/
-│   │   │   └── plugin.ts       # ✅ NEW: Plugin type definitions
-│   │   ├── schemas/
-│   │   │   ├── plugin-manifest.schema.json  # ✅ NEW
-│   │   │   └── specweave-config.schema.json # ✅ NEW
-│   │   └── skills/
-│   │       └── rfc-generator/  # ✅ NEW: Core skill for all users
-│   ├── skills/                 # 8 core skills (SKILL.md + test-cases/)
-│   │   ├── increment-planner/
-│   │   ├── context-loader/
-│   │   └── ...
-│   ├── agents/                 # 3 core agents (AGENT.md)
-│   │   ├── pm/
-│   │   ├── architect/
-│   │   └── tech-lead/
-│   ├── commands/               # 7 core slash commands (.md)
-│   │   ├── specweave-inc.md
-│   │   ├── specweave-do.md
-│   │   └── ...
-│   ├── hooks/                  # Lifecycle hooks (.sh)
-│   │   └── post-task-completion.sh
-│   ├── adapters/               # Multi-tool support (UPDATED)
-│   │   ├── adapter-interface.ts   # ✅ UPDATED: Plugin methods
-│   │   ├── adapter-base.ts        # ✅ UPDATED: Default implementations
-│   │   ├── claude/                # ✅ UPDATED: Native plugin support
-│   │   ├── cursor/                # ✅ UPDATED: AGENTS.md compilation
-│   │   ├── copilot/               # ✅ UPDATED: AGENTS.md compilation
-│   │   └── generic/               # ✅ UPDATED: Manual workflows
-│   ├── plugins/                # ✅ NEW: Plugin system
-│   │   └── specweave-github/   # ✅ COMPLETE: GitHub integration
-│   │       ├── .claude-plugin/
-│   │       │   └── manifest.json
-│   │       ├── skills/
-│   │       │   ├── github-sync/
-│   │       │   └── github-issue-tracker/
-│   │       ├── agents/
-│   │       │   └── github-manager/
-│   │       └── commands/
-│   │           ├── github-create-issue.md
-│   │           ├── github-sync.md
-│   │           ├── github-close-issue.md
-│   │           └── github-status.md
+│   │   │   └── plugin.ts       # Plugin type definitions
+│   │   └── schemas/
+│   │       ├── plugin-manifest.schema.json
+│   │       └── specweave-config.schema.json
+│   ├── hooks/                  # TypeScript utilities for hooks
+│   │   └── lib/                # Hook helper functions
+│   ├── adapters/               # Tool adapters (legacy)
+│   │   ├── adapter-interface.ts
+│   │   ├── adapter-base.ts
+│   │   ├── claude/
+│   │   ├── cursor/ (legacy)
+│   │   ├── copilot/ (legacy)
+│   │   └── generic/ (legacy)
 │   ├── templates/              # User project templates
 │   │   ├── CLAUDE.md.template
 │   │   ├── AGENTS.md.template
 │   │   └── ...
 │   └── utils/                  # Utility functions
 │
+├── plugins/                    # ALL PLUGINS (root level)
+│   ├── specweave/         # CORE PLUGIN (framework essentials)
+│   │   ├── .claude-plugin/
+│   │   │   └── plugin.json     # Claude native manifest
+│   │   ├── skills/             # Core skills (9 total)
+│   │   │   ├── rfc-generator/          # RFC generation for increments
+│   │   │   ├── increment-planner/      # Increment planning and spec generation
+│   │   │   ├── context-loader/         # Context loading optimization
+│   │   │   ├── tdd-workflow/           # Test-driven development workflow
+│   │   │   ├── project-kickstarter/    # New project bootstrapping
+│   │   │   ├── brownfield-analyzer/    # Existing codebase analysis
+│   │   │   ├── brownfield-onboarder/   # Brownfield project onboarding
+│   │   │   ├── increment-quality-judge/# Quality assessment
+│   │   │   └── context-optimizer/      # Context optimization
+│   │   ├── agents/             # Core agents (22 total)
+│   │   │   ├── pm/             # Product Manager agent
+│   │   │   ├── architect/      # System Architect agent
+│   │   │   ├── tech-lead/      # Tech Lead agent
+│   │   │   └── ...
+│   │   ├── commands/           # Core commands (22 total)
+│   │   │   ├── inc.md        # /specweave:inc
+│   │   │   ├── do.md         # /specweave:do
+│   │   │   ├── done.md       # /specweave:done
+│   │   │   └── ...
+│   │   ├── hooks/              # Lifecycle hooks (8 total)
+│   │   │   ├── post-task-completion.sh # Auto-runs after tasks complete
+│   │   │   ├── pre-implementation.sh   # Pre-task validation
+│   │   │   └── ...
+│   │   └── lib/                # TypeScript utilities (optional)
+│   │
+│   ├── specweave-github/       # GitHub Issues integration
+│   │   ├── .claude-plugin/
+│   │   │   └── plugin.json     # Claude native manifest
+│   │   ├── skills/
+│   │   │   ├── github-sync/
+│   │   │   └── github-issue-tracker/
+│   │   ├── agents/
+│   │   │   └── github-manager/
+│   │   ├── commands/
+│   │   │   ├── github-create-issue.md
+│   │   │   ├── github-sync.md
+│   │   │   └── ...
+│   │   └── lib/                # TypeScript utilities
+│   ├── specweave-figma/        # Figma design sync
+│   ├── specweave-infrastructure/ # K8s, Helm, Terraform
+│   └── ... (18 plugins total)
+│
+├── .claude-plugin/             # Claude Code marketplace (root level)
+│   ├── marketplace.json        # Plugin catalog (18 plugins)
+│   └── README.md               # Marketplace documentation
+│
 ├── .claude/                    # Pre-installed for SpecWeave dev
-│   ├── skills/                 # Synced from src/skills/
-│   ├── agents/                 # Synced from src/agents/
-│   └── commands/               # Synced from src/commands/
+│   ├── agents/                 # Installed from plugins/*/agents/
+│   ├── commands/               # Installed from plugins/*/commands/
+│   ├── hooks/                  # Installed from plugins/*/hooks/
+│   └── skills/                 # Installed from plugins/*/skills/
 │
 ├── .specweave/                 # SpecWeave's own increments
 │   ├── increments/
@@ -411,8 +973,17 @@ specweave/
 │   │   │   └── reports/        # ✅ Analysis files
 │   │   └── _backlog/
 │   ├── docs/
-│   │   ├── internal/           # Strategic docs
-│   │   └── public/             # Published docs
+│   │   ├── internal/           # Strategic docs (NEVER published)
+│   │   │   ├── strategy/       # Business strategy, market analysis
+│   │   │   ├── architecture/   # Technical architecture
+│   │   │   │   ├── adr/        # Architecture Decision Records
+│   │   │   │   ├── rfc/        # ✅ Request for Comments (detailed specs)
+│   │   │   │   ├── diagrams/   # Mermaid + SVG
+│   │   │   │   └── hld-system.md # High-Level Design
+│   │   │   └── delivery/       # Implementation notes, runbooks
+│   │   └── public/             # User-facing docs (can publish)
+│   │       ├── guides/
+│   │       └── api/
 │   └── logs/
 │
 ├── tests/
@@ -452,33 +1023,13 @@ specweave/
 
 ### ❌ NEVER Create in Root (Pollutes Repository)
 
-All AI-generated files MUST go into increment folders:
-
-```
-❌ WRONG:
-/SESSION-SUMMARY-2025-10-28.md          # NO!
-/ADR-006-DEEP-ANALYSIS.md               # NO!
-/ANALYSIS-MULTI-TOOL-COMPARISON.md      # NO!
-/CONTEXT-LOADER-CORRECTIONS.md          # NO!
-
-✅ CORRECT:
-.specweave/increments/0002-core-enhancements/
-├── reports/
-│   ├── SESSION-SUMMARY-2025-10-28.md
-│   ├── ADR-006-DEEP-ANALYSIS.md
-│   ├── ANALYSIS-MULTI-TOOL-COMPARISON.md
-│   └── CONTEXT-LOADER-CORRECTIONS.md
-├── logs/
-│   └── execution-2025-10-28.log
-└── scripts/
-    └── migration-helper.sh
-```
+**See comprehensive rules at top of document**: [🚨 CRITICAL: NEVER POLLUTE PROJECT ROOT!](#-critical-never-pollute-project-root)
 
-**Why?**
-- ✅ Complete traceability (which increment created which files)
-- ✅ Easy cleanup (delete increment folder = delete all files)
-- ✅ Clear context (all files for a feature in one place)
-- ✅ No root clutter
+**Quick summary**:
+- ✅ ALL AI-generated files → increment folders (`.specweave/increments/####/reports/`, `logs/`, `scripts/`)
+- ✅ Architecture decisions → `.specweave/docs/internal/architecture/adr/`
+- ❌ NEVER create `.md` files, scripts, or logs in project root
+- ❌ Build artifacts (`.tgz`, `.pt`, etc.) → add to `.gitignore`
 
 ### Runtime Artifacts (NOT Source Controlled)
 
@@ -508,51 +1059,50 @@ All AI-generated files MUST go into increment folders:
 
 ### Making Changes
 
-**1. Skills** (`src/skills/skill-name/`):
+**ALL components belong to plugins** (following [Claude Code's plugin system](https://docs.claude.com/en/docs/claude-code/plugins)).
+
+**1. Editing Skills** (any plugin):
 ```bash
-# Edit source
-vim src/skills/context-loader/SKILL.md
+# Core plugin (auto-loaded):
+vim plugins/specweave/skills/rfc-generator/SKILL.md
 
-# Sync to .claude/
-npm run install:skills
+# Other plugins (opt-in):
+vim plugins/specweave-github/skills/github-sync/SKILL.md
 
-# Test
-/context-loader-test
+# Skills auto-activate based on description keywords
 ```
 
-**2. Agents** (`src/agents/agent-name/`):
+**2. Editing Agents** (any plugin):
 ```bash
-# Edit source
-vim src/agents/pm/AGENT.md
+# Core plugin (auto-loaded):
+vim plugins/specweave/agents/pm/AGENT.md
 
-# Sync to .claude/
-npm run install:agents
+# Other plugins (opt-in):
+vim plugins/specweave-github/agents/github-manager/AGENT.md
 
 # Test by invoking via Task tool
 ```
 
-**3. Commands** (`src/commands/command-name.md`):
+**3. Editing Commands** (any plugin):
 ```bash
-# Edit source
-vim src/commands/specweave.do.md
+# Core plugin (auto-loaded):
+vim plugins/specweave/commands/do.md
 
-# Sync to .claude/
-npm run install:all
+# Other plugins (opt-in):
+vim plugins/specweave-github/commands/github-sync.md
 
-# Test
-/specweave.do
+# Test via /command-name
 ```
 
-**4. Core Logic** (`src/core/`, `src/cli/`):
+**4. Creating New Plugins** (see "Plugins" section below for complete instructions)
+
+**5. Editing Framework Code** (`src/core/`, `src/cli/`):
 ```bash
-# Edit TypeScript
+# Edit TypeScript (config manager, plugin loader, etc.)
 vim src/core/config-manager.ts
 
-# Build
-npm run build
-
-# Test
-npm test
+# Build and test
+npm run build && npm test
 ```
 
 ### Testing Strategy
@@ -567,10 +1117,10 @@ npm test
    - Test coverage plans per increment
    - TC-XXXX test case IDs
 
-3. **Skill Tests** (`src/skills/{name}/test-cases/*.yaml`)
-   - YAML-based test cases
+3. **Skill Tests** (`tests/specs/{skill-name}/` or `tests/integration/{skill-name}/`)
+   - Test cases for skill functionality
    - Minimum 3 test cases per skill
-   - Run via: `npm run test:skill`
+   - Run via: `npm run test:integration`
 
 4. **Code Tests** (`tests/`)
    - **E2E (Playwright)**: MANDATORY for UI features
@@ -590,339 +1140,182 @@ npm test
 
 ### Hooks and Automation
 
-**Post-Task Completion Hook** (`.claude/hooks/post-task-completion.sh`):
-- ✅ Plays completion sound (Glass.aiff on macOS)
-- ✅ Outputs JSON systemMessage reminder
-- ✅ Logs to `.specweave/logs/tasks.log`
+**Post-Task Completion Hook v2.0** (`.claude/hooks/post-task-completion.sh`):
+
+**Smart Session-End Detection**:
+- ✅ Tracks inactivity gaps between TodoWrite calls
+- ✅ Only plays sound when session is TRULY ending (15s+ inactivity after all tasks complete)
+- ✅ Skips sound during rapid work (Claude creating multiple todo lists)
+- ✅ Enhanced logging with decision reasoning in `.specweave/logs/hooks-debug.log`
+- ✅ Debouncing prevents duplicate hook fires
+
+**How It Works**:
+```
+Problem: Claude creates multiple todo lists in one conversation
+- List 1: [A, B, C] → completes → sound plays ❌
+- List 2: [D, E] → completes 30s later → sound plays again ❌
+- User hears sounds while Claude is still working!
+
+Solution: Inactivity-based detection
+- 10:00:00 - Task done (gap: 5s) → skip sound
+- 10:00:05 - Task done (gap: 5s) → skip sound
+- 10:00:10 - All done (gap: 5s) → skip sound (rapid work)
+- ... (15+ seconds pass)
+- 10:01:00 - All done (gap: 50s) → PLAY SOUND! ✅ (session ending)
+```
+
+**Configuration** (`src/hooks/post-task-completion.sh`):
+- `INACTIVITY_THRESHOLD=15` - Seconds of inactivity to assume session ending (adjustable)
+- `DEBOUNCE_SECONDS=2` - Prevents duplicate hook fires
 
 **Manual Actions** (Claude MUST do after each task):
 - Update `CLAUDE.md` when structure changes
 - Update `README.md` for user-facing changes
 - Update `CHANGELOG.md` for API changes
 
-**Living Docs Sync** (after `/specweave.do` completes):
-- Run `/sync-docs update`
+**Living Docs Sync** (after `/specweave:do` completes):
+- Run `/specweave:sync-docs update`
 - Updates `.specweave/docs/` with implementation learnings
 - Updates ADRs from Proposed → Accepted
 
 ---
 
-## Plugin Architecture (v0.4.0)
+## Plugins
 
-### Overview
+**SpecWeave is built 100% on [Claude Code's native plugin system](https://docs.claude.com/en/docs/claude-code/plugins)**.
 
-SpecWeave v0.4.0 introduces a **modular plugin system** that:
-- Reduces context usage by 60-80%
-- Enables community contributions
-- Maintains multi-tool support (Claude, Cursor, Copilot, Generic)
-- Preserves Claude Code's native advantages
+### Architecture: Everything is a Plugin
 
-### Core vs. Plugin Decision Tree
+**Critical Understanding**: SpecWeave doesn't have a "core framework" separate from plugins. Instead:
 
 ```
-Is this feature...
-├─ Used by EVERY project? → CORE
-├─ Specific to a tech stack (React, K8s, ML)? → PLUGIN
-├─ Part of increment lifecycle (spec, plan, tasks)? → CORE
-├─ Domain-specific expertise (DevOps, design, payments)? → PLUGIN
-├─ Automated via hooks (living docs)? → CORE
-└─ Nice-to-have but not essential? → PLUGIN
+SpecWeave = Collection of Claude Code Plugins
+├── specweave (auto-loaded) ← The "framework" IS a plugin
+├── specweave-github (opt-in)
+├── specweave-figma (opt-in)
+└── ...all other plugins (opt-in)
 ```
 
-### Plugin Structure
+**What this means**:
+- ✅ `specweave` is a Claude Code plugin (happens to auto-load)
+- ✅ All plugins follow identical structure (`.claude-plugin/plugin.json`, `skills/`, `agents/`, `commands/`)
+- ✅ Adding a skill = adding it to a plugin (always)
+- ❌ There are NO "core framework components" outside plugins
 
-```
-src/plugins/kubernetes/
-├── .claude-plugin/
-│   └── manifest.json           # Metadata, auto-detection, triggers
-├── skills/
-│   ├── k8s-deployer/
-│   │   ├── SKILL.md
-│   │   └── test-cases/
-│   ├── helm-manager/
-│   └── k8s-troubleshooter/
-├── agents/
-│   └── devops/
-│       └── AGENT.md
-├── commands/
-│   └── k8s-deploy.md
-└── README.md
-```
+**Why this matters**:
+- Uniform architecture (no special cases)
+- All plugins discoverable via Claude Code's plugin system
+- Easy to extend (just add another plugin)
+- Future-proof (follows Anthropic's standards)
 
-### Plugin Manifest Example
+**Further reading**:
+- 📖 [Claude Code Plugin Docs](https://docs.claude.com/en/docs/claude-code/plugins)
+- 📖 [Plugin Reference](https://docs.claude.com/en/docs/claude-code/plugins-reference)
+- 📖 [Plugin Marketplaces](https://docs.claude.com/en/docs/claude-code/plugin-marketplaces)
 
-```json
-{
-  "name": "specweave-kubernetes",
-  "version": "1.0.0",
-  "description": "Kubernetes deployment and management",
-  "author": "SpecWeave Team",
-  "license": "MIT",
-  "specweave_core_version": ">=0.4.0",
-
-  "auto_detect": {
-    "files": ["kubernetes/", "k8s/", "helm/"],
-    "packages": ["@kubernetes/client-node"],
-    "env_vars": ["KUBECONFIG"]
-  },
-
-  "provides": {
-    "skills": ["k8s-deployer", "helm-manager", "k8s-troubleshooter"],
-    "agents": ["devops"],
-    "commands": ["specweave.k8s.deploy"]
-  },
-
-  "triggers": ["kubernetes", "k8s", "kubectl", "helm", "pod", "deployment"]
-}
-```
+### Available SpecWeave Plugins
 
-### How Adapters Handle Plugins
+**Location**: `plugins/` (root level)
 
-**Claude Code** (Native):
-- Copies plugins to `.claude/skills/`, `.claude/agents/`, `.claude/commands/`
-- Skills auto-activate based on context
-- Hooks fire automatically
-- Quality: ⭐⭐⭐⭐⭐ (100%)
+**Discovery**:
+- Browse all plugins: `ls plugins/` or check [.claude-plugin/marketplace.json](/.claude-plugin/marketplace.json)
+- Live catalog: See `.claude-plugin/README.md` for current marketplace contents
+- Auto-detection during `specweave init` suggests relevant plugins
 
-**Cursor 2.0** (Compiled):
-- Appends plugin to `AGENTS.md`
-- Generates `cursor-team-commands.json` for dashboard
-- Creates `@<plugin-name>` context shortcuts
-- Quality: ⭐⭐⭐⭐ (85%)
+**Plugin Structure** (all follow same pattern):
+```
+plugins/specweave-{name}/
+├── .claude-plugin/plugin.json  # Claude native manifest
+├── skills/                     # Auto-activating capabilities (SKILL.md files)
+├── agents/                     # Specialized AI agents (AGENT.md files)
+├── commands/                   # Slash commands (.md files)
+└── lib/                        # TypeScript utilities (optional)
+```
 
-**Copilot** (Compiled):
-- Appends plugin to `.github/copilot/instructions.md`
-- Natural language instructions only
-- Quality: ⭐⭐⭐ (60%)
+**Key Plugins** (for reference):
+- `specweave` - Framework essentials (always loaded)
+- `specweave-github` - GitHub Issues integration
+- `specweave-{frontend|backend|infrastructure}` - Tech stack plugins
 
-**Generic** (Manual):
-- Appends plugin to `SPECWEAVE-MANUAL.md`
-- User copy-pastes relevant sections
-- Quality: ⭐⭐ (40%)
+**For complete list**: Check `plugins/` directory or marketplace.json
 
-### Four-Phase Plugin Detection
+### Plugin Decision Tree
 
-1. **Init-Time** (during `specweave init`):
-   - Scans `package.json`, directories, env vars
-   - Suggests plugins: "Found React. Enable frontend-stack? (Y/n)"
+**Key Insight**: In Claude Code's plugin system, EVERYTHING is a plugin. The only question is: **Which plugin does this belong to?**
 
-2. **First Increment** (during `/specweave.inc`):
-   - Analyzes increment description for keywords
-   - Suggests before creating spec: "This needs kubernetes plugin. Enable? (Y/n)"
+**Decision**: Which plugin should contain this feature?
 
-3. **Pre-Task** (before task execution):
-   - Hook scans task description
-   - Non-blocking suggestion: "This task mentions K8s. Consider enabling plugin."
+```
+Is this feature...
+├─ Used by EVERY project? → specweave (auto-loaded)
+│  Examples: increment-planner, rfc-generator, tdd-workflow, PM/Architect agents
+│
+├─ Part of increment lifecycle? → specweave (auto-loaded)
+│  Examples: /specweave:inc, /specweave:do, living docs hooks
+│
+├─ Tech stack specific? → New plugin: specweave-{stack}
+│  Examples: specweave-frontend (React, Next.js), specweave-kubernetes
+│
+├─ Domain expertise? → New plugin: specweave-{domain}
+│  Examples: specweave-ml (TensorFlow), specweave-payments (Stripe)
+│
+├─ External integration? → New plugin: specweave-{tool}
+│  Examples: specweave-github, specweave-jira, specweave-figma
+│
+└─ Optional enhancement? → New plugin: specweave-{feature}
+   Examples: specweave-diagrams, specweave-cost-optimizer
+```
 
-4. **Post-Increment** (after completion):
-   - Hook scans git diff for new dependencies
-   - Suggests for next increment: "Detected Stripe. Enable payment-processing plugin?"
+**Plugin Structure** (all follow Claude Code's standard):
+```
+plugins/specweave-{name}/
+├── .claude-plugin/plugin.json  # Required
+├── skills/                     # Optional
+├── agents/                     # Optional
+├── commands/                   # Optional
+└── hooks/                      # Optional
+```
 
-### Creating a New Plugin
+**Result**: Core plugin stayed at ~12K tokens (75% smaller than v0.3.7!)
 
-**For SpecWeave Contributors**:
+### Adding a New Plugin (Contributors)
 
+**Create New Plugin**:
 ```bash
-# 1. Create structure
-mkdir -p src/plugins/my-plugin/{.claude-plugin,skills,agents,commands}
+# 1. Create plugin structure
+mkdir -p plugins/specweave-myplugin/{.claude-plugin,skills,agents,commands,lib}
 
-# 2. Create manifest
-cat > src/plugins/my-plugin/.claude-plugin/manifest.json << 'EOF'
+# 2. Create plugin.json (Claude native format)
+cat > plugins/specweave-myplugin/.claude-plugin/plugin.json << 'EOF'
 {
-  "name": "specweave-my-plugin",
+  "name": "specweave-myplugin",
+  "description": "What it does and when to use it",
   "version": "1.0.0",
-  "description": "What it does",
-  "provides": {
-    "skills": ["skill-name"],
-    "agents": ["agent-name"],
-    "commands": ["command-name"]
-  },
-  "triggers": ["keyword1", "keyword2"]
+  "author": {"name": "Your Name"}
 }
 EOF
 
-# 3. Add skills/agents/commands (same format as core)
-
-# 4. Test
-specweave plugin enable my-plugin
+# 3. Add components (see Claude docs for format):
+# - skills/my-skill/SKILL.md
+# - agents/my-agent/AGENT.md
+# - commands/my-command.md
+# - lib/my-utility.ts (optional)
+
+# 4. Add to marketplace
+vim .claude-plugin/marketplace.json
+# Add entry:
+# {
+#   "name": "specweave-myplugin",
+#   "description": "What it does and when to use it",
+#   "source": "../plugins/specweave-myplugin"
+# }
+
+# 5. Test locally
+/plugin marketplace add ./.claude-plugin
+/plugin install myplugin@marketplace
 ```
 
-### Attribution for Borrowed Plugins
-
-If you fork a community plugin (e.g., from wshobson/agents):
-
-```json
-{
-  "name": "specweave-observability",
-  "version": "1.0.0",
-  "description": "Observability & monitoring for SpecWeave",
-
-  "credits": {
-    "based_on": "https://github.com/wshobson/agents/observability-monitoring",
-    "original_author": "Seth Hobson",
-    "license": "MIT",
-    "modifications": [
-      "Adapted for SpecWeave increment lifecycle",
-      "Added /sync-docs integration",
-      "SpecWeave naming conventions"
-    ]
-  }
-}
-```
-
-**Requirements**:
-- ✅ Clear attribution in manifest
-- ✅ Same or compatible open-source license
-- ✅ Document modifications made
-- ✅ Link to upstream prominently
-- ✅ Contribute improvements back (if possible)
-
-### Marketplace Publication
-
-SpecWeave publishes plugins to **two places**:
-
-1. **NPM Package** (primary):
-   - Full SpecWeave framework with plugin system
-   - `npm install -g specweave`
-
-2. **Anthropic Marketplace** (secondary):
-   - Individual plugins for standalone use
-   - `/plugin marketplace add specweave/marketplace`
-   - Works without full framework
-
-**Publishing a Plugin to Marketplace**:
-
-```bash
-# 1. Copy plugin to marketplace repo
-cp -r src/plugins/kubernetes marketplace/plugins/
-
-# 2. Update marketplace manifest
-# marketplace/.claude-plugin/marketplace.json
-
-# 3. Tag release
-git tag kubernetes-v1.0.0
-git push --tags
-
-# 4. Test installation
-/plugin marketplace add specweave/marketplace
-/plugin install kubernetes
-```
-
----
-
-## Current Work (Increment 0004)
-
-**Increment**: 0004-plugin-architecture
-**Title**: Plugin Architecture - Modular, Context-Efficient, Multi-Tool Support
-**Status**: ✅ COMPLETE (Foundation + GitHub plugin)
-**Priority**: P0
-**Started**: 2025-10-31
-**Completed**: 2025-10-31
-
-**Summary**:
-Successfully implemented modular plugin architecture with 60-80% context reduction, multi-tool support (Claude/Cursor/Copilot/Generic), and production-ready GitHub plugin. Core framework is complete and extensible for future plugins.
-
-**Key Achievements**:
-- ✅ **Core Plugin System** (T-001 to T-007):
-  - Plugin type definitions (Plugin, PluginManifest, Skill, Agent, Command)
-  - JSON Schema validation (plugin-manifest.schema.json, specweave-config.schema.json)
-  - PluginLoader (manifest validation, component loading, integrity checks)
-  - PluginManager (lifecycle management, dependency resolution, config management)
-  - PluginDetector (4-phase detection: init/spec/task/git-diff)
-
-- ✅ **Multi-Tool Adapter Support** (T-008 to T-010):
-  - Claude adapter: Native `.claude/` installation
-  - Cursor adapter: AGENTS.md compilation with HTML markers
-  - Copilot adapter: AGENTS.md compilation with HTML markers
-  - Generic adapter: AGENTS.md for manual workflows
-
-- ✅ **GitHub Plugin** (T-013 to T-022):
-  - 2 skills: github-sync, github-issue-tracker
-  - 1 agent: github-manager (GitHub CLI specialist)
-  - 4 commands: create-issue, sync, close-issue, status
-  - Auto-detection: `.git/` + `github.com` remote + `GITHUB_TOKEN`
-  - Production-ready manifest with proper dependencies
-
-- ✅ **Build & Configuration**:
-  - TypeScript compilation successful (all errors resolved)
-  - Updated .gitignore for plugin caching
-  - Ajv dependency added for JSON Schema validation
-  - ESM module compatibility maintained
-
-**Context Reduction Achieved**:
-- Basic project: 50K → 12K tokens (76% reduction!)
-- React app: 50K → 16K tokens (68% reduction!)
-- Backend API: 50K → 15K tokens (70% reduction!)
-
-**Files Implemented**:
-- `src/core/types/plugin.ts` - Complete type system
-- `src/core/schemas/plugin-manifest.schema.json` - Manifest validation
-- `src/core/schemas/specweave-config.schema.json` - Config validation
-- `src/core/plugin-loader.ts` - Plugin loading & validation
-- `src/core/plugin-manager.ts` - Lifecycle & dependency management
-- `src/core/plugin-detector.ts` - Auto-detection system
-- `src/adapters/*/adapter.ts` - Multi-tool plugin compilation
-- `src/plugins/specweave-github/` - Complete GitHub plugin
-
-**Next Steps**:
-1. ✅ Foundation complete - ready for additional plugins!
-2. 🔮 Future plugins (separate increments):
-   - specweave-jira (JIRA integration)
-   - specweave-ado (Azure DevOps)
-   - specweave-frontend-stack (React/Vue/Angular)
-   - specweave-backend-stack (Node/Python/.NET)
-
----
-
-## Previous Work (Increment 0003)
-
-**Increment**: 0003-intelligent-model-selection
-**Title**: Intelligent Model Selection - Automatic Cost Optimization
-**Status**: Planned (just created, ready to implement)
-**Priority**: P1
-**Started**: 2025-10-30
-
-**Summary**:
-Implement automatic cost optimization by intelligently routing work to Sonnet 4.5 (planning/analysis) vs Haiku 4.5 (execution), following Anthropic's official guidance. Expected 60-70% cost savings.
-
-**Key Features**:
-- ✅ Spec.md created (8 user stories, complete product requirements)
-- ✅ Plan.md created (comprehensive technical architecture)
-- ✅ Tasks.md created (22 implementation tasks)
-- ✅ Tests.md created (100+ test cases, quality validation)
-
-**Three-Layer System**:
-1. **Agent Model Preferences** - Each agent declares optimal model (Sonnet/Haiku/Auto)
-2. **Phase Detection** - Analyze user intent to detect planning vs execution
-3. **Cost Tracking** - Real-time cost visibility with savings calculations
-
-**Files to Focus On**:
-- `.specweave/increments/0003-intelligent-model-selection/spec.md`
-- `.specweave/increments/0003-intelligent-model-selection/plan.md`
-- `.specweave/increments/0003-intelligent-model-selection/tasks.md`
-- `.specweave/increments/0003-intelligent-model-selection/tests.md`
-
-**Next Steps**:
-1. Execute Task T-001: Create type definitions
-2. Execute Task T-002: Create pricing constants
-3. Execute Task T-003: Implement AgentModelManager
-4. Continue through all 22 tasks
-
----
-
-## Previous Work (Increment 0002)
-
-**Increment**: 0002-core-enhancements
-**Title**: Core Framework Enhancements - Multi-Tool Support & Diagram Agents
-**Status**: Completed (testing phase)
-**Priority**: P1
-**Started**: 2025-10-27
-
-**Key Achievements**:
-- ✅ Migrated commands to dot notation (`specweave.xxx`)
-- ✅ Diagram generation agents (C4, Sequence, ER)
-- ✅ Fixed context documentation
-- ✅ Corrected ADR-0002 (context loading architecture)
+**See**: [.claude-plugin/README.md](/.claude-plugin/README.md) for marketplace documentation
 
 ---
 
@@ -946,7 +1339,7 @@ Implement automatic cost optimization by intelligently routing work to Sonnet 4.
 
 ### 4. Incremental Development
 - Work in small, measurable increments
-- Use SpecWeave's own workflow (`/specweave.inc`, `/specweave.do`, etc.)
+- Use SpecWeave's own workflow (`/specweave:inc`, `/specweave:do`, etc.)
 - All work traces back to specs
 
 ### 5. Adapter-First Design
@@ -985,94 +1378,44 @@ git push origin develop --tags
 
 ---
 
-## Adapter System
-
-SpecWeave supports multiple AI coding tools via adapters:
-
-**Supported Tools**:
-- ✅ Claude Code (best-in-class, native support)
-- ✅ Cursor (via `.cursorrules` + Markdown commands)
-- ✅ GitHub Copilot (via `.github/copilot/instructions.md`)
-- ⏳ Generic (Markdown-only, for ChatGPT/Gemini/etc.)
-- 🔮 Windsurf (planned)
-
-**Adapter Pattern**:
-```
-src/adapters/
-├── claude/               # Claude Code native (slash commands, agents)
-│   ├── adapter.ts
-│   └── README.md
-├── cursor/               # Cursor (.cursorrules)
-│   ├── adapter.ts
-│   └── README.md
-├── copilot/              # GitHub Copilot (instructions.md)
-│   ├── adapter.ts
-│   └── README.md
-└── generic/              # Generic Markdown (all others)
-    ├── adapter.ts
-    └── SPECWEAVE-MANUAL.md
-```
-
-**Auto-Detection**:
-- Detects user's AI tool during `specweave init`
-- Installs appropriate adapter
-- Falls back to generic if unknown
-
----
-
-## Common Tasks
+## Adapter System (Legacy)
 
-### Add a New Skill
+**SpecWeave is Claude Code-first** - The framework is designed specifically for Claude Code's native capabilities.
 
-```bash
-# 1. Create skill directory
-mkdir -p src/skills/my-new-skill/test-cases
+**Primary Tool**:
+- ✅ **Claude Code** - Native support (slash commands, agents, skills, hooks, MCP)
 
-# 2. Create SKILL.md
-cat > src/skills/my-new-skill/SKILL.md << 'EOF'
----
-name: my-new-skill
-description: What it does and when to activate
----
+**Legacy Multi-Tool Support** (may be removed):
+- ⚠️  Cursor (via `.cursorrules` + AGENTS.md compilation)
+- ⚠️  GitHub Copilot (via `.github/copilot/instructions.md`)
+- ⚠️  Generic (Markdown-only, for ChatGPT/Gemini/etc.)
 
-# My New Skill
+**Why Claude-First?**
+The adapter system was originally designed to support multiple tools, but this added significant complexity without meaningful benefit. Claude Code provides:
+- ✅ **Native plugin marketplace** - No compilation needed
+- ✅ **Auto-activating skills** - No manual @ mentions
+- ✅ **Isolated agent contexts** - True role separation
+- ✅ **Pre/post lifecycle hooks** - Automated living docs sync
+- ✅ **MCP protocol** - Industry standard for context management
 
-Content here...
-EOF
+Other tools simply can't match these capabilities. The adapters remain in the codebase for now but are considered legacy and may be removed in a future version.
 
-# 3. Add test cases (minimum 3)
-vim src/skills/my-new-skill/test-cases/test-1-basic.yaml
+**See**: "Why Claude Code is Best-in-Class" section above for detailed comparison
 
-# 4. Install locally
-npm run install:skills
-
-# 5. Test
-# Ask Claude something that matches the skill's description
-```
-
-### Add a New Command
-
-```bash
-# 1. Create command file
-cat > src/commands/specweave.newcmd.md << 'EOF'
----
-name: newcmd
-description: Short description
 ---
 
-# New Command
+## Common Tasks
 
-Prompt for Claude...
-EOF
+### Adding Skills, Agents, or Commands
 
-# 2. Install locally
-npm run install:all
+**All components go into plugins** (see "Plugins" section above for complete instructions).
 
-# 3. Test
-/specweave.newcmd
+**Quick reference**:
+- **Core components**: `plugins/specweave/{skills|agents|commands|hooks}/`
+- **Plugin components**: `plugins/specweave-{name}/{skills|agents|commands}/`
+- **Tests**: `tests/integration/{component-name}/` or `tests/unit/`
 
-# 4. Add to commands/README.md index
-```
+**For detailed instructions**: See "Adding a New Plugin (Contributors)" section above (line ~1250)
 
 ### Update Documentation
 
@@ -1138,12 +1481,12 @@ cd docs-site && npm run build
 ## Quick Reference
 
 **Commands (for SpecWeave development)**:
-- `/specweave.inc "feature"` - Plan new increment
-- `/specweave.do` - Execute tasks (smart resume)
-- `/specweave.progress` - Check status
-- `/specweave.validate 0002` - Validate increment
-- `/specweave.done 0002` - Close increment
-- `/sync-docs update` - Sync living docs
+- `/specweave:inc "feature"` - Plan new increment
+- `/specweave:do` - Execute tasks (smart resume)
+- `/specweave:progress` - Check status
+- `/specweave:validate 0002` - Validate increment
+- `/specweave:done 0002` - Close increment
+- `/specweave:sync-docs update` - Sync living docs
 
 **Build & Test**:
 - `npm run build` - Compile TypeScript