specweave 0.4.1 → 0.6.0

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

@@ -0,0 +1,265 @@
+#!/bin/bash
+
+# SpecWeave Post-Task-Completion Hook
+# Runs automatically after ANY task is marked complete via TodoWrite
+#
+# SMART SESSION-END DETECTION (v2.0):
+# =====================================
+# Problem: Claude creates multiple todo lists in one conversation
+# - List 1: [A, B, C] → completes → sound plays
+# - List 2: [D, E] → completes 30s later → sound plays again
+# - User hears sounds while Claude is still working!
+#
+# Solution: Inactivity-based detection
+# - Track time gaps BETWEEN TodoWrite calls
+# - If all tasks complete AND gap > INACTIVITY_THRESHOLD (15s)
+#   → Session is winding down → Play sound
+# - If rapid completions (gap < threshold)
+#   → Claude still actively working → Skip sound
+#
+# Example:
+# 10:00:00 - Task done (gap: 5s) → skip sound
+# 10:00:05 - Task done (gap: 5s) → skip sound
+# 10:00:10 - All done (gap: 5s) → skip sound (rapid work)
+# ...
+# 10:01:00 - All done (gap: 50s) → PLAY SOUND! (session ending)
+#
+# DEBOUNCING: Prevents duplicate fires (Claude Code calls hooks twice)
+
+set -e
+
+PROJECT_ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/../.." && pwd)"
+cd "$PROJECT_ROOT" 2>/dev/null || true
+
+# ============================================================================
+# CONFIGURATION
+# ============================================================================
+
+# Debounce window to prevent duplicate hook fires
+DEBOUNCE_SECONDS=2
+
+# Inactivity threshold to detect session end
+# If gap between TodoWrite calls > this value, assume session is ending
+INACTIVITY_THRESHOLD=15  # seconds (configurable)
+
+# File paths
+LOGS_DIR=".specweave/logs"
+LAST_FIRE_FILE="$LOGS_DIR/last-hook-fire"
+LAST_TODOWRITE_FILE="$LOGS_DIR/last-todowrite-time"
+DEBUG_LOG="$LOGS_DIR/hooks-debug.log"
+TASKS_LOG="$LOGS_DIR/tasks.log"
+
+mkdir -p "$LOGS_DIR" 2>/dev/null || true
+
+# ============================================================================
+# DEBOUNCING
+# ============================================================================
+
+CURRENT_TIME=$(date +%s)
+
+# Skip if hook fired within last N seconds (prevents duplicates)
+if [ -f "$LAST_FIRE_FILE" ]; then
+  LAST_FIRE=$(cat "$LAST_FIRE_FILE" 2>/dev/null || echo "0")
+  TIME_DIFF=$((CURRENT_TIME - LAST_FIRE))
+
+  if [ "$TIME_DIFF" -lt "$DEBOUNCE_SECONDS" ]; then
+    echo "[$(date)] ⏭️  Debounced (last fire: ${TIME_DIFF}s ago)" >> "$DEBUG_LOG" 2>/dev/null || true
+    cat <<EOF
+{
+  "continue": true
+}
+EOF
+    exit 0
+  fi
+fi
+
+echo "$CURRENT_TIME" > "$LAST_FIRE_FILE"
+
+# ============================================================================
+# CAPTURE INPUT
+# ============================================================================
+
+STDIN_DATA=$(mktemp)
+cat > "$STDIN_DATA"
+
+echo "[$(date)] 📋 TodoWrite hook fired" >> "$DEBUG_LOG" 2>/dev/null || true
+echo "[$(date)] Input JSON:" >> "$DEBUG_LOG" 2>/dev/null || true
+cat "$STDIN_DATA" >> "$DEBUG_LOG" 2>/dev/null || true
+echo "" >> "$DEBUG_LOG" 2>/dev/null || true
+
+# ============================================================================
+# INACTIVITY DETECTION
+# ============================================================================
+
+INACTIVITY_GAP=0
+PREVIOUS_TODOWRITE_TIME=0
+
+if [ -f "$LAST_TODOWRITE_FILE" ]; then
+  PREVIOUS_TODOWRITE_TIME=$(cat "$LAST_TODOWRITE_FILE" 2>/dev/null || echo "0")
+  INACTIVITY_GAP=$((CURRENT_TIME - PREVIOUS_TODOWRITE_TIME))
+  echo "[$(date)] ⏱️  Inactivity gap: ${INACTIVITY_GAP}s (threshold: ${INACTIVITY_THRESHOLD}s)" >> "$DEBUG_LOG" 2>/dev/null || true
+else
+  echo "[$(date)] 🆕 First TodoWrite in session" >> "$DEBUG_LOG" 2>/dev/null || true
+fi
+
+# Save current timestamp for next call
+echo "$CURRENT_TIME" > "$LAST_TODOWRITE_FILE"
+
+# ============================================================================
+# PARSE TASK COMPLETION STATE
+# ============================================================================
+
+ALL_COMPLETED=false
+
+if command -v jq >/dev/null 2>&1; then
+  # Use jq if available (more reliable)
+  PENDING_COUNT=$(jq -r '.tool_input.todos // [] | map(select(.status != "completed")) | length' "$STDIN_DATA" 2>/dev/null || echo "1")
+  TOTAL_COUNT=$(jq -r '.tool_input.todos // [] | length' "$STDIN_DATA" 2>/dev/null || echo "0")
+
+  echo "[$(date)] 📊 Tasks: $((TOTAL_COUNT - PENDING_COUNT))/$TOTAL_COUNT completed" >> "$DEBUG_LOG" 2>/dev/null || true
+
+  if [ "$PENDING_COUNT" = "0" ] && [ "$TOTAL_COUNT" != "0" ]; then
+    ALL_COMPLETED=true
+  fi
+else
+  # Fallback: Simple grep check (less reliable but works without jq)
+  if grep -q '"status":"pending"\|"status":"in_progress"' "$STDIN_DATA" 2>/dev/null; then
+    ALL_COMPLETED=false
+  else
+    ALL_COMPLETED=true
+  fi
+fi
+
+rm -f "$STDIN_DATA"
+
+# ============================================================================
+# SESSION-END DETECTION LOGIC
+# ============================================================================
+
+SESSION_ENDING=false
+DECISION_REASON=""
+
+if [ "$ALL_COMPLETED" = "true" ]; then
+  if [ "$INACTIVITY_GAP" -ge "$INACTIVITY_THRESHOLD" ]; then
+    SESSION_ENDING=true
+    DECISION_REASON="All tasks complete + ${INACTIVITY_GAP}s inactivity ≥ ${INACTIVITY_THRESHOLD}s threshold"
+    echo "[$(date)] 🎉 SESSION ENDING DETECTED! ($DECISION_REASON)" >> "$DEBUG_LOG" 2>/dev/null || true
+  else
+    DECISION_REASON="All tasks complete, but rapid activity (${INACTIVITY_GAP}s < ${INACTIVITY_THRESHOLD}s) - Claude likely creating more work"
+    echo "[$(date)] ⚡ $DECISION_REASON (no sound)" >> "$DEBUG_LOG" 2>/dev/null || true
+  fi
+else
+  DECISION_REASON="Tasks remaining in current list"
+  echo "[$(date)] 🔄 $DECISION_REASON (no sound)" >> "$DEBUG_LOG" 2>/dev/null || true
+fi
+
+# ============================================================================
+# UPDATE TASKS.MD (NEW in v0.6.1)
+# ============================================================================
+
+if command -v node &> /dev/null; then
+  # Detect current increment (latest non-backlog increment)
+  CURRENT_INCREMENT=$(ls -t .specweave/increments/ 2>/dev/null | grep -v "_backlog" | head -1)
+
+  if [ -n "$CURRENT_INCREMENT" ] && [ -f ".specweave/increments/$CURRENT_INCREMENT/tasks.md" ]; then
+    echo "[$(date)] 📝 Updating tasks.md for $CURRENT_INCREMENT" >> "$DEBUG_LOG" 2>/dev/null || true
+
+    # Run task updater (non-blocking, best-effort)
+    node dist/hooks/lib/update-tasks-md.js "$CURRENT_INCREMENT" 2>&1 | tee -a "$DEBUG_LOG" >/dev/null || {
+      echo "[$(date)] ⚠️  Failed to update tasks.md (non-blocking)" >> "$DEBUG_LOG" 2>/dev/null || true
+    }
+  else
+    echo "[$(date)] ℹ️  No current increment or tasks.md found, skipping tasks.md update" >> "$DEBUG_LOG" 2>/dev/null || true
+  fi
+else
+  echo "[$(date)] ⚠️  Node.js not found, skipping tasks.md update" >> "$DEBUG_LOG" 2>/dev/null || true
+fi
+
+# ============================================================================
+# SYNC LIVING DOCS (NEW in v0.6.1)
+# ============================================================================
+
+if command -v node &> /dev/null; then
+  if [ -n "$CURRENT_INCREMENT" ]; then
+    echo "[$(date)] 📚 Checking living docs sync for $CURRENT_INCREMENT" >> "$DEBUG_LOG" 2>/dev/null || true
+
+    # Run living docs sync (non-blocking, best-effort)
+    node dist/hooks/lib/sync-living-docs.js "$CURRENT_INCREMENT" 2>&1 | tee -a "$DEBUG_LOG" >/dev/null || {
+      echo "[$(date)] ⚠️  Failed to sync living docs (non-blocking)" >> "$DEBUG_LOG" 2>/dev/null || true
+    }
+  fi
+fi
+
+# ============================================================================
+# TRANSLATE LIVING DOCS (NEW in v0.6.0 - i18n)
+# ============================================================================
+
+if command -v node &> /dev/null; then
+  if [ -n "$CURRENT_INCREMENT" ]; then
+    echo "[$(date)] 🌐 Checking if living docs translation is needed for $CURRENT_INCREMENT" >> "$DEBUG_LOG" 2>/dev/null || true
+
+    # Run living docs translation (non-blocking, best-effort)
+    node dist/hooks/lib/translate-living-docs.js "$CURRENT_INCREMENT" 2>&1 | tee -a "$DEBUG_LOG" >/dev/null || {
+      echo "[$(date)] ⚠️  Failed to translate living docs (non-blocking)" >> "$DEBUG_LOG" 2>/dev/null || true
+    }
+  fi
+fi
+
+# ============================================================================
+# PLAY SOUND (only if session is truly ending)
+# ============================================================================
+
+play_sound() {
+  case "$(uname -s)" in
+    Darwin)
+      afplay /System/Library/Sounds/Glass.aiff 2>/dev/null || true
+      ;;
+    Linux)
+      paplay /usr/share/sounds/freedesktop/stereo/complete.oga 2>/dev/null || \
+      aplay /usr/share/sounds/alsa/Front_Center.wav 2>/dev/null || true
+      ;;
+    MINGW*|MSYS*|CYGWIN*)
+      powershell -c "(New-Object Media.SoundPlayer 'C:\Windows\Media\chimes.wav').PlaySync();" 2>/dev/null || true
+      ;;
+  esac
+}
+
+if [ "$SESSION_ENDING" = "true" ]; then
+  echo "[$(date)] 🔔 Playing completion sound" >> "$DEBUG_LOG" 2>/dev/null || true
+  play_sound
+fi
+
+# ============================================================================
+# LOGGING
+# ============================================================================
+
+echo "[$(date)] Status: All_completed=$ALL_COMPLETED, Session_ending=$SESSION_ENDING, Inactivity=${INACTIVITY_GAP}s" >> "$TASKS_LOG" 2>/dev/null || true
+echo "[$(date)] Reason: $DECISION_REASON" >> "$TASKS_LOG" 2>/dev/null || true
+echo "---" >> "$DEBUG_LOG" 2>/dev/null || true
+
+# ============================================================================
+# OUTPUT TO CLAUDE
+# ============================================================================
+
+if [ "$SESSION_ENDING" = "true" ]; then
+  cat <<EOF
+{
+  "continue": true,
+  "systemMessage": "🎉 ALL WORK COMPLETED! Session ending detected (${INACTIVITY_GAP}s inactivity). Remember to update documentation with inline edits to CLAUDE.md and README.md as needed."
+}
+EOF
+elif [ "$ALL_COMPLETED" = "true" ]; then
+  cat <<EOF
+{
+  "continue": true,
+  "systemMessage": "✅ Task batch completed (${INACTIVITY_GAP}s since last activity). Continuing work..."
+}
+EOF
+else
+  cat <<EOF
+{
+  "continue": true,
+  "systemMessage": "✅ Task completed. More tasks remaining - keep going!"
+}
+EOF
+fi

package/plugins/specweave-core/skills/SKILLS-INDEX.md

@@ -0,0 +1,229 @@
+# SpecWeave Skills Index
+
+**Purpose**: Quick reference for all available skills. Read this file BEFORE starting any task.
+
+**Last Updated**: 2025-11-03T04:18:05.042Z (auto-generated, do not edit manually)
+
+**Total Skills**: 12
+
+---
+
+## 🚀 Quick Start (Progressive Disclosure)
+
+**MANDATORY**: Skills are your expert manuals. Always check for relevant skills BEFORE starting implementation.
+
+### Progressive Disclosure Pattern
+
+1. **Scan this index** to find skills matching your task
+2. **Match activation keywords** to your current request
+3. **Load full SKILL.md** for matching skills
+4. **Follow the workflow** in SKILL.md precisely
+
+### Example Workflow
+
+```
+User asks: "Plan a new feature for user authentication"
+
+Step 1: Scan this index → Find "increment-planner" skill
+Step 2: Check keywords → Matches "feature planning", "create increment"
+Step 3: Load skill → cat .claude/skills/increment-planner/SKILL.md
+Step 4: Execute → Follow the increment planning workflow
+```
+
+---
+
+## 📚 All Available Skills
+
+
+### Framework Core
+
+#### context-loader
+
+**Description**: Explains how SpecWeave achieves context efficiency through Claude's native progressive disclosure mechanism and sub-agent parallelization. Skills load only when relevant, sub-agents isolate context. Activates when users ask about context loading, token usage, or how SpecWeave scales. Keywords: context loading, progressive disclosure, token efficiency, sub-agents, context management.
+
+**Location**: `.claude/skills/context-loader/SKILL.md`
+
+---
+
+#### context-optimizer
+
+**Description**: Second-pass context optimization that analyzes user prompts and removes irrelevant specs, agents, and skills from loaded context. Achieves 80%+ token reduction through smart cleanup. Activates for optimize context, reduce tokens, clean context, smart context, precision loading.
+
+**Location**: `.claude/skills/context-optimizer/SKILL.md`
+
+**Allowed tools**: Read, Grep, Glob
+
+---
+
+#### increment-planner
+
+**Description**: Creates comprehensive implementation plans for SpecWeave increments (aka features - both terms are interchangeable). This skill should be used when planning new increments/features, creating specifications, or organizing implementation work. Activates for: increment planning, feature planning, implementation plan, create increment, create feature, plan increment, plan feature, organize work, break down increment, break down feature, new product, build project, MVP, SaaS, app development, product description, tech stack planning, feature list.
+
+**Activates for**: increment planning, feature planning, implementation plan, create increment, create feature, plan increment, plan feature, organize work, break down increment, break down feature, new product, build project, MVP, SaaS, app development, product description, tech stack planning, feature list
+
+**Location**: `.claude/skills/increment-planner/SKILL.md`
+
+---
+
+#### increment-quality-judge
+
+**Description**: Optional AI-powered quality assessment for specifications, plans, and tests. Goes beyond rule-based validation to evaluate clarity, testability, edge cases, and architecture soundness. Activates for validate quality, quality check, assess spec, evaluate increment, spec review, quality score.
+
+**Location**: `.claude/skills/increment-quality-judge/SKILL.md`
+
+**Allowed tools**: Read, Grep, Glob
+
+---
+
+#### specweave-detector
+
+**Description**: Detects SpecWeave context (.specweave/ directory exists) and provides workflow documentation. v0.3.8+ features PROACTIVE auto-detection - when in SpecWeave folder, product descriptions automatically trigger increment planning. Explicit slash commands still work (/inc, /do, /progress, /validate, /done, /sync-docs, /sync-github). Keywords slash commands, /inc, /increment, /do, /progress, /validate, /done, specweave commands, smart workflow, auto-detection, specweave folder.
+
+**Location**: `.claude/skills/specweave-detector/SKILL.md`
+
+---
+
+#### specweave-framework
+
+**Description**: Expert knowledge of SpecWeave framework structure, rules, conventions, and increment lifecycle. Deep understanding of source-of-truth discipline, increment naming, hook system, and plugin architecture. Activates for: specweave rules, how does specweave work, framework structure, increment lifecycle, what is specweave, specweave conventions, specweave discipline, specweave architecture, where do files go, source of truth, increment naming, tasks.md format, spec.md structure, living docs sync, hook system, plugin architecture, how to use specweave, specweave best practices.
+
+**Activates for**: specweave rules, how does specweave work, framework structure, increment lifecycle, what is specweave, specweave conventions, specweave discipline, specweave architecture, where do files go, source of truth, increment naming, tasks
+
+**Location**: `.claude/skills/specweave-framework/SKILL.md`
+
+**Allowed tools**: Read, Grep, Glob
+
+---
+
+
+### Orchestration & Planning
+
+#### role-orchestrator
+
+**Description**: Multi-agent orchestration system that coordinates specialized agents (PM, Architect, DevOps, QA, Tech Lead, Security) to work together on complex tasks. Implements hierarchical orchestrator-worker pattern. Activates for complex multi-step requests requiring multiple roles/skills. Keywords: build product, create SaaS, full implementation, end-to-end, multi-agent, orchestrate, coordinate roles, complex project.
+
+**Location**: `.claude/skills/role-orchestrator/SKILL.md`
+
+---
+
+
+### Documentation
+
+#### brownfield-analyzer
+
+**Description**: Analyzes existing brownfield projects to map documentation structure to SpecWeave's PRD/HLD/RFC/Runbook pattern. Scans folders, classifies documents, detects external tools (Jira, ADO, GitHub), and generates migration plan. Activates for brownfield, existing project, migrate, analyze structure, legacy documentation.
+
+**Location**: `.claude/skills/brownfield-analyzer/SKILL.md`
+
+---
+
+#### translator
+
+**Description**: LLM-native translation skill for SpecWeave content. Activates when translation is needed for CLI messages, templates, documentation, or living docs. Uses the current LLM session for zero-cost translation. Keywords: translate, translation, language, multilingual, i18n, internationalization, Russian, Spanish, Chinese, German, French, localization, translate to.
+
+**Location**: `.claude/skills/translator/SKILL.md`
+
+**Allowed tools**: Read, Write, Edit, Grep, Glob
+
+---
+
+
+### Other
+
+#### brownfield-onboarder
+
+**Description**: Intelligently onboards brownfield projects by merging existing CLAUDE.md backups into SpecWeave structure. Extracts project-specific knowledge, domain context, team conventions, and technical details from backup CLAUDE.md files, then distributes content to appropriate SpecWeave folders without bloating CLAUDE.md. Activates for: merge docs, merge claude, onboard brownfield, import existing docs, claude backup, specweave merge-docs.
+
+**Activates for**: merge docs, merge claude, onboard brownfield, import existing docs, claude backup, specweave merge-docs
+
+**Location**: `.claude/skills/brownfield-onboarder/SKILL.md`
+
+---
+
+#### project-kickstarter
+
+**Description**: Proactively detects product/project descriptions and guides users through SpecWeave increment planning. Activates when user provides product name, features, tech stack, timeline, or problem description. Keywords: project, product, SaaS, app, MVP, build, new project, features, tech stack, core functionality, monetization, timeline, I want to build, let's build, quick build, core features.
+
+**Location**: `.claude/skills/project-kickstarter/SKILL.md`
+
+---
+
+#### tdd-workflow
+
+**Description**: Test-Driven Development workflow coordinator. Detects TDD intent and offers guided red-green-refactor cycle. Activates for TDD, test-driven, red-green-refactor, write tests first, test-first development, Kent Beck, TDD cycle.
+
+**Location**: `.claude/skills/tdd-workflow/SKILL.md`
+
+---
+
+
+## 💡 How Skills Work
+
+**Level 1 - Discovery (this file)**:
+- Scan activation keywords
+- Match to your current task
+- Identify 1-3 relevant skills
+
+**Level 2 - Deep Dive (SKILL.md)**:
+- Load full skill documentation
+- Read required prerequisites
+- Follow step-by-step workflow
+
+**Level 3 - Execution**:
+- Apply skill's instructions
+- Use recommended tools
+- Follow SpecWeave best practices
+
+---
+
+## 🎯 Task → Skill Matching Guide
+
+| Your Task | Relevant Skill | Keywords |
+|-----------|---------------|----------|
+| "Plan a new feature" | `increment-planner` | "feature planning", "create increment" |
+| "Sync to JIRA" | `jira-sync` | "JIRA sync", "create JIRA issue" |
+| "Create diagram" | `diagrams-architect` | "architecture diagram", "C4 diagram" |
+| "Build React UI" | `frontend` | "React", "components", "UI" |
+| "Deploy to cloud" | `hetzner-provisioner` | "deploy", "infrastructure" |
+| "Quality check" | `increment-quality-judge` | "quality check", "assess spec" |
+| "E2E testing" | `e2e-playwright` | "E2E test", "browser test" |
+| "Generate docs site" | `docusaurus` | "documentation site", "docs" |
+
+---
+
+## ⚡ Why Skills Matter
+
+**Without skills**:
+- ❌ Reinvent workflows every session
+- ❌ Inconsistent increment structure
+- ❌ Miss SpecWeave conventions
+- ❌ Waste tokens on irrelevant docs
+
+**With skills**:
+- ✅ Proven workflows ready to use
+- ✅ Consistent high-quality output
+- ✅ SpecWeave best practices enforced
+- ✅ Efficient token usage (load only what's needed)
+
+---
+
+## 🔧 For AI Tool Developers
+
+This index simulates Claude Code's native progressive disclosure:
+- Claude pre-loads skill metadata at startup (name + description)
+- Other tools read this index file for same benefit
+- Single file read replaces 12 individual file scans
+- Token savings: ~97% (1 file vs 12 files)
+
+**How to use in your AI tool**:
+1. Load this file at session start
+2. Parse activation keywords
+3. Match user requests to keywords
+4. Load full SKILL.md when matched
+5. Execute skill workflow
+
+---
+
+**Generated by**: `src/utils/generate-skills-index.ts`
+
+**Regenerate with**: `npm run generate-skills-index`

package/{src → plugins/specweave-core}/skills/brownfield-analyzer/SKILL.md

@@ -1,14 +1,16 @@
 ---
 name: brownfield-analyzer
-description: Analyzes existing brownfield projects to map documentation structure to SpecWeave's PRD/HLD/RFC/Runbook pattern. Scans folders, classifies documents, detects external tools (Jira, ADO, GitHub), and generates migration plan. Activates for brownfield, existing project, migrate, analyze structure, legacy documentation.
+description: Analyzes existing brownfield projects to map documentation structure to SpecWeave's PRD/HLD/RFC/Runbook pattern. Scans folders, classifies documents, detects external tools (Jira, ADO, GitHub), and creates project context map for just-in-time migration. Activates for brownfield, existing project, migrate, analyze structure, legacy documentation.
 ---
 
 # Brownfield Analyzer Skill
 
-**Purpose**: Analyze existing brownfield projects and generate a migration plan to SpecWeave's PRD/HLD/RFC/Runbook pattern.
+**Purpose**: Analyze existing brownfield projects and create project context map (awareness, not prescription) for just-in-time migration to SpecWeave.
 
 **When to Use**: When onboarding an existing project to SpecWeave.
 
+**Philosophy**: Document structure migration (one-time), feature migration (just-in-time per increment). NO big-bang planning of all features upfront.
+
 ---
 
 ## Capabilities
@@ -545,7 +547,9 @@ If you prefer full upfront documentation:
 
 ---
 
-## External Tool Integration
+## External Tool Integration (Awareness Only)
+
+**NOTE**: We detect external tools for AWARENESS, not for creating increments upfront.
 
 ### Jira
 - **URL**: https://company.atlassian.net
@@ -555,16 +559,37 @@ If you prefer full upfront documentation:
   - PROJ-124: Payment Processing
   - ... (list all)
 
-**Suggested Mapping**:
-- Epic PROJ-123 → Increment 0001-user-authentication
-- Epic PROJ-124 → Increment 0002-payment-processing
-- ... (one increment per epic)
+**Context Mapping** (saved to `.specweave/brownfield-context.json`):
+```json
+{
+  "jira": {
+    "url": "https://company.atlassian.net",
+    "project": "PROJ",
+    "epics": [
+      {
+        "id": "PROJ-123",
+        "title": "User Authentication",
+        "suggestedIncrementName": "0001-user-authentication",
+        "status": "In Progress"
+      },
+      {
+        "id": "PROJ-124",
+        "title": "Payment Processing",
+        "suggestedIncrementName": "0002-payment-processing",
+        "status": "To Do"
+      }
+    ]
+  }
+}
+```
+
+**When user creates increment**: Auto-detect if description matches an Epic, offer to link.
 
 ### Azure DevOps
-- (if detected)
+- (if detected, same awareness approach)
 
 ### GitHub
-- (if detected)
+- (if detected, same awareness approach)
 
 ---
 
@@ -587,16 +612,27 @@ If you prefer full upfront documentation:
 1. Convert {count} PNG/DrawIO diagrams to Mermaid
 2. Co-locate diagrams with markdown files
 
-### Phase 4: Increment Creation ({X} hours)
-1. Create {count} increments (one per Jira Epic)
-2. Create `metadata.yaml` for each increment
-3. Link increments to related docs (PRD, HLD, ADR, RFC)
-
-### Phase 5: External Tool Sync ({X} hours)
-1. Run sync command to link Epics → Increments (credentials auto-detected or prompted)
-2. Verify all Epics are mapped
-
-### Phase 6: Verification (30 minutes)
+### Phase 4: External Tool Context ({X} hours) 🔄 CHANGED
+**NOTE**: We DON'T create increments upfront. Instead, we create awareness.
+
+1. Create `.specweave/brownfield-context.json` with:
+   - Jira Epic inventory ({count} epics detected)
+   - ADO Feature inventory (if detected)
+   - GitHub Milestone inventory (if detected)
+   - Mapping suggestions (Epic ID → suggested increment name)
+2. Document external tool configuration for future sync
+3. When user creates increment via `/specweave:inc`:
+   - Auto-detect if it matches a known Epic
+   - Offer to link and sync
+   - Include Epic context in spec
+
+**Why not create increments now?**
+- ❌ User hasn't decided what to work on yet
+- ❌ Creating 50+ placeholder increments is overwhelming
+- ❌ Violates just-in-time philosophy
+- ✅ Just-in-time: Create increment when user chooses to work on it
+
+### Phase 5: Verification (30 minutes)
 1. Run `specweave verify`
 2. Review migration report
 3. Manual review of {count} documents flagged for attention
@@ -610,11 +646,12 @@ If you prefer full upfront documentation:
 | Structure Creation | 0.25 |
 | Document Migration | {X} |
 | Diagram Conversion | {Y} |
-| Increment Creation | {Z} |
-| External Tool Sync | {A} |
+| External Tool Context (awareness only) | 0.5 |
 | Verification | 0.5 |
 | **Total** | **{Total} hours** |
 
+**Note**: Increments are created just-in-time when user works on features, not upfront.
+
 ---
 
 ## Next Steps
@@ -626,18 +663,23 @@ If you prefer full upfront documentation:
    ```bash
    specweave migrate --plan analysis-report.md --execute
    ```
-5. **Enable sync** - Run sync commands for Jira/ADO integration
+5. **Create brownfield context** - Generate `.specweave/brownfield-context.json` with Epic/Feature inventory
+6. **Start working** - Create your first increment via `/specweave:inc "feature name"`
+   - SpecWeave will auto-detect if it matches a Jira Epic
+   - Offer to link and sync
+   - Include existing code analysis in spec
 
 ---
 
 ## Questions for User
 
 - [ ] Are document classifications correct?
-- [ ] Should we sync with Jira/ADO/GitHub?
-- [ ] Are Jira Epic → Increment mappings correct?
+- [ ] Should we track external tools (Jira/ADO/GitHub) for awareness?
 - [ ] Any documents to exclude from migration?
 - [ ] Proceed with migration?
 
+**Note**: We won't create increments for all Jira Epics upfront. Instead, when you create an increment, we'll offer to link it to a matching Epic if found.
+
 ---
 
 ## Appendix: Full File List

package/{src → plugins/specweave-core}/skills/context-loader/SKILL.md

@@ -232,7 +232,7 @@ SpecWeave's **role-orchestrator** skill automatically:
 **Example:**
 
 ```
-User: "/specweave.inc 'Full-stack SaaS with Stripe payments'"
+User: "/specweave:inc 'Full-stack SaaS with Stripe payments'"
     ↓
 role-orchestrator activates
     ↓