specweave 0.4.1 → 0.6.3

package/plugins/specweave/skills/specweave-framework/SKILL.md

@@ -0,0 +1,498 @@
+---
+name: 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.
+allowed-tools: Read, Grep, Glob
+---
+
+# SpecWeave Framework Expert
+
+I am an expert on the SpecWeave framework - a spec-driven development framework for Claude Code (and other AI coding assistants). I have deep knowledge of its structure, rules, conventions, and best practices.
+
+## Core Philosophy
+
+SpecWeave follows **spec-driven development** with **increment-based workflows**:
+
+1. **Specification First** - Write WHAT and WHY before HOW
+2. **Incremental Delivery** - Ship small, complete features
+3. **Living Documentation** - Docs update automatically via hooks
+4. **Source of Truth Discipline** - Single source, zero duplication
+5. **Multi-Tool Support** - Works with Claude, Cursor, Copilot, and generic AI
+
+## Increment-Based Development
+
+### What is an Increment?
+
+An **increment** = a complete feature with:
+- `spec.md` - Product requirements (WHAT and WHY)
+- `plan.md` - Technical architecture (HOW to implement)
+- `tasks.md` - Task breakdown (WORK to do)
+- `tests.md` - Quality gates (TEST coverage)
+
+### Increment Naming Convention (v0.6.0+)
+
+**CRITICAL RULE**: All increments MUST use descriptive names, not just numbers!
+
+**Format**: `####-descriptive-kebab-case-name`
+
+**Examples**:
+- ✅ `0001-core-framework`
+- ✅ `0002-core-enhancements`
+- ✅ `0003-intelligent-model-selection`
+- ✅ `0004-plugin-architecture`
+- ✅ `0006-llm-native-i18n`
+- ❌ `0003` (too generic, rejected!)
+- ❌ `0004` (no description, rejected!)
+
+**Rationale**:
+- Clear intent at a glance
+- Easy to reference in conversation
+- Better git history
+- Searchable by feature name
+- Self-documenting increment folders
+
+### Increment Lifecycle
+
+```
+1. Plan    → /specweave:inc "feature-name"
+            ↓ PM agent creates spec.md, plan.md, tasks.md, tests.md
+
+2. Execute → /specweave:do
+            ↓ Selects next task, executes, marks complete
+
+3. Validate → /specweave:validate 0001
+            ↓ Checks spec compliance, test coverage
+
+4. Close   → /specweave:done 0001
+            ↓ Creates COMPLETION-SUMMARY.md, archives
+```
+
+### Increment Discipline (v0.6.0+)
+
+**THE IRON RULE**: Cannot start increment N+1 until increment N is DONE!
+
+**Enforcement**:
+- `/specweave:inc` **blocks** if previous increments incomplete
+- Use `/specweave:status` to check all increments
+- Use `/specweave:close` to close incomplete work
+- `--force` flag for emergencies (logged, should be rare)
+
+**What "DONE" Means**:
+1. All tasks in `tasks.md` marked `[x] Completed`, OR
+2. `COMPLETION-SUMMARY.md` exists with "✅ COMPLETE" status, OR
+3. Explicit closure via `/specweave:close`
+
+**Three Options for Closing**:
+1. **Adjust Scope** - Remove features from spec.md, regenerate tasks
+2. **Move Scope** - Transfer incomplete tasks to next increment
+3. **Extend Existing** - Update spec.md, add tasks, continue in same increment
+
+**Example**:
+```bash
+# Check status
+/specweave:status
+# Shows: 0002 (73% complete), 0003 (50% complete)
+
+# Try to start new increment
+/specweave:inc "0004-new-feature"
+# ❌ Blocked! "Close 0002 and 0003 first"
+
+# Close previous work
+/specweave:close
+# Interactive: Choose force-complete, move tasks, or reduce scope
+
+# Now can proceed
+/specweave:inc "0004-new-feature"
+# ✅ Works! Clean slate
+```
+
+## Directory Structure
+
+### Root-Level .specweave/ Folder (MANDATORY)
+
+**CRITICAL ARCHITECTURE RULE**: SpecWeave ONLY supports root-level `.specweave/` folders.
+
+**Correct Structure**:
+```
+my-project/
+├── .specweave/              ← ONE source of truth (root-level)
+│   ├── increments/
+│   │   ├── 0001-core-framework/
+│   │   │   ├── spec.md
+│   │   │   ├── plan.md
+│   │   │   ├── tasks.md
+│   │   │   ├── tests.md
+│   │   │   ├── logs/        ← Session logs
+│   │   │   ├── scripts/     ← Helper scripts
+│   │   │   └── reports/     ← Analysis files
+│   │   └── _backlog/
+│   ├── docs/
+│   │   ├── internal/        ← Strategic docs (NEVER published)
+│   │   │   ├── strategy/    ← Business strategy
+│   │   │   ├── architecture/ ← ADRs, RFCs, diagrams
+│   │   │   └── delivery/    ← Implementation notes
+│   │   └── public/          ← User-facing docs (can publish)
+│   └── logs/
+├── frontend/
+├── backend/
+└── infrastructure/
+```
+
+**WRONG** (nested .specweave/ folders - NOT SUPPORTED):
+```
+my-project/
+├── .specweave/              ← Root level
+├── backend/
+│   └── .specweave/          ← ❌ NESTED - PREVENTS THIS!
+└── frontend/
+    └── .specweave/          ← ❌ NESTED - PREVENTS THIS!
+```
+
+**Why Root-Level Only?**
+- ✅ Single source of truth
+- ✅ Cross-cutting features natural (frontend + backend + infra)
+- ✅ No duplication or fragmentation
+- ✅ Clear ownership
+- ✅ Simplified living docs sync
+
+**Multi-Repo Solution**:
+For huge projects with multiple repos, create a **parent folder**:
+```
+my-big-project/              ← Create parent folder
+├── .specweave/              ← ONE source of truth for ALL repos
+├── auth-service/            ← Separate git repo
+├── payment-service/         ← Separate git repo
+├── frontend/                ← Separate git repo
+└── infrastructure/          ← Separate git repo
+```
+
+## Source of Truth Discipline
+
+**CRITICAL PRINCIPLE**: SpecWeave has strict source-of-truth rules!
+
+### Three Directories, Three Purposes
+
+```
+src/                         ← SOURCE OF TRUTH (version controlled)
+├── skills/                  ← Source for skills
+├── agents/                  ← Source for agents
+├── commands/                ← Source for slash commands
+├── hooks/                   ← Source for hooks
+├── adapters/                ← Tool adapters (Claude/Cursor/Copilot/Generic)
+└── templates/               ← Templates for user projects
+
+.claude/                     ← INSTALLED (gitignored in user projects)
+├── skills/                  ← Installed from src/skills/
+├── agents/                  ← Installed from src/agents/
+├── commands/                ← Installed from src/commands/
+└── hooks/                   ← Installed from src/hooks/
+
+.specweave/                  ← FRAMEWORK DATA (always present)
+├── increments/              ← Feature development
+├── docs/                    ← Strategic documentation
+└── logs/                    ← Logs and execution history
+```
+
+### Golden Rules
+
+1. **✅ ALWAYS edit files in `src/`** (source of truth)
+2. **✅ Run install scripts to sync changes to `.claude/`**
+3. **❌ NEVER edit files in `.claude/` directly** (they get overwritten)
+4. **❌ NEVER create new files in project root** (use increment folders)
+
+**Example Workflow**:
+```bash
+# CORRECT: Edit source
+vim src/skills/increment-planner/SKILL.md
+
+# Sync to .claude/
+npm run install:skills
+
+# Test (skill activates from .claude/)
+/specweave:inc "test feature"
+
+# WRONG: Edit installed file
+vim .claude/skills/increment-planner/SKILL.md  # ❌ Gets overwritten!
+```
+
+### File Organization Rules
+
+**✅ ALLOWED in Root**:
+- `CLAUDE.md` (this file)
+- `README.md`, `CHANGELOG.md`, `LICENSE`
+- Standard config files (`package.json`, `tsconfig.json`, `.gitignore`)
+- Build artifacts (`dist/`, only if needed temporarily)
+
+**❌ NEVER Create in Root** (pollutes repository):
+All AI-generated files MUST go into increment folders:
+
+```
+❌ WRONG:
+/SESSION-SUMMARY-2025-10-28.md          # NO!
+/ADR-006-DEEP-ANALYSIS.md               # NO!
+/ANALYSIS-MULTI-TOOL-COMPARISON.md      # NO!
+
+✅ CORRECT:
+.specweave/increments/0002-core-enhancements/
+├── reports/
+│   ├── SESSION-SUMMARY-2025-10-28.md
+│   ├── ADR-006-DEEP-ANALYSIS.md
+│   └── ANALYSIS-MULTI-TOOL-COMPARISON.md
+├── logs/
+│   └── execution-2025-10-28.log
+└── scripts/
+    └── migration-helper.sh
+```
+
+**Why?**
+- ✅ Complete traceability (which increment created which files)
+- ✅ Easy cleanup (delete increment folder = delete all files)
+- ✅ Clear context (all files for a feature in one place)
+- ✅ No root clutter
+
+## Hook System
+
+### What are Hooks?
+
+Hooks are shell scripts that fire automatically on SpecWeave events:
+- `post-task-completion` - After EVERY task completion via TodoWrite
+- `pre-task-plugin-detect` - Before task execution (plugin detection)
+- `post-increment-plugin-detect` - After increment creation
+- `pre-implementation` - Before implementation starts
+
+### Current Hook: post-task-completion
+
+**Fires**: After EVERY TodoWrite call
+**Purpose**: Notify when work completes
+
+**What it does** (v2.0):
+- ✅ Detects session end (inactivity-based, 15s threshold)
+- ✅ Plays notification sound (macOS/Linux/Windows)
+- ✅ Shows completion message
+- ✅ Logs to `.specweave/logs/hooks-debug.log`
+- ✅ Debounces duplicate fires (2s window)
+
+**What it does NOT do yet** (planned for v0.6.1):
+- ⏳ Update `tasks.md` completion status
+- ⏳ Sync living docs automatically
+- ⏳ Consolidate GitHub/Jira tasks
+- ⏳ Calculate increment progress percentage
+
+**Smart Session-End Detection**:
+```
+Problem: Claude creates multiple todo lists → sound plays multiple times
+Solution: Track inactivity gaps between TodoWrite calls
+- Rapid completions (< 15s gap) = Claude still working → skip sound
+- Long gap (> 15s) + all done = Session ending → play sound!
+```
+
+### Hook Configuration
+
+**File**: `.specweave/config.json`
+
+```json
+{
+  "hooks": {
+    "post_task_completion": {
+      "enabled": true,
+      "update_tasks_md": false,       // TODO: v0.6.1
+      "sync_living_docs": false,      // TODO: v0.6.1
+      "play_sound": true,
+      "show_message": true
+    }
+  }
+}
+```
+
+### Manual Actions (Until v0.6.1)
+
+Until hooks are fully automated, **YOU MUST**:
+- Update `CLAUDE.md` when structure changes
+- Update `README.md` for user-facing changes
+- Update `CHANGELOG.md` for API changes
+- Update `tasks.md` completion status manually (or use TodoWrite carefully)
+
+## Plugin Architecture (v0.4.0+)
+
+### Core vs. Plugin
+
+**Core Framework** (always loaded):
+- 8 core skills (increment-planner, rfc-generator, context-loader, etc.)
+- 3 core agents (PM, Architect, Tech Lead)
+- 7 core commands (/specweave:inc, /specweave:do, etc.)
+
+**Plugins** (opt-in):
+- `specweave-github` - GitHub integration (issue sync, PR creation)
+- `specweave-jira` - Jira integration (task sync)
+- `specweave-kubernetes` - K8s deployment (planned)
+- `specweave-frontend-stack` - React/Vue/Angular (planned)
+- `specweave-ml-ops` - Machine learning (planned)
+
+### Context Reduction
+
+**Before plugins** (v0.3.7):
+- Simple React app: 50K tokens (ALL 44 skills + 20 agents loaded)
+- Backend API: 50K tokens
+- ML pipeline: 50K tokens
+
+**After plugins** (v0.4.0+):
+- Simple React app: Core + frontend-stack + github ≈ **16K tokens** (68% reduction!)
+- Backend API: Core + nodejs-backend + github ≈ **15K tokens** (70% reduction!)
+- ML pipeline: Core + ml-ops + github ≈ **18K tokens** (64% reduction!)
+
+### Four-Phase Plugin Detection
+
+1. **Init-Time** (during `specweave init`):
+   - Scans package.json, directories, env vars
+   - Suggests plugins: "Found React. Enable frontend-stack? (Y/n)"
+
+2. **First Increment** (during `/specweave:inc`):
+   - Analyzes increment description for keywords
+   - Suggests before creating spec: "This needs kubernetes plugin. Enable? (Y/n)"
+
+3. **Pre-Task** (before task execution):
+   - Hook scans task description
+   - Non-blocking suggestion: "This task mentions K8s. Consider enabling plugin."
+
+4. **Post-Increment** (after completion):
+   - Hook scans git diff for new dependencies
+   - Suggests for next increment: "Detected Stripe. Enable payment-processing plugin?"
+
+### Hybrid Plugin System (v0.4.1)
+
+SpecWeave plugins support **dual distribution**:
+
+1. **NPM Package** (SpecWeave CLI):
+   - `npm install -g specweave`
+   - `specweave plugin install github`
+   - Works with ALL tools (Claude, Cursor, Copilot, Generic)
+
+2. **Claude Code Marketplace** (Native `/plugin`):
+   - `/plugin marketplace add specweave/marketplace`
+   - `/plugin install github@specweave`
+   - Best UX for Claude Code users
+
+**Plugin Manifests** (both required):
+- `plugin.json` - Claude Code native format
+- `manifest.json` - SpecWeave custom format (richer metadata)
+
+## Multi-Tool Support
+
+SpecWeave works with multiple AI coding assistants:
+
+### Claude Code (⭐⭐⭐⭐⭐ 100%)
+- Native `.claude/` installation
+- Skills auto-activate
+- Hooks fire automatically
+- Slash commands work natively
+- Agents isolate context
+- **BEST EXPERIENCE**
+
+### Cursor 2.0 (⭐⭐⭐⭐ 85%)
+- `AGENTS.md` compilation
+- Team commands via dashboard
+- `@context` shortcuts
+- Shared agent context (8 parallel agents)
+- Manual hook triggers
+
+### GitHub Copilot (⭐⭐⭐ 60%)
+- `.github/copilot/instructions.md` compilation
+- Natural language instructions only
+- Manual workflows
+- No hooks or slash commands
+
+### Generic (⭐⭐ 40%)
+- `SPECWEAVE-MANUAL.md` for copy-paste
+- Manual workflows
+- No automation
+
+**Recommendation**: Use Claude Code for SpecWeave. Other tools work, but you'll miss the magic.
+
+## Key Commands
+
+### Increment Lifecycle
+- `/specweave:inc "feature-name"` - Plan new increment (PM-led process)
+- `/specweave:do` - Execute next task (smart resume)
+- `/specweave:progress` - Show progress, PM gate status, next action
+- `/specweave:validate 0001` - Validate spec, tests, quality
+- `/specweave:done 0001` - Close increment (PM validation)
+- `/specweave:next` - Auto-close if ready, suggest next work
+
+### Increment Discipline
+- `/specweave:status` - Show all increments and completion status
+- `/specweave:close` - Interactive closure of incomplete increments
+
+### Documentation Sync
+- `/specweave:sync-docs review` - Review strategic docs before implementation
+- `/specweave:sync-docs update` - Update living docs from completed increments
+
+### External Platform Sync
+- `/specweave:sync-github` - Bidirectional GitHub sync
+- `/specweave:sync-jira` - Bidirectional Jira sync
+
+## Common Questions
+
+### Q: Where do I create a new increment?
+**A**: Use `/specweave:inc "####-descriptive-name"`. It creates:
+```
+.specweave/increments/####-descriptive-name/
+├── spec.md
+├── plan.md
+├── tasks.md
+└── tests.md
+```
+
+### Q: Where do I put analysis files?
+**A**: In the increment's `reports/` folder:
+```
+.specweave/increments/0002-core-enhancements/reports/
+└── ANALYSIS-XYZ.md
+```
+
+### Q: How do I know what tasks are left?
+**A**: Use `/specweave:progress` or read `.specweave/increments/####/tasks.md`
+
+### Q: Can I start a new increment before finishing the current one?
+**A**: NO! (v0.6.0+) The framework **blocks** you. Use `/specweave:status` to check, `/specweave:close` to close.
+
+### Q: Where do I edit skills/agents/commands?
+**A**: Edit in `src/` (source of truth), then run `npm run install:all` to sync to `.claude/`
+
+### Q: How do I know if a plugin is needed?
+**A**: SpecWeave auto-detects! It will suggest plugins during init or increment creation.
+
+### Q: Why does the hook play a sound?
+**A**: Session-end detection! If all tasks complete AND you've been idle > 15s, it assumes you're done. Configurable in `.specweave/config.json`.
+
+### Q: How do I disable a hook?
+**A**: Edit `hooks/hooks.json` and set `"enabled": false` for that hook.
+
+## Activation Keywords
+
+I activate when you ask about:
+- SpecWeave rules / conventions / best practices
+- Increment naming / structure / lifecycle
+- Where files go / directory structure
+- Source of truth / what to edit
+- Hook system / automation
+- Plugin architecture / context reduction
+- How to use SpecWeave / getting started
+- What is spec.md / plan.md / tasks.md
+- Living docs sync
+- Increment discipline / closure
+- Multi-tool support (Claude/Cursor/Copilot)
+
+## When to Use Other Skills/Agents
+
+- **increment-planner** - Planning NEW increments (/specweave:inc)
+- **PM agent** - Leading increment creation (auto-invoked by /specweave:inc)
+- **Architect agent** - Designing system architecture
+- **Tech Lead agent** - Code review, best practices
+- **rfc-generator** - Creating detailed technical RFCs
+- **context-loader** - Explaining context efficiency
+- **diagrams-architect** - Creating C4/Mermaid diagrams
+
+I focus on **framework knowledge**. For **increment execution**, use the PM agent and commands!
+
+---
+
+Let me help you understand and use SpecWeave correctly! 🚀

package/plugins/specweave/skills/specweave-framework/test-cases/test-1-increment-naming.yaml

@@ -0,0 +1,11 @@
+name: Increment Naming Validation
+description: User asks about increment naming conventions - skill should explain the descriptive naming rule
+input: "What's the correct format for naming an increment in SpecWeave?"
+expected_output_contains:
+  - "####-descriptive-kebab-case-name"
+  - "0001-core-framework"
+  - "descriptive names"
+  - "not just numbers"
+expected_not_contains:
+  - "0001 is fine"
+  - "just use numbers"

package/plugins/specweave/skills/specweave-framework/test-cases/test-2-source-of-truth.yaml

@@ -0,0 +1,11 @@
+name: Source of Truth Discipline
+description: User asks where to edit files - skill should explain src/ vs .claude/ distinction
+input: "I need to update a skill. Should I edit the file in src/skills/ or .claude/skills/?"
+expected_output_contains:
+  - "src/"
+  - "source of truth"
+  - "NEVER edit .claude/"
+  - "npm run install"
+expected_not_contains:
+  - "either is fine"
+  - "edit .claude directly"

package/plugins/specweave/skills/specweave-framework/test-cases/test-3-increment-discipline.yaml

@@ -0,0 +1,12 @@
+name: Increment Discipline Rule
+description: User asks about starting multiple increments - skill should explain the Iron Rule
+input: "Can I start working on increment 0006 while 0002 and 0003 are still in progress?"
+expected_output_contains:
+  - "Iron Rule"
+  - "Cannot start N+1 until N is DONE"
+  - "/specweave.status"
+  - "/specweave.close-previous"
+  - "blocks"
+expected_not_contains:
+  - "yes, you can"
+  - "work on multiple increments"

package/plugins/specweave/skills/specweave-framework/test-cases/test-4-file-placement.yaml

@@ -0,0 +1,11 @@
+name: File Placement Rules
+description: User asks where to put analysis files - skill should explain increment folders
+input: "Where should I save my analysis document for increment 0002?"
+expected_output_contains:
+  - ".specweave/increments/0002"
+  - "reports/"
+  - "increment folders"
+  - "NEVER create in root"
+expected_not_contains:
+  - "save in project root"
+  - "anywhere is fine"

package/{src → plugins/specweave}/skills/tdd-workflow/SKILL.md

@@ -15,8 +15,8 @@ This skill acts as a **discovery hub** for Test-Driven Development (TDD) in Spec
 
 **NOT a full TDD implementation** - delegates to:
 - `tdd-orchestrator` agent (deep TDD expertise)
-- `/specweave.tdd-cycle` command (enforced red-green-refactor)
-- Individual phase commands (`/specweave.tdd-red`, `/specweave.tdd-green`, `/specweave.tdd-refactor`)
+- `/specweave:tdd:cycle` command (enforced red-green-refactor)
+- Individual phase commands (`/specweave:tdd:red`, `/specweave:tdd:green`, `/specweave:tdd:refactor`)
 
 ---
 
@@ -64,7 +64,7 @@ Would you like to:"
 ```typescript
 Question: "How would you like to implement TDD for this feature?"
 Options:
-  1. "Guided TDD Workflow (/specweave.tdd-cycle)"
+  1. "Guided TDD Workflow (/specweave:tdd:cycle)"
      Description: "Full red-green-refactor cycle with gates between phases.
                    Can't proceed to GREEN without RED test. Most rigorous."
 
@@ -81,12 +81,12 @@ Options:
 
 **Option 1: Guided TDD Workflow**
 ```bash
-Invoke: /specweave.tdd-cycle
+Invoke: /specweave:tdd:cycle
 
 This command orchestrates:
-1. /specweave.tdd-red    - Write failing test (blocks until red)
-2. /specweave.tdd-green  - Implement minimal code (blocks until green)
-3. /specweave.tdd-refactor - Refactor safely (tests must stay green)
+1. /specweave:tdd:red    - Write failing test (blocks until red)
+2. /specweave:tdd:green  - Implement minimal code (blocks until green)
+3. /specweave:tdd:refactor - Refactor safely (tests must stay green)
 
 Benefits:
 - Enforces discipline (gates prevent skipping phases)
@@ -162,7 +162,7 @@ I'll notify you at each phase transition."
 
 **In Increment Workflow**:
 ```
-/specweave.inc "Authentication feature" → spec.md created
+/specweave:inc "Authentication feature" → spec.md created
 ↓
 User: "Implement with TDD"
 ↓
@@ -170,7 +170,7 @@ tdd-workflow skill activates → offers options
 ↓
 User chooses: Guided TDD Workflow
 ↓
-/specweave.tdd-cycle invoked
+/specweave:tdd:cycle invoked
   ↓
   Phase 1: RED   - tests.md updated with failing tests
   Phase 2: GREEN - tasks.md implementation
@@ -193,16 +193,16 @@ tdd-workflow can coordinate test-first bug fixes
 ## Commands Reference
 
 ### Full Cycle
-- `/specweave.tdd-cycle` - Complete red-green-refactor orchestration
+- `/specweave:tdd:cycle` - Complete red-green-refactor orchestration
 
 ### Individual Phases
-- `/specweave.tdd-red` - RED phase only (write failing test)
-- `/specweave.tdd-green` - GREEN phase only (make test pass)
-- `/specweave.tdd-refactor` - REFACTOR phase only (improve code)
+- `/specweave:tdd:red` - RED phase only (write failing test)
+- `/specweave:tdd:green` - GREEN phase only (make test pass)
+- `/specweave:tdd:refactor` - REFACTOR phase only (improve code)
 
 ### When to Use Each
 
-**Use /specweave.tdd-cycle when**:
+**Use /specweave:tdd:cycle when**:
 - ✅ Starting new feature from scratch
 - ✅ Learning TDD or teaching team
 - ✅ Want enforced discipline (gates)
@@ -242,7 +242,7 @@ Great! TDD (Test-Driven Development) follows red-green-refactor:
 
 **tdd-workflow**:
 ```
-Perfect! I'm invoking /specweave.tdd-cycle to orchestrate your TDD workflow.
+Perfect! I'm invoking /specweave:tdd:cycle to orchestrate your TDD workflow.
 
 🔴 Starting RED phase...
 Write a failing test for user registration. Let me create the test skeleton:
@@ -252,7 +252,7 @@ Write a failing test for user registration. Let me create the test skeleton:
 ✅ Test written and failing. Run: npm test
 ❌ Expected failure confirmed.
 
-Ready to proceed to GREEN phase? (type 'yes' or run /specweave.tdd-green)
+Ready to proceed to GREEN phase? (type 'yes' or run /specweave:tdd:green)
 ```
 
 ---
@@ -292,7 +292,7 @@ Invoking tdd-orchestrator agent for advanced refactoring support...
 Great! Tests are passing. Time for REFACTOR phase.
 
 You can:
-1. Run /specweave.tdd-refactor (guided refactoring)
+1. Run /specweave:tdd:refactor (guided refactoring)
 2. Refactor manually (I'll verify tests stay green)
 
 Which would you prefer?
@@ -309,7 +309,7 @@ Perfect! I'll monitor your refactoring:
 ✅ Tests still passing after refactor
 ✅ TDD cycle maintained
 
-Ready for next feature? Run /specweave.tdd-cycle or continue manually.
+Ready for next feature? Run /specweave:tdd:cycle or continue manually.
 ```
 
 ---
@@ -352,8 +352,8 @@ tdd:
 - `qa-lead` - Test strategy overlaps with TDD principles
 
 **Commands**:
-- `/specweave.tdd-cycle` - Full red-green-refactor orchestration
-- `/specweave.tdd-red`, `/specweave.tdd-green`, `/specweave.tdd-refactor` - Individual phases
+- `/specweave:tdd:cycle` - Full red-green-refactor orchestration
+- `/specweave:tdd:red`, `/specweave:tdd:green`, `/specweave:tdd:refactor` - Individual phases
 
 ---
 
@@ -369,7 +369,7 @@ tdd:
 
 **Not a replacement for**:
 - `tdd-orchestrator` agent (deep expertise)
-- `/specweave.tdd-*` commands (workflow enforcement)
+- `/specweave:tdd-*` commands (workflow enforcement)
 
 **Instead, it's the entry point** that helps users choose the right TDD tool for their context.