specweave 1.0.31 → 1.0.33

package/plugins/specweave-release/commands/npm.md

@@ -1,6 +1,6 @@
 ---
 name: sw-release:npm
-description: Bump patch version, auto-commit dirty changes, push to GitHub, build, publish to npmjs.org. Use --quick for save+release (no GH workflow). Use --ci for GitHub Actions publish. Use --only for local publish without git push. Use --only --local for version bump only.
+description: Full patch release - auto-commit, push, build, npm publish, AND GitHub Release creation. Use --quick for save+release (no GH release). Use --ci for GitHub Actions publish. Use --only for local publish without git push. Use --only --local for version bump only.
 ---
 
 # /sw-release:npm - NPM Release Automation
@@ -49,9 +49,9 @@ fi
 
 | Command | Flow | Use Case |
 |---------|------|----------|
-| `/sw-release:npm` | Auto-commit → **PUSH** → Bump → Build → **Publish** → Push tag | **DEFAULT: INSTANT RELEASE** |
-| `/sw-release:npm --quick` | Auto-commit → **PUSH** → Bump → Build → **Publish locally** → NO GH workflow | **QUICK: Save + Local Release** |
-| `/sw-release:npm --ci` | Bump → Push → **CI publishes** | Let GitHub Actions handle npm publish |
+| `/sw-release:npm` | Auto-commit → **PUSH** → Bump → Build → **Publish** → Push tag → **GH Release** | **DEFAULT: FULL RELEASE** |
+| `/sw-release:npm --quick` | Auto-commit → **PUSH** → Bump → Build → **Publish locally** → NO GH release | **QUICK: Save + Local Release** |
+| `/sw-release:npm --ci` | Bump → Push → **CI publishes + GH Release** | Let GitHub Actions handle everything |
 | `/sw-release:npm --only` | Bump → Build → **Publish locally** → NO push | Quick local release, push later |
 | `/sw-release:npm --only --local` | **Bump ONLY** → NO build, NO publish, NO git | FASTEST: Local testing only |
 | `/sw-release:npm --stable` | Same as default, but promotes prerelease to stable | **PROMOTE TO STABLE** |
@@ -198,14 +198,56 @@ npm publish --registry https://registry.npmjs.org
 git push origin develop --follow-tags
 ```
 
-### 8. Report Results
+### 8. Create GitHub Release
+
+```bash
+# Get the new version
+NEW_VERSION=$(node -p "require('./package.json').version")
+
+# Extract release notes from CHANGELOG.md (if available)
+if [ -f CHANGELOG.md ] && grep -q "## \[$NEW_VERSION\]" CHANGELOG.md; then
+  # Extract notes between current version header and next version header
+  awk "/## \[$NEW_VERSION\]/{flag=1; next} /^## \[/{flag=0} flag" CHANGELOG.md > /tmp/release-notes.md
+else
+  # Generate minimal release notes from recent commits
+  echo "## What's Changed" > /tmp/release-notes.md
+  echo "" >> /tmp/release-notes.md
+  LAST_TAG=$(git describe --tags --abbrev=0 HEAD^ 2>/dev/null || echo "")
+  if [ -n "$LAST_TAG" ]; then
+    git log --oneline "$LAST_TAG"..HEAD~1 --no-merges | head -10 | sed 's/^[a-f0-9]* /- /' >> /tmp/release-notes.md
+  else
+    git log --oneline -10 --no-merges | sed 's/^[a-f0-9]* /- /' >> /tmp/release-notes.md
+  fi
+fi
+
+# Create GitHub release (prerelease if version contains -rc, -beta, -alpha)
+if [[ "$NEW_VERSION" == *"-rc"* ]] || [[ "$NEW_VERSION" == *"-beta"* ]] || [[ "$NEW_VERSION" == *"-alpha"* ]]; then
+  gh release create "v$NEW_VERSION" \
+    --title "v$NEW_VERSION" \
+    --notes-file /tmp/release-notes.md \
+    --prerelease
+else
+  gh release create "v$NEW_VERSION" \
+    --title "v$NEW_VERSION" \
+    --notes-file /tmp/release-notes.md \
+    --latest
+fi
+```
+
+**What this does**:
+- Extracts release notes from CHANGELOG.md (or generates from commits)
+- Creates GitHub Release with proper title and notes
+- Marks prereleases appropriately (rc, beta, alpha)
+- Marks stable releases as "latest"
+
+### 9. Report Results
 
 ```markdown
-✅ **Instant release complete!**
+✅ **Full patch release complete!**
 
 📦 **Version**: vX.Y.Z
 🔗 **NPM**: https://www.npmjs.com/package/specweave
-🏷️ **GitHub**: https://github.com/anton-abyzov/specweave/releases/tag/vX.Y.Z
+🏷️ **GitHub Release**: https://github.com/anton-abyzov/specweave/releases/tag/vX.Y.Z
 
 **What happened**:
 - ✅ Dirty changes auto-committed
@@ -214,6 +256,7 @@ git push origin develop --follow-tags
 - ✅ Package built
 - ✅ Published to npmjs.org
 - ✅ Version tag pushed to GitHub
+- ✅ GitHub Release created with release notes
 
 **Verify**: `npm view specweave version --registry https://registry.npmjs.org`
 ```
@@ -227,6 +270,7 @@ git push origin develop --follow-tags
 ✅ Package rebuilt
 ✅ Published to npmjs.org (explicit registry!)
 ✅ Version commit + tag pushed to GitHub
+✅ **GitHub Release created with release notes**
 
 ---
 
@@ -549,10 +593,10 @@ Show the user:
 ## Quick Reference
 
 ```bash
-# DEFAULT: Instant release (auto-commits dirty, publishes, pushes + tag)
+# DEFAULT: Full release (auto-commits dirty, publishes, pushes + tag, GH release)
 /sw-release:npm
 
-# QUICK: Save + local release (auto-commits, pushes, publishes - NO GH workflow)
+# QUICK: Save + local release (auto-commits, pushes, publishes - NO GH release)
 /sw-release:npm --quick
 
 # CI release (GitHub Actions handles npm publish) - requires clean tree
@@ -568,14 +612,14 @@ Show the user:
 /sw-release:npm --stable
 ```
 
-| Scenario | Command | Prerelease Handling | Git Pushed | Tag Pushed |
-|----------|---------|---------------------|------------|------------|
-| **INSTANT RELEASE** | (no flags) | `rc.1`→`rc.2` (smart) | ✅ Yes | ✅ Yes |
-| **QUICK RELEASE** | `--quick` | `rc.1`→`rc.2` (smart) | ✅ Yes | ❌ No |
-| CI release | `--ci` | `rc.1`→`rc.2` (smart) | ✅ Yes | ✅ Yes |
-| Local publish | `--only` | `rc.1`→`rc.2` (smart) | ❌ No | ❌ No |
-| Local bump | `--only --local` | `rc.1`→`rc.2` (smart) | ❌ No | ❌ No |
-| **PROMOTE** | `--stable` | `rc.X`→`X.Y.Z+1` | ✅ Yes | ✅ Yes |
+| Scenario | Command | Prerelease Handling | Git Pushed | Tag Pushed | GH Release |
+|----------|---------|---------------------|------------|------------|------------|
+| **FULL RELEASE** | (no flags) | `rc.1`→`rc.2` (smart) | ✅ Yes | ✅ Yes | ✅ Yes |
+| **QUICK RELEASE** | `--quick` | `rc.1`→`rc.2` (smart) | ✅ Yes | ❌ No | ❌ No |
+| CI release | `--ci` | `rc.1`→`rc.2` (smart) | ✅ Yes | ✅ Yes | ✅ (via CI) |
+| Local publish | `--only` | `rc.1`→`rc.2` (smart) | ❌ No | ❌ No | ❌ No |
+| Local bump | `--only --local` | `rc.1`→`rc.2` (smart) | ❌ No | ❌ No | ❌ No |
+| **PROMOTE** | `--stable` | `rc.X`→`X.Y.Z+1` | ✅ Yes | ✅ Yes | ✅ Yes |
 
 ---
 

package/plugins/specweave-release/hooks/post-task-completion.sh

@@ -8,9 +8,8 @@
 
 # CRITICAL (v0.25.2): NEVER use 'set -e' in hooks - causes Claude Code crashes
 # See: CLAUDE.md Section 9a (Hook Safety Checklist), ADR-0060 (Hook Performance)
-set +e  # Allow commands to fail without terminating script
-set -u  # Fail on undefined variables
-set -o pipefail  # Fail if any command in pipeline fails
+# v1.0.33 - Fixed: removed set -o pipefail for hook safety
+set +e  # CRITICAL: Never use set -e or pipefail in hooks (causes cascading failures)
 
 # Constants
 SPECWEAVE_ROOT="${SPECWEAVE_ROOT:-$(pwd)}"

package/src/templates/AGENTS.md.template

@@ -17,6 +17,7 @@
 
 ---
 
+<!-- SECTION:index -->
 ## Section Index (Use Ctrl+F to Navigate)
 
 | Section | Search For | Purpose |
@@ -28,18 +29,22 @@
 | Sync | `#sync-workflow` | When/how to sync |
 | Context | `#context-loading` | Token savings (70%+) |
 | 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}
 
 ```
@@ -62,9 +67,11 @@
 ├── scripts/                       # Helper scripts
 └── logs/                          # Execution logs
 ```
+<!-- /SECTION -->
 
 ---
 
+<!-- SECTION:commands required -->
 ## Commands Reference {#commands}
 
 ### Core Commands
@@ -86,9 +93,11 @@
 | `/sw-github:sync 0001` | Sync increment to GitHub issue |
 | `/sw-jira:sync 0001` | Sync to Jira |
 | `/sw-ado:sync 0001` | Sync to Azure DevOps |
+<!-- /SECTION -->
 
 ---
 
+<!-- SECTION:nonclaudetools required -->
 ## Non-Claude Tools (Cursor, Copilot, etc.) {#non-claude-tools}
 
 **CRITICAL**: Claude Code has automatic hooks. Other tools DO NOT.
@@ -339,9 +348,11 @@ cat plugins/specweave/commands/increment.md
 ```
 
 **Without these manual steps, your work won't be tracked!**
+<!-- /SECTION -->
 
 ---
 
+<!-- SECTION:syncworkflow -->
 ## Sync Workflow {#sync-workflow}
 
 ### Source of Truth Hierarchy
@@ -421,9 +432,11 @@ TASK COMPLETED
 | `PostIncrementDone` | Increment closed | Closes issues, syncs all docs |
 
 **Non-Claude tools**: NO HOOKS EXIST. See "Hook Behavior You Must Mimic" section above.
+<!-- /SECTION -->
 
 ---
 
+<!-- SECTION:contextloading -->
 ## Context Loading {#context-loading}
 
 ### Efficient Context Management
@@ -441,9 +454,11 @@ Read only what's needed for the current task:
 2. Reference `spec.md` for acceptance criteria
 3. Load living docs only when needed for context
 4. Avoid loading entire documentation trees
+<!-- /SECTION -->
 
 ---
 
+<!-- SECTION:structure -->
 ## Project Structure
 
 ```
@@ -462,17 +477,21 @@ Read only what's needed for the current task:
 │   └── delivery/         # CI/CD, deployment guides
 └── state/                # Runtime state (active increment, caches)
 ```
+<!-- /SECTION -->
 
 ---
 
+<!-- SECTION:agents -->
 ## Agents (Roles)
 
 {AGENTS_SECTION}
 
 **Usage**: Adopt role perspective when working on related tasks.
+<!-- /SECTION -->
 
 ---
 
+<!-- SECTION:skills -->
 ## Skills (Capabilities)
 
 {SKILLS_SECTION}
@@ -520,9 +539,11 @@ AI: [Creates .specweave/increments/0001-auth/spec.md with **Project**: my-app pe
 ```
 
 **⛔ CRITICAL**: The AI MUST run `specweave context projects` BEFORE creating spec.md, and use the output values in every `**Project**:` field!
+<!-- /SECTION -->
 
 ---
 
+<!-- SECTION:taskformat required -->
 ## Task Format
 
 ```markdown
@@ -534,7 +555,11 @@ AI: [Creates .specweave/increments/0001-auth/spec.md with **Project**: my-app pe
 **Test Plan** (BDD):
 - Given [context] → When [action] → Then [result]
 ```
+<!-- /SECTION -->
 
+---
+
+<!-- SECTION:usformat required -->
 ## User Story Format (CRITICAL for spec.md) {#user-story-format}
 
 **⛔ MANDATORY: Every User Story MUST have `**Project**:` field!**
@@ -566,9 +591,11 @@ specweave context projects
 # {"level":2,"projects":[...],"boardsByProject":{"corp":[{"id":"digital-ops"}]}}
 # → Use: **Project**: corp AND **Board**: digital-ops
 ```
+<!-- /SECTION -->
 
 ---
 
+<!-- SECTION:workflows -->
 ## Workflows
 
 ### Creating Increment
@@ -623,9 +650,11 @@ title: "Feature Title"
 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 |
@@ -633,9 +662,11 @@ title: "Feature Title"
 | `/sw-github:sync` | GitHub sync |
 | `/sw-jira:sync` | Jira sync |
 | `/sw-ado:sync` | Azure DevOps |
+<!-- /SECTION -->
 
 ---
 
+<!-- SECTION:troubleshooting required -->
 ## Troubleshooting {#troubleshooting}
 
 ### Commands Not Working
@@ -738,9 +769,11 @@ npx playwright test
 - Reading skill files manually
 - Following the workflows inside
 - Running `npx` instead of MCP tools (better anyway!)
+<!-- /SECTION -->
 
 ---
 
+<!-- SECTION:docs -->
 ## Documentation
 
 | Resource | Purpose |
@@ -749,6 +782,7 @@ npx playwright test
 | AGENTS.md | This file (non-Claude tools) |
 | spec-weave.com | Official documentation |
 | .specweave/docs/ | Project-specific docs |
+<!-- /SECTION -->
 
 ---
 

package/src/templates/CLAUDE.md.template

@@ -1,208 +1,174 @@
-# {PROJECT_NAME} - SpecWeave Quick Reference
+# {PROJECT_NAME} - SpecWeave Reference
 
-**Framework**: SpecWeave (spec-first development)
-**Source of Truth**: `spec.md` + `tasks.md` (not internal TODO)
+<!-- SECTION:header required -->
+**Framework**: SpecWeave | **Truth**: `spec.md` + `tasks.md`
+<!-- /SECTION -->
 
----
+<!-- SECTION:start -->
+## Getting Started
 
-## Critical Rules
+**Initial increment**: `0001-project-setup` (auto-created by `specweave init`)
 
-### 1. File Organization
-**NEVER pollute project root!** All AI-generated files → increment folders.
+**Options**:
+1. **Start fresh**: `rm -rf .specweave/increments/0001-project-setup` → `/sw:increment "your-feature"`
+2. **Customize**: Edit spec.md and use for setup tasks
+<!-- /SECTION -->
 
-```
-.specweave/increments/####-name/
-├── spec.md, plan.md, tasks.md    ← ONLY these at root
-├── reports/                       ← Reports, summaries, analysis
-├── scripts/                       ← Helper scripts, migrations
-└── logs/                          ← Execution logs, temp data
-```
+<!-- SECTION:autodetect -->
+## Auto-Detection
 
-### 2. Source of Truth
-After completing work, **IMMEDIATELY update both files**:
-```typescript
-TodoWrite([{task: "T-001", status: "completed"}]);
-Edit("tasks.md", "**Status**: [ ] pending", "**Status**: [x] completed");
-Edit("spec.md", "- [ ] **AC-US1-01**", "- [x] **AC-US1-01**");
-```
+SpecWeave auto-detects product descriptions and routes to `/sw:increment`:
 
-### 3. Increment Numbers Must Be Unique
-**Format**: `####-descriptive-name` (e.g., `0001-user-auth`)
-**Check before creating**: `ls -1 .specweave/increments/ | grep -E "^[0-9]{4}-" | sort | tail -5`
+**Signals** (5+ = auto-route): Project name | Features list (3+) | Tech stack | Timeline/MVP | Problem statement | Business model
 
-### 4. Emergency Minimal Mode
+**Opt-out phrases**: "Just brainstorm first" | "Don't plan yet" | "Quick discussion" | "Let's explore ideas"
+<!-- /SECTION -->
 
-**Activates ONLY on**: "emergency mode", "minimal mode ON", "crashed N times"
+<!-- SECTION:metarule required -->
+## Meta-Rule: Think-Before-Act
 
-**Rules:** `READ: limit:50 | EDIT: 1/response | AGENTS: none | FLOW: "Done. Next?"`
+**Satisfy dependencies BEFORE dependent operations.**
 
-**Phrase:** `EMERGENCY MODE. 1 edit. 50 lines max. No agents.`
+```
+❌ node script.js → Error → npm run build
+✅ npm run build → node script.js → Success
+```
+<!-- /SECTION -->
 
----
+<!-- SECTION:rules required -->
+## Rules
 
-## Core Workflow
+1. **Files** → `.specweave/increments/####-name/` (spec.md, plan.md, tasks.md at root; reports/, scripts/, logs/ subfolders)
+2. **Update immediately**: `Edit("tasks.md", "[ ] pending", "[x] completed")` + `Edit("spec.md", "[ ] AC-", "[x] AC-")`
+3. **Unique IDs**: Check `ls .specweave/increments/ | grep "^[0-9]" | tail -5`
+4. **Emergency**: "emergency mode" → 1 edit, 50 lines max, no agents
+5. **Root clean**: NEVER create .md/reports/scripts in project root → use increment folders
+<!-- /SECTION -->
 
-```
-/sw:increment "feature" → /sw:do → /sw:progress → /sw:done 0001
-```
+<!-- SECTION:workflow required -->
+## Workflow
 
-| Command | Purpose |
-|---------|---------|
-| `/sw:increment "X"` | Plan new feature |
-| `/sw:do` | Execute implementation |
-| `/sw:progress` | Check status |
-| `/sw:validate 0001` | Quality check |
-| `/sw:done 0001` | Close increment |
+`/sw:increment "X"` → `/sw:do` → `/sw:progress` → `/sw:done 0001`
 
-**Sync Commands** (if plugins installed):
-- `/sw-github:sync` - Sync to GitHub Issues
-- `/sw-jira:sync` - Sync to Jira
-- `/sw-ado:sync` - Sync to Azure DevOps
+| Cmd | Action |
+|-----|--------|
+| `/sw:increment` | Plan feature |
+| `/sw:do` | Execute |
+| `/sw:validate` | Quality check |
+| `/sw:done` | Close |
+| `/sw-github:sync` | GitHub sync |
+| `/sw-jira:sync` | Jira sync |
 
----
+**Natural language**: "Let's build X" → `/sw:increment` | "What's status?" → `/sw:progress` | "We're done" → `/sw:done`
+<!-- /SECTION -->
 
-## Project Structure
+<!-- SECTION:structure -->
+## Structure
 
 ```
 .specweave/
-├── increments/              # Feature increments (####-name/)
-│   └── 0001-feature/
-│       ├── metadata.json    # Increment metadata - REQUIRED
-│       ├── spec.md          # WHAT & WHY
-│       ├── plan.md          # HOW (optional)
-│       └── tasks.md         # Checklist with embedded tests
+├── increments/####-name/     # metadata.json, spec.md, tasks.md
 ├── docs/internal/
-│   ├── strategy/            # Business specs
-│   ├── specs/               # Living docs (post-completion)
-│   │   └── {project}/       # Project-specific specs
-│   ├── architecture/        # Technical design, ADRs
-│   └── operations/          # Runbooks, SLOs
-└── config.json              # Project configuration
+│   ├── specs/{project}/      # Living docs
+│   ├── architecture/adr/     # ADRs
+│   └── operations/           # Runbooks
+└── config.json
 ```
 
----
+**Multi-repo**: Clone to `/repositories`, not root → `repositories/backend/src/...`
+<!-- /SECTION -->
 
-## Task Format (Mandatory)
+<!-- SECTION:taskformat required -->
+## Task Format
 
 ```markdown
-### T-001: Task Title
-**User Story**: US-001           ← REQUIRED
-**Satisfies ACs**: AC-US1-01     ← REQUIRED
-**Status**: [x] completed
-
-**Test Plan** (BDD):
-- **Given** [context] → **When** [action] → **Then** [result]
+### T-001: Title
+**User Story**: US-001 | **Satisfies ACs**: AC-US1-01 | **Status**: [x] completed
+**Test**: Given [X] → When [Y] → Then [Z]
 ```
+<!-- /SECTION -->
 
----
-
-## Increment Files
-
-**Required files** for every increment:
-1. `metadata.json` - Increment metadata (status, type, dates) - MUST create FIRST
-2. `spec.md` - User stories, acceptance criteria
-3. `tasks.md` - Implementation tasks with embedded tests
+<!-- SECTION:secrets required -->
+## Secrets Check
 
-**Optional**:
-- `plan.md` - Technical design (for complex features only)
-- `reports/` - Completion reports, analyses
-
----
+**BEFORE CLI tools**: Check existing config first!
+```bash
+grep -E "(GITHUB_TOKEN|JIRA_|ADO_)" .env 2>/dev/null
+cat .specweave/config.json | grep -A5 '"sync"'
+gh auth status
+```
+<!-- /SECTION -->
 
-## Automatic Syncing (Hooks)
+<!-- SECTION:syncing -->
+## Auto-Sync (Hooks)
 
-After **EVERY task completion**, hooks automatically:
-1. Update `tasks.md` status
-2. Sync to living docs (`.specweave/docs/internal/specs/`)
-3. Sync to external trackers (GitHub/Jira/ADO) if configured
+Post-task: updates tasks.md → living docs → external trackers (if configured)
 
-**Configuration** (`.specweave/config.json`):
-```json
-{
-  "hooks": {
-    "post_task_completion": {
-      "sync_living_docs": true,
-      "external_tracker_sync": true
-    }
-  }
-}
-```
+Config: `.specweave/config.json` → `hooks.post_task_completion`
+<!-- /SECTION -->
 
----
-
-## GitHub Sync Mapping
+<!-- SECTION:mapping -->
+## GitHub Mapping
 
 | SpecWeave | GitHub |
 |-----------|--------|
-| Feature (FS-XXX) | Milestone |
-| User Story (US-XXX) | Issue |
-| Task (T-XXX) | Checkbox |
-
-**Issue Title Format**: `[FS-XXX][US-YYY] User Story Title`
-
----
-
-## Tech Stack
-
-**Type**: {MONOREPO_OR_SINGLE}
-
-{#IF_SINGLE_STACK}
-- Language: {DETECTED_LANGUAGE}
-- Framework: {DETECTED_FRAMEWORK}
-- Database: {SPECIFIED_DATABASE}
-{#ENDIF}
-
-{#IF_MONOREPO}
-**Services**:
-- {SERVICE_1_NAME}: {SERVICE_1_LANGUAGE} ({SERVICE_1_PATH}/)
-- {SERVICE_2_NAME}: {SERVICE_2_LANGUAGE} ({SERVICE_2_PATH}/)
-{#ENDIF}
-
----
+| Feature FS-XXX | Milestone |
+| Story US-XXX | Issue `[FS-XXX][US-YYY] Title` |
+| Task T-XXX | Checkbox |
+<!-- /SECTION -->
 
+<!-- SECTION:testing -->
 ## Testing
 
-**Test-Aware Planning**: Tests embedded in `tasks.md` (BDD format)
-- Unit tests: >80% coverage
-- Integration tests: Critical paths
-- E2E tests: When UI exists
-
-**Test Files**: `.test.ts` (Vitest), NOT `.spec.ts`
-
----
+BDD in tasks.md | Unit >80% | `.test.ts` (Vitest)
 
-## File Size
+```typescript
+// Vitest pattern: vi.fn() not jest.fn(), import not require
+import { vi } from 'vitest';
+vi.mock('fs', () => ({ readFile: vi.fn() }));
+```
+<!-- /SECTION -->
 
-**Max 1500 lines/file**. Over 1000 → extract before adding code.
+<!-- SECTION:limits -->
+## Limits
 
----
+**Max 1500 lines/file** — extract before adding
+<!-- /SECTION -->
 
+<!-- SECTION:troubleshooting required -->
 ## Troubleshooting
 
-| Issue | Solution |
-|-------|----------|
-| Skills not activating | Restart Claude Code |
-| Commands not found | Check plugin: `/plugin list --installed` |
-| Root polluted | Move files to increment folders |
-| Tasks out of sync | `/sw:sync-tasks` |
-| Can't find increment | `/sw:status` |
-
----
+| Issue | Fix |
+|-------|-----|
+| Skills missing | Restart Claude Code |
+| Commands gone | `/plugin list --installed` |
+| Out of sync | `/sw:sync-tasks` |
+| Find increment | `/sw:status` |
+| Root polluted | Move files to `.specweave/increments/####/reports/` |
+| Duplicate IDs | `/sw:fix-duplicates` |
+| External not syncing | Check `config.json` → `external_tracker_sync: true` |
+<!-- /SECTION -->
 
-## Documentation
+<!-- SECTION:principles -->
+## Principles
 
-- **Quick Reference**: This file
-- **Full Docs**: https://spec-weave.com
-- **Project Docs**: `.specweave/docs/internal/`
+1. **Spec-first**: `/sw:increment` before coding
+2. **Docs = truth**: Specs guide implementation
+3. **Incremental**: Small, validated increments
+4. **Traceable**: All work → specs → ACs
+5. **Clean**: All files in increment folders
+<!-- /SECTION -->
 
----
+<!-- SECTION:linking -->
+## Bidirectional Linking
 
-## Project-Specific Notes
+Tasks ↔ User Stories auto-linked via AC-IDs: `AC-US1-01` → `US-001`
 
-{#CUSTOM_NOTES}
-<!-- Add project-specific conventions here -->
-{#ENDCUSTOM}
+Task format: `**AC**: AC-US1-01, AC-US1-02` (CRITICAL for linking)
+<!-- /SECTION -->
 
----
+<!-- SECTION:docs -->
+## Docs
 
-**SpecWeave**: Specification-first AI development framework
+[spec-weave.com](https://spec-weave.com) | `.specweave/docs/internal/`
+<!-- /SECTION -->