specweave 0.1.9 → 0.3.0

package/src/commands/{build.md → specweave.do.md}

@@ -1,11 +1,11 @@
 ---
-name: build
+name: specweave.do
 description: Execute increment implementation following spec and plan - hooks run after EVERY task
 ---
 
-# Build Increment
+# Do Increment
 
-**Implementation Execution**: Following spec.md and plan.md to build the increment.
+**Implementation Execution**: Following spec.md and plan.md to execute the increment work.
 
 You are helping the user implement a SpecWeave increment by executing tasks from tasks.md with automatic documentation updates after EVERY task completion.
 
@@ -13,10 +13,10 @@ You are helping the user implement a SpecWeave increment by executing tasks from
 
 ```bash
 # Auto-resumes from last incomplete task
-/build <increment-id>
+/do <increment-id>
 
 # Or let it find active increment automatically
-/build
+/do
 ```
 
 ## Arguments
@@ -57,7 +57,7 @@ You are helping the user implement a SpecWeave increment by executing tasks from
    • tasks.md (42 tasks, estimated 3-4 weeks)
    • tests.md (12 test cases, 85% coverage)
 
-🎯 Ready to build!
+🎯 Ready to execute!
 ```
 
 ### Step 2: Smart Resume - Find Next Incomplete Task
@@ -129,13 +129,32 @@ If already "in-progress", keep existing metadata.
    - Add completion timestamp
    - Note any deviations from plan
 
-4. **🔥 CRITICAL: Run hooks after EVERY task**:
-   - Hook: `post-task-completion`
-   - Actions:
-     - Update documentation (CLAUDE.md, README.md)
-     - Update CHANGELOG.md if needed
-     - Verify docs reflect new code
-     - Check for doc/code drift
+4. **🔥 CRITICAL: After EVERY task completion**:
+
+   **Step A: Hook executes automatically (via .claude/hooks.json)**:
+   - 🔊 Plays completion sound (Glass.aiff on macOS)
+   - 📝 Shows reminder message
+   - ✅ This happens automatically when you mark task complete
+
+   **Step B: Update project documentation inline**:
+   - Update CLAUDE.md if task added:
+     - New commands or CLI flags
+     - New file structure
+     - New configuration options
+     - New skills or agents
+   - Update README.md if task added:
+     - User-facing features
+     - Installation steps
+     - Usage examples
+     - API changes
+   - Update CHANGELOG.md if task added:
+     - Public API changes
+     - Breaking changes
+     - New features
+
+   **Step C: Continue to next task**:
+   - Do NOT call `/sync-docs` yet (wait until all tasks complete)
+   - Move to next incomplete task
 
 **Example task execution**:
 ```
@@ -148,7 +167,7 @@ TASK T001: Create User model (PostgreSQL)
    • Description: Create User model with Prisma
    • Acceptance: Model has id, email, passwordHash, createdAt fields
 
-🔨 Implementing...
+🔨 Executing...
    ✓ Created src/models/User.ts
    ✓ Added Prisma schema definition
    ✓ Generated migration file
@@ -156,14 +175,19 @@ TASK T001: Create User model (PostgreSQL)
 
 ✅ Task T001 completed
 
-🪝 Running post-task hooks...
-   ✓ Updated CLAUDE.md (added User model to schema)
-   ✓ Updated README.md (added database section)
-   ✓ Verified documentation consistency
+🔊 [Glass.aiff plays automatically via hook]
+🔔 Task completed! Remember to update documentation...
+
+📝 Updating project documentation:
+   ✓ Updated CLAUDE.md (added User model to schema reference)
+   ✓ Updated README.md (added database section with example)
+   ✓ No CHANGELOG.md update needed (internal model)
 
 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 
 Progress: 1/42 tasks (2%) | Estimated remaining: 3.9 weeks
+
+Moving to next task...
 ```
 
 ### Step 4: Handle Blockers
@@ -268,6 +292,29 @@ Up next:
 ✅ Tasks: 42/42 (100%)
 ⏱️  Time taken: 3.2 weeks (vs estimated 3-4 weeks)
 
+🔊 [Playing celebration sound...]
+
+📝 Now syncing implementation learnings to living docs...
+```
+
+**CRITICAL: Now run `/sync-docs update` to sync to living docs**:
+
+```bash
+/sync-docs update
+```
+
+This will:
+- Update ADRs with implementation details (Proposed → Accepted)
+- Update API documentation with actual endpoints
+- Update architecture diagrams with actual system
+- Update feature lists with completed features
+- May prompt for conflict resolution if needed
+
+**After `/sync-docs update` completes**:
+
+```
+✅ Living documentation synchronized!
+
 Next steps:
 1. Run full test suite: npm test
 2. Validate increment: /validate 0001 --quality
@@ -278,66 +325,77 @@ Next steps:
 
 ## Hook Integration (CRITICAL!)
 
-**Post-Task Completion Hook** runs after EVERY task:
+**Post-Task Completion Hook** runs after EVERY task via `.claude/hooks.json`:
 
 ### Configuration
 
-**File**: `.specweave/config.yaml`
+**File**: `.claude/hooks.json`
 
-```yaml
-hooks:
-  enabled: true
-  post_task_completion:
-    enabled: true        # ← MUST be true
-    actions:
-      - update_documentation    # Update CLAUDE.md, README.md
-      - update_changelog        # Update CHANGELOG.md if public API changes
-      - verify_consistency      # Check docs match code
+```json
+{
+  "hooks": {
+    "PostToolUse": [
+      {
+        "matcher": "TodoWrite",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "bash .claude/hooks/post-task-completion.sh"
+          }
+        ]
+      }
+    ]
+  }
+}
+```
+
+**Hook Script**: `.claude/hooks/post-task-completion.sh`
+
+```bash
+#!/bin/bash
+# Plays completion sound and outputs reminder JSON
+# Output: {"continue": true, "systemMessage": "Task completed! Update docs..."}
 ```
 
 ### Hook Behavior
 
-**After EVERY task completion**:
+**After EVERY task completion (via TodoWrite)**:
 
-1. **Scan changed files**:
-   - Detect new functions, classes, APIs
-   - Detect changed behavior
-   - Detect new configuration
+1. **Play sound synchronously**:
+   - macOS: Glass.aiff via `afplay`
+   - Linux: complete.oga via `paplay`
+   - Windows: chimes.wav via PowerShell
+   - Sound plays BEFORE Claude continues
 
-2. **Update documentation**:
-   - CLAUDE.md: Add to quick reference tables
-   - README.md: Update examples if needed
-   - API docs: Regenerate if API changed
+2. **Show reminder**:
+   - JSON systemMessage displayed to user
+   - Reminds to update CLAUDE.md, README.md inline
 
-3. **Verify consistency**:
-   - Check docs mention new features
-   - Check no stale references
-   - Check examples still work
+3. **Log completion**:
+   - Appends to `.specweave/logs/tasks.log`
 
-4. **Report**:
-```
-🪝 Post-task documentation update:
+### Documentation Updates (Manual)
 
-Files updated:
-  • CLAUDE.md (+3 lines: Added User model to schema reference)
-  • README.md (+12 lines: Added authentication example)
+After each task, Claude should manually update:
 
-Consistency checks:
-  ✓ All code references up to date
-  ✓ Examples tested and working
-  ✓ No stale documentation
+- **CLAUDE.md**: New commands, file structure, config options, skills, agents
+- **README.md**: User-facing features, installation, usage, API changes
+- **CHANGELOG.md**: Public API changes, breaking changes, new features
 
-Documentation drift: 0% (perfect sync)
-```
+**Living docs sync** (via `/sync-docs update`):
+- Only after ALL tasks complete
+- Updates `.specweave/docs/` with implementation learnings
+- Updates ADRs from Proposed → Accepted
+- Updates architecture diagrams with actual system
 
 ---
 
 ## Examples
 
-### Example 1: Build Complete Increment
+### Example 1: Execute Complete Increment
 
 ```bash
-/build 0001
+/do 0001
 ```
 
 **Output**:
@@ -346,7 +404,7 @@ Documentation drift: 0% (perfect sync)
 
 ✅ Context loaded (spec.md, plan.md, tasks.md, tests.md)
 
-🔨 Starting implementation (42 tasks)...
+🔨 Starting execution (42 tasks)...
 
 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 Task T001: Create User model
@@ -360,17 +418,17 @@ Task T001: Create User model
 Next: /validate 0001 --quality
 ```
 
-### Example 2: Build with Blocker
+### Example 2: Execute with Blocker
 
 ```bash
-/build 0002
+/do 0002
 ```
 
 **Output**:
 ```
 📂 Loading increment 0002-payment-processing...
 
-🔨 Implementing tasks...
+🔨 Executing tasks...
 
 Task T005: Integrate Stripe payment
 ⚠️ Blocker: Stripe API key not in .env
@@ -383,10 +441,10 @@ Options:
 Your choice? [A/B/C]: _
 ```
 
-### Example 3: Build with Test Failure
+### Example 3: Execute with Test Failure
 
 ```bash
-/build 0003
+/do 0003
 ```
 
 **Output**:
@@ -423,14 +481,14 @@ Available increments:
   • 0002-core-enhancements (planned)
   • 0003-payment-processing (in-progress)
 
-Usage: /build <increment-id>
+Usage: /do <increment-id>
 ```
 
 ### Increment Not Planned
 ```
-❌ Error: Cannot build increment 0001 (status: backlog)
+❌ Error: Cannot execute increment 0001 (status: backlog)
 
-Increment must be "planned" before building.
+Increment must be "planned" before execution.
 
 Run: /increment "User authentication" to plan this increment first.
 ```
@@ -453,8 +511,8 @@ Options:
 ## Related Commands
 
 - `/increment`: Plan increment (creates spec.md, plan.md, tasks.md)
-- `/validate`: Validate quality before building
-- `/done`: Close increment (PM validates completion)
+- `/validate`: Validate quality before executing
+- `/specweave done`: Close increment (PM validates completion)
 - `/list-increments`: List all increments with status
 
 ---
@@ -469,6 +527,20 @@ Options:
 
 ---
 
-**Important**: This command is designed for continuous execution. It's normal to run `/build` and let it execute multiple tasks sequentially with documentation updates after each one.
+## Why "/do" instead of "/do"?
+
+**Universal applicability**: SpecWeave isn't just for software engineering!
+
+- Software projects: Writing code, tests, documentation
+- Writing projects: Chapters, articles, research papers
+- Design projects: Mockups, prototypes, design systems
+- Business projects: Reports, analyses, presentations
+- Creative projects: Scripts, storyboards, content
+
+"/do" works for any domain - it's about **executing the planned work**, whatever that work may be.
+
+---
+
+**Important**: This command is designed for continuous execution. It's normal to run `/do` and let it execute multiple tasks sequentially with documentation updates after each one.
 
-**Best Practice**: Always run `/validate 0001 --quality` after building to ensure quality before closing with `/done`.
+**Best Practice**: Always run `/validate 0001 --quality` after execution to ensure quality before closing with `/done`.

package/src/commands/{done.md → specweave.done.md}

@@ -1,5 +1,5 @@
 ---
-name: done
+name: specweave.done
 description: Close increment with PM validation - checks tasks, tests, and docs before closing
 ---
 
@@ -501,7 +501,7 @@ Usage: /done <increment-id>
 
 Increment must be "in-progress" before closing.
 
-Run: /build 0001 to start implementation first.
+Run: /do 0001 to start implementation first.
 ```
 
 ### Major Blockers Found
@@ -531,7 +531,7 @@ Check progress: /list-increments
 ## Related Commands
 
 - `/increment`: Plan new increment
-- `/build`: Execute implementation
+- `/do`: Execute implementation
 - `/validate`: Validate quality before closing
 - `/list-increments`: List all increments with status
 

package/src/commands/{inc.md → specweave.inc.md}

@@ -1,5 +1,5 @@
 ---
-name: inc
+name: specweave.inc
 description: Shorthand for /increment - Plan new Product Increment (PM-led process)
 ---
 
@@ -53,7 +53,7 @@ Runs the full `/increment` command, which:
    - QA defines test strategy
    - DevOps plans infrastructure
 4. **User review checkpoint**
-5. **Ready to build**: `/build 0001`
+5. **Ready to build**: `/do 0001`
 
 ---
 
@@ -67,7 +67,7 @@ Runs the full `/increment` command, which:
 #    spec.md, plan.md, tasks.md, tests.md
 
 # 3. Build it
-/build 0001
+/do 0001
 
 # 4. Validate quality (optional)
 /validate 0001 --quality
@@ -78,7 +78,7 @@ Runs the full `/increment` command, which:
 
 ---
 
-**💡 Pro Tip**: `/inc` is the ONLY aliased command. Use full names for others (`/build`, `/validate`, `/done`) to keep the workflow clear and explicit.
+**💡 Pro Tip**: `/inc` is the ONLY aliased command. Use full names for others (`/specweave do`, `/specweave validate`, `/specweave done`) to keep the workflow clear and explicit.
 
 ---
 

package/src/commands/{increment.md → specweave.increment.md}

@@ -1,5 +1,5 @@
 ---
-name: increment
+name: specweave.increment
 description: Plan new Product Increment - PM-led process (market research, spec, plan, auto-generate tasks). Auto-closes previous increment if PM gates pass.
 ---
 
@@ -74,7 +74,7 @@ You are helping the user create a new SpecWeave increment with automatic closure
 
    Options:
    A. Complete 0001 first (recommended)
-      → Run `/build 0001` to finish remaining tasks
+      → Run `/do 0001` to finish remaining tasks
 
    B. Force close 0001 and defer tasks to 0002
       → Transfer T006, T007 to new increment
@@ -99,7 +99,7 @@ You are helping the user create a new SpecWeave increment with automatic closure
 - Next increment: 003
 
 ### Step 2: Detect tech stack (CRITICAL - framework-agnostic)
-   - Check `.specweave/config.yaml` for tech_stack configuration
+   - Settings auto-detected
    - If not found, detect from project files:
      - `package.json` → TypeScript/JavaScript
      - `requirements.txt` or `pyproject.toml` → Python
@@ -117,72 +117,109 @@ You are helping the user create a new SpecWeave increment with automatic closure
 - "What's the short name?" (e.g., "user-authentication" for increment 003-user-authentication)
 - "Priority? (P1/P2/P3)" (default: P1)
 
-### Step 4: Activate role-orchestrator
-
-- Analyze user's description
-- Determine which strategic agents are needed:
-  - pm-agent (product strategy)?
-  - architect-agent (system design)?
-  - devops-agent (infrastructure)?
-  - security-agent (security review)?
-  - qa-lead-agent (testing strategy)?
-
-### Step 5: Ask clarifying questions (if needed)
-
-- Target users/scale?
-- Technology preferences? (if not detected)
-- Budget constraints?
-- Deployment platform?
-- Payment processing needed?
-- Authentication method?
-
-### Step 6: Run strategic agents (with user approval)
-
-- **Pass detected tech stack to ALL agents** (CRITICAL!)
-- PM agent creates pm-analysis.md
-- Architect agent creates architecture.md, ADRs (using detected tech stack)
-- DevOps agent creates infrastructure.md (platform-specific)
-- Security agent creates security.md (framework-specific security)
-- QA agent creates test-strategy.md (framework-specific tests)
-
-### Step 7: Present strategic docs for review
-
-- Show summary of all strategic outputs
-- Ask: "Review docs with /review-docs or approve to continue?"
-- Wait for user approval
-
-### Step 8: Create spec.md (based on strategic docs)
-   - Frontmatter with increment number, title, priority, status, dependencies
-   - **Include detected tech stack in frontmatter** (see format below)
-   - Overview section
-   - Business value
-   - User stories with acceptance tests
-   - Functional requirements
-   - Out of scope
-   - Success criteria
-   - Dependencies
-
-### Step 9: Create tasks.md (task-builder skill)
-
-**🎯 CRITICAL: Auto-generate tasks from plan.md**
-
-- Analyze all strategic docs
-- Break down into phases (framework-specific)
-- Create tasks with:
-  - Agent references (use framework-specific agents if available)
-  - File paths (framework-specific paths: src/ for TS, app/ for Django, etc.)
-  - Implementation snippets (framework-specific code)
-  - Acceptance criteria
-  - Documentation updates
-
-### Step 10: Save increment
-
-- Create `.specweave/increments/####-name/`
-- Save spec.md
-- Save tasks.md (auto-generated!)
-- Save strategic docs (pm-analysis.md, architecture.md, etc.)
-
-### Step 11: Output to user
+### Step 4: Activate Increment Planning Workflow
+
+**🚨 CRITICAL - YOU MUST USE THE SKILL TOOL:**
+
+**DO NOT** manually create files. **DO NOT** skip this step. **DO NOT** write spec.md or plan.md directly.
+
+You MUST invoke the increment-planner skill to orchestrate the full PM-led workflow:
+
+```
+Use the Skill tool:
+command: "increment-planner"
+```
+
+The increment-planner skill will:
+1. Invoke PM agent (via Task tool with subagent_type="pm")
+2. Invoke Architect agent (via Task tool with subagent_type="architect")
+3. Invoke other strategic agents as needed
+4. Create living documentation in .specweave/docs/internal/
+5. Create increment files that reference living docs
+6. Auto-generate tasks.md using task-builder skill
+7. Create context-manifest.yaml
+8. Apply validation hooks
+9. Trigger post-increment hooks (doc sync)
+
+**WHY THIS IS MANDATORY:**
+- ✅ Living docs get created (source of truth)
+- ✅ Agents collaborate properly (PM → Architect flow)
+- ✅ Tasks auto-generated from plan
+- ✅ Hooks run (validation, doc sync)
+- ✅ Quality gates enforced
+- ❌ Direct file writing bypasses entire workflow
+
+### Step 5: Skill Tool Invocation (MANDATORY)
+
+**BEFORE PROCEEDING, USE THE SKILL TOOL:**
+
+You must literally call the Skill tool like this:
+```
+Skill(command: "increment-planner")
+```
+
+Wait for the skill to complete. Do NOT continue to Step 6 until the increment-planner skill returns.
+
+### Step 6: Alternative Approach (ONLY IF SKILL FAILS)
+
+**Only use this if Skill tool is unavailable or fails:**
+
+Manually invoke agents using Task tool:
+
+1. **Invoke PM Agent:**
+   ```
+   Task(
+     subagent_type: "pm",
+     prompt: "Create product strategy for: [user description]
+             Detect tech stack from: [detected tech info]
+             Create living docs in .specweave/docs/internal/strategy/
+             Create increment spec.md that references strategy docs",
+     description: "PM product strategy"
+   )
+   ```
+
+2. **Invoke Architect Agent:**
+   ```
+   Task(
+     subagent_type: "architect",
+     prompt: "Read PM's strategy docs from .specweave/docs/internal/strategy/
+             Create technical architecture for: [user description]
+             Tech stack: [detected tech stack]
+             Create living docs in .specweave/docs/internal/architecture/
+             Create ADRs for all technical decisions
+             Create increment plan.md that references architecture docs",
+     description: "Architect technical design"
+   )
+   ```
+
+3. **Auto-generate tasks.md:**
+   ```
+   Skill(command: "task-builder")
+   ```
+
+**Pass detected tech stack to ALL agents** (CRITICAL!)
+
+### Step 7: Verify Increment Creation
+
+After the increment-planner skill completes, verify:
+
+1. **Living docs created:**
+   - `.specweave/docs/internal/strategy/{module}/` exists
+   - `.specweave/docs/internal/architecture/adr/` has ADRs
+
+2. **Increment files created:**
+   - `.specweave/increments/####-name/spec.md` (references strategy docs)
+   - `.specweave/increments/####-name/plan.md` (references architecture docs)
+   - `.specweave/increments/####-name/tasks.md` (auto-generated from plan)
+   - `.specweave/increments/####-name/tests.md` (test strategy)
+   - `.specweave/increments/####-name/context-manifest.yaml`
+
+3. **Hooks executed:**
+   - Validation hooks ran
+   - Post-increment hooks ran
+   - Living documentation synced
+
+### Step 8: Output to user
     ```
     ✅ Created increment 0003-user-authentication
 
@@ -204,16 +241,46 @@ You are helping the user create a new SpecWeave increment with automatic closure
        - test-strategy.md (E2E tests for {framework})
 
        ⏱️  Estimated effort: 3-4 weeks
+    ```
+
+### Step 9: Sync Strategic Docs to Living Docs
+
+**🔥 CRITICAL: After increment planning, sync to living docs**
+
+```
+🔊 [Playing celebration sound...]
+
+📝 Now syncing strategic documentation to living docs...
+```
+
+**Run `/sync-docs update` to create initial documentation**:
+
+```bash
+/sync-docs update
+```
+
+This will:
+- Create ADRs from architectural decisions in plan.md (status: Proposed)
+- Add new features to `.specweave/docs/public/overview/features.md`
+- Add architecture diagrams to `.specweave/docs/internal/architecture/diagrams/`
+- Update infrastructure docs in `.specweave/docs/internal/operations/`
+- Update security docs in `.specweave/docs/internal/security/`
+- May prompt for conflict resolution if needed
+
+**After `/sync-docs update` completes**:
+
+```
+✅ Strategic documentation synchronized!
 
-       Next steps:
-       1. Review docs: /review-docs
-       2. Start implementation: Begin with Task T001 in tasks.md
-       3. Sync to GitHub: /sync-github
+Next steps:
+1. Review the increment plan and strategic docs
+2. Start implementation: /do 0003
+3. (Optional) Sync to GitHub: /sync-github
     ```
 
 ## Frontmatter Format (spec.md):
 
-**IMPORTANT**: Tech stack is DETECTED from `.specweave/config.yaml` or project files, NOT hardcoded!
+**IMPORTANT**: Tech stack is AUTO-DETECTED from project files (package.json, requirements.txt, etc.), NOT hardcoded!
 
 ```yaml
 ---
@@ -227,7 +294,7 @@ structure: user-stories
 
 # Tech stack is DETECTED, not hardcoded
 tech_stack:
-  detected_from: ".specweave/config.yaml"  # or "package.json", "requirements.txt", etc.
+  detected_from: "package.json"  # or "requirements.txt", "go.mod", etc.
   language: "{detected-language}"          # e.g., "typescript", "python", "go", "java", "rust"
   framework: "{detected-framework}"        # e.g., "nextjs", "django", "fastapi", "spring-boot", "gin"
   database: "{specified-database}"         # e.g., "postgresql", "mysql", "mongodb", "sqlite"
@@ -307,7 +374,7 @@ If user says "autonomous mode" or "full automation":
 
 ## Error Handling:
 
-- If `.specweave/` not found: "Error: Not a SpecWeave project. Run /create-project first."
+- If `.specweave/` not found: "Error: Not a SpecWeave project. Run specweave init first."
 - If user description too vague: Ask more clarifying questions
 - If strategic agents not available: "Warning: Some agents missing. Continue with basic spec?"