specweave 0.1.8 → 0.3.0

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

@@ -1,23 +1,29 @@
 ---
-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.
 
 ## Usage
 
 ```bash
-/build <increment-id>
+# Auto-resumes from last incomplete task
+/do <increment-id>
+
+# Or let it find active increment automatically
+/do
 ```
 
 ## Arguments
 
-- `<increment-id>`: Required. Increment ID (e.g., "001", "0001", "1", "0042")
+- `<increment-id>`: Optional. Increment ID (e.g., "001", "0001", "1", "0042")
+  - If omitted, finds the active in-progress increment automatically
+  - **Smart resume**: Automatically starts from next incomplete task
 
 ---
 
@@ -51,12 +57,45 @@ 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: Update Status to In-Progress
+### Step 2: Smart Resume - Find Next Incomplete Task
+
+**🎯 CRITICAL: Auto-resume functionality** - no need to remember which task you were on!
+
+1. **Parse tasks.md**:
+   - Scan all tasks in order
+   - Check completion status (`[x]` = complete, `[ ]` = incomplete)
+   - Find first incomplete task
+
+2. **Determine starting point**:
+   - If all tasks complete → Show completion message
+   - If tasks incomplete → Resume from first incomplete task
+   - If no tasks started → Start from T001
+
+3. **Show resume context**:
+   ```
+   📊 Resume Context:
+
+   Completed: 3/12 tasks (25%)
+   ├─ [✅] T001: Setup auth module (P1)
+   ├─ [✅] T002: Create user model (P1)
+   ├─ [✅] T003: Implement JWT tokens (P1)
+   └─ [⏳] T004: Add password hashing (P1) ← RESUMING HERE
+
+   Remaining: 9 tasks (estimated 2 weeks)
+   ```
+
+**Why smart resume?**
+- ✅ No manual tracking needed
+- ✅ Seamlessly continue after breaks
+- ✅ Prevents duplicate work
+- ✅ Shows progress at a glance
+
+### Step 3: Update Status to In-Progress (if needed)
 
-Update `spec.md` frontmatter:
+If status is "planned", update `spec.md` frontmatter:
 
 ```yaml
 ---
@@ -66,7 +105,9 @@ started: 2025-10-28      # ← Start date
 ---
 ```
 
-### Step 3: Execute Tasks Sequentially
+If already "in-progress", keep existing metadata.
+
+### Step 4: Execute Tasks Sequentially
 
 **For each task in tasks.md**:
 
@@ -88,13 +129,32 @@ started: 2025-10-28      # ← Start date
    - 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**:
 ```
@@ -107,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
@@ -115,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
@@ -227,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
@@ -237,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**:
@@ -305,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
@@ -319,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
@@ -342,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**:
@@ -382,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.
 ```
@@ -412,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
 
 ---
@@ -428,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.
 
 ---