specweave 1.0.326 → 1.0.327

package/src/templates/AGENTS.md.template

@@ -1,269 +1,74 @@
 # {PROJECT_NAME}
 
 **Framework**: SpecWeave - Specification-First Development
-**Standard**: [agents.md](https://agents.md/) for universal AI compatibility
-
----
-
-> ⛔ **NON-CLAUDE TOOLS (Cursor, Copilot, etc.): READ THIS FIRST!**
->
-> Before creating ANY increment, you MUST run: `specweave context projects`
->
-> Then add `**Project**: <value>` to EVERY User Story in spec.md.
-> For 2-level structures, also add `**Board**: <value>`.
->
-> **Missing this = increment creation will FAIL!**
-> See [#user-story-format](#user-story-format) for details.
-
----
-
-<!-- SECTION:index -->
-## Section Index (Use Ctrl+F to Navigate)
-
-| Section | Search For | Purpose |
-|---------|------------|---------|
-| Rules | `#essential-rules` | Critical rules, file organization |
-| **Orchestration** | `#workflow-orchestration` | **Plan Mode, Subagents, Verification** |
-| **Principles** | `#core-principles` | **Quality: Simplicity, No Laziness** |
-| Commands | `#commands` | All SpecWeave commands |
-| **Hooks** | `#non-claude-tools` | **CRITICAL: Hook behavior to mimic** |
-| **User Story** | `#user-story-format` | **CRITICAL: Project/Board fields** |
-| Sync | `#sync-workflow` | When/how to sync |
-| Context | `#context-loading` | Efficient context loading |
-| Troubleshoot | `#troubleshooting` | Common issues |
-<!-- /SECTION -->
-
----
-
-<!-- SECTION:quickstart required -->
-## Quick Start
-
-1. **Get Project Context FIRST**: `specweave context projects` (save the output!)
-2. **Create Your First Increment**: `/sw:increment "your-feature"`
-3. **Customize**: Edit spec.md - **EVERY User Story needs `**Project**:` field!**
-4. **Execute**: `/sw:do` to start implementation
-<!-- /SECTION -->
 
 ---
 
 <!-- SECTION:rules required -->
-## Essential Rules {#essential-rules}
+## Essential Rules
 
 ```
 1. NEVER pollute project root with .md files
 2. Increment IDs unique (0001-9999)
-3. ⛔ ONLY 4 files in increment root: metadata.json, spec.md, plan.md, tasks.md
-4. ⛔ ALL reports/scripts/logs → increment subfolders (NEVER at root!)
+3. ONLY 4 files in increment root: metadata.json, spec.md, plan.md, tasks.md
+4. ALL reports/scripts/logs → increment subfolders (NEVER at root!)
 5. metadata.json MUST exist BEFORE spec.md can be created
 6. tasks.md + spec.md = SOURCE OF TRUTH (update after every task!)
-7. ⛔ EVERY User Story MUST have **Project**: field
-8. ⛔ For 2-level structures: EVERY US also needs **Board**: field
+7. EVERY User Story MUST have **Project**: field
+8. For 2-level structures: EVERY US also needs **Board**: field
 ```
 
-### ⛔ INCREMENT FOLDER CLEANLINESS (CRITICAL!)
+### Increment Folder Structure
 
-**Increment folders MUST stay organized. NEVER create random files at increment root!**
-
-| File Type | Correct Location |
-|-----------|-----------------|
-| Reports, summaries, analysis (*.md) | `reports/` |
-| Validation/QA/completion reports | `reports/` |
-| Auto-session summaries | `reports/` |
-| Logs, execution output | `logs/{YYYY-MM-DD}/` |
-| Helper scripts | `scripts/` |
-| Domain docs | `docs/domain/` |
-
-**File Organization**:
 ```
-# ✅ CORRECT - clean increment structure
 .specweave/increments/0001-feature/
 ├── metadata.json                  # REQUIRED - create FIRST
 ├── spec.md                        # WHAT & WHY
 ├── plan.md                        # HOW (optional)
 ├── tasks.md                       # Task checklist
 ├── reports/                       # ALL other .md files go here!
-│   ├── validation-report.md
-│   ├── completion-report.md
-│   └── auto-session-summary.md
 ├── scripts/                       # Helper scripts
 └── logs/                          # Execution logs
     └── 2026-01-04/
-
-# ❌ WRONG - polluted increment folder!
-.specweave/increments/0001-feature/
-├── metadata.json
-├── spec.md
-├── tasks.md
-├── completion-report.md          # WRONG! Move to reports/
-├── auto-session-summary.md       # WRONG! Move to reports/
-└── some-analysis.md              # WRONG! Move to reports/
 ```
 <!-- /SECTION -->
 
 ---
 
 <!-- SECTION:orchestration required -->
-## Workflow Orchestration {#workflow-orchestration}
-
-**Claude Code has built-in orchestration features. Non-Claude tools must implement these manually.**
+## Workflow Orchestration
 
-### 1. Plan Mode Default (Use SpecWeave Increments!)
+### 1. Plan Before Code
 
-**Claude Code**: Has `EnterPlanMode` tool → triggers `/sw:increment` workflow automatically.
-
-**Non-Claude Tools - Use SpecWeave Increment Structure:**
-```
 BEFORE implementing ANY non-trivial task (3+ steps):
+1. Create increment: spec.md (WHAT/WHY) + plan.md (HOW) + tasks.md (checklist)
+2. Get user approval before implementing
+3. If something goes sideways → STOP and re-plan
 
-1. STOP - Don't start coding immediately
-2. Create increment folder: `.specweave/increments/XXXX-feature/`
-3. Create the 3 required files:
-   - spec.md   → WHAT & WHY (user stories, acceptance criteria)
-   - plan.md   → HOW (architecture, approach, risks)
-   - tasks.md  → Task checklist with test plans
-4. GET USER APPROVAL before implementing
-
-If something goes sideways during implementation:
-→ STOP and re-plan (don't keep pushing)
-→ Update spec.md/plan.md with revised approach
-→ Get approval again if scope changed
-```
-
-**SpecWeave Planning Files:**
-
-**spec.md** (WHAT & WHY):
-```markdown
----
-increment: 0001-feature-name
-title: "Feature Title"
----
-
-### US-001: User Story Title
-**Project**: my-app              # ← MANDATORY! Get from: specweave context projects
-
-**As a** [user type]
-**I want** [goal]
-**So that** [benefit]
-
-**Acceptance Criteria**:
-- [ ] **AC-US1-01**: [Criterion 1]
-- [ ] **AC-US1-02**: [Criterion 2]
-```
-
-**plan.md** (HOW):
-```markdown
-# Plan: Feature Name
-
-## Approach
-[High-level architecture/approach]
-
-## Risks & Decisions
-- [ ] Decision: [question needing user input]
-- Risk: [potential issue and mitigation]
-```
-
-**tasks.md** (Checklist):
-```markdown
-### T-001: Task Title
-**User Story**: US-001
-**Satisfies ACs**: AC-US1-01
-**Status**: [ ] pending
-
-**Test Plan** (BDD):
-- Given [context] → When [action] → Then [result]
-```
-
-### 2. Subagent Strategy (Parallel Execution)
-
-**Claude Code**: Can spawn subagents with `Task` tool for parallel work.
-
-**Non-Claude Tools - Manual Parallelization:**
-```
-For large exploration/analysis tasks:
-
-Option A: Sequential Breakdown
-1. Split work into independent chunks
-2. Process one chunk at a time
-3. Aggregate results
-
-Option B: Parallel Prompts (Cursor/Copilot)
-1. Open multiple chat sessions
-2. Give each session one focused task
-3. Combine outputs manually
-
-Best practices:
-- One task per "subagent" (focused execution)
-- Keep analysis/exploration separate from implementation
-- Use checklists to track parallel workstreams
-```
-
-**When to use parallel approach:**
-- Codebase exploration (search multiple areas)
-- Multi-file analysis (review patterns across modules)
-- Batch validation (check multiple files for issues)
-- Large-scale refactoring analysis
-
-### 3. Verification Before Done
-
-**Claude Code**: PostToolUse hooks validate completion automatically.
-
-**Non-Claude Tools - Manual Verification Checklist:**
-```
-⛔ NEVER mark a task complete without proving it works!
-
-Before marking ANY task as [x] completed:
-
-□ Code compiles/builds successfully
-□ Tests pass (run: npm test, pytest, etc.)
-□ Manual verification performed (if applicable)
-□ Acceptance criteria actually satisfied (re-read AC)
-□ No console errors in browser (for frontend)
-□ API returns expected responses (for backend)
+See **Task Format** and **User Story Format** sections for templates.
 
-Ask yourself: "Would a staff engineer approve this?"
+### 2. Verify Before Done
 
-If answer is NO → task is NOT complete
-```
-
-**Verification Commands by Stack:**
-```bash
-# JavaScript/TypeScript
-npm run build && npm test
-
-# Python
-pytest && mypy .
+Never mark a task complete without proving it works:
+- Code compiles/builds successfully
+- Tests pass
+- Acceptance criteria actually satisfied
+- Ask: "Would a staff engineer approve this?"
 
-# .NET
-dotnet build && dotnet test
+### 3. Dependencies First
 
-# General
-git diff  # Review what actually changed
-```
-
-### 4. Think-Before-Act (Dependencies)
-
-**Satisfy dependencies BEFORE dependent operations.**
+Satisfy dependencies BEFORE dependent operations.
 
 ```
-❌ Wrong: node script.js → Error → npm run build
-✅ Correct: npm run build → node script.js → Success
-
-❌ Wrong: Import module → Error → Install package
-✅ Correct: npm install package → Import module → Success
+Bad:  node script.js → Error → npm run build
+Good: npm run build → node script.js → Success
 ```
-
-**Dependency Detection Questions:**
-1. Does this require a build step first?
-2. Are all imports/packages installed?
-3. Does this depend on another file being created?
-4. Is there a database migration needed?
-5. Are environment variables configured?
 <!-- /SECTION -->
 
 ---
 
 <!-- SECTION:principles required -->
-## Core Principles (Quality) {#core-principles}
+## Core Principles (Quality)
 
 ### Simplicity First
 - Write the simplest code that solves the problem
@@ -305,9 +110,7 @@ git diff  # Review what actually changed
 ---
 
 <!-- SECTION:commands required -->
-## Commands Reference {#commands}
-
-### Core Commands
+## Commands Reference
 
 | Command | Purpose |
 |---------|---------|
@@ -318,11 +121,6 @@ git diff  # Review what actually changed
 | `/sw:validate 0001` | Quality check before closing |
 | `/sw:progress-sync` | Sync tasks.md with reality |
 | `/sw:sync-docs update` | Sync to living docs |
-
-### Plugin Commands (when installed)
-
-| Command | Purpose |
-|---------|---------|
 | `/sw-github:sync 0001` | Sync increment to GitHub issue |
 | `/sw-jira:sync 0001` | Sync to Jira |
 | `/sw-ado:sync 0001` | Sync to Azure DevOps |
@@ -331,356 +129,76 @@ git diff  # Review what actually changed
 ---
 
 <!-- SECTION:nonclaudetools required -->
-## Non-Claude Tools (Cursor, Copilot, etc.) {#non-claude-tools}
-
-**CRITICAL**: Claude Code has automatic hooks and orchestration. Other tools DO NOT.
+## Non-Claude Tools (Cursor, Copilot, etc.)
 
-> **See also**: [Workflow Orchestration](#workflow-orchestration) for Plan Mode, Subagent Strategy, and Verification protocols.
+Claude Code has automatic hooks and orchestration. Other tools must do these manually.
 
-### Built-in vs Manual - Complete Comparison
+### Capability Comparison
 
 | Capability | Claude Code | Non-Claude Tools |
 |------------|-------------|------------------|
 | **Plan Mode** | `EnterPlanMode` → `/sw:increment` | Manual: Create spec.md + plan.md + tasks.md |
-| **Subagents** | `Task` tool spawns parallel agents | Manual: Split work, parallel prompts |
-| **Verification** | PostToolUse hooks validate | Manual: Run tests, check AC checklist |
+| **Subagents** | `Task` tool for parallel work | Split into multiple chat sessions |
+| **Verification** | PostToolUse hooks auto-validate | Manual: Run tests, check ACs |
 | **Hooks** | Auto-run on events | YOU must mimic (see below) |
 | **Task sync** | Automatic AC updates | Manual: Edit tasks.md + spec.md |
-| **Commands** | Slash syntax works | Read command .md, follow manually |
-| **Skills** | Auto-activate on keywords | Read SKILL.md, follow workflow |
-
-### Latest Features
-
-SpecWeave v0.28+ introduces powerful automation that **works differently** in non-Claude tools:
-
-| Feature | Claude Code | Non-Claude Tools |
-|---------|-------------|------------------|
-| **Living Docs Builder** | Auto-runs after init | Use `specweave jobs --follow` to monitor |
-| **Bidirectional Sync** | Pull sync on session start | Run `specweave jobs` to check status |
-| **Background Jobs** | Automatic with hooks | Monitor with `specweave jobs` CLI |
-| **EDA Hooks** | Auto-detect task completion | Manually update tasks.md + spec.md |
-
-### Background Jobs Workflow 
-SpecWeave now runs heavy operations as **background jobs**:
-
-```bash
-# Monitor all jobs
-specweave jobs
-
-# Follow a specific job
-specweave jobs --follow <job-id>
-
-# View job logs
-specweave jobs --logs <job-id>
-
-# Pause/resume long-running jobs
-specweave jobs --kill <job-id>    # Pauses gracefully
-specweave jobs --resume <job-id>  # Resumes from checkpoint
-```
-
-**Job Types**:
-- `clone-repos` - Clone multiple repositories (ADO/GitHub)
-- `import-issues` - Import work items from external tools
-- `living-docs-builder` - Generate documentation from codebase
-- `sync-external` - Bidirectional sync with external tools
-- `brownfield-analysis` - Analyze existing/legacy codebases
-- `codebase-rescan` - Rescan codebase after increment closure
-
-**Job Dependencies**: The `living-docs-builder` waits for `clone-repos` and `import-issues` to complete before starting. This is automatic - just monitor with `specweave jobs`.
-
-### Code-First Approach (MANDATORY for Non-Claude Tools)
-
-> **Engineering insight**: [Anthropic research](https://www.anthropic.com/engineering/code-execution-with-mcp) shows code execution achieves **98% token reduction** vs MCP tool calls.
->
-> **For non-Claude tools, this is even MORE important** - MCP support varies, but `npx` works everywhere!
-
-**Rule**: Always prefer direct code execution over MCP:
-
-```bash
-# ❌ DON'T: Use Playwright MCP for testing
-# ✅ DO: Write Playwright tests and run with npx
-npx playwright test
-
-# ❌ DON'T: Use Kafka MCP for messaging
-# ✅ DO: Write kafkajs code
-import { Kafka } from 'kafkajs';
-const kafka = new Kafka({ brokers: ['localhost:9092'] });
-
-# ❌ DON'T: Chain multiple MCP tool calls
-# ✅ DO: Write a script that does all the work
-npx ts-node scripts/process-data.ts
-```
-
-**Why code is better**:
-| Aspect | MCP | Code (`npx`) |
-|--------|-----|--------------|
-| Token cost | High (tool defs + data duplication) | Low (only results) |
-| Reusability | Ephemeral | Committed to git |
-| CI/CD | Usually can't run | Native execution |
-| Debugging | Limited | Full stack traces |
-| Works with | Tools with MCP support | ANY tool |
-
-**Pattern for non-Claude tools**:
-```
-1. AI writes code (test, script, automation)
-2. You run: npx <command>
-3. AI analyzes output
-4. Repeat
-```
-
-This gives you the SAME experience as Claude Code with MCP, but deterministic and reusable!
-
-### What's Different
-
-| 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 |
-
-### Hook Behavior You Must Mimic
-
-**Claude Code hooks do these automatically. YOU must do them manually:**
-
-#### 1. After EVERY Task Completion
-```bash
-# Claude Code: PostToolUse hook detects task completion automatically
-# You must run these commands:
-
-# Step 1: Update tasks.md (source of truth)
-# Change: **Status**: [ ] pending → **Status**: [x] completed
-
-# Step 2: Update spec.md ACs (if task satisfies any)
-# Change: - [ ] AC-US1-01 → - [x] AC-US1-01
-
-# Step 3: Sync to external tools (if configured)
-/sw:progress-sync
-/sw-github:sync <increment-id>   # If GitHub enabled
-/sw-jira:sync <increment-id>     # If Jira enabled
-```
-
-#### 2. After User Story Completion (all ACs satisfied)
-```bash
-# Claude Code: PostToolUse hook detects US completion via AC pattern matching
-# When ALL acceptance criteria for a user story are [x] checked:
-
-# Step 1: Sync to living docs
-/sw:sync-docs update
-
-# Step 2: Update GitHub/Jira issue status
-/sw-github:sync <increment-id>
-```
-
-#### 3. After Increment Completion
-```bash
-# Claude Code: /sw:done skill orchestrates closure automatically
-# When running /sw:done:
-
-# Step 1: Validate all tasks complete
-/sw:validate <increment-id>
-
-# Step 2: Sync living docs
-/sw:sync-docs update
-
-# Step 3: Close external issues
-/sw-github:close-issue <increment-id>
-```
+| **Skills** | Auto-activate on keywords | Read SKILL.md, follow manually |
 
-#### 4. After Writing to spec.md or tasks.md
-```bash
-# Claude Code: PostToolUse hook auto-syncs on spec/tasks edits
-# After any edit to spec.md or tasks.md:
-
-# Sync status line cache
-/sw:progress-sync
-
-# If external tools configured, sync progress
-/sw-github:sync <increment-id>
-```
-
-#### 5. Session Start - Check External Changes
-```bash
-# Claude hook: SessionStart (runs automatically)
-# For non-Claude tools, check for external changes manually:
-
-# Check if any background sync jobs ran
-specweave jobs
-
-# Check progress to see current state
-/sw:progress
-
-# If external tools are configured, sync progress
-/sw-github:sync <increment-id>
-/sw-jira:sync <increment-id>
-```
-
-#### 6. After Init on Brownfield Project
-```bash
-# SpecWeave automatically launches living-docs-builder job after init
-# For non-Claude tools, monitor it manually:
-
-# Check job status
-specweave jobs
-
-# Follow the living-docs-builder progress
-specweave jobs --follow <job-id>
-
-# The job runs in 6 phases:
-# 1. waiting - Waits for clone/import jobs to complete
-# 2. discovery - Scans codebase structure (no LLM, fast)
-# 3. foundation - Generates overview.md, tech-stack.md (1-2 hours)
-# 4. integration - Matches work items to discovered modules
-# 5. deep-dive - Analyzes modules one at a time with checkpoints
-# 6. suggestions - Generates SUGGESTIONS.md with next steps
-
-# Output locations:
-# - .specweave/docs/internal/architecture/overview.md
-# - .specweave/docs/internal/architecture/tech-stack.md
-# - .specweave/docs/internal/strategy/modules-skeleton.md
-# - .specweave/docs/internal/SUGGESTIONS.md
-```
-
-### How to Check if External Tools Configured
-
-```bash
-# Check increment metadata for external tool config
-cat .specweave/increments/<id>/metadata.json
-
-# Look for these fields:
-# "github": { "issue": 123 }     → GitHub enabled
-# "jira": { "issue": "PROJ-123" } → Jira enabled
-# "ado": { "item": 456 }          → Azure DevOps enabled
-```
-
-### Manual Command Execution
+### Manual Hook Checklist
 
-In non-Claude tools, commands are markdown workflows:
+**After EVERY task completion:**
+1. Update tasks.md: `[ ] pending` → `[x] completed`
+2. Update spec.md ACs if satisfied: `[ ] AC` → `[x] AC`
+3. Run `/sw:progress-sync`
+4. Run `/sw-github:sync <id>` (if GitHub configured)
 
-```bash
-# Find and read command file
-cat plugins/specweave/commands/increment.md
-# Follow the workflow steps manually
-```
+**After all ACs for a User Story are done:**
+- Run `/sw:sync-docs update`
 
-### Quick Reference: After EVERY Task
+**After increment completion:**
+1. `/sw:validate <id>`
+2. `/sw:sync-docs update`
+3. `/sw-github:close-issue <id>`
 
-```
-┌─────────────────────────────────────────────────────────────┐
-│ AFTER COMPLETING ANY TASK (MANDATORY FOR NON-CLAUDE TOOLS)  │
-├─────────────────────────────────────────────────────────────┤
-│ 1. Update tasks.md: [ ] → [x]                               │
-│ 2. Update spec.md ACs if satisfied: [ ] → [x]               │
-│ 3. Run: /sw:progress-sync                               │
-│ 4. Run: /sw-github:sync <id>  (if GitHub configured) │
-│ 5. If all ACs for US done: /sw:sync-docs update      │
-└─────────────────────────────────────────────────────────────┘
-```
+**Session start:**
+1. `specweave jobs` (check background jobs)
+2. `/sw:progress` (check current state)
+3. `/sw:do` (continue work)
 
-### Quick Reference: Session Start Routine
-```
-┌─────────────────────────────────────────────────────────────┐
-│ START OF EVERY SESSION (FOR NON-CLAUDE TOOLS)               │
-├─────────────────────────────────────────────────────────────┤
-│ 1. Check job status:      specweave jobs                    │
-│ 2. Check progress:        /sw:progress               │
-│ 3. Continue work:         /sw:do                     │
-└─────────────────────────────────────────────────────────────┘
-```
-
-**Without these manual steps, your work won't be tracked!**
+**Background jobs**: Monitor with `specweave jobs` (clone-repos, import-issues, living-docs-builder, sync-external).
 <!-- /SECTION -->
 
 ---
 
 <!-- SECTION:syncworkflow -->
-## Sync Workflow {#sync-workflow}
-
-### Source of Truth Hierarchy
-
-```
-┌─────────────────────────────────────────────────────────────┐
-│ 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                │
-└─────────────────────────────────────────────────────────────┘
-```
+## Sync Workflow
 
-**Update Order**: ALWAYS tasks.md/spec.md FIRST → sync-tasks → sync-docs → external tools
+### Source of Truth
 
-### Sync Commands Reference
+| Level | Location | Update Method |
+|-------|----------|---------------|
+| **Source** | tasks.md + spec.md | Edit directly |
+| **Derived** | .specweave/docs/internal/specs/ | `/sw:sync-docs update` |
+| **Mirror** | GitHub/Jira/ADO | `/sw-github:sync`, `/sw-jira:sync`, `/sw-ado:sync` |
 
-| Command | What It Does | When to Run |
-|---------|--------------|-------------|
-| `/sw:progress-sync` | Recalculates progress from tasks.md | After editing tasks.md |
-| `/sw:sync-docs update` | Updates living docs from increment | After US complete |
-| `/sw-github:sync <id>` | Syncs progress to GitHub issue | After each task |
-| `/sw-github:close-issue <id>` | Closes GitHub issue | On increment done |
-| `/sw-jira:sync <id>` | Syncs progress to Jira story | After each task |
-| `/sw-ado:sync <id>` | Syncs to Azure DevOps work item | After each task |
+**Update order**: ALWAYS tasks.md/spec.md FIRST → progress-sync → sync-docs → external tools
 
-### Complete Sync Flow (Non-Claude Tools)
+### Sync Commands
 
-```
-TASK COMPLETED
-     │
-     ▼
-┌─────────────────────────────┐
-│ 1. Edit tasks.md            │
-│    [ ] pending → [x] done   │
-└─────────────────────────────┘
-     │
-     ▼
-┌─────────────────────────────┐
-│ 2. Edit spec.md ACs         │
-│    [ ] AC → [x] AC          │
-└─────────────────────────────┘
-     │
-     ▼
-┌─────────────────────────────┐
-│ 3. /sw:progress-sync    │
-│    Updates progress cache   │
-└─────────────────────────────┘
-     │
-     ▼
-┌─────────────────────────────┐
-│ 4. /sw-github:sync   │
-│    Updates GitHub issue     │
-└─────────────────────────────┘
-     │
-     ▼ (if all ACs for US done)
-┌─────────────────────────────┐
-│ 5. /sw:sync-docs     │
-│    Updates living docs      │
-└─────────────────────────────┘
-```
-
-### Claude Code Hooks (Automatic)
-
-| Hook | Trigger | What It Does |
-|------|---------|--------------|
-| `SessionStart` | Session begins | Loads config, checks active increments |
-| `UserPromptSubmit` | Every prompt | WIP limits, discipline checks, intent detection |
-| `PreToolUse` | Before file write/edit | Validates spec constraints |
-| `PostToolUse` | After file write/edit | Detects task completion, syncs progress, updates GitHub/Jira |
-| `Stop` | Session ends | Cleanup, state persistence |
-
-**Non-Claude tools**: NO HOOKS EXIST. See "Hook Behavior You Must Mimic" section above.
+| Command | When to Run |
+|---------|-------------|
+| `/sw:progress-sync` | After editing tasks.md |
+| `/sw:sync-docs update` | After US complete |
+| `/sw-github:sync <id>` | After each task |
+| `/sw-github:close-issue <id>` | On increment done |
+| `/sw-jira:sync <id>` | After each task |
+| `/sw-ado:sync <id>` | After each task |
 <!-- /SECTION -->
 
 ---
 
 <!-- SECTION:contextloading -->
-## Context Loading {#context-loading}
+## Context Loading
 
 ### Efficient Context Management
 
@@ -757,49 +275,13 @@ umbrella-project/
 
 {SKILLS_SECTION}
 
-**Usage for Claude Code**: Skills auto-activate based on keywords in your prompt.
-
-**Usage for Non-Claude Tools (Cursor, Copilot, etc.)**:
-Skills don't auto-activate. You must manually load them:
-
-```bash
-# Step 1: Find relevant skill
-ls plugins/specweave*/skills/
-
-# Step 2: Read the skill file
-cat plugins/specweave/skills/increment/SKILL.md
-
-# Step 3: Tell AI to follow the skill's workflow
-"Follow the increment skill workflow to create my feature"
-
-# Step 4: AI reads skill content and follows instructions
-```
-
-**Skill Simulation Pattern**:
-```
-Non-Claude AI Tools simulate skills by:
-1. Reading SKILL.md files from plugins/ folder
-2. Following the workflow instructions inside
-3. Using the patterns and templates provided
-4. Running `npx` commands instead of MCP tools (code-first!)
-```
+**Claude Code**: Skills auto-activate based on keywords in your prompt.
 
-**Example** - Creating increment with Cursor:
-```
-User: "Create an increment for user authentication"
-
-# STEP 0: AI MUST run this first!
-AI: [Runs: specweave context projects]
-AI: [Gets output: {"level":1,"projects":[{"id":"my-app"}]}]
-AI: [Stores: RESOLVED_PROJECT = "my-app"]
-
-# Then follow the skill workflow
-AI: [Reads plugins/specweave/skills/increment/SKILL.md]
-AI: [Follows PM workflow: research → spec → plan → tasks]
-AI: [Creates .specweave/increments/0001-auth/spec.md with **Project**: my-app per US!]
-```
-
-**⛔ CRITICAL**: The AI MUST run `specweave context projects` BEFORE creating spec.md, and use the output values in every `**Project**:` field!
+**Non-Claude Tools**: Skills don't auto-activate. Manually load them:
+1. Find: `ls plugins/specweave*/skills/`
+2. Read: `cat plugins/specweave/skills/<name>/SKILL.md`
+3. Follow the workflow instructions inside
+4. Run `specweave context projects` BEFORE creating any increment
 <!-- /SECTION -->
 
 ---
@@ -821,9 +303,9 @@ AI: [Creates .specweave/increments/0001-auth/spec.md with **Project**: my-app pe
 ---
 
 <!-- SECTION:usformat required -->
-## User Story Format (CRITICAL for spec.md) {#user-story-format}
+## User Story Format (CRITICAL for spec.md)
 
-**⛔ MANDATORY: Every User Story MUST have `**Project**:` field!**
+**MANDATORY: Every User Story MUST have `**Project**:` field!**
 
 ```markdown
 ### US-001: Feature Name
@@ -860,176 +342,39 @@ specweave context projects
 ## Workflows
 
 ### Creating Increment
-
-**⛔ STEP 0: Get Project Context FIRST (BLOCKING!)**
-```bash
-# YOU CANNOT CREATE spec.md UNTIL YOU COMPLETE THIS STEP!
-specweave context projects
-# Store the output - you'll need project IDs for every User Story
-```
-
-**Main Steps:**
-1. `mkdir -p .specweave/increments/0001-feature`
-2. Create `metadata.json` (increment metadata) - **MUST be FIRST**
-3. Create `spec.md` (WHAT/WHY, user stories, ACs) - **EVERY US needs `**Project**:` field!**
-4. Create `tasks.md` (task checklist with tests)
-5. Optional: Create `plan.md` (HOW, architecture) for complex features
-
-**Example spec.md (CORRECT):**
-```markdown
----
-increment: 0001-feature-name
-title: "Feature Title"
----
-
-### US-001: Login Form
-**Project**: my-app              # ← Value from step 0!
-
-**As a** user
-**I want** to log in
-**So that** I can access my account
-
-**Acceptance Criteria**:
-- [ ] **AC-US1-01**: Login form displays username/password fields
-```
-
-**Example spec.md (WRONG - WILL FAIL!):**
-```markdown
-### US-001: Login Form
-**As a** user                     # ← Missing **Project**: = BLOCKED!
-**I want** to log in
-```
+1. Run `specweave context projects` → store project IDs
+2. `mkdir -p .specweave/increments/XXXX-feature`
+3. Create `metadata.json` (MUST be FIRST)
+4. Create `spec.md` — every US needs `**Project**:` field (see User Story Format)
+5. Create `tasks.md` (task checklist with BDD tests)
+6. Optional: `plan.md` for complex features
 
 ### Completing Tasks
 1. Implement the task
-2. Update `tasks.md`: `[ ] pending` → `[x] completed`
-3. Update `spec.md`: Check off satisfied ACs
+2. Update tasks.md: `[ ] pending` → `[x] completed`
+3. Update spec.md: check off satisfied ACs
 4. Sync to external trackers if enabled
 
 ### Closing Increment
-1. Run `/sw:done 0001`
-2. PM validates 3 gates (tasks, tests, docs)
-3. Living docs synced automatically
-4. GitHub issue closed (if enabled)
-<!-- /SECTION -->
-
----
-
-<!-- SECTION:plugincommands -->
-## Plugin Commands
-
-| Command | Plugin |
-|---------|--------|
-| `/sw-github:sync` | GitHub sync |
-| `/sw-jira:sync` | Jira sync |
-| `/sw-ado:sync` | Azure DevOps |
+1. `/sw:done 0001` — PM validates 3 gates (tasks, tests, docs)
+2. Living docs synced automatically
+3. GitHub/Jira issue closed if enabled
 <!-- /SECTION -->
 
 ---
 
 <!-- SECTION:troubleshooting required -->
-## Troubleshooting {#troubleshooting}
-
-### Commands Not Working
-
-**Non-Claude tools**: Commands are markdown workflows, not slash syntax.
-
-```bash
-# Find and read the command file
-ls plugins/specweave/commands/
-cat plugins/specweave/commands/increment.md
-# Follow the workflow steps manually
-```
-
-### Sync Issues
-
-**Symptoms**: GitHub/Jira not updating, living docs stale
-
-**Solution** (run after EVERY task in non-Claude tools):
-```bash
-/sw:progress-sync                  # Update tasks.md
-/sw:sync-docs update            # Sync living docs
-/sw-github:sync <increment-id>  # Sync to GitHub
-```
-
-### Root Folder Polluted
-
-**Symptoms**: `git status` shows .md files in project root
-
-**Fix**:
-```bash
-CURRENT=$(ls -t .specweave/increments/ | head -1)
-mv *.md .specweave/increments/$CURRENT/reports/
-```
-
-### Tasks Out of Sync
-
-**Symptoms**: Progress shows wrong completion %
-
-**Fix**: Update tasks.md manually:
-```markdown
-**Status**: [ ] pending  →  **Status**: [x] completed
-```
-
-Or run: `/sw:progress-sync`
-
-### Context Explosion / Crashes
-
-**Symptoms**: Tool crashes 10-50s after start
-
-**Causes**: Loading too many files at once
-
-**Fix**:
-1. Load only the active increment's spec.md and tasks.md
-2. Reference living docs only when needed for specific tasks
-3. Never load entire `.specweave/docs/` folder at once
-
-### Increment Creation Fails / Missing **Project**: Field
-
-**Symptoms**: Increment creation blocked, validation errors about missing `**Project**:` field
-
-**Cause**: Every User Story in spec.md MUST have `**Project**:` (and `**Board**:` for 2-level structures)
-
-**Fix**:
-```bash
-# 1. Get valid project IDs
-specweave context projects
-
-# 2. Add **Project**: to EVERY user story in spec.md
-### US-001: Feature Name
-**Project**: my-app        # ← Add this line!
-**As a** user...
-
-# 3. For 2-level structures, also add **Board**:
-**Project**: corp
-**Board**: digital-ops     # ← Add for 2-level!
-```
-
-**Why this happens**: Non-Claude tools don't have hooks that auto-detect project context. You MUST run `specweave context projects` BEFORE creating any increment and use those values in every User Story.
-
-### Skills/Agents Not Activating
-
-**Non-Claude tools**: Skills don't auto-activate. This is EXPECTED.
-
-**Manual activation (Cursor, Copilot, Windsurf, etc.)**:
-```bash
-# 1. Find skills in plugins folder (NOT .claude/)
-ls plugins/specweave*/skills/
-
-# 2. Read the skill file
-cat plugins/specweave/skills/e2e-playwright/SKILL.md
-
-# 3. Tell AI to follow it
-"Read the e2e-playwright skill and write tests for my login page"
-
-# 4. AI writes code, YOU run it (code-first!)
-npx playwright test
-```
-
-**Remember**: Non-Claude tools get SAME functionality by:
-- Reading skill files manually
-- Following the workflows inside
-- Running `npx` instead of MCP tools (better anyway!)
+## Troubleshooting
+
+| Issue | Fix |
+|-------|-----|
+| Commands not working (non-Claude) | Read `plugins/specweave/commands/<name>.md`, follow manually |
+| GitHub/Jira not updating | `/sw:progress-sync` → `/sw:sync-docs update` → `/sw-github:sync <id>` |
+| .md files in project root | `mv *.md .specweave/increments/<current>/reports/` |
+| Progress % wrong | Update tasks.md manually or `/sw:progress-sync` |
+| Tool crashes on start | Load only active increment's spec.md + tasks.md, not entire docs/ |
+| Missing **Project**: field | `specweave context projects`, add `**Project**:` to every US |
+| Skills not activating (non-Claude) | Expected — read SKILL.md from `plugins/specweave*/skills/` |
 <!-- /SECTION -->
 
 ---
@@ -1040,7 +385,7 @@ npx playwright test
 | Resource | Purpose |
 |----------|---------|
 | CLAUDE.md | Quick reference (Claude Code) |
-| AGENTS.md | This file (non-Claude tools) |
+| AGENTS.md | This file (all AI tools) |
 | spec-weave.com | Official documentation |
 | .specweave/docs/ | Project-specific docs |
 <!-- /SECTION -->