specweave 0.26.11 → 0.26.13

package/src/templates/AGENTS.md.template

@@ -1,2619 +1,468 @@
 # {PROJECT_NAME}
 
 **Framework**: SpecWeave - Specification-First Development
-**Standard**: This file follows [agents.md](https://agents.md/) for universal AI compatibility
+**Standard**: [agents.md](https://agents.md/) for universal AI compatibility
 
 ---
 
-## 🎯 Getting Started
+## Section Index (Use Ctrl+F to Navigate)
 
-**Initial Increment Created**: `0001-project-setup` (`.specweave/increments/0001-project-setup/`)
-
-This increment was auto-generated by `specweave init` to give you a starting point.
-
-**Your Options**:
-1. **Start Fresh** (Recommended): Delete it and create your first real feature
-   - Delete the increment folder manually
-   - Ask user to run `/specweave:increment "your-feature-name"` (if in Claude Code) or create new increment via this file's commands
-2. **Customize It**: Edit the spec.md in the increment folder and use it for initial setup tasks
-
-**Note**: SpecWeave works best when each increment represents a single, focused feature or bugfix.
-
----
-
-## 🚨 CRITICAL: How to Use This File (Non-Claude Code Tools)
-
-**You're using Cursor, GitHub Copilot, or another AI tool - NOT Claude Code.**
-
-This means you **DO NOT have progressive disclosure** - this ENTIRE file (2000+ lines) is loaded into your context right now.
-
-**BUT** - you don't need to process everything at once!
-
-### Think of This File as a REFERENCE MANUAL
-
-- 📖 **Skim section headers** at session start (don't read all details)
-- 🔍 **Search for sections** when needed (use Ctrl+F / Command+F)
-- ✅ **Process ONLY relevant section** for current task
-- ♻️ **Ignore irrelevant sections** (don't waste tokens processing them)
-
-### Navigation Pattern
-
-**When user requests a task**:
-1. Search for relevant section (use Section Index below)
-2. Example: "sync to GitHub" → Search for `#workflow-github-sync`
-3. Read ONLY that section (50-100 lines)
-4. Execute workflow from that section
-5. Ignore other 1900+ lines (not needed right now!)
-
-### Example Workflow
-
-```
-User says: "Create new increment for user auth"
-↓
-You search: "increment" or "#command-increment"
-↓
-You find: ## Command: /specweave:increment {#command-increment}
-↓
-You read: That section ONLY (workflow, parameters, examples)
-↓
-You execute: Follow workflow from that section
-↓
-Done! (Ignored 95% of file - that's good!)
-```
-
-**This simulates progressive disclosure without tool support!**
-
----
-
-## 📑 SECTION INDEX (Your Navigation Menu)
-
-**Use Ctrl+F / Command+F to jump to sections instantly!**
-
-### 🎯 Essential (Read First - Always)
-- [Essential Knowledge](#essential-knowledge) ← **START HERE** every session
-- [Quick Reference Cards](#quick-reference-cards) ← Common commands
-- [Critical Rules](#critical-rules) ← Never violate these
-- [File Organization](#file-organization) ← Where files go
-
-### 🚀 Commands (When User Requests Action)
-Search pattern: `#command-{name}`
-
-**Core Commands**:
-- [/specweave:increment](#command-increment) - Plan new feature
-- [/specweave:do](#command-do) - Execute tasks
-- [/specweave:done](#command-done) - Close increment
-- [/specweave:progress](#command-progress) - Check status
-- [/specweave:validate](#command-validate) - Quality check
-- [/specweave:sync-docs](#command-sync-docs) - Sync living docs
-- [/specweave:sync-tasks](#command-sync-tasks) - Sync task status
-- [/specweave:next](#command-next) - Smart transition
-- [/specweave:costs](#command-costs) - AI cost dashboard
-
-**Plugin Commands** (if installed):
-- [/specweave:github:sync](#command-github-sync) - Sync to GitHub
-- [/specweave:jira:sync](#command-jira-sync) - Sync to Jira
-- [/specweave:ado:sync](#command-ado-sync) - Sync to Azure DevOps
-
-### 🎓 Skills (When You Need Specific Capability)
-Search pattern: `#skill-{name}`
-
-**Core Skills**:
-- [increment-planner](#skill-increment-planner) - Plan features
-- [spec-generator](#skill-spec-generator) - Generate specs
-- [context-loader](#skill-context-loader) - Token optimization
-- [brownfield-analyzer](#skill-brownfield-analyzer) - Analyze existing projects
-
-**Integration Skills**:
-- [github-sync](#skill-github-sync) - GitHub integration
-- [jira-sync](#skill-jira-sync) - Jira integration
-- [ado-sync](#skill-ado-sync) - Azure DevOps integration
-
-**Tech Stack Skills**:
-- [frontend](#skill-frontend) - React/Next.js/Vue
-- [backend](#skill-backend) - Node.js/Python/.NET
-- [infrastructure](#skill-infrastructure) - DevOps/Cloud
-
-### 👔 Agents (When You Need Role Perspective)
-Search pattern: `#agent-{name}`
-
-**Core Agents**:
-- [PM (Product Manager)](#agent-pm) - Requirements, user stories
-- [Architect](#agent-architect) - System design, technical planning
-- [Tech Lead](#agent-tech-lead) - Code review, best practices
-- [DevOps](#agent-devops) - Infrastructure, deployment
-- [QA Lead](#agent-qa-lead) - Testing strategy, quality gates
-- [Security](#agent-security) - Threat modeling, compliance
-
-### 📖 Workflows (Step-by-Step Procedures)
-Search pattern: `#workflow-{name}`
-
-**Daily Workflows**:
-- [Daily Development Workflow](#workflow-daily-development)
-- [Feature Increment Lifecycle](#workflow-increment-lifecycle)
-- [Task Completion Workflow](#workflow-task-completion)
-
-**Sync Workflows**:
-- [Living Docs Sync](#workflow-living-docs-sync)
-- [GitHub Sync](#workflow-github-sync)
-- [Jira Sync](#workflow-jira-sync)
-- [External Tracker Sync](#workflow-external-sync)
-
-**Advanced Workflows**:
-- [Multi-Project Setup](#workflow-multi-project)
-- [Increment Closure](#workflow-increment-closure)
-- [Documentation Updates](#workflow-documentation-updates)
-
-### 🆘 Common Issues (When Stuck)
-Search pattern: `#troubleshoot-{topic}`
-
-- [Skills Not Working](#troubleshoot-skills)
-- [Commands Not Found](#troubleshoot-commands)
-- [Sync Issues](#troubleshoot-sync)
-- [Root Folder Polluted](#troubleshoot-root-pollution)
-- [Duplicate Increments](#troubleshoot-duplicates)
-- [More Troubleshooting →](#troubleshooting)
-
-### 🔍 Search Patterns Reference
-
-| What You Need | Search For | Example |
-|---------------|------------|---------|
-| Command workflow | `#command-{name}` | "github sync" → `#command-github-sync` |
-| Skill capability | `#skill-{name}` | "planning" → `#skill-increment-planner` |
-| Agent role | `#agent-{name}` | "architect" → `#agent-architect` |
-| Procedure | `#workflow-{name}` | "daily work" → `#workflow-daily-development` |
-| Problem solving | `#troubleshoot-{topic}` | "sync broken" → `#troubleshoot-sync` |
-
-**Remember**: You have access to ALL knowledge - use search to find it efficiently!
+| Section | Search For | Purpose |
+|---------|------------|---------|
+| Rules | `#essential-rules` | Critical rules, file organization |
+| Commands | `#commands` | All SpecWeave commands |
+| **Hooks** | `#non-claude-tools` | **CRITICAL: Hook behavior to mimic** |
+| Sync | `#sync-workflow` | When/how to sync |
+| Context | `#context-loading` | Token savings (70%+) |
+| Troubleshoot | `#troubleshooting` | Common issues |
 
 ---
 
-## Project Overview
-
-This is a **SpecWeave project** where specifications and documentation are the source of truth.
-
-### Core Principle
-**Specification Before Implementation** - Define WHAT and WHY before HOW
-
-### Key Concepts
-- **Increments**: Feature units with spec.md (WHAT/WHY), plan.md (HOW), tasks.md (checklist)
-- **Context Manifests**: Load only relevant files (70%+ token reduction)
-- **Living Documentation**: Specs evolve with code, never diverge
-- **Role-Based Development**: PM defines requirements, Architect designs, DevOps deploys
-- **Bidirectional Linking**: Tasks automatically link to user stories (and vice versa)
-
-### Bidirectional Task ↔ User Story Linking
-
-**AUTOMATIC FEATURE**: When increment completes (`/specweave:done`), SpecWeave creates bidirectional links.
-
-**How It Works**:
-1. User stories extracted to `.specweave/docs/internal/specs/{project}/`
-2. Tasks.md automatically updated with links back to user stories
-3. Complete bidirectional navigation created!
-
-**Requirements**:
-- Tasks MUST have **AC**: field with AC-IDs (e.g., `AC-US1-01, AC-US1-02`)
-- AC-IDs map to user stories: `AC-US1-01` → `US-001`
-
-**Example Task** (WITH bidirectional link):
-```markdown
-### T-001: Implement User Login
-
-**User Story**: [US-001: User Authentication](../../docs/internal/specs/default/auth-service/us-001-user-authentication.md)
-
-**AC**: AC-US1-01, AC-US1-02, AC-US1-03
+## Quick Start
 
-**Test Plan** (BDD):
-- **Given** valid credentials → **When** login → **Then** receive JWT token
-```
+**Initial Increment**: `0001-project-setup` (`.specweave/increments/0001-project-setup/`)
 
-**Benefits**:
-- ✅ Navigate both directions (Tasks → User Stories → Tasks)
-- ✅ Automatic (no manual linking)
-- ✅ Multi-project aware (works with backend, frontend, mobile, etc.)
+1. **Start Fresh**: Delete it, run `/specweave:increment "your-feature"`
+2. **Customize**: Edit spec.md in the increment folder
 
 ---
 
-## 📋 Quick Reference Cards {#quick-reference-cards}
-
-### 🎯 Essential Knowledge {#essential-knowledge}
-
-**Read this EVERY session start!**
+## Essential Rules {#essential-rules}
 
-#### Critical Rules {#critical-rules}
 ```
-⛔ NEVER pollute project root with .md files!
-⛔ Increment IDs must be unique (0001-9999)!
-⛔ ONLY 3 files in increment root: spec.md, plan.md, tasks.md
-⛔ All reports/scripts/logs go in increment subfolders!
-⛔ Always check: git status (before committing)!
+1. NEVER pollute project root with .md files
+2. Increment IDs unique (0001-9999)
+3. ONLY 3 files in increment root: spec.md, plan.md, tasks.md
+4. All reports/scripts/logs → increment subfolders
+5. Read context-manifest.yaml first (70%+ token savings)
+6. tasks.md + spec.md = SOURCE OF TRUTH (update after every task!)
 ```
 
-#### File Organization {#file-organization}
-
-**Increment Structure (MANDATORY)**:
+**File Organization**:
 ```
 .specweave/increments/0001-feature/
-├── spec.md              # ⚠️ ONLY THESE 3 FILES in root!
-├── plan.md
-├── tasks.md
-├── reports/             # ✅ ALL REPORTS HERE
-│   ├── SESSION-*.md
-│   ├── QUICK-START.md
-│   ├── ULTRATHINK-*.md
-│   └── ANALYSIS-*.md
-├── scripts/             # ✅ ALL SCRIPTS HERE
-│   └── *.{py,sh,ts}
-└── logs/                # ✅ ALL LOGS HERE
-    └── *.log
-```
-
-**File Placement Rules**:
-```
-┌────────────────────────────────────────────────────────────┐
-│ NEVER in Root           ↔ ALWAYS in Increment Folder      │
-├────────────────────────────────────────────────────────────┤
-│ ❌ QUICK-START.md       ↔ ✅ .../0001/reports/QUICK-START  │
-│ ❌ analysis.md          ↔ ✅ .../0001/reports/analysis.md  │
-│ ❌ migration.py         ↔ ✅ .../0001/scripts/migration.py │
-│ ❌ execution.log        ↔ ✅ .../0001/logs/execution.log   │
-│ ❌ session-notes.md     ↔ ✅ .../0001/reports/session.md   │
-└────────────────────────────────────────────────────────────┘
-```
-
-### Daily Workflow
-```
-┌────────────────────────────────────────────────────────────┐
-│ TASK                    → COMMAND                          │
-├────────────────────────────────────────────────────────────┤
-│ Plan new feature        → /specweave:increment "feature"   │
-│ Execute tasks           → /specweave:do                    │
-│ Check progress          → /specweave:progress              │
-│ Validate quality        → /specweave:validate 0001         │
-│ Close increment         → /specweave:done 0001             │
-└────────────────────────────────────────────────────────────┘
-```
-
-### After EVERY Task Completion (CRITICAL!)
-```
-⚠️ Non-Claude tools do NOT have automatic hooks!
-
-After completing EACH task, you MUST run:
-
-1. /specweave:sync-tasks                  # Update tasks.md
-2. /specweave:sync-docs update            # Sync living docs
-3. /specweave:github:sync <increment-id>  # Sync to GitHub (if enabled)
-
-Without these, your work won't be tracked properly!
+├── spec.md, plan.md, tasks.md    # ONLY these in root
+├── reports/                       # SESSION-*.md, analysis, etc.
+├── scripts/                       # Helper scripts
+└── logs/                          # Execution logs
 ```
 
-### When to Use Which Command
-
-| User Says...              | Use Command                        |
-|---------------------------|------------------------------------|
-| "Let's build X"           | `/specweave:increment "X"`         |
-| "Start implementing"      | `/specweave:do`                    |
-| "What's the status?"      | `/specweave:progress`              |
-| "Is this ready?"          | `/specweave:validate 0001`         |
-| "We're done"              | `/specweave:done 0001`             |
-| "Sync to GitHub"          | `/specweave:github:sync`           |
-| "Sync to Jira"            | `/specweave:jira:sync`             |
-| "Update docs"             | `/specweave:sync-docs update`      |
-
 ---
 
-## Project Structure
-
-**IMPORTANT**: This project uses {MONOREPO_OR_SINGLE} mode.
-
-{#IF_SINGLE_PROJECT}
-### Single Project Structure
-
-```
-.specweave/
-├── increments/              # Feature increments (auto-numbered)
-│   └── 0001-feature-name/
-│       ├── spec.md          # WHAT & WHY (business requirements)
-│       ├── plan.md          # HOW (technical implementation)
-│       ├── tasks.md         # Tasks with embedded test plans (BDD format)
-│       ├── context-manifest.yaml  # Selective loading (token savings!)
-│       ├── logs/            # Execution logs, errors
-│       ├── scripts/         # Helper scripts
-│       └── reports/         # Analysis, completion reports
-├── docs/internal/
-│   ├── strategy/            # Business specs (WHAT, WHY)
-│   ├── specs/               # Feature specifications (living docs)
-│   │   └── default/         # ✅ All specs in default project
-│   ├── architecture/        # Technical design (HOW)
-│   ├── delivery/            # Roadmap, CI/CD, guides
-│   ├── operations/          # Runbooks, SLOs
-│   └── governance/          # Security, compliance
-
-.claude/                     # Claude Code components (if using Claude)
-├── agents/                  # Specialized roles (PM, Architect, DevOps, etc.)
-├── skills/                  # Capabilities (increment-planner, context-loader, etc.)
-└── commands/                # Slash commands (/specweave:increment, /specweave:do, /specweave:done)
-
-plugins/                     # Optional plugins (extended capabilities)
-└── specweave-{name}/
-    ├── .claude-plugin/      # Plugin manifest (Claude native format)
-    │   └── plugin.json
-    ├── skills/              # Plugin-specific skills
-    ├── agents/              # Plugin-specific agents
-    └── commands/            # Plugin-specific commands
-```
-{#ENDIF}
-
-{#IF_MULTI_PROJECT}
-### Multi-Project Structure (v0.16.11+ Flattened)
-
-**CRITICAL**: Specs are organized by project with FLATTENED structure (v0.16.11+).
-
-```
-.specweave/
-├── docs/internal/
-│   ├── strategy/            # Cross-project strategy
-│   ├── specs/               # ✅ FLATTENED structure (v0.16.11+)
-│   │   ├── backend/         # Backend project specs
-│   │   │   ├── spec-001-api-auth.md
-│   │   │   └── spec-002-data-layer.md
-│   │   ├── frontend/        # Frontend project specs
-│   │   │   ├── spec-001-user-dashboard.md
-│   │   │   └── spec-002-dark-mode.md
-│   │   ├── mobile/          # Mobile project specs (if applicable)
-│   │   │   └── spec-001-push-notifications.md
-│   │   └── _parent/         # Parent repo specs (multi-repo only)
-│   │       └── spec-001-system-architecture.md
-│   ├── architecture/        # System-wide technical design
-│   ├── delivery/            # Cross-project delivery
-│   ├── operations/          # Cross-project operations
-│   └── governance/          # Cross-project governance
-├── increments/
-│   ├── 0001-backend-auth/   # Backend increment
-│   ├── 0002-frontend-ui/    # Frontend increment
-│   └── 0003-mobile-push/    # Mobile increment
-└── ...
-```
+## Commands Reference {#commands}
 
-**Living Docs Path Format**:
-- ✅ **CORRECT** (v0.16.11+): `.specweave/docs/internal/specs/{project-id}/spec-NNN-name.md`
-- ❌ **OLD** (v0.8.0-v0.16.10): `.specweave/docs/internal/projects/{project-id}/specs/...` (DEPRECATED)
+### Core Commands
 
-**Project Detection** (automatic):
-- **From increment name**: `0001-backend-auth` → project: `backend`
-- **From tech stack**: React/Next.js → `frontend`, ASP.NET/Node.js → `backend`
-- **From config**: `multiProject.activeProject` in `.specweave/config.json`
-- **Fallback**: Uses `default` project
+| Command | Purpose |
+|---------|---------|
+| `/specweave:increment "name"` | Plan new feature (PM-led) |
+| `/specweave:do` | Execute tasks from active increment |
+| `/specweave:done 0001` | Close increment (validates gates) |
+| `/specweave:progress` | Show task completion status |
+| `/specweave:validate 0001` | Quality check before closing |
+| `/specweave:sync-tasks` | Sync tasks.md with reality |
+| `/specweave:sync-docs update` | Sync to living docs |
 
-**When creating living docs specs**:
-1. Detect project from increment name or tech stack
-2. Use flattened path: `specs/{project-id}/spec-NNN-name.md`
-3. Never use old nested structure: `projects/{project-id}/specs/...`
-{#ENDIF}
+### Plugin Commands (when installed)
 
-**CRITICAL**: Always read `context-manifest.yaml` first! Only load files listed there.
+| Command | Purpose |
+|---------|---------|
+| `/specweave-github:sync 0001` | Sync increment to GitHub issue |
+| `/specweave-jira:sync 0001` | Sync to Jira |
+| `/specweave-ado:sync 0001` | Sync to Azure DevOps |
 
 ---
 
-## 🔌 Plugin Architecture (IMPORTANT FOR NON-CLAUDE TOOLS)
-
-### For Claude Code Users
-
-Plugins work automatically via marketplace:
-```bash
-/plugin install github
-```
-
-Skills, agents, and commands are immediately available. **Skip this section if using Claude Code.**
-
-### For Other Tools (Cursor, Copilot, ChatGPT, etc.)
+## Non-Claude Tools (Cursor, Copilot, etc.) {#non-claude-tools}
 
-**⚠️ CRITICAL**: Claude Code has native plugin support. **Other tools DO NOT.**
+**CRITICAL**: Claude Code has automatic hooks. Other tools DO NOT.
 
-You MUST manually discover and load plugins at the start of each session:
+### What's Different
 
-#### Step 1: Check for Plugins
+| Feature | Claude Code | Cursor/Copilot |
+|---------|-------------|----------------|
+| Commands | Slash syntax works | Manual workflow |
+| Hooks | Auto-run on events | **YOU must mimic** |
+| Task sync | Automatic | Manual |
+| GitHub/Jira sync | Automatic | Manual |
+| Living docs | Auto-updated | Manual |
 
-```bash
-# Check if project uses plugins
-ls plugins/
-
-# Example output:
-# specweave-github/
-# specweave-jira/
-```
-
-If `plugins/` folder exists, proceed to Step 2.
+### Hook Behavior You Must Mimic
 
-#### Step 2: Load Plugin Components
-
-**For EACH plugin, load its components BEFORE starting work:**
+**Claude Code hooks do these automatically. YOU must do them manually:**
 
+#### 1. After EVERY Task Completion
 ```bash
-# Example: Loading GitHub plugin
-
-# 1. Check plugin structure
-ls plugins/specweave-github/
+# Claude hook: PostTaskCompletion
+# You must run these commands:
 
-# 2. Load ALL plugin skills (like core skills)
-cat plugins/specweave-github/skills/github-sync/SKILL.md
-cat plugins/specweave-github/skills/github-issue-tracker/SKILL.md
+# Step 1: Update tasks.md (source of truth)
+# Change: **Status**: [ ] pending → **Status**: [x] completed
 
-# 3. Load plugin agents (if any)
-cat plugins/specweave-github/agents/github-manager/AGENT.md
+# Step 2: Update spec.md ACs (if task satisfies any)
+# Change: - [ ] AC-US1-01 → - [x] AC-US1-01
 
-# 4. Note available commands (load on-demand when user requests)
-ls plugins/specweave-github/commands/
-# github-create-issue.md, github-sync.md, github-status.md
+# Step 3: Sync to external tools (if configured)
+/specweave:sync-tasks
+/specweave-github:sync <increment-id>   # If GitHub enabled
+/specweave-jira:sync <increment-id>     # If Jira enabled
 ```
 
-#### Step 3: Make Plugin Capabilities Available
-
-Treat plugin components like core components:
-
-**Plugin Skills**:
-- Same activation pattern as core skills
-- Check "Activates for" keywords in SKILL.md
-- Follow workflow when relevant
-
-**Plugin Agents**:
-- Adopt role when needed (like core agents)
-- Example: "Adopting github-manager agent role..."
-
-**Plugin Commands**:
-- Load command file when user requests action
-- Example: User says "sync to GitHub" → Load `plugins/specweave-github/commands/github-sync.md`
-
-#### Step 4: Document Loaded Plugins
+#### 2. After User Story Completion (all ACs satisfied)
+```bash
+# Claude hook: PostUserStoryCompletion
+# When ALL acceptance criteria for a user story are [x] checked:
 
-At session start, note which plugins are active:
+# Step 1: Sync to living docs
+/specweave:sync-docs update
 
-```markdown
-# Session Context
-- Core skills: ✅ Loaded from .claude/skills/
-- Core agents: ✅ Loaded from .claude/agents/
-- Plugins detected:
-  - specweave-github: ✅ Loaded (2 skills, 1 agent, 4 commands)
-  - specweave-jira: ✅ Loaded (1 skill, 1 agent, 2 commands)
+# Step 2: Update GitHub/Jira issue status
+/specweave-github:sync <increment-id>
 ```
 
-### Why Manual Loading Is Required
-
-**Claude Code**: Has native plugin marketplace, auto-loads plugins, manages dependencies.
-
-**Other Tools**: No plugin system, so you must:
-- ✅ Discover plugins in `plugins/` folder
-- ✅ Read plugin skills/agents/commands manually
-- ✅ Make them available in your context
-- ✅ Use them like core components
-
-**This is NOT optional** - plugins extend SpecWeave capabilities. Without loading them, you're missing critical functionality (GitHub sync, Jira integration, tech-specific skills, etc.).
-
-### Example: Session Start Routine (Non-Claude Tools)
-
+#### 3. After Increment Completion
 ```bash
-# 1. Load core components
-cat .claude/skills/SKILLS-INDEX.md  # Core skills index
-cat AGENTS.md                        # This file
-
-# 2. Check for plugins
-if [ -d "plugins" ]; then
-  # 3. For each plugin, load components
-  for plugin in plugins/*/; do
-    echo "Loading plugin: $(basename $plugin)"
+# Claude hook: PostIncrementDone
+# When running /specweave:done:
 
-    # Load all skills
-    find "$plugin/skills" -name "SKILL.md" -exec cat {} \;
+# Step 1: Validate all tasks complete
+/specweave:validate <increment-id>
 
-    # Load all agents
-    find "$plugin/agents" -name "AGENT.md" -exec cat {} \;
-
-    # Note available commands
-    ls "$plugin/commands/"
-  done
-fi
+# Step 2: Sync living docs
+/specweave:sync-docs update
 
-# 4. Now ready to work with full SpecWeave capabilities
+# Step 3: Close external issues
+/specweave-github:close-issue <increment-id>
 ```
 
-### Plugin Naming Convention
-
-Plugin commands use namespace pattern:
-
-**Core commands** (no namespace):
-- `/specweave:increment` → Core framework
-- `/specweave:do` → Core framework
-- `/specweave:progress` → Core framework
-
-**Plugin commands** (with namespace):
-- `/specweave:github:sync` → GitHub plugin
-- `/specweave:github:create-issue` → GitHub plugin
-- `/specweave:jira:sync` → Jira plugin
-- `/specweave:jira:create-ticket` → Jira plugin
-
-**In non-Claude tools**: Read the command file when user requests the action:
+#### 4. After Writing to spec.md or tasks.md
 ```bash
-# User: "Sync this increment to GitHub"
-# You: Load and execute command
-cat plugins/specweave-github/commands/github-sync.md
-# Then follow the instructions in that file
-```
-
----
+# Claude hook: PostToolUse (Write/Edit to spec/tasks files)
+# After any edit to spec.md or tasks.md:
 
-## 🚀 SpecWeave Commands (Executable Workflows)
-
-**⚡ CRITICAL FOR NON-CLAUDE TOOLS**: Commands are NOT automatic in GitHub Copilot, Cursor, or other tools. You MUST manually discover and execute them.
-
-### What Are Commands?
-
-Commands are **executable workflows** defined as `.md` files in `plugins/specweave/commands/`. Each file contains:
-- Command name (from filename, e.g., `specweave-increment.md` → `/specweave:increment`)
-- Complete workflow instructions
-- Parameters and usage examples
-- Step-by-step execution guide
-
-**Think of them as runnable scripts** - when user requests a command, you read the file and execute the workflow.
-
-### Command Discovery (MANDATORY!)
-
-**At the start of EVERY session**, discover available commands:
-
-```bash
-# List all core commands
-ls plugins/specweave/commands/
+# Sync status line cache
+/specweave:sync-tasks
 
-# Common output:
-# specweave-increment.md  - Plan new increment (/specweave:increment "feature")
-# specweave-do.md         - Execute implementation (/specweave:do)
-# specweave-done.md       - Close increment (/specweave:done 0001)
-# specweave-validate.md   - Validate increment (/specweave:validate 0001)
-# specweave-progress.md   - Check status (/specweave:progress)
-# specweave-sync-docs.md  - Sync living docs (/specweave:sync-docs)
-# specweave-next.md       - Smart increment transition (/specweave:next)
-# specweave-costs.md      - Display AI cost dashboard (/specweave:costs)
-# specweave-translate.md  - Translate content (/specweave:translate)
-# tdd-*.md        - TDD workflow commands
-# ... (17 commands total)
+# If external tools configured, sync progress
+/specweave-github:sync <increment-id>
 ```
 
-**For plugin commands** (if plugins/ folder exists):
+### How to Check if External Tools Configured
 
 ```bash
-# List plugin commands
-ls plugins/specweave-github/commands/
-
-# Example output:
-# github-create-issue.md
-# github-sync.md
-# github-close-issue.md
-# github-status.md
-```
-
-### How to Execute Commands (Step-by-Step)
-
-**When user says**: "create new increment for user auth" or "run /specweave:increment user auth"
-
-**You should**:
-
-1. **Identify the command**:
-   - Keywords match: "create increment" → `specweave-increment.md`
-   - Explicit slash: "/specweave:increment" → `specweave-increment.md`
-   - Map request to command file
+# Check increment metadata for external tool config
+cat .specweave/increments/<id>/metadata.json
 
-2. **Read the command file**:
-   ```bash
-   cat plugins/specweave/commands/specweave-increment.md
-   ```
-
-3. **Parse the workflow**:
-   - Read YAML frontmatter for metadata
-   - Read markdown body for steps
-   - Note required parameters
-   - Understand expected output
-
-4. **Execute the workflow**:
-   - Follow instructions EXACTLY as written
-   - Use parameters from user request
-   - Reference related files (spec templates, etc.)
-   - Show progress as you work
-
-5. **Provide output**:
-   - Confirm completion
-   - Show created files
-   - Suggest next steps
-
-### Example: Executing /specweave:increment Command
+# Look for these fields:
+# "github": { "issue": 123 }     → GitHub enabled
+# "jira": { "issue": "PROJ-123" } → Jira enabled
+# "ado": { "item": 456 }          → Azure DevOps enabled
+```
 
-**User says**: "create new increment for user authentication"
+### Manual Command Execution
 
-**Your workflow**:
+In non-Claude tools, commands are markdown workflows:
 
 ```bash
-# Step 1: Identify command
-# "create increment" → specweave-increment.md
-
-# Step 2: Read command file
+# Find and read command file
 cat plugins/specweave/commands/specweave-increment.md
+# Follow the workflow steps manually
 ```
 
-**After reading specweave-increment.md, you learn**:
-- This is PM-led increment planning
-- Requires: feature description
-- Creates: spec.md, plan.md, tasks.md, tests.md
-- Location: `.specweave/increments/####-feature-name/`
+### Quick Reference: After EVERY Task
 
-**Step 3: Execute workflow from inc.md**:
-
-```markdown
-# You see these instructions in inc.md:
-
-1. **Detect tech stack** (TypeScript, Python, Go, etc.)
-2. **PM-led planning**:
-   - Market research
-   - Create spec.md (WHAT & WHY)
-   - Create plan.md (HOW)
-   - Auto-generate tasks.md from plan
-   - Create tests.md (test strategy)
-3. **Strategic agent review**:
-   - Architect designs system
-   - Security reviews threats
-   - QA defines test strategy
-4. **User review checkpoint**
-5. **Ready to build**
 ```
-
-**Step 4: Execute those steps**:
-
+┌─────────────────────────────────────────────────────────────┐
+│ AFTER COMPLETING ANY TASK (MANDATORY FOR NON-CLAUDE TOOLS)  │
+├─────────────────────────────────────────────────────────────┤
+│ 1. Update tasks.md: [ ] → [x]                               │
+│ 2. Update spec.md ACs if satisfied: [ ] → [x]               │
+│ 3. Run: /specweave:sync-tasks                               │
+│ 4. Run: /specweave-github:sync <id>  (if GitHub configured) │
+│ 5. If all ACs for US done: /specweave:sync-docs update      │
+└─────────────────────────────────────────────────────────────┘
 ```
-📂 Creating increment 0001-user-authentication...
-
-🔍 Tech stack detected: TypeScript + Node.js + PostgreSQL
-
-👔 Adopting PM role to create spec.md...
-   ✓ Market research: Auth requirements
-   ✓ User stories: Login, Register, Password Reset
-   ✓ Acceptance criteria: TC-0001 to TC-0015
-   ✓ Created spec.md (WHAT & WHY, technology-agnostic)
 
-🏗️ Adopting Architect role to create plan.md...
-   ✓ Architecture: JWT + bcrypt + Prisma
-   ✓ API contracts: POST /auth/login, /auth/register
-   ✓ Data model: User table schema
-   ✓ Created plan.md (HOW, technology-specific)
+**Without these manual steps, your work won't be tracked!**
 
-📋 Auto-generating tasks.md from plan.md...
-   ✓ Generated 42 tasks with model hints
-   ✓ Estimated: 3-4 weeks
-
-🧪 Creating tests.md (QA strategy)...
-   ✓ 12 test cases, 85% coverage target
-
-✅ Increment 0001-user-authentication ready!
+---
 
-Next: /specweave:do (execute implementation)
-```
+## Sync Workflow {#sync-workflow}
 
-**Step 5: Confirm completion**:
+### Source of Truth Hierarchy
 
 ```
-✅ Created increment 0001-user-authentication
-
-Files:
-  • .specweave/increments/0001-user-authentication/spec.md
-  • .specweave/increments/0001-user-authentication/plan.md
-  • .specweave/increments/0001-user-authentication/tasks.md
-  • .specweave/increments/0001-user-authentication/tests.md
-
-Next steps:
-  1. Review generated files
-  2. Run: /specweave:do (execute implementation)
+┌─────────────────────────────────────────────────────────────┐
+│ SOURCE OF TRUTH (edit here first!)                          │
+│ ├── tasks.md: Task completion status                        │
+│ └── spec.md: Acceptance criteria checkboxes                 │
+├─────────────────────────────────────────────────────────────┤
+│ DERIVED (auto-updated via sync commands)                    │
+│ └── .specweave/docs/internal/specs/: Living documentation   │
+├─────────────────────────────────────────────────────────────┤
+│ MIRROR (synced to external tools)                           │
+│ ├── GitHub Issues: Task checklist, AC progress              │
+│ ├── Jira Stories: Status, story points, completion          │
+│ └── Azure DevOps: Work item state, task list                │
+└─────────────────────────────────────────────────────────────┘
 ```
 
-### Core Command Reference
-
-**Most Common** (use these daily):
-
-| Command | File | Purpose | Example |
-|---------|------|---------|---------|
-| `/specweave:increment` | `specweave-increment.md` | Plan new increment | `/specweave:increment "user auth"` |
-| `/specweave:do` | `specweave-do.md` | Execute implementation | `/specweave:do` |
-| `/specweave:done` | `specweave-done.md` | Close increment | `/specweave:done 0001` |
-| `/specweave:validate` | `specweave-validate.md` | Validate quality | `/specweave:validate 0001` |
-| `/specweave:progress` | `specweave-progress.md` | Check status | `/specweave:progress` |
-
-**Specialized** (use when needed):
-
-| Command | File | Purpose | Example |
-|---------|------|---------|---------|
-| `/specweave:sync-docs` | `specweave-sync-docs.md` | Sync living docs | `/specweave:sync-docs update` |
-| `/specweave:next` | `specweave-next.md` | Smart increment transition | `/specweave:next` |
-| `/specweave:costs` | `specweave-costs.md` | AI cost dashboard | `/specweave:costs 0001` |
-| `/specweave:translate` | `specweave-translate.md` | Translate content | `/specweave:translate ru` |
-| `/specweave:tdd-cycle` | `specweave-tdd-cycle.md` | TDD workflow | `/specweave:tdd-cycle` |
-
-**Plugin Commands** (when plugins installed):
-
-| Command | File | Purpose | Plugin |
-|---------|------|---------|--------|
-| `/github:sync` | `plugins/specweave-github/commands/github-sync.md` | Sync to GitHub | specweave-github |
-| `/github:create-issue` | `plugins/specweave-github/commands/github-create-issue.md` | Create GitHub issue | specweave-github |
-| `/sync-tasks` | `commands/sync-tasks.md` | Sync tasks.md status | specweave (core) |
-
----
-
-### 🚨 CRITICAL: Task Completion Tracking
-
-**Problem**: Commands like `/progress`, `/validate`, `/done` rely on `tasks.md` status being accurate.
-If tasks.md shows "1/24 complete" but you've actually finished 24 tasks, everything breaks!
-
-**Solution**: Update `tasks.md` after EACH task completes.
-
-#### For Claude Code Users (Automatic ✅)
-
-**Good news**: This happens automatically via `post-task-completion.sh` hook!
-
-When you complete a task (mark todo as done), the hook:
-1. ✅ Detects completion
-2. ✅ Updates corresponding task in tasks.md
-3. ✅ Recalculates progress %
-4. ✅ Syncs to GitHub issue (if enabled)
-
-**You don't need to do anything manually!**
-
-#### For Other AI Tools (Manual ⚠️)
-
-**⚠️ IMPORTANT**: After completing EACH task, run these slash commands to keep everything in sync:
-
-**Quick Commands** (copy-paste friendly):
-
-```bash
-# After completing a task, run these three commands:
-
-/specweave:sync-tasks                  # 1. Update tasks.md completion status
-/specweave:sync-docs update            # 2. Sync to living docs (THIS IS CRITICAL!)
-/specweave-github:sync <increment-id>  # 3. Sync to GitHub (replace <increment-id> with your increment, e.g., 0007)
-```
+**Update Order**: ALWAYS tasks.md/spec.md FIRST → sync-tasks → sync-docs → external tools
 
-**🔥 CRITICAL: Living Docs Sync (`/specweave:sync-docs`)**
+### Sync Commands Reference
 
-The `/specweave:sync-docs` command is one of the MOST IMPORTANT commands in SpecWeave. It ensures your increment work gets properly archived in the living documentation.
+| Command | What It Does | When to Run |
+|---------|--------------|-------------|
+| `/specweave:sync-tasks` | Recalculates progress from tasks.md | After editing tasks.md |
+| `/specweave:sync-docs update` | Updates living docs from increment | After US complete |
+| `/specweave-github:sync <id>` | Syncs progress to GitHub issue | After each task |
+| `/specweave-github:close-issue <id>` | Closes GitHub issue | On increment done |
+| `/specweave-jira:sync <id>` | Syncs progress to Jira story | After each task |
+| `/specweave-ado:sync <id>` | Syncs to Azure DevOps work item | After each task |
 
-**How to call it** (for non-Claude tools):
+### Complete Sync Flow (Non-Claude Tools)
 
-```bash
-# Read the command file
-cat plugins/specweave/commands/specweave-sync-docs.md
-
-# Then execute the workflow described in that file
-# The command will:
-# 1. Extract user stories from spec.md
-# 2. Distribute them to .specweave/docs/internal/specs/{project}/
-# 3. Create bidirectional links (Tasks ↔ User Stories)
-# 4. Update epic folders (FS-*) with latest content
-# 5. Generate proper Docusaurus frontmatter
 ```
-
-**When to run it**:
-- ✅ After completing an increment (`/specweave:done`)
-- ✅ After making significant spec changes
-- ✅ After implementing multiple user stories
-- ✅ Before creating a PR/merge request
-- ❌ NOT after every single task (too frequent)
-
-**Two modes**:
-- `review` mode: Review strategic docs BEFORE implementation starts
-- `update` mode: Sync living docs AFTER implementation completes
-
-**Example workflow**:
-
-```bash
-# Complete increment
-/specweave:done 0031
-
-# Sync to living docs (MANDATORY!)
-/specweave:sync-docs update 0031
-
-# Result: All user stories from increment 0031 are now in:
-# .specweave/docs/internal/specs/{project}/FS-031-feature-name/
-#   ├── README.md (epic overview)
-#   ├── us-001-story-title.md (user story)
-#   ├── us-002-story-title.md
-#   └── ... (all user stories)
+TASK COMPLETED
+     │
+     ▼
+┌─────────────────────────────┐
+│ 1. Edit tasks.md            │
+│    [ ] pending → [x] done   │
+└─────────────────────────────┘
+     │
+     ▼
+┌─────────────────────────────┐
+│ 2. Edit spec.md ACs         │
+│    [ ] AC → [x] AC          │
+└─────────────────────────────┘
+     │
+     ▼
+┌─────────────────────────────┐
+│ 3. /specweave:sync-tasks    │
+│    Updates progress cache   │
+└─────────────────────────────┘
+     │
+     ▼
+┌─────────────────────────────┐
+│ 4. /specweave-github:sync   │
+│    Updates GitHub issue     │
+└─────────────────────────────┘
+     │
+     ▼ (if all ACs for US done)
+┌─────────────────────────────┐
+│ 5. /specweave:sync-docs     │
+│    Updates living docs      │
+└─────────────────────────────┘
 ```
 
-**Why this matters**:
-- ✅ Permanent archive of all user stories (never lost)
-- ✅ Bidirectional links created automatically
-- ✅ Epic folders organized hierarchically
-- ✅ Docusaurus-ready frontmatter generated
-- ✅ Complete traceability (increment → living docs)
-
-Without running this command, your increment work stays isolated in the increment folder and NEVER makes it to the permanent living documentation!
-
-**Alternative: Manual Update** (if slash commands unavailable):
+### Claude Code Hooks (Automatic)
 
-```bash
-# Example: You just completed T-001
-
-# 1. Open tasks.md
-vim .specweave/increments/0007-feature-name/tasks.md
-
-# 2. Find the task you completed
-#### T-001: Implement authentication service
-
-# 3. Change status from pending to completed
-**Status**: [ ] pending
-# ↓ Change to ↓
-**Status**: [x] completed
+| Hook | Trigger | What It Does |
+|------|---------|--------------|
+| `UserPromptSubmit` | Every prompt | WIP limits, discipline checks |
+| `PostToolUse` | File write/edit | Detects task completion, syncs |
+| `PostTaskCompletion` | Task done | Updates GitHub/Jira progress |
+| `PostIncrementDone` | Increment closed | Closes issues, syncs all docs |
 
-# 4. Update progress counters at the top
-**Completed**: 0  # ← Increment this (0 → 1)
-**Progress**: 0%  # ← Recalculate (1/24 = 4%)
+**Non-Claude tools**: NO HOOKS EXIST. See "Hook Behavior You Must Mimic" section above.
 
-# 5. Save and commit
-git add .specweave/increments/0007-feature-name/tasks.md
-git commit -m "chore: mark T-001 as complete"
-```
-
-**Why This Matters**:
-- `/progress` shows accurate completion % ✅
-- `/validate` checks pass ✅
-- `/done` can close the increment ✅
-- Team knows real status ✅
-
-**Validation Check**:
-```bash
-# Verify tasks.md is in sync
-/sync-tasks --validate
+---
 
-# If out of sync:
-/sync-tasks  # Auto-fix from GitHub or git history
-```
+## Context Loading {#context-loading}
 
-**Quick Reference Card** (print and keep handy):
+### Why Context Manifests Matter
 
 ```
-┌────────────────────────────────────────────────┐
-│  AFTER EACH TASK: Update tasks.md Status      │
-├────────────────────────────────────────────────┤
-│  1. Open: .specweave/increments/XXXX/tasks.md │
-│  2. Find: #### T-XXX                           │
-│  3. Change: [ ] pending → [x] completed        │
-│  4. Update: Completed count & Progress %       │
-│  5. Commit: git commit -m "chore: mark done"   │
-└────────────────────────────────────────────────┘
+Without manifest: Load all docs (50k tokens) → Crash risk
+With manifest:    Load relevant files (5k tokens) → 90% savings
 ```
 
----
-
-### Command Execution Pattern (Template)
+### Using context-manifest.yaml
 
-Use this pattern for ANY command execution:
-
-```bash
-# 1. User request
-# User: "sync to GitHub"
-
-# 2. Identify command
-# Keywords: "sync", "GitHub" → github-sync.md
-
-# 3. Read command file
-cat plugins/specweave-github/commands/github-sync.md
-
-# 4. Parse workflow
-# - Requires: increment ID, GitHub token
-# - Creates: GitHub issue
-# - Syncs: tasks, progress, labels
-
-# 5. Execute workflow
-# Follow steps in github-sync.md:
-#   - Load increment
-#   - Create/update GitHub issue
-#   - Sync task checklist
-#   - Add labels and milestone
-#   - Post comment with summary
-
-# 6. Confirm completion
-# "✅ Synced increment 0001 to GitHub issue #42"
+```yaml
+# .specweave/increments/0001-feature/context-manifest.yaml
+spec_sections:
+  - .specweave/docs/internal/strategy/prd.md
+  - .specweave/docs/internal/architecture/hld.md
+documentation:
+  - .specweave/docs/internal/specs/default/relevant-spec.md
+max_context_tokens: 10000
 ```
 
-### Why This Matters (Claude Code vs Other Tools)
-
-**Claude Code** (automatic):
-- Commands work via native slash syntax: `/inc "feature"`
-- No manual reading needed
-- Commands execute automatically
-
-**Other Tools** (manual):
-- ❌ No native command support
-- ✅ **Solution**: Read command .md file and execute workflow
-- Commands become "pseudo-executable" via this pattern
-- Same workflows, just manual discovery
+**Rule**: Read context-manifest.yaml FIRST. Only load files listed there.
 
-**GitHub Copilot Example**:
-
-```
-User: "create increment for payments"
+---
 
-Copilot (you):
-1. Recognize command request: "create increment" → /inc
-2. Read: cat plugins/specweave/commands/inc.md
-3. Execute: Follow PM-led workflow from inc.md
-4. Create: spec.md, plan.md, tasks.md in .specweave/increments/0002-payments/
-5. Confirm: "✅ Increment 0002-payments created"
+## Project Structure
 
-User gets SAME result as Claude Code, just via manual execution!
 ```
-
-### Command Discovery Checklist (Session Start)
-
-**MANDATORY for non-Claude tools**:
-
-```bash
-# 1. Discover core commands
-ls plugins/specweave/commands/
-# Note: 17 commands available (inc, do, done, validate, etc.)
-
-# 2. Check for plugin commands
-if [ -d "plugins/specweave-github" ]; then
-  ls plugins/specweave-github/commands/
-  # Note: 4 GitHub commands available
-fi
-
-# 3. Document available commands
-echo "Session Context:
-- Core commands: 17 available (inc, do, done, validate, ...)
-- Plugin commands: 4 GitHub commands (if plugin installed)
-- Command execution: Read .md file → Execute workflow
-"
-
-# 4. Ready to execute commands when requested
+.specweave/
+├── increments/           # Feature increments (0001-9999)
+│   └── 0001-feature/
+│       ├── spec.md       # WHAT & WHY (user stories, ACs)
+│       ├── plan.md       # HOW (architecture, APIs)
+│       ├── tasks.md      # Task checklist with test plans
+│       └── context-manifest.yaml  # Files to load
+├── docs/internal/
+│   ├── strategy/         # PRD, business requirements
+│   ├── specs/            # Living docs (extracted user stories)
+│   │   └── {project}/    # Per-project specs
+│   ├── architecture/     # HLD, ADRs, technical design
+│   └── delivery/         # CI/CD, deployment guides
+└── state/                # Runtime state (active increment, caches)
 ```
 
-### Advanced: Batch Command Execution
-
-Some workflows require multiple commands:
-
-**Example**: Complete increment lifecycle
+---
 
-```bash
-# User: "Plan, build, and close user auth feature"
+## Agents (Roles)
 
-# Step 1: Execute /inc
-cat plugins/specweave/commands/inc.md
-# → Create spec.md, plan.md, tasks.md
+{AGENTS_SECTION}
 
-# Step 2: Execute /do
-cat plugins/specweave/commands/do.md
-# → Execute all 42 tasks
+**Usage**: Adopt role perspective when working on related tasks.
 
-# Step 3: Execute /validate
-cat plugins/specweave/commands/validate.md
-# → Quality checks
+---
 
-# Step 4: Execute /done
-cat plugins/specweave/commands/done.md
-# → PM validation and closure
-```
+## Skills (Capabilities)
 
-### Troubleshooting
+{SKILLS_SECTION}
 
-**Command file not found?**
+**Usage**: Check SKILLS-INDEX.md, match task to skill, follow workflow.
 
-```bash
-# Check if command exists
-ls plugins/specweave/commands/ | grep inc
-# If not found, command doesn't exist
+---
 
-# Check plugin commands
-ls plugins/specweave-*/commands/
-```
+## Task Format
 
-**Command syntax unclear?**
+```markdown
+### T-001: Task Title
+**User Story**: US-001
+**Satisfies ACs**: AC-US1-01, AC-US1-02
+**Status**: [ ] pending / [x] completed
 
-```bash
-# Read command README
-cat plugins/specweave/commands/README.md
-# Contains overview of all commands
+**Test Plan** (BDD):
+- Given [context] → When [action] → Then [result]
 ```
 
-**Command fails during execution?**
-
-- Re-read command file for missed steps
-- Check required files exist (spec.md, plan.md, etc.)
-- Verify parameters are correct
-- Check error messages for hints
-
-### Summary: Making Commands Work Without Claude Code
-
-**The Key Insight**: Commands are just markdown files with workflows!
-
-1. **Discover**: `ls plugins/specweave/commands/`
-2. **Read**: `cat plugins/specweave/commands/{command}.md`
-3. **Execute**: Follow the workflow in the file
-4. **Confirm**: Show completion and next steps
-
-**Result**: GitHub Copilot, Cursor, and other tools get the SAME SpecWeave command capabilities as Claude Code, just via manual execution instead of slash syntax.
-
-**This is CRITICAL** - without command execution, you're missing 90% of SpecWeave's automation!
-
 ---
 
-## Available Agents (Specialized Roles)
+## Workflows
 
-SpecWeave uses role-based development. When working on tasks, adopt the appropriate role:
+### Creating Increment
+1. `mkdir -p .specweave/increments/0001-feature`
+2. Create `spec.md` (WHAT/WHY, user stories, ACs)
+3. Create `plan.md` (HOW, architecture, APIs)
+4. Create `tasks.md` (task checklist with tests)
+5. Create `context-manifest.yaml` (selective loading)
 
-{AGENTS_SECTION}
-
-### How to Use Agents
+### Completing Tasks
+1. Implement the task
+2. Update `tasks.md`: `[ ] pending` → `[x] completed`
+3. Update `spec.md`: Check off satisfied ACs
+4. Sync to external trackers if enabled
 
-**In Claude Code** (automatic):
-- Agents activate automatically when needed
-- Separate context windows for each role
-
-**In other tools** (manual):
-- Read the agent file: `.claude/agents/{agent-name}/AGENT.md`
-- Adopt that role's perspective and responsibilities
-- Example: "Adopting PM role to create spec.md..."
+### Closing Increment
+1. Run `/specweave:done 0001`
+2. PM validates 3 gates (tasks, tests, docs)
+3. Living docs synced automatically
+4. GitHub issue closed (if enabled)
 
 ---
 
-## 🎯 CRITICAL: Skills Are Your Expert Manuals (Read First!)
-
-**MANDATORY**: Before starting ANY implementation task, check for relevant skills.
+## Plugin Commands
 
-### What Are Skills?
+| Command | Plugin |
+|---------|--------|
+| `/specweave-github:sync` | GitHub sync |
+| `/specweave-jira:sync` | Jira sync |
+| `/specweave-ado:sync` | Azure DevOps |
 
-Skills are **specialized expert manuals** that contain:
-- Proven workflows for specific tasks
-- SpecWeave conventions and best practices
-- Required files to read and tools to use
-- Step-by-step instructions
-- Examples and test cases
-
-**There are 34+ skills available** organized into categories:
-- **Framework Core**: increment-planner, context-loader, context-optimizer
-- **External Integrations**: jira-sync, ado-sync, github-sync
-- **Architecture & Design**: diagrams-architect, design-system-architect
-- **Development**: frontend, nodejs-backend, python-backend, nextjs, dotnet-backend
-- **Quality & Testing**: increment-quality-judge, e2e-playwright
-- **Infrastructure**: hetzner-provisioner, cost-optimizer
-- **Documentation**: docusaurus, figma-to-code, figma-designer
-- **Orchestration**: role-orchestrator, skill-router, spec-driven-brainstorming
+---
 
-### Progressive Disclosure Pattern (How to Use Skills)
+## Troubleshooting {#troubleshooting}
 
-**STEP 1: Discovery (Always Start Here)**
+### Commands Not Working
 
-Before starting ANY task, read the skills index:
+**Non-Claude tools**: Commands are markdown workflows, not slash syntax.
 
 ```bash
-cat .claude/skills/SKILLS-INDEX.md
+# Find and read the command file
+ls plugins/specweave/commands/
+cat plugins/specweave/commands/specweave-increment.md
+# Follow the workflow steps manually
 ```
 
-This single file contains ALL available skills with their activation keywords. **This is your first stop for every task.**
-
-**STEP 2: Matching**
-
-Look for skills whose "Activates for" keywords match your current task:
-
-| Your Task | Relevant Skill | Keywords |
-|-----------|---------------|----------|
-| "Plan a new feature for user auth" | `increment-planner` | "feature planning", "create increment" |
-| "Sync this to JIRA" | `jira-sync` | "JIRA sync", "create JIRA issue" |
-| "Create architecture diagram" | `diagrams-architect` | "architecture diagram", "C4 diagram" |
-| "Implement React component" | `frontend` | "React", "components", "UI" |
-| "Deploy to cloud" | `hetzner-provisioner` or `cost-optimizer` | "deploy", "hosting", "infrastructure" |
-| "Quality check" | `increment-quality-judge` | "validate quality", "quality check" |
-| "E2E test" | `e2e-playwright` | "E2E test", "browser automation" |
-| "Generate docs site" | `docusaurus` | "documentation site", "docs" |
+### Sync Issues
 
-**STEP 3: Load Full Skill**
-
-Once you've identified 1-3 relevant skills, load their full documentation:
+**Symptoms**: GitHub/Jira not updating, living docs stale
 
+**Solution** (run after EVERY task in non-Claude tools):
 ```bash
-cat .claude/skills/{skill-name}/SKILL.md
+/specweave:sync-tasks                  # Update tasks.md
+/specweave:sync-docs update            # Sync living docs
+/specweave-github:sync <increment-id>  # Sync to GitHub
 ```
 
-**STEP 4: Execute Workflow**
-
-Follow the skill's instructions precisely:
-- Read required files listed in skill
-- Use recommended tools
-- Follow step-by-step workflow
-- Apply SpecWeave best practices
-
-### Why This Matters (Token Savings + Quality)
-
-**Scenario**: User asks to plan a new feature
+### Root Folder Polluted
 
-**Without skills** (bad):
-```
-❌ Read entire .specweave/docs/ folder (50k tokens)
-❌ Guess at SpecWeave conventions
-❌ Create inconsistent increment structure
-❌ Miss context-manifest.yaml (no token savings)
-❌ Reinvent workflow from scratch
-Result: High token cost, inconsistent output
-```
+**Symptoms**: `git status` shows .md files in project root
 
-**With skills** (good):
-```
-✅ Read SKILLS-INDEX.md (2k tokens)
-✅ Match "plan feature" → increment-planner skill
-✅ Load increment-planner SKILL.md (3k tokens)
-✅ Follow proven workflow with templates
-✅ Create proper context-manifest.yaml (70% token savings)
-Result: 5k tokens vs 50k = 90% savings + higher quality
+**Fix**:
+```bash
+CURRENT=$(ls -t .specweave/increments/ | head -1)
+mv *.md .specweave/increments/$CURRENT/reports/
 ```
 
-### Skills vs Agents (What's the Difference?)
+### Tasks Out of Sync
 
-**Skills = Capabilities (WHAT you can do)**
-- increment-planner: Creates feature plans
-- jira-sync: Syncs with external tools
-- diagrams-architect: Creates diagrams
-- **Use skills for workflows and procedures**
+**Symptoms**: Progress shows wrong completion %
 
-**Agents = Roles (WHO you become)**
-- PM: Product manager perspective
-- Architect: Technical design perspective
-- DevOps: Infrastructure perspective
-- **Use agents when you need to adopt a specific role/perspective**
-
-### For Non-Claude Code Users
-
-**GitHub Copilot, Cursor, Windsurf, etc.:**
-
-Since these tools don't have native skill support, you MUST:
-
-1. **At session start**: Always read `SKILLS-INDEX.md` first
-2. **Before each task**: Check if relevant skills exist
-3. **During execution**: Follow skill workflows precisely
-4. **When stuck**: Re-read the relevant SKILL.md
-
-**Treat this as mandatory**, not optional. Skills are the difference between:
-- Inconsistent ad-hoc work ❌
-- Professional SpecWeave-compliant output ✅
-
----
-
-## Available Skills (Specialized Capabilities)
-
-SpecWeave has specialized capabilities for different tasks:
+**Fix**: Update tasks.md manually:
+```markdown
+**Status**: [ ] pending  →  **Status**: [x] completed
+```
 
-{SKILLS_SECTION}
+Or run: `/specweave:sync-tasks`
 
-### How to Use Skills
+### Context Explosion / Crashes
 
-**In Claude Code** (automatic):
-- Skills activate based on keywords in your request
-- No manual invocation needed
-- Claude reads SKILLS-INDEX.md at startup
-- Full SKILL.md loaded when relevant
+**Symptoms**: Tool crashes 10-50s after start
 
-**In other tools** (manual):
-- Read `.claude/skills/SKILLS-INDEX.md` first (mandatory)
-- Match task to activation keywords
-- Load full skill: `.claude/skills/{skill-name}/SKILL.md`
-- Follow the workflow precisely
-- Example: "Following increment-planner skill workflow..."
+**Causes**: Loading too many files, no context manifest
 
----
+**Fix**:
+1. Create `context-manifest.yaml` in increment folder
+2. List only files needed for current task
+3. Never load entire `.specweave/docs/` folder
 
-## Common Workflows
+### Skills/Agents Not Activating
 
-### Creating a Feature Increment
+**Non-Claude tools**: Skills don't auto-activate.
 
-**Step 1: Create Increment Folder**
+**Manual activation**:
 ```bash
-mkdir -p .specweave/increments/0001-feature-name
-cd .specweave/increments/0001-feature-name
-```
+# 1. Check skills index
+cat .claude/skills/SKILLS-INDEX.md
 
-**Step 2: Create spec.md (Adopt PM Role)**
-- Focus on WHAT and WHY (not HOW)
-- Technology-agnostic requirements
-- User stories with acceptance criteria
+# 2. Match your task to a skill
+# 3. Load the skill manually
+cat .claude/skills/increment-planner/SKILL.md
 
-Template:
-```markdown
----
-increment: 0001-feature-name
-title: "Feature Title"
-priority: P1
-status: planned
----
-
-# Increment 0001: Feature Name
-
-## Overview
-[Problem statement and solution]
-
-## User Stories
-
-### US-001: User Story Title
-**As a** [role]
-**I want to** [action]
-**So that** [benefit]
-
-**Acceptance Criteria**:
-- [ ] TC-0001: [testable condition]
-- [ ] TC-0002: [testable condition]
-```
-
-**Step 3: Create plan.md (Adopt Architect Role)**
-- Focus on HOW (technical implementation)
-- Technology-specific details
-- Component design, data models, APIs
-
-Template:
-```markdown
-# Technical Plan: Feature Name
-
-## Architecture
-[Component design]
-
-## Data Model
-[Database schema]
-
-## API Contracts
-[Endpoints, request/response]
-
-## Implementation Strategy
-[Step-by-step approach]
-```
-
-**Step 4: Create tasks.md (with embedded tests)**
-```markdown
----
-increment: 0001-feature-name
-total_tasks: 10
-completed_tasks: 0
----
-
-# Implementation Tasks
-
-## T-001: Task description
-
-**AC**: AC-US1-01, AC-US1-02
-
-**Test Plan** (BDD):
-- **Given** [context] → **When** [action] → **Then** [expected result]
-
-**Test Cases**:
-- Unit (`*.test.ts`): testCase1, testCase2 → 90% coverage
-- Integration (`*.spec.ts`): integrationTest → 85% coverage
-
-**Implementation**: [Technical details]
-```
-
-**Step 5: Create context-manifest.yaml (CRITICAL)**
-```yaml
-spec_sections:
-  - .specweave/docs/internal/strategy/relevant-spec.md
-documentation:
-  - .specweave/docs/internal/architecture/relevant-design.md
-max_context_tokens: 10000
-```
-
-### Context Loading (70%+ Token Savings)
-
-**CRITICAL RULE**: Always read `context-manifest.yaml` first!
-
-**Why?**
-- Full specs: 500+ pages (50k tokens) ❌
-- Manifest files: 50 pages (5k tokens) ✅
-- **Savings: 90% = 45k tokens saved!**
-
-**How:**
-1. Navigate to increment folder
-2. Read `context-manifest.yaml`
-3. Load ONLY files listed in manifest
-4. Do NOT load entire `.specweave/docs/` folder
-
-### Working with Slash Commands (Claude Code)
-
-If using Claude Code, these slash commands are available:
-
-**Core Commands** (always available):
-| Command | Purpose | Example |
-|---------|---------|---------|
-| `/specweave:increment` | Create new increment | `/specweave:increment "user authentication"` |
-| `/specweave:do` | Execute implementation | `/specweave:do` |
-| `/specweave:progress` | Check status | `/specweave:progress` |
-| `/specweave:done` | Close increment | `/specweave:done 0001` |
-| `/specweave:validate` | Validate quality | `/specweave:validate 0001 --quality` |
-
-### 🚨 MANDATORY: Increment Closure Workflow
-
-**For ALL tools (Claude Code + non-Claude)**:
-
-When closing an increment with `/specweave:done`, the following MUST happen to maintain source of truth integrity:
-
-```
-1. PM validates 3 gates (tasks, tests, docs)
-2. Increment marked as complete
-3. Living docs spec MUST be synced    ← MANDATORY!
-4. GitHub Project MUST be synced      ← MANDATORY!
-5. GitHub Issue closed (optional)
-```
-
-**For Claude Code** (automated via hooks):
-- ✅ Steps 3-5 happen AUTOMATICALLY via `post-increment-done` hook
-- No manual action needed!
-
-**For non-Claude tools** (manual workflow):
-
-After `/specweave:done 0001` completes, **YOU MUST manually run**:
-
-```bash
-# Step 1: Close increment (PM agent validates)
-/specweave:done 0001
-
-# Step 2: Sync living docs spec to GitHub Project (MANDATORY!)
-# Find the spec file first:
-SPEC_FILE=$(find .specweave/docs/internal/specs/ -name "spec-0001*.md" | head -1)
-
-# Then sync to GitHub Project:
-/specweave-github:sync-spec "$SPEC_FILE"
-
-# Step 3: Close GitHub Issue (optional)
-/specweave-github:close-issue 0001
-```
-
-**Why MANDATORY?**
-- Living docs specs (`.specweave/docs/internal/specs/`) = Permanent source of truth
-- GitHub Projects = External mirror of source of truth
-- Without sync, GitHub Projects become stale and unreliable!
-
-**Plugin Commands** (when plugin installed):
-| Command | Purpose | Plugin |
-|---------|---------|--------|
-| `/specweave:github:sync` | Sync to GitHub | specweave-github |
-| `/specweave:github:create-issue` | Create GitHub issue | specweave-github |
-| `/specweave:jira:sync` | Sync to Jira | specweave-jira |
-| `/specweave:jira:create-ticket` | Create Jira ticket | specweave-jira |
-
-**For non-Claude tools**: Read the command file when user requests the action:
-```bash
-# User: "Sync to GitHub"
-cat plugins/specweave-github/commands/github-sync.md
-# Then follow instructions in that file
-```
-
----
-
-## 📖 Documentation Preview with Docusaurus (Port 3016)
-
-**IMPORTANT**: SpecWeave supports beautiful documentation preview using Docusaurus. This is NOT just for Claude Code - it works for ALL tools!
-
-### Overview
-
-The `/specweave-docs-preview:preview` command launches an interactive Docusaurus development server to preview your living documentation at **http://localhost:3016** (NOT port 3000!).
-
-**Why Port 3016?**
-- Port 3000 is commonly used by other development servers (React, Next.js, etc.)
-- Port 3016 avoids conflicts with client projects
-- This is the default for ALL SpecWeave documentation preview
-
-### Quick Start
-
-**For Claude Code** (slash command):
-```bash
-/specweave-docs-preview:preview
-```
-
-**For Other Tools** (manual execution):
-```bash
-# 1. Read the command file
-cat plugins/specweave-docs-preview/commands/preview.md
-
-# 2. Execute the workflow manually (follow the instructions in preview.md)
-# The command will:
-# - Install Docusaurus (~30 seconds first time)
-# - Generate configuration
-# - Create sidebar from folder structure
-# - Start server on http://localhost:3016
-# - Open browser automatically
-
-# 3. Access the documentation
-# Open browser to: http://localhost:3016
-```
-
-### Common MDX Compilation Errors (MUST READ!)
-
-**Problem**: Docusaurus uses MDX (Markdown + JSX) which has stricter parsing rules than regular Markdown. Files with certain patterns may cause compilation errors like:
-
-```
-Error: MDX compilation failed for file ".../adr-001-signalr-vs-websockets.md"
-Cause: Unexpected character `1` (U+0031) before name
-```
-
-**Solutions** (in order of preference):
-
-#### Solution 1: Use Frontmatter for Problematic Files
-
-Add YAML frontmatter to files with numeric prefixes or special characters:
-
-```markdown
----
-id: adr-001-signalr-vs-websockets
-title: ADR 001: SignalR vs WebSockets
-sidebar_label: SignalR vs WebSockets
----
-
-# ADR 001: SignalR vs WebSockets
-
-[Rest of content...]
-```
-
-#### Solution 2: Exclude Problematic Files
-
-If certain files can't be fixed, exclude them from the build:
-
-**Edit `.specweave/config.json`:**
-```json
-{
-  "documentation": {
-    "preview": {
-      "enabled": true,
-      "port": 3016,
-      "excludeFolders": ["legacy", "node_modules", "problematic-folder"]
-    }
-  }
-}
-```
-
-#### Solution 3: Use MDX1 Compatibility Mode
-
-The config generator already adds MDX1 compatibility mode to handle most common issues:
-
-```javascript
-// This is already in the generated docusaurus.config.js
-markdown: {
-  mermaid: true,
-  format: 'mdx',
-  mdx1Compat: {
-    comments: true,
-    admonitions: true,
-    headingIds: true,
-  },
-}
-```
-
-#### Solution 4: Fix Special Characters in Content
-
-MDX interprets `<`, `>`, `{`, `}` as JSX. Escape them in your markdown:
-
-**Bad** (causes MDX errors):
-```markdown
-Use <Component> to render the UI
-Configure {apiKey} in the settings
-```
-
-**Good** (works):
-```markdown
-Use `<Component>` to render the UI
-Configure `{apiKey}` in the settings
-```
-
-Or use code blocks:
-```markdown
-```
-Use <Component> to render the UI
-```
-
-### Configuration Reference
-
-**Default Configuration** (`.specweave/config.json`):
-```json
-{
-  "documentation": {
-    "preview": {
-      "enabled": true,
-      "autoInstall": true,
-      "port": 3016,
-      "openBrowser": true,
-      "theme": "default",
-      "excludeFolders": ["legacy", "node_modules"]
-    }
-  }
-}
-```
-
-**Configuration Options**:
-- `enabled`: Enable/disable docs preview (default: true)
-- `autoInstall`: Auto-install Docusaurus on first run (default: true)
-- `port`: Port for dev server (default: 3016, NEVER use 3000!)
-- `openBrowser`: Auto-open browser (default: true)
-- `theme`: Theme variant ("default", "classic", "dark")
-- `excludeFolders`: Folders to exclude from build (array)
-
-### Features
-
-**What You Get**:
-- ✅ Auto-generated navigation from folder structure
-- ✅ Search functionality (instant local search)
-- ✅ Beautiful theming (light/dark mode)
-- ✅ Mermaid diagram rendering
-- ✅ Hot reload (edit markdown, see changes instantly)
-- ✅ Professional typography and layout
-- ✅ Mobile responsive design
-
-**Hot Reload**:
-- Edit any file in `.specweave/docs/internal/`
-- Save the file
-- Browser refreshes automatically
-- No need to restart server!
-
-### Troubleshooting
-
-**Port Already in Use:**
-```bash
-# Error: Port 3016 is already in use
-# Solution 1: Change port in config
-vim .specweave/config.json
-# Change "port": 3016 to "port": 3017
-
-# Solution 2: Stop the service
-lsof -i :3016  # Find PID
-kill -9 <PID>  # Kill the process
-```
-
-**Build Fails with MDX Errors:**
-```bash
-# Check which files are causing errors
-# Look for files with:
-# - Numeric prefixes (adr-001-, spec-123-)
-# - Special characters in content (<, >, {, })
-# - JSX-like syntax
-
-# Fix using Solution 1-4 above (add frontmatter, exclude files, etc.)
-```
-
-**Node.js Version:**
-```bash
-# Error: Node.js 18+ required
-# Solution: Update Node.js
-nvm install 20  # Using nvm
-# Or download from nodejs.org
-node --version  # Verify
+# 4. Follow the skill's workflow
 ```
 
-### Best Practices
-
-**1. Always Use Port 3016** (NOT 3000):
-```json
-// ✅ CORRECT
-{"documentation": {"preview": {"port": 3016}}}
-
-// ❌ WRONG
-{"documentation": {"preview": {"port": 3000}}}
-```
-
-**2. Add Frontmatter to ADRs/Specs:**
-```markdown
----
-id: unique-identifier
-title: Human-Readable Title
-sidebar_label: Short Label
----
-
-# Your content here
-```
-
-**3. Escape Special Characters:**
-```markdown
-Use backticks: `<Component>`, `{variable}`
-Or code blocks for multiline
-```
-
-**4. Test Before Committing:**
-```bash
-# Start preview locally
-/specweave-docs-preview:preview
-
-# Check for errors in console
-# Fix any MDX compilation errors
-# Then commit
-```
-
-### Integration with SpecWeave Workflow
-
-**After Creating Increment:**
-```bash
-/specweave:increment "User Authentication"
-# → Creates spec.md, plan.md, tasks.md
-
-/specweave-docs-preview:preview
-# → Preview shows new spec in sidebar
-```
-
-**After Completing Increment:**
-```bash
-/specweave:done 0008
-# → Syncs spec.md to .specweave/docs/internal/specs/
-
-# Hot reload automatically shows the new spec!
-# No need to restart preview server
-```
-
-### For Non-Claude Tools: Manual Execution
-
-**Step-by-Step Workflow:**
-
-```bash
-# 1. Load the command
-cat plugins/specweave-docs-preview/commands/preview.md
-
-# 2. Create or verify config
-vim .specweave/config.json
-# Ensure "documentation.preview.enabled" is true
-# Ensure "documentation.preview.port" is 3016
-
-# 3. Run the preview (follow instructions from preview.md)
-# The command will guide you through:
-# - Installing Docusaurus (first time only)
-# - Generating config and sidebar
-# - Starting server on port 3016
-# - Opening browser
-
-# 4. Access documentation
-# Open: http://localhost:3016
-
-# 5. Edit docs and see changes live
-# Edit any file in .specweave/docs/internal/
-# Browser refreshes automatically!
-
-# 6. Stop server when done
-# Press Ctrl+C in terminal
-```
-
-### Summary
-
-- 🌐 **Default Port**: 3016 (NOT 3000!)
-- 📁 **Source**: `.specweave/docs/internal/`
-- 🔧 **Config**: `.specweave/config.json`
-- 🔄 **Hot Reload**: Automatic
-- ⚠️ **MDX Errors**: Add frontmatter or escape special chars
-- ✅ **Works for ALL tools** (Claude Code, Cursor, Copilot, etc.)
-
----
-
-## Build & Test Commands
-
-```bash
-# Install dependencies
-npm install
-
-# Build project
-npm run build
-
-# Run tests
-npm test
-
-# Run E2E tests (if applicable)
-npm run test:e2e
-
-# Type check
-npm run type-check
-
-# Lint
-npm run lint
-```
-
----
-
-## Code Style Guidelines
-
-### Specification Files
-
-**spec.md** (Technology-Agnostic):
-- Focus on WHAT and WHY, not HOW
-- Use user stories (US-001, US-002, ...)
-- Use acceptance criteria (TC-0001, TC-0002, ...)
-- No technology-specific details
-
-**plan.md** (Technology-Specific):
-- Focus on HOW to implement
-- Include component designs, data models, APIs
-- Reference ADRs (Architecture Decision Records)
-- Technology stack details
-
-### Code Organization
-
-**ALL supporting files belong to an increment:**
-- Logs → `.specweave/increments/{id}/logs/`
-- Scripts → `.specweave/increments/{id}/scripts/`
-- Reports → `.specweave/increments/{id}/reports/`
-- NEVER create supporting files in project root
-
-**Benefits:**
-- Complete traceability (know which increment created which files)
-- Easy cleanup (delete increment folder = delete all related files)
-- Clear context (all files for a feature in one place)
-
----
-
-## Testing Strategy
-
-**Four Levels of Test Cases**:
-
-1. **Specification** (`.specweave/docs/internal/strategy/`) - AC-IDs (AC-US1-01, etc.)
-2. **Feature** (`.specweave/increments/####/tasks.md`) - Test plans embedded in tasks (BDD format)
-3. **Skill** (`src/skills/{name}/test-cases/`) - YAML test cases (if creating skills)
-4. **Code** (`tests/`) - Automated tests (Unit, Integration, E2E)
-
-**Test-Aware Planning**: Tests are embedded directly in tasks.md using BDD format (Given/When/Then), with AC-ID traceability (mapping to spec.md acceptance criteria) and realistic coverage targets (80-90%).
-
-**Requirements:**
-- E2E tests (Playwright/Cypress) when UI exists
-- >80% coverage for critical paths
-- Tests MUST tell the truth (no false positives)
-
----
-
-## 📝 Documentation Updates (CRITICAL FOR NON-CLAUDE TOOLS)
-
-**IMPORTANT**: Claude Code has automatic hooks that remind you to update documentation. **GitHub Copilot, Cursor, and other tools DO NOT have these hooks!**
-
-### You MUST Manually Update Documentation After Every Task
-
-When you complete ANY task (implementation, bug fix, refactoring), you MUST update:
-
-#### 1. Living Docs (.specweave/docs/)
-
-After implementing features, update strategic documentation:
-
-**Strategy Docs** (`.specweave/docs/internal/strategy/`):
-- Update PRDs when requirements change
-- Add new user stories if scope expanded
-- Document discovered requirements
-
-**Architecture Docs** (`.specweave/docs/internal/architecture/`):
-- Update HLD (high-level design) when architecture changes
-- Update LLD (low-level design) when components change
-- Update ADRs from "Proposed" → "Accepted" after implementation
-- Add new ADRs for significant decisions made during implementation
-
-**Delivery Docs** (`.specweave/docs/internal/delivery/`):
-- Update deployment guides after infrastructure changes
-- Update CI/CD docs after pipeline modifications
-
-**Operations Docs** (`.specweave/docs/internal/operations/`):
-- Update runbooks after operational changes
-- Update monitoring/alerting docs
-
-#### 2. Increment Documentation
-
-**Always update these files in `.specweave/increments/{increment-id}/`**:
-
-```bash
-# Update implementation status
-vim .specweave/increments/0001-feature/plan.md
-# Add: "## Implementation Notes" section with learnings
-
-# Update task checklist
-vim .specweave/increments/0001-feature/tasks.md
-# Mark completed: - [x] T001: Task description
-
-# Document completion
-vim .specweave/increments/0001-feature/reports/completion-report.md
-# Add: Summary of what was implemented, challenges, solutions
-```
-
-#### 3. Project Documentation
-
-**CLAUDE.md or AGENTS.md** (this file):
-- Update when project structure changes
-- Add new workflows or commands
-- Update "Current Work" section
-
-**README.md** (user-facing):
-- Update when features are added
-- Update installation instructions if changed
-- Update usage examples
-
-**CHANGELOG.md** (version history):
-- Add entries for all user-facing changes
-- Format: `## [version] - date` with bullet points
-
-#### 4. Code Documentation
-
-**Inline comments**:
-- Add JSDoc/TSDoc for new functions
-- Update existing comments if behavior changes
-- Explain "why" not just "what"
-
-### When to Update (Checklist)
-
-After you:
-- ✅ Complete a task → Update increment tasks.md
-- ✅ Implement a feature → Update living docs (architecture, strategy)
-- ✅ Make architecture decision → Create or update ADR
-- ✅ Change project structure → Update CLAUDE.md/AGENTS.md
-- ✅ Add user-facing feature → Update README.md
-- ✅ Fix a bug → Update CHANGELOG.md
-- ✅ Change API → Update API documentation
-- ✅ Modify deployment → Update deployment guide
-
-### Example Workflow (GitHub Copilot/Cursor Users)
-
-```markdown
-# After completing "Implement user authentication" task:
-
-1. Update living docs:
-   echo "## Implementation Notes
-   - Used JWT for stateless authentication
-   - Password hashing with bcrypt
-   - Session timeout: 24 hours
-   " >> .specweave/increments/0001-auth/plan.md
-
-2. Update architecture:
-   vim .specweave/docs/internal/architecture/hld-system.md
-   # Add authentication component diagram
-
-3. Create ADR:
-   vim .specweave/docs/internal/architecture/adr-003-jwt-authentication.md
-
-4. Update README:
-   vim README.md
-   # Add authentication usage example
-
-5. Update CHANGELOG:
-   echo "### Added
-   - User authentication with JWT
-   - Password reset flow
-   " >> CHANGELOG.md
-
-6. Mark task complete:
-   vim .specweave/increments/0001-auth/tasks.md
-   # Change [ ] to [x] for completed tasks
-```
-
-### Why This Matters
-
-**Without documentation updates**:
-- ❌ Specs diverge from implementation (specs become useless)
-- ❌ Team members don't know what changed
-- ❌ Future AI sessions have outdated context
-- ❌ SpecWeave's core principle (living documentation) breaks down
-
-**With documentation updates**:
-- ✅ Specs stay synchronized with code
-- ✅ Clear audit trail of changes
-- ✅ AI agents have accurate context
-- ✅ Team members stay informed
-- ✅ SpecWeave philosophy is maintained
-
-### Tools That Need Manual Updates
-
-These tools **DO NOT** have automatic documentation hooks:
-- GitHub Copilot (all versions)
-- Cursor
-- Windsurf
-- Gemini CLI
-- Generic AI tools (ChatGPT, Claude web, etc.)
-
-Only **Claude Code** has automatic hooks that remind you to update docs.
-
----
-
-## 🔗 External Tracker Sync (CRITICAL FOR NON-CLAUDE TOOLS)
-
-**IMPORTANT**: Claude Code has automatic hooks that sync to external trackers (GitHub Issues, Jira, Azure DevOps) after each task completion. **GitHub Copilot, Cursor, and other tools DO NOT have these hooks!**
-
-### You MUST Manually Sync to External Trackers After Every Task
-
-When you complete ANY task, you MUST sync progress to external trackers if they are enabled for the project.
-
-#### Step 1: Detect Which Trackers Are Enabled
-
-Check the current increment's `metadata.json`:
-
-```bash
-# Find current increment (latest non-backlog increment)
-CURRENT_INCREMENT=$(ls -t .specweave/increments/ 2>/dev/null | grep -v "_backlog" | head -1)
-
-# Check metadata
-cat .specweave/increments/$CURRENT_INCREMENT/metadata.json
-```
-
-**Example metadata.json**:
-```json
-{
-  "id": "0007-smart-increment-discipline",
-  "title": "Increment Management v2.0",
-  "status": "active",
-  "github": {
-    "issue": 4,
-    "url": "https://github.com/anton-abyzov/specweave/issues/4"
-  },
-  "jira": {
-    "issue": "PROJ-123",
-    "url": "https://company.atlassian.net/browse/PROJ-123"
-  },
-  "ado": {
-    "item": 456,
-    "url": "https://dev.azure.com/org/project/_workitems/edit/456"
-  }
-}
-```
-
-#### Step 2: Sync to Each Enabled Tracker
-
-**For GitHub** (if `github.issue` exists):
-
-```bash
-# Get issue number
-GITHUB_ISSUE=$(jq -r '.github.issue' .specweave/increments/$CURRENT_INCREMENT/metadata.json)
-
-# Post progress comment
-gh issue comment "$GITHUB_ISSUE" --body "Progress update: Task T-XXX completed in increment $CURRENT_INCREMENT
-
-Details:
-- Task: [Task description]
-- Status: Completed
-- Timestamp: $(date -u +"%Y-%m-%dT%H:%M:%SZ")
-
-Next: [Next task or completion status]
-"
-```
-
-**For Jira** (if `jira.issue` exists):
-
-```bash
-# Get issue key
-JIRA_ISSUE=$(jq -r '.jira.issue' .specweave/increments/$CURRENT_INCREMENT/metadata.json)
-
-# Add comment (requires jira CLI: https://github.com/ankitpokhrel/jira-cli)
-jira issue comment add "$JIRA_ISSUE" "Progress update: Task T-XXX completed
-
-Details:
-- Task: [Task description]
-- Status: Completed
-- Increment: $CURRENT_INCREMENT
-"
-
-# Update status if task is major milestone
-# jira issue move "$JIRA_ISSUE" "In Progress" / "Review" / "Done"
-```
-
-**For Azure DevOps** (if `ado.item` exists):
-
-```bash
-# Get work item ID
-ADO_ITEM=$(jq -r '.ado.item' .specweave/increments/$CURRENT_INCREMENT/metadata.json)
-
-# Add comment (requires az CLI: https://aka.ms/azure-cli)
-az boards work-item update --id "$ADO_ITEM" --discussion "Progress update: Task T-XXX completed
-
-Details:
-- Task: [Task description]
-- Status: Completed
-- Increment: $CURRENT_INCREMENT
-"
-```
-
-#### Step 3: When to Sync
-
-**After EVERY task completion**, sync to all enabled trackers:
-
-```bash
-# Example workflow after completing T-003:
-
-# 1. Mark task complete in tasks.md
-vim .specweave/increments/0007-feature/tasks.md
-# Change: - [ ] T003: Task → - [x] T003: Task ✅
-
-# 2. Update increment documentation (plan.md, etc.)
-# [See "Documentation Updates" section above]
-
-# 3. Sync to external trackers
-gh issue comment 4 --body "✅ T-003 Complete: Create test-aware-planner structure
-
-Directory structure created at plugins/specweave/agents/test-aware-planner/
-
-Next: T-004 - Write test-aware-planner AGENT.md prompt
-"
-
-# 4. Continue to next task
-```
-
-#### Step 4: Update Task Checklist in GitHub/Jira
-
-**For GitHub Issues with task checklists**:
-
-The issue body likely contains a task checklist:
-
-```markdown
-## Tasks
-- [x] T-001: Update plan.md
-- [x] T-002: Add auto-sync hook
-- [ ] T-003: Create test-aware-planner structure
-- [ ] T-004: Write AGENT.md prompt
-```
-
-**Update the checklist** after each task:
-
-```bash
-# Get current issue body
-gh issue view 4 --json body -q .body > issue-body.md
-
-# Edit the checklist (mark T-003 as done)
-vim issue-body.md
-# Change: - [ ] T-003 → - [x] T-003
-
-# Update issue
-gh issue edit 4 --body-file issue-body.md
-```
-
-**For Jira** (subtasks):
-
-If tasks are represented as subtasks:
-
-```bash
-# List subtasks
-jira issue list --parent PROJ-123
-
-# Update subtask status
-jira issue move PROJ-123-SUB1 "Done"
-```
-
-#### Step 5: Sync Increment Status Changes
-
-When increment status changes (active → paused → completed), sync that too:
-
-```bash
-# Example: Increment completed
-gh issue comment 4 --body "🎉 INCREMENT COMPLETED!
-
-All 24 tasks finished. Increment 0007-smart-increment-discipline is now complete.
-
-See completion report: .specweave/increments/0007-smart-increment-discipline/reports/COMPLETION-SUMMARY.md
-"
-
-# Close the issue
-gh issue close 4 --comment "Increment completed and merged to main branch."
-```
-
-### Why This Matters
-
-**Without external tracker sync**:
-- ❌ Stakeholders don't see progress
-- ❌ Team members work in isolation
-- ❌ No audit trail of work done
-- ❌ GitHub/Jira becomes stale and useless
-
-**With external tracker sync**:
-- ✅ Real-time visibility into progress
-- ✅ Team stays informed
-- ✅ Stakeholders can track without asking
-- ✅ Complete audit trail
-- ✅ GitHub/Jira remains the source of truth
-
-### Tools That Need Manual Sync
-
-These tools **DO NOT** have automatic external tracker sync:
-- GitHub Copilot (all versions)
-- Cursor
-- Windsurf
-- Gemini CLI
-- Generic AI tools (ChatGPT, Claude web, etc.)
-
-Only **Claude Code** has automatic hooks (via `post-task-completion.sh`) that sync to external trackers.
-
-### Summary Checklist (After Every Task)
-
-When you complete a task in non-Claude tools, **run these slash commands**:
-
-#### Quick Sync (After Each Task Completion)
-
-```bash
-# 1. Sync tasks.md with completion status
-/specweave:sync-tasks
-
-# 2. Update living docs from completed work
-/specweave:sync-docs update
-```
-
-#### External Tracker Sync (If Enabled)
-
-```bash
-# 3. Sync to external tracker (choose one based on your setup):
-
-# GitHub Issues:
-/specweave-github:sync <increment-id>
-
-# Jira:
-/specweave-jira:sync <increment-id>
-
-# Azure DevOps:
-/specweave-ado:sync <increment-id>
-```
-
-#### Example Full Workflow
-
-```bash
-# After completing a task in your current increment:
-
-# Step 1: Update tasks.md
-/specweave:sync-tasks
-
-# Step 2: Sync living docs
-/specweave:sync-docs update
-
-# Step 3: Sync to GitHub (if using GitHub tracking)
-/specweave-github:sync <increment-id>  # e.g., /specweave-github:sync 0016
-
-# Done! Continue to next task.
-```
-
-**Remember**: In Claude Code, all of this happens **automatically via hooks**. In other tools (Cursor, Copilot, ChatGPT), **YOU must run these commands manually** after each task!
-
----
-
-## Security Considerations
-
-- Never commit secrets (use `.env` files, gitignored)
-- Follow principle of least privilege
-- Review security implications in ADRs
-- Use the `security` agent role for security reviews
-
----
-
-## Finding the Right Agent or Skill
-
-When you encounter a new task:
-
-**Finding Skills:**
-1. Check this file (Available Skills section above)
-2. Browse: `ls .claude/skills/`
-3. Read: `.claude/skills/{skill-name}/SKILL.md`
-4. Follow the workflow
-
-**Finding Agents:**
-1. Check this file (Available Agents section above)
-2. Browse: `ls .claude/agents/`
-3. Read: `.claude/agents/{agent-name}/AGENT.md`
-4. Adopt the role
-
-**Pro Tips:**
-- Skills are capabilities (what you CAN do)
-- Agents are roles (who you BECOME to do it)
-- When stuck, ask: "Which SpecWeave skill or agent helps with [task]?"
-
----
-
-## Important Reminders
-
-1. ✅ **Always read context-manifest.yaml first** (70%+ token savings)
-2. ✅ **Load only files listed in manifest** (not entire docs folder)
-3. ✅ **Adopt role when acting as agent** (PM, Architect, DevOps, etc.)
-4. ✅ **Technology-agnostic in spec.md** (WHAT/WHY only)
-5. ✅ **Technology-specific in plan.md** (HOW with details)
-6. ✅ **Use checkboxes in tasks.md** for tracking
-7. ✅ **All supporting files in increment folders** (never in root)
-8. 🔴 **UPDATE DOCUMENTATION AFTER EVERY TASK** (see "Documentation Updates" section above - CRITICAL for non-Claude tools!)
-
----
-
-## 🆘 Troubleshooting {#troubleshooting}
-
-**Use Ctrl+F / Command+F with the search patterns below to jump to specific issues!**
-
-### Skills Not Working {#troubleshoot-skills}
-
-**Symptoms**: Expected skill didn't activate or can't find skill
-
-**Solutions (Non-Claude Tools)**:
-1. **Skills don't auto-activate in Cursor/Copilot** - This is normal!
-   - You must manually discover skills from Section Index above
-   - Search for relevant skill: `#skill-{name}`
-   - Read that section and follow the workflow
-
-2. **Can't find the right skill**:
-   ```bash
-   # Check Section Index above for skill list
-   # Search this file for: #skill-increment-planner, #skill-github-sync, etc.
-   ```
-
-3. **Skill workflow unclear**:
-   - Each skill section has "How It Works" and "Workflow" subsections
-   - Follow step-by-step instructions
-   - Check examples provided
-
-**Remember**: In non-Claude tools, YOU control skill discovery (search this file), not automatic activation!
-
----
-
-### Commands Not Found {#troubleshoot-commands}
-
-**Symptoms**: `/specweave:increment` or other commands don't work
-
-**Solutions (Non-Claude Tools)**:
-1. **Commands are NOT slash commands in Cursor/Copilot** - They're workflows!
-   - Search this file for: `#command-increment`, `#command-do`, etc.
-   - Read the workflow from that section
-   - Execute manually (step by step)
-
-2. **Example**: User says "create increment"
-   ```
-   You search: "#command-increment"
-   You find: ## Command: /specweave:increment {#command-increment}
-   You read: Workflow section (PM-led planning, spec creation, etc.)
-   You execute: Follow those steps manually
-   ```
-
-3. **Command workflow unclear**:
-   - Each command section has detailed workflow
-   - Check "When to use", "Parameters", "Workflow", "Example"
-   - Follow step-by-step
-
-**Remember**: In non-Claude tools, commands are manual workflows, not automatic slash commands!
-
----
-
-### Sync Issues {#troubleshoot-sync}
-
-**Symptoms**: GitHub/Jira not updating, living docs not syncing
-
-**Solutions (Non-Claude Tools)**:
-1. **No automatic hooks** - You must manually sync:
-   ```bash
-   # After EACH task completion:
-   /specweave:sync-tasks                  # Update tasks.md
-   /specweave:sync-docs update            # Sync living docs
-   /specweave:github:sync <increment-id>  # Sync to GitHub
-   ```
-
-2. **Living docs sync not working**:
-   - Search for: `#workflow-living-docs-sync`
-   - Follow manual workflow from that section
-   - Check: `.specweave/docs/internal/specs/{project}/` for output
-
-3. **GitHub sync not working**:
-   - Search for: `#workflow-github-sync`
-   - Verify credentials: `gh auth status`
-   - Check metadata: `cat .specweave/increments/0001/metadata.json`
-   - Manual sync: Follow workflow from `#command-github-sync`
-
-4. **Jira sync not working**:
-   - Search for: `#workflow-jira-sync`
-   - Verify credentials: `jira config list`
-   - Manual sync: Follow workflow from `#command-jira-sync`
-
-**Remember**: Automatic sync ONLY works in Claude Code. In other tools, you must manually run sync commands!
-
----
-
-### Root Folder Polluted {#troubleshoot-root-pollution}
-
-**Symptoms**: `git status` shows `.md` files in project root
-
-**Solutions**:
-1. **Immediate fix** - Move files to increment folder:
-   ```bash
-   # Find current increment
-   CURRENT=$(ls -t .specweave/increments/ | grep -v "_backlog" | head -1)
-
-   # Move files
-   mv SESSION-NOTES.md .specweave/increments/$CURRENT/reports/
-   mv analysis.md .specweave/increments/$CURRENT/reports/
-   mv migration.py .specweave/increments/$CURRENT/scripts/
-   mv execution.log .specweave/increments/$CURRENT/logs/
-   ```
-
-2. **Update .gitignore** if needed:
-   ```bash
-   echo "/*.md" >> .gitignore  # Ignore all root .md files except CLAUDE.md
-   echo "!CLAUDE.md" >> .gitignore
-   echo "!README.md" >> .gitignore
-   ```
-
-3. **Commit cleaned structure**:
-   ```bash
-   git add .
-   git commit -m "fix: move reports/scripts/logs to increment folders"
-   ```
-
-**Prevention**: Always create files in increment folders (reports/, scripts/, logs/), NEVER in root!
-
----
-
-### Duplicate Increments {#troubleshoot-duplicates}
-
-**Symptoms**: Multiple increments with same number (0001, 0001, etc.)
-
-**Solutions**:
-1. **Check for duplicates**:
-   ```bash
-   ls -1 .specweave/increments/ | grep -E "^[0-9]{4}-" | sort
-   # Look for duplicate numbers
-   ```
-
-2. **Find next available number**:
-   ```bash
-   ls -1 .specweave/increments/ | grep -E "^[0-9]{4}-" | sort | tail -1
-   # Increment the number by 1
-   ```
-
-3. **Fix duplicates** (if they exist):
-   - Search for: `#command-fix-duplicates`
-   - Follow manual workflow to resolve
-
-**Prevention**: Always check existing increments before creating new ones!
-
----
-
-### Tasks.md Out of Sync {#troubleshoot-tasks-out-of-sync}
-
-**Symptoms**: Progress shows 0/24 but many tasks actually done
-
-**Solutions**:
-1. **Auto-sync from reality**:
-   - Search for: `#command-sync-tasks`
-   - Follow workflow to sync tasks.md with actual status
-
-2. **Manual update**:
-   ```bash
-   # Open tasks.md
-   vim .specweave/increments/0001/tasks.md
-
-   # Change completed tasks:
-   **Status**: [ ] pending  → **Status**: [x] completed
-
-   # Update progress counters:
-   **Completed**: 0  → **Completed**: 15
-   **Progress**: 0%  → **Progress**: 62%  (15/24 = 62%)
-   ```
-
-3. **Verify sync**:
-   - Search for: `#command-progress`
-   - Run progress check to verify correct counts
-
-**Prevention**: In non-Claude tools, manually update tasks.md after EACH task completion!
-
----
-
-### Can't Find Current Increment {#troubleshoot-find-increment}
-
-**Symptoms**: Don't know which increment is active
-
-**Solutions**:
-1. **Check active increment**:
-   ```bash
-   cat .specweave/state/active-increment.json
-   ```
-
-2. **List all increments with status**:
-   - Search for: `#command-status`
-   - Follow workflow to see all increments and their states
-
-3. **Check progress**:
-   - Search for: `#command-progress`
-   - Shows active increment and completion %
-
----
-
-### Commands Taking Too Long {#troubleshoot-slow-commands}
-
-**Symptoms**: Command workflows seem to take forever
-
-**Solutions**:
-1. **Loading entire AGENTS.md** - This is normal!
-   - File is 2000+ lines (comprehensive)
-   - Use search (Ctrl+F) to jump to relevant sections
-   - Don't read everything - only what you need
-
-2. **Too much context loaded**:
-   - Check for `context-manifest.yaml` in increment folder
-   - Load ONLY files listed there
-   - Don't load entire `.specweave/docs/` folder
-
-3. **Workflow unclear**:
-   - Each section has step-by-step workflow
-   - Follow instructions precisely
-   - Check examples
-
-**Optimization**: Use Section Index above to quickly find and jump to relevant sections!
-
----
-
-### Living Docs Not Updating {#troubleshoot-living-docs}
-
-**Symptoms**: `.specweave/docs/internal/specs/` not showing new user stories
-
-**Solutions**:
-1. **Manual sync required** (non-Claude tools):
-   - Search for: `#command-sync-docs`
-   - Follow workflow to sync increment → living docs
-
-2. **Check spec distribution**:
-   ```bash
-   # After sync, verify files exist:
-   ls -la .specweave/docs/internal/specs/{project}/
-   # Should show FS-XXX folders with us-XXX.md files
-   ```
-
-3. **Verify project detection**:
-   ```bash
-   # Check increment name for project hint:
-   ls .specweave/increments/
-   # Example: 0001-backend-auth → project: backend
-   #          0002-frontend-ui → project: frontend
-   ```
-
-**Prevention**: Run `/specweave:sync-docs update` after completing increments!
-
----
-
-### External Tracker Credentials {#troubleshoot-credentials}
-
-**Symptoms**: GitHub/Jira sync fails with auth errors
-
-**Solutions**:
-
-**For GitHub**:
-```bash
-# Check auth status
-gh auth status
-
-# Re-authenticate if needed
-gh auth login
-
-# Test access
-gh repo view
-```
-
-**For Jira**:
-```bash
-# Check config
-jira config list
-
-# Set up credentials
-jira init
-
-# Test access
-jira issue list --project PROJ
-```
-
-**For Azure DevOps**:
-```bash
-# Check auth
-az account show
-
-# Login if needed
-az login
-
-# Set default org/project
-az devops configure --defaults organization=https://dev.azure.com/YOUR_ORG project=YOUR_PROJECT
-```
-
----
-
-### Context Manifest Not Working {#troubleshoot-context-manifest}
-
-**Symptoms**: Loading too many files, high token usage
-
-**Solutions**:
-1. **Check for context-manifest.yaml**:
-   ```bash
-   ls .specweave/increments/0001/context-manifest.yaml
-   ```
-
-2. **If missing, create one**:
-   ```yaml
-   # .specweave/increments/0001/context-manifest.yaml
-   spec_sections:
-     - .specweave/docs/internal/strategy/relevant-spec.md
-   documentation:
-     - .specweave/docs/internal/architecture/relevant-design.md
-   max_context_tokens: 10000
-   ```
-
-3. **Load ONLY files listed**:
-   - Read context-manifest.yaml first
-   - Load files from `spec_sections` and `documentation`
-   - Don't load entire `.specweave/docs/` folder
-
-**Token Savings**: 70%+ reduction when using context manifests!
-
----
-
-### Version Conflicts {#troubleshoot-version-conflicts}
-
-**Symptoms**: SpecWeave commands fail with unexpected errors, missing files, or format incompatibilities
-
-**Solutions**:
-1. **Check SpecWeave version**:
-   ```bash
-   specweave --version
-   # Compare with project requirements
-   ```
-
-2. **Update SpecWeave CLI**:
-   ```bash
-   npm install -g specweave@latest
-   # Or for local project:
-   npm install specweave@latest
-   ```
-
-3. **Check project `.specweave/config.json`**:
-   ```bash
-   cat .specweave/config.json | grep version
-   # Verify compatible with CLI version
-   ```
-
-4. **Migrate if needed**:
-   - Check CHANGELOG.md for breaking changes
-   - Follow migration guide for your version
-   - Update templates and plugins
-
-**Prevention**: Pin SpecWeave version in package.json and update intentionally
-
----
-
-### Multi-Tool Confusion {#troubleshoot-multi-tool}
-
-**Symptoms**: Instructions mention Claude Code but I'm using Cursor/Copilot
-
-**Solutions**:
-1. **Look for multi-tool callouts**:
-   ```markdown
-   **For Claude Code**: ✅ Automatic via hooks
-   **For Other Tools**: ⚠️ manual sync required
-   ```
-
-2. **If instruction says "automatic"**:
-   - In Claude Code: It's automatic
-   - In other tools: Find manual workflow section
-
-3. **General pattern**:
-   - Claude Code: Commands via slash syntax, hooks automatic
-   - Other tools: Commands via manual workflows, sync manual
-
-**This file (AGENTS.md) is optimized for non-Claude tools!** Follow the manual workflows.
-
----
-
-### More Help {#more-help}
-
-**Documentation**:
-- Official docs: https://spec-weave.com/docs
-- Troubleshooting guide: https://spec-weave.com/docs/troubleshooting
-- Multi-tool guide: https://spec-weave.com/docs/multi-tool-support
-
-**Community**:
-- GitHub Issues: https://github.com/anton-abyzov/specweave/issues
-- Discussions: https://github.com/anton-abyzov/specweave/discussions
-- Discord: https://discord.gg/specweave (if available)
-
-**Quick Reference**:
-- Section Index: See top of this file
-- Search patterns: `#command-*`, `#skill-*`, `#agent-*`, `#workflow-*`
-- Quick reference cards: See `#quick-reference-cards` above
-
-**When reporting issues**:
-1. Tool used (Cursor, Copilot, ChatGPT, etc.)
-2. SpecWeave version: `specweave --version`
-3. Command/workflow attempted
-4. Error message or unexpected behavior
-5. Relevant files (metadata.json, config.json)
-
 ---
 
 ## Documentation
 
-- **CLAUDE.md**: Quick reference for Claude Code users
-- **SPECWEAVE.md**: Complete framework documentation (if exists)
-- **spec-weave.com**: Official website
-- **.specweave/docs/**: Project-specific documentation
+| Resource | Purpose |
+|----------|---------|
+| CLAUDE.md | Quick reference (Claude Code) |
+| AGENTS.md | This file (non-Claude tools) |
+| spec-weave.com | Official documentation |
+| .specweave/docs/ | Project-specific docs |
 
 ---
 
-**Generated by SpecWeave** - Specification-first AI development framework
-**Compatible with**: Claude Code, Cursor, Gemini CLI, Codex, GitHub Copilot, and more
+**Generated by SpecWeave** - Specification-first AI development
+**Compatible with**: Claude Code, Cursor, Copilot, Gemini CLI, ChatGPT, and more
 **Last Updated**: {TIMESTAMP}