specweave 1.0.244 → 1.0.246

package/src/templates/AGENTS.md.template

@@ -29,7 +29,7 @@
 | **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` | Token savings (70%+) |
+| Context | `#context-loading` | Efficient context loading |
 | Troubleshoot | `#troubleshooting` | Common issues |
 <!-- /SECTION -->
 
@@ -344,7 +344,7 @@ SpecWeave v0.28+ introduces powerful automation that **works differently** in no
 | 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 `/sw:sync-pull` manually |
+| **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 |
 
@@ -369,8 +369,10 @@ 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 (NEW!)
+- `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`.
 
@@ -432,7 +434,7 @@ This gives you the SAME experience as Claude Code with MCP, but deterministic an
 
 #### 1. After EVERY Task Completion
 ```bash
-# Claude hook: PostTaskCompletion
+# Claude Code: PostToolUse hook detects task completion automatically
 # You must run these commands:
 
 # Step 1: Update tasks.md (source of truth)
@@ -449,7 +451,7 @@ This gives you the SAME experience as Claude Code with MCP, but deterministic an
 
 #### 2. After User Story Completion (all ACs satisfied)
 ```bash
-# Claude hook: PostUserStoryCompletion
+# 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
@@ -461,7 +463,7 @@ This gives you the SAME experience as Claude Code with MCP, but deterministic an
 
 #### 3. After Increment Completion
 ```bash
-# Claude hook: PostIncrementDone
+# Claude Code: /sw:done skill orchestrates closure automatically
 # When running /sw:done:
 
 # Step 1: Validate all tasks complete
@@ -476,7 +478,7 @@ This gives you the SAME experience as Claude Code with MCP, but deterministic an
 
 #### 4. After Writing to spec.md or tasks.md
 ```bash
-# Claude hook: PostToolUse (Write/Edit to spec/tasks files)
+# Claude Code: PostToolUse hook auto-syncs on spec/tasks edits
 # After any edit to spec.md or tasks.md:
 
 # Sync status line cache
@@ -486,24 +488,20 @@ This gives you the SAME experience as Claude Code with MCP, but deterministic an
 /sw-github:sync <increment-id>
 ```
 
-#### 5. Bidirectional Sync - PULL from External Tools
+#### 5. Session Start - Check External Changes
 ```bash
 # Claude hook: SessionStart (runs automatically)
-# For non-Claude tools, run manually to catch external changes:
+# For non-Claude tools, check for external changes manually:
 
-# Pull changes from external tools (status, priority, assignee)
-/sw:sync-pull
+# Check if any background sync jobs ran
+specweave jobs
 
-# This does:
-# 1. Query ADO/JIRA/GitHub for items changed since last sync
-# 2. Pull status/priority/assignee updates to living docs
-# 3. Use timestamp-based conflict resolution (latest wins)
-# 4. Log all changes with full audit trail
+# Check progress to see current state
+/sw:progress
 
-# When to run:
-# - Start of each work session (catch overnight changes)
-# - Before starting work on a linked increment
-# - After PM updates status in external tool
+# If external tools are configured, sync progress
+/sw-github:sync <increment-id>
+/sw-jira:sync <increment-id>
 ```
 
 #### 6. After Init on Brownfield Project
@@ -568,15 +566,14 @@ cat plugins/specweave/commands/increment.md
 └─────────────────────────────────────────────────────────────┘
 ```
 
-### Quick Reference: Session Start Routine 
+### Quick Reference: Session Start Routine
 ```
 ┌─────────────────────────────────────────────────────────────┐
 │ START OF EVERY SESSION (FOR NON-CLAUDE TOOLS)               │
 ├─────────────────────────────────────────────────────────────┤
-│ 1. Pull external changes: /sw:sync-pull              │
-│ 2. Check job status:      specweave jobs                    │
-│ 3. Check progress:        /sw:progress               │
-│ 4. Continue work:         /sw:do                     │
+│ 1. Check job status:      specweave jobs                    │
+│ 2. Check progress:        /sw:progress               │
+│ 3. Continue work:         /sw:do                     │
 └─────────────────────────────────────────────────────────────┘
 ```
 
@@ -659,10 +656,11 @@ TASK 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 |
+| `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.
 <!-- /SECTION -->

package/src/templates/CLAUDE.md.template

@@ -194,6 +194,8 @@ SpecWeave auto-detects product descriptions and routes to `/sw:increment`:
    ls docs/ | grep -E '^[0-9]{2}-' | cut -d'-' -f1 | sort -u
    ```
    Use next available number. **NEVER create duplicate prefixes.**
+8. **⛔ Multi-repo**: ALL repos MUST be at `repositories/{org}/{repo-name}/` — NEVER directly under `repositories/`
+   Discover org from config: `repository.organization` → `sync.profiles` → `umbrella.childRepos` → filesystem
 <!-- /SECTION -->
 
 <!-- SECTION:workflow required -->
@@ -608,7 +610,7 @@ Claude Code runs hooks automatically. **You must trigger these manually:**
 | **After EVERY task** | Update tasks.md `[ ]→[x]` + spec.md ACs `[ ]→[x]` + `/sw:sync-tasks` |
 | **After all ACs done** | `/sw:sync-docs update` to sync living docs |
 | **On increment close** | `/sw:validate {id}` then `/sw:done {id}` |
-| **Session start** | `/sw:sync-pull` to pull external changes |
+| **Session start** | Check `specweave jobs` + `/sw:progress` for current state |
 
 **Full hook simulation guide:** See `AGENTS.md` for detailed instructions.