specweave 0.3.7 → 0.3.8

package/CLAUDE.md

@@ -1,7 +1,7 @@
 # SpecWeave - Development Guide
 
 **Project**: SpecWeave - Spec-Driven Development Framework
-**Version**: 0.2.0
+**Version**: 0.3.7 (Windows fix + Competitive advantages documented)
 **Type**: Open Source NPM Package (TypeScript CLI)
 **Repository**: https://github.com/anton-abyzov/specweave
 **Website**: https://spec-weave.com
@@ -13,9 +13,10 @@ Users receive a different CLAUDE.md via the template system.
 
 ## Quick Start for Contributors
 
-**Current Work**: Increment 0002 - Core Framework Enhancements (73% complete)
+**Current Work**: Increment 0002 - Core Framework Enhancements (complete - testing phase)
 **Active Branch**: `develop` → merges to `features/001-core-feature`
-**Current Focus**: Diagram agents, command refactoring, context loading improvements
+**Latest**: v0.3.7 - Fixed Windows installation (defaults to claude instead of generic)
+**Next**: v0.4.0 - Hook debouncing, improved detection, GitHub release automation
 
 **Typical Workflow**:
 ```bash

package/README.md

@@ -3,7 +3,7 @@
 > **Spec-Driven Development Framework** - Where specifications and documentation are the source of truth
 
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
-[![Version](https://img.shields.io/badge/version-0.2.0-blue.svg)](https://github.com/anton-abyzov/specweave/releases/tag/v0.2.0)
+[![Version](https://img.shields.io/badge/version-0.3.7-blue.svg)](https://github.com/anton-abyzov/specweave/releases/tag/v0.3.7)
 [![Status](https://img.shields.io/badge/status-beta-blue.svg)]()
 [![Website](https://img.shields.io/badge/website-spec--weave.com-green.svg)](https://spec-weave.com)
 
@@ -31,9 +31,9 @@
 - 🤖 **Autonomous & Smart** - Just works! Agents ask clarifying questions, review output, validate quality—minimal interaction required
 - ⚡ **Seamless Workflow** - Auto-resume, auto-close, progress tracking—natural flow without overhead
 - 🎯 **10 Agents + 35+ Skills** - PM, Architect, DevOps, QA, Security work in parallel (minimizes context usage). Easily extensible!
-- 🔧 **Universal Support** - Works with Claude (native), Cursor, Gemini CLI, Codex, Copilot, and ANY AI tool (100% market coverage)
-  - **Claude Code**: Native agents/skills pre-installed in `.claude/`
-  - **Other tools**: Accessible via universal AGENTS.md adapter
+- 🔧 **Universal Support** - Works with Claude Code (default), Cursor, Gemini CLI, Codex, Copilot, and ANY AI tool (100% market coverage)
+  - **Claude Code** (default): Native agents/skills pre-installed in `.claude/` - best experience!
+  - **Other tools**: Accessible via adapters (Cursor, Copilot) or universal AGENTS.md
 - 🧪 **Complete Test Coverage** - 4-level strategy from specs to integration tests (APIs, UIs, CLIs, libraries)
 - 📚 **Living Documentation** - Specs auto-update after every operation and test—always in sync with code
 - 🎨 **Visual Architecture** - C4 Model diagrams (Context, Container, Component)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "specweave",
-  "version": "0.3.7",
+  "version": "0.3.8",
   "description": "Replace vibe coding with spec-driven development. Smart workflow: /specweave inc auto-closes previous, /specweave build auto-resumes, /specweave progress shows status. PM-led planning, 10 agents, 35+ skills. spec-weave.com",
   "type": "module",
   "main": "dist/index.js",

package/src/adapters/copilot/README.md

@@ -134,7 +134,7 @@ max_context_tokens: 10000
 ❌ **No workflow automation** - Must create folders/files manually
 ❌ **No skills/agents** - Can't simulate roles like Cursor
 ❌ **No commands** - No slash commands or @ shortcuts
-❌ **No hooks** - Can't auto-update docs
+❌ **No hooks** - Can't auto-update docs (see workaround below)
 ⚠️ **Completely manual workflow** - Just better code suggestions
 
 ✅ **But still helpful for**:
@@ -142,6 +142,19 @@ max_context_tokens: 10000
 - Suggesting file structures
 - Copilot Chat Q&A about project
 
+### Documentation Update Workaround
+
+Since GitHub Copilot doesn't have hooks, you MUST manually update documentation after every task.
+
+**See the comprehensive guide in AGENTS.md** (section: "Documentation Updates - CRITICAL FOR NON-CLAUDE TOOLS")
+
+**Quick checklist after completing any task**:
+1. Update `.specweave/increments/{id}/tasks.md` (mark tasks complete)
+2. Update `.specweave/docs/internal/architecture/` (HLD/LLD/ADRs)
+3. Update `.specweave/docs/internal/strategy/` (PRDs if requirements changed)
+4. Update `README.md` (user-facing changes)
+5. Update `CHANGELOG.md` (version history)
+
 ## When to Use This Adapter
 
 ✅ **Use Copilot adapter if**:

package/src/adapters/cursor/README.md

@@ -206,11 +206,24 @@ documentation:
 
 ❌ **No auto-activation** - Must explicitly request workflows
 ❌ **No separate context windows** - All context shared
-❌ **No hooks** - Can't auto-update docs on events
+❌ **No hooks** - Can't auto-update docs on events (see workaround below)
 ⚠️ **Manual role adoption** - Must say "act as PM"
 
 ✅ **But Composer + @ shortcuts provide great UX!**
 
+### Documentation Update Workaround
+
+Since Cursor doesn't have hooks, you MUST manually update documentation after every task.
+
+**See the comprehensive guide in AGENTS.md** (section: "Documentation Updates - CRITICAL FOR NON-CLAUDE TOOLS")
+
+**Quick checklist after completing any task**:
+1. Update `.specweave/increments/{id}/tasks.md` (mark tasks complete)
+2. Update `.specweave/docs/internal/architecture/` (HLD/LLD/ADRs)
+3. Update `.specweave/docs/internal/strategy/` (PRDs if requirements changed)
+4. Update `README.md` (user-facing changes)
+5. Update `CHANGELOG.md` (version history)
+
 ## Tips & Tricks
 
 ### 1. Always Mention Context-Manifest

package/src/hooks/post-task-completion.sh

@@ -7,14 +7,42 @@
 # 1. Play completion sound (synchronously, not background)
 # 2. Output JSON systemMessage reminding to update docs
 # 3. Log completion
+#
+# DEBOUNCING: Prevents rapid duplicate fires (Claude Code calls hooks twice)
 
 set -e
 
 PROJECT_ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/../.." && pwd)"
 cd "$PROJECT_ROOT" 2>/dev/null || true
 
-# DEBUG: Log hook invocation
+# Debounce: Skip if hook fired within last 2 seconds
+LAST_FIRE_FILE=".specweave/logs/last-hook-fire"
+CURRENT_TIME=$(date +%s)
+DEBOUNCE_SECONDS=2
+
 mkdir -p .specweave/logs 2>/dev/null || true
+
+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
+    # Too soon - skip this invocation (prevents duplicates)
+    echo "[$(date)] Hook skipped (debounced - last fire was ${TIME_DIFF}s ago)" >> .specweave/logs/hooks-debug.log 2>/dev/null || true
+    # Output minimal JSON (no systemMessage)
+    cat <<EOF
+{
+  "continue": true
+}
+EOF
+    exit 0
+  fi
+fi
+
+# Save current timestamp
+echo "$CURRENT_TIME" > "$LAST_FIRE_FILE"
+
+# DEBUG: Log hook invocation
 echo "[$(date)] Hook invoked! PWD=$PWD Args=$*" >> .specweave/logs/hooks-debug.log 2>/dev/null || true
 echo "[$(date)] Hook stdin:" >> .specweave/logs/hooks-debug.log 2>/dev/null || true
 cat >> .specweave/logs/hooks-debug.log 2>/dev/null || true
@@ -40,7 +68,6 @@ play_sound() {
 play_sound
 
 # 2. Log completion
-mkdir -p .specweave/logs 2>/dev/null || true
 echo "[$(date)] Task completed" >> .specweave/logs/tasks.log 2>/dev/null || true
 
 # 3. Output JSON to instruct Claude (systemMessage is shown to user)

package/src/templates/AGENTS.md.template

@@ -276,6 +276,152 @@ npm run lint
 
 ---
 
+## 📝 Documentation Updates (CRITICAL FOR NON-CLAUDE TOOLS)
+
+**IMPORTANT**: Claude Code has automatic hooks that remind you to update documentation. **GitHub Copilot, Cursor, and other tools DO NOT have these hooks!**
+
+### You MUST Manually Update Documentation After Every Task
+
+When you complete ANY task (implementation, bug fix, refactoring), you MUST update:
+
+#### 1. Living Docs (.specweave/docs/)
+
+After implementing features, update strategic documentation:
+
+**Strategy Docs** (`.specweave/docs/internal/strategy/`):
+- Update PRDs when requirements change
+- Add new user stories if scope expanded
+- Document discovered requirements
+
+**Architecture Docs** (`.specweave/docs/internal/architecture/`):
+- Update HLD (high-level design) when architecture changes
+- Update LLD (low-level design) when components change
+- Update ADRs from "Proposed" → "Accepted" after implementation
+- Add new ADRs for significant decisions made during implementation
+
+**Delivery Docs** (`.specweave/docs/internal/delivery/`):
+- Update deployment guides after infrastructure changes
+- Update CI/CD docs after pipeline modifications
+
+**Operations Docs** (`.specweave/docs/internal/operations/`):
+- Update runbooks after operational changes
+- Update monitoring/alerting docs
+
+#### 2. Increment Documentation
+
+**Always update these files in `.specweave/increments/{increment-id}/`**:
+
+```bash
+# Update implementation status
+vim .specweave/increments/0001-feature/plan.md
+# Add: "## Implementation Notes" section with learnings
+
+# Update task checklist
+vim .specweave/increments/0001-feature/tasks.md
+# Mark completed: - [x] T001: Task description
+
+# Document completion
+vim .specweave/increments/0001-feature/reports/completion-report.md
+# Add: Summary of what was implemented, challenges, solutions
+```
+
+#### 3. Project Documentation
+
+**CLAUDE.md or AGENTS.md** (this file):
+- Update when project structure changes
+- Add new workflows or commands
+- Update "Current Work" section
+
+**README.md** (user-facing):
+- Update when features are added
+- Update installation instructions if changed
+- Update usage examples
+
+**CHANGELOG.md** (version history):
+- Add entries for all user-facing changes
+- Format: `## [version] - date` with bullet points
+
+#### 4. Code Documentation
+
+**Inline comments**:
+- Add JSDoc/TSDoc for new functions
+- Update existing comments if behavior changes
+- Explain "why" not just "what"
+
+### When to Update (Checklist)
+
+After you:
+- ✅ Complete a task → Update increment tasks.md
+- ✅ Implement a feature → Update living docs (architecture, strategy)
+- ✅ Make architecture decision → Create or update ADR
+- ✅ Change project structure → Update CLAUDE.md/AGENTS.md
+- ✅ Add user-facing feature → Update README.md
+- ✅ Fix a bug → Update CHANGELOG.md
+- ✅ Change API → Update API documentation
+- ✅ Modify deployment → Update deployment guide
+
+### Example Workflow (GitHub Copilot/Cursor Users)
+
+```markdown
+# After completing "Implement user authentication" task:
+
+1. Update living docs:
+   echo "## Implementation Notes
+   - Used JWT for stateless authentication
+   - Password hashing with bcrypt
+   - Session timeout: 24 hours
+   " >> .specweave/increments/0001-auth/plan.md
+
+2. Update architecture:
+   vim .specweave/docs/internal/architecture/hld-system.md
+   # Add authentication component diagram
+
+3. Create ADR:
+   vim .specweave/docs/internal/architecture/adr-003-jwt-authentication.md
+
+4. Update README:
+   vim README.md
+   # Add authentication usage example
+
+5. Update CHANGELOG:
+   echo "### Added
+   - User authentication with JWT
+   - Password reset flow
+   " >> CHANGELOG.md
+
+6. Mark task complete:
+   vim .specweave/increments/0001-auth/tasks.md
+   # Change [ ] to [x] for completed tasks
+```
+
+### Why This Matters
+
+**Without documentation updates**:
+- ❌ Specs diverge from implementation (specs become useless)
+- ❌ Team members don't know what changed
+- ❌ Future AI sessions have outdated context
+- ❌ SpecWeave's core principle (living documentation) breaks down
+
+**With documentation updates**:
+- ✅ Specs stay synchronized with code
+- ✅ Clear audit trail of changes
+- ✅ AI agents have accurate context
+- ✅ Team members stay informed
+- ✅ SpecWeave philosophy is maintained
+
+### Tools That Need Manual Updates
+
+These tools **DO NOT** have automatic documentation hooks:
+- GitHub Copilot (all versions)
+- Cursor
+- Windsurf
+- Gemini CLI
+- Generic AI tools (ChatGPT, Claude web, etc.)
+
+Only **Claude Code** has automatic hooks that remind you to update docs.
+
+---
+
 ## Security Considerations
 
 - Never commit secrets (use `.env` files, gitignored)
@@ -317,6 +463,7 @@ When you encounter a new task:
 5. ✅ **Technology-specific in plan.md** (HOW with details)
 6. ✅ **Use checkboxes in tasks.md** for tracking
 7. ✅ **All supporting files in increment folders** (never in root)
+8. 🔴 **UPDATE DOCUMENTATION AFTER EVERY TASK** (see "Documentation Updates" section above - CRITICAL for non-Claude tools!)
 
 ---