specweave 0.21.2 → 0.22.0

package/plugins/specweave/agents/pm/AGENT.md

@@ -300,8 +300,8 @@ if (shouldSuggestLivingDocs) {
   console.log('  ✅ Complete requirements in one place');
   console.log('  ✅ Increment specs reference it (avoid duplication)');
   console.log('');
-  console.log('Location: .specweave/docs/internal/specs/spec-####-{name}.md');
-  console.log('⚠️  CRITICAL: Specs are FILES, not directories!');
+  console.log('Location: .specweave/docs/internal/specs/_features/FS-####/FEATURE.md');
+  console.log('⚠️  CRITICAL: Living docs created via /specweave:sync-docs update!');
   console.log('');
   console.log('💡 See FAQ: https://spec-weave.com/docs/faq#do-i-need-both-for-every-feature');
   console.log('');
@@ -398,17 +398,18 @@ The PM Agent acts as your AI Product Manager, helping you:
    - **From config**: `multiProject.activeProject` field
    - **Fallback**: Use `default` project
 
-3. **Use CORRECT flattened path** (v0.16.11+):
-   - ✅ **CORRECT**: `.specweave/docs/internal/specs/{project-id}/spec-{number}-{name}.md`
-   - ❌ **WRONG**: `.specweave/docs/internal/projects/{project-id}/specs/...` (OLD nested structure)
+3. **Use CORRECT three-layer structure** (v0.18.0+):
+   - ✅ **CORRECT**: `.specweave/docs/internal/specs/_features/FS-{number}/FEATURE.md` (cross-project)
+   - ✅ **CORRECT**: `.specweave/docs/internal/specs/{project}/FS-{number}/us-*.md` (project-specific)
+   - ❌ **WRONG**: `.specweave/docs/internal/specs/{project}/spec-{number}-{name}.md` (OLD v0.17.x)
 
 **Examples**:
-- Single project: `.specweave/docs/internal/specs/default/spec-0001-user-authentication.md`
-- Backend project: `.specweave/docs/internal/specs/backend/spec-0002-api-auth.md`
-- Frontend project: `.specweave/docs/internal/specs/frontend/spec-0003-dark-mode.md`
-- Parent repo: `.specweave/docs/internal/specs/_parent/spec-0004-system-architecture.md`
+- Feature overview: `.specweave/docs/internal/specs/_features/FS-001/FEATURE.md`
+- Backend user story: `.specweave/docs/internal/specs/backend/FS-002/us-001-api-auth.md`
+- Frontend user story: `.specweave/docs/internal/specs/frontend/FS-003/us-001-dark-mode.md`
+- Cross-project feature: `.specweave/docs/internal/specs/_features/FS-004/FEATURE.md`
 
-**CRITICAL**: Specs are **FILES**, not directories! The spec file itself contains all content.
+**CRITICAL**: Living docs are created via `/specweave:sync-docs update` - NOT manually created!
 
 **Purpose**: Complete, detailed requirements specification - PERMANENT source of truth
 
@@ -427,7 +428,7 @@ status: proposed|accepted|implemented
 created: 2025-11-04
 ---
 
-# SPEC-{number}: [Feature Name]
+# FS-{number}: [Feature Name]
 
 ## Overview
 
@@ -611,14 +612,14 @@ High-level business context: [Strategy Overview](../../docs/internal/strategy/{m
 ```markdown
 # Feature: [Name]
 
-[Copy all content from SPEC-{number}-{name}/spec.md here]
+[Copy all content from FS-{number}/FEATURE.md here]
 ```
 
 **Option B: Reference Spec** (minimal approach):
 ```markdown
 # Feature: [Name]
 
-**Complete Requirements**: See [SPEC-{number}-{name}](../../docs/internal/specs/{project-id}/spec-{number}-{name}.md)
+**Complete Requirements**: See [FS-{number}](../../docs/internal/specs/_features/FS-{number}/FEATURE.md)
 
 **Quick Summary**:
 - US-001: View current weather

package/plugins/specweave/commands/specweave-check-hooks.md

@@ -0,0 +1,186 @@
+# Check Hook Health
+
+**Command**: `/specweave:check-hooks`
+
+Runs comprehensive health check on all hooks in the project.
+Detects import errors, runtime failures, performance issues, and provides auto-fix suggestions.
+
+## Usage
+
+```bash
+# Check all hooks
+/specweave:check-hooks
+
+# Check and auto-fix issues
+/specweave:check-hooks --fix
+
+# Check only critical hooks
+/specweave:check-hooks --critical
+
+# Verbose output with details
+/specweave:check-hooks --verbose
+
+# Check specific hook
+/specweave:check-hooks update-ac-status
+
+# Generate markdown report
+/specweave:check-hooks --format markdown --output report.md
+```
+
+## Options
+
+- `--fix` - Automatically repair fixable issues (missing .js extensions, etc.)
+- `--critical` - Check only critical hooks (post-task-completion, user-prompt-submit)
+- `--verbose` - Show detailed error messages and stack traces
+- `--format <format>` - Output format: console (default), markdown, json, junit
+- `--output <file>` - Write report to file
+- `--timeout <ms>` - Hook execution timeout (default: 5000ms)
+- `--fail-on-warnings` - Exit with error code if warnings detected
+
+## What It Checks
+
+### Import Errors (ERR_MODULE_NOT_FOUND)
+- Missing .js extensions in ES module imports
+- Incorrect import paths
+- Missing dependencies
+
+### Runtime Errors
+- Static vs instance method mismatches
+- Syntax errors
+- JSON parse errors
+
+### Performance Issues
+- Hooks exceeding expected execution time
+- Slow file I/O operations
+
+### Best Practices
+- Deprecated API usage
+- Security vulnerabilities
+
+## Auto-Fix Capabilities
+
+The `--fix` flag can automatically repair:
+
+1. **Missing .js Extensions**
+   ```typescript
+   // Before:
+   import { ACStatusManager } from '../../../../src/core/increment/ac-status-manager';
+
+   // After:
+   import { ACStatusManager } from '../../../../src/core/increment/ac-status-manager.js';
+   ```
+
+2. **Import Path Corrections** (high confidence only)
+
+## Output Formats
+
+### Console (Default)
+Colorized output for terminal viewing:
+
+```
+🏥 Hook Health Check
+═══════════════════════════════════════════════════════════
+
+✅ All hooks healthy (8/8 passed)
+
+Hooks Checked:
+  ✅ update-ac-status (42ms)
+  ✅ auto-transition (38ms)
+  ✅ sync-living-docs (156ms)
+  ...
+
+Summary:
+  Total Hooks: 8
+  ✅ Passed: 8
+  ⏱️  Total Time: 625ms
+```
+
+### Markdown
+Detailed report for documentation:
+
+```markdown
+# 🏥 Hook Health Check Report
+
+**Generated**: 2025-11-16 14:00:00
+**Overall Health**: 🟢 HEALTHY
+
+## Summary
+- **Total Hooks**: 8
+- **Passed**: ✅ 8
+- **Failed**: ❌ 0
+```
+
+### JSON
+Machine-readable format for CI/CD:
+
+```json
+{
+  "timestamp": "2025-11-16T14:00:00Z",
+  "totalHooks": 8,
+  "passedHooks": 8,
+  "failedHooks": 0,
+  "overallHealth": "healthy"
+}
+```
+
+### JUnit XML
+For CI/CD test reporting:
+
+```xml
+<testsuite name="Hook Health Check" tests="8" failures="0">
+  <testcase name="update-ac-status" classname="specweave" time="0.042"/>
+</testsuite>
+```
+
+## Exit Codes
+
+- `0` - All hooks healthy
+- `1` - Hook failures detected
+- `2` - Critical hook failures (blocks workflow)
+
+## Examples
+
+### Pre-Build Health Check
+```bash
+npm run check:hooks
+```
+
+### CI/CD Integration
+```yaml
+# .github/workflows/test.yml
+- name: Check Hook Health
+  run: npm run check:hooks -- --format junit --output junit.xml
+
+- name: Publish Test Results
+  uses: EnricoMi/publish-unit-test-result-action@v2
+  with:
+    files: junit.xml
+```
+
+### Pre-Commit Hook
+```bash
+#!/bin/bash
+# .git/hooks/pre-commit
+
+npm run check:hooks --critical
+if [ $? -ne 0 ]; then
+  echo "❌ Critical hooks failing - commit blocked"
+  exit 1
+fi
+```
+
+## Troubleshooting
+
+### "Hook execution timeout"
+Increase timeout: `/specweave:check-hooks --timeout 10000`
+
+### "Cannot find module"
+Run with auto-fix: `/specweave:check-hooks --fix`
+
+### "Permission denied"
+Check hook file permissions: `chmod +x plugins/*/hooks/*.sh`
+
+## See Also
+
+- Hook Health Check Architecture: `.specweave/increments/0037-project-specific-tasks/architecture/HOOK-HEALTH-CHECK-ARCHITECTURE.md`
+- Hook Development Guide: `.specweave/docs/public/guides/hook-development.md`

package/plugins/specweave/commands/specweave-plan.md

@@ -0,0 +1,151 @@
+---
+name: specweave-plan
+description: Generate plan.md and tasks.md for PLANNING increment using Architect Agent
+---
+
+# /specweave:plan - Generate Implementation Plan
+
+Generate `plan.md` and `tasks.md` for an increment using Architect Agent and test-aware-planner.
+
+## Usage
+
+```bash
+/specweave:plan                      # Auto-detect PLANNING increment
+/specweave:plan 0039                 # Explicit increment ID
+/specweave:plan --force              # Overwrite existing plan/tasks
+/specweave:plan 0039 --verbose       # Verbose output
+```
+
+## What It Does
+
+1. **Auto-detect increment** (if not specified):
+   - Prefers PLANNING status
+   - Falls back to single ACTIVE increment
+
+2. **Validate pre-conditions**:
+   - spec.md exists and is not empty
+   - Increment is not COMPLETED/ABANDONED
+   - plan.md/tasks.md don't exist (unless --force)
+
+3. **Generate plan.md** (via Architect Agent):
+   - Technical approach
+   - Architecture design
+   - Dependencies
+   - Risk assessment
+
+4. **Generate tasks.md** (via test-aware-planner):
+   - Checkable task list
+   - Embedded test plans (BDD format)
+   - Coverage targets
+
+5. **Update metadata**:
+   - PLANNING → ACTIVE transition (tasks.md now exists)
+   - Update lastUpdated timestamp
+
+## Options
+
+- `--force`: Overwrite existing plan.md/tasks.md
+- `--preserve-task-status`: Keep existing task completion status (requires --force)
+- `--verbose`: Show detailed execution information
+
+## Examples
+
+**Auto-detect and plan**:
+```bash
+/specweave:plan
+# ✅ Auto-detected increment: 0039-ultra-smart-next-command
+# ✅ Generated plan.md (2.5K)
+# ✅ Generated tasks.md (4.2K, 15 tasks)
+# ✅ Transitioned PLANNING → ACTIVE
+```
+
+**Force regenerate**:
+```bash
+/specweave:plan 0039 --force
+# ⚠️  Overwriting existing plan.md
+# ⚠️  Overwriting existing tasks.md
+# ✅ Generated plan.md (2.8K)
+# ✅ Generated tasks.md (5.1K, 18 tasks)
+```
+
+**Multiple PLANNING increments**:
+```bash
+/specweave:plan
+# ❌ Multiple increments in PLANNING status found:
+#    - 0040-feature-a
+#    - 0041-feature-b
+# Please specify: /specweave:plan 0040
+```
+
+## Workflow Integration
+
+**Typical workflow**:
+```bash
+# 1. Create increment (generates spec.md)
+/specweave:increment "Add user authentication"
+# Status: BACKLOG → PLANNING (spec.md created)
+
+# 2. Edit spec.md (add requirements, ACs)
+# ... edit spec.md ...
+
+# 3. Generate plan and tasks
+/specweave:plan
+# Status: PLANNING → ACTIVE (tasks.md created)
+
+# 4. Execute tasks
+/specweave:do
+```
+
+## Error Handling
+
+**spec.md not found**:
+```bash
+❌ spec.md not found in increment '0039-ultra-smart-next-command'
+💡 Create spec.md first using `/specweave:increment` or manually
+```
+
+**plan.md already exists**:
+```bash
+❌ plan.md already exists in increment '0039'
+💡 Use --force to overwrite existing plan.md
+```
+
+**Increment closed**:
+```bash
+❌ Cannot generate plan for COMPLETED increment
+💡 Reopen increment with `/specweave:reopen` first
+```
+
+## Architecture
+
+**Components**:
+- `IncrementDetector`: Auto-detect or validate increment
+- `PlanValidator`: Validate pre-conditions
+- `ArchitectAgentInvoker`: Generate plan.md via Architect Agent
+- `TaskGeneratorInvoker`: Generate tasks.md via test-aware-planner
+- `PlanCommandOrchestrator`: Coordinate execution pipeline
+
+**State transitions**:
+- PLANNING → ACTIVE (when tasks.md created)
+- ACTIVE → ACTIVE (regenerate plan/tasks)
+- BACKLOG → (no change - spec.md already exists)
+
+## Related Commands
+
+- `/specweave:increment` - Create new increment (generates spec.md)
+- `/specweave:do` - Execute tasks from tasks.md
+- `/specweave:validate` - Validate increment structure
+- `/specweave:sync-docs` - Sync spec changes to living docs
+
+## Notes
+
+- **Auto-transition**: Creating tasks.md automatically transitions PLANNING → ACTIVE
+- **Force mode**: Use with caution - overwrites existing work
+- **Preserve status**: Use `--preserve-task-status` to keep completion checkmarks when regenerating
+- **Architect Agent**: Requires ~10-30 seconds for plan generation
+- **Test coverage**: tasks.md includes embedded test plans for each task
+
+---
+
+**Part of**: Increment 0039 (Ultra-Smart Next Command)
+**Status**: Phase 1 - Foundation (US-007)