specweave 0.6.8 → 0.7.1

package/plugins/specweave/agents/test-aware-planner/templates/README.md

@@ -0,0 +1,118 @@
+# Test-Aware Planner Templates
+
+This directory contains templates for generating tasks.md with embedded test plans.
+
+## Templates
+
+### 1. task-testable.md.template
+
+**Purpose**: Template for tasks that have automated tests (unit/integration/E2E)
+
+**Variables**:
+- `{task_number}`: Sequential task number (001, 002, 003, ...)
+- `{task_title}`: Clear, action-oriented task description
+- `{user_story}`: User story ID (US1, US2, ...)
+- `{ac_ids}`: Acceptance criteria IDs (AC-US1-01, AC-US1-02)
+- `{priority}`: Priority level (P0, P1, P2)
+- `{estimate}`: Time estimate in hours (2-8 typical)
+
+**Test Plan Variables**:
+- `{given_condition}`: Precondition/setup
+- `{when_action}`: Action or event
+- `{then_outcome}`: Expected result
+- `{and_additional}`: Additional conditions (optional)
+
+**Test Cases Variables**:
+- `{unit_test_path}`: Path to unit test file (e.g., `tests/unit/feature.test.ts`)
+- `{testFunction1}`, `{testFunction2}`: Test function names
+- `{test1_description}`: One-line test description
+- `{unit_coverage}`: Coverage target for unit tests (85-95%)
+- `{integration_test_path}`: Path to integration test file
+- `{integration_coverage}`: Coverage target for integration tests (80-90%)
+- `{e2e_test_path}`: Path to E2E test file (optional)
+- `{overall_coverage}`: Overall coverage target (80-90%)
+
+**Implementation Variables**:
+- `{step1}`, `{step2}`, ...: Implementation steps
+- `{unit_test_count}`: Number of unit tests
+- `{int_test_count}`: Number of integration tests
+- `{e2e_test_count}`: Number of E2E tests (optional)
+- `{unit_test_command}`: Command to run unit tests
+- `{int_test_command}`: Command to run integration tests
+- `{e2e_test_command}`: Command to run E2E tests
+
+**TDD Workflow Variables**:
+- `{total_test_count}`: Total number of tests across all levels
+- `{feature_name}`: Name of feature being implemented
+- `{impl_step_count}`: Number of implementation steps
+
+### 2. task-non-testable.md.template
+
+**Purpose**: Template for tasks without automated tests (documentation, configuration, manual processes)
+
+**Variables**:
+- Same header variables as testable template (task_number, task_title, etc.)
+- `{task_type}`: Type of task (documentation, configuration, deployment, etc.)
+
+**Validation Variables**:
+- `{validation1}`, `{validation2}`: Validation methods
+- `{validation1_description}`: What to check/verify
+- `{validation_command}`: Command to run validation
+- `{review_criteria}`: Manual review criteria
+
+### 3. tasks-frontmatter.md.template
+
+**Purpose**: Template for tasks.md file header (YAML frontmatter)
+
+**Variables**:
+- `{increment_id}`: Increment ID (e.g., 0007-smart-increment-discipline)
+- `{total_tasks}`: Total number of tasks
+- `{test_mode}`: TDD or standard
+- `{coverage_target}`: Overall coverage target (80-90%)
+- `{tasks_content}`: Concatenated tasks from other templates
+
+## Usage Example
+
+```typescript
+// Pseudo-code for using templates
+
+const taskTemplate = fs.readFileSync('task-testable.md.template', 'utf-8');
+
+const taskContent = taskTemplate
+  .replace('{task_number}', '001')
+  .replace('{task_title}', 'Implement User Authentication')
+  .replace('{user_story}', 'US1')
+  .replace('{ac_ids}', 'AC-US1-01, AC-US1-02')
+  .replace('{priority}', 'P1')
+  .replace('{estimate}', '6')
+  .replace('{given_condition}', 'a registered user with email "test@example.com"')
+  .replace('{when_action}', 'they submit valid credentials')
+  .replace('{then_outcome}', 'they should be redirected to dashboard')
+  .replace('{and_additional}', 'session cookie should be created')
+  // ... replace all other variables
+
+// Repeat for each task, then assemble into tasks.md
+```
+
+## Template Design Principles
+
+1. **Consistency**: All tasks follow the same structure
+2. **Flexibility**: Optional sections (E2E tests, And clauses) can be removed
+3. **Clarity**: Variable names are self-explanatory
+4. **Completeness**: All required sections included
+5. **Validation**: Templates match ARCHITECTURE-PIVOT.md format
+
+## Template Validation
+
+Before using templates, verify:
+- [ ] All variables are documented
+- [ ] Format matches ARCHITECTURE-PIVOT.md
+- [ ] Examples in AGENT.md use these templates
+- [ ] Both testable and non-testable scenarios covered
+- [ ] TDD workflow optional but included
+
+## Further Reading
+
+- AGENT.md: Complete agent workflow using these templates
+- ARCHITECTURE-PIVOT.md: Rationale for embedded test format
+- tasks.md: Real example of template output (dogfooding in increment 0007)

package/plugins/specweave/agents/test-aware-planner/templates/task-non-testable.md.template

@@ -0,0 +1,24 @@
+### T-{task_number}: {task_title}
+
+**User Story**: {user_story}
+**Acceptance Criteria**: {ac_ids}
+**Priority**: {priority}
+**Estimate**: {estimate} hours
+**Status**: [ ] pending
+
+**Test Plan**: N/A ({task_type} task)
+
+**Validation**:
+- {validation1}: {validation1_description}
+- {validation2}: {validation2_description}
+- {validation3}: {validation3_description}
+- {validation4}: {validation4_description} (add more as needed)
+
+**Implementation**:
+1. {step1}
+2. {step2}
+3. {step3}
+4. {step4}
+5. {step5}
+6. Run validation: {validation_command}
+7. Manual review: {review_criteria}

package/plugins/specweave/agents/test-aware-planner/templates/task-testable.md.template

@@ -0,0 +1,53 @@
+### T-{task_number}: {task_title}
+
+**User Story**: {user_story}
+**Acceptance Criteria**: {ac_ids}
+**Priority**: {priority}
+**Estimate**: {estimate} hours
+**Status**: [ ] pending
+
+**Test Plan**:
+- **Given** {given_condition}
+- **When** {when_action}
+- **Then** {then_outcome}
+- **And** {and_additional} (optional, remove if not needed)
+
+**Test Cases**:
+1. **Unit**: `{unit_test_path}`
+   - {testFunction1}(): {test1_description}
+   - {testFunction2}(): {test2_description}
+   - {testFunction3}(): {test3_description} (add more as needed)
+   - **Coverage Target**: {unit_coverage}%
+
+2. **Integration**: `{integration_test_path}`
+   - {testIntegration1}(): {integration1_description}
+   - {testIntegration2}(): {integration2_description} (add more as needed)
+   - **Coverage Target**: {integration_coverage}%
+
+3. **E2E**: `{e2e_test_path}` (optional, include only for user-facing features)
+   - {testE2E1}(): {e2e1_description}
+   - **Coverage Target**: 100% (critical path)
+
+**Overall Coverage Target**: {overall_coverage}%
+
+**Implementation**:
+1. {step1}
+2. {step2}
+3. {step3}
+4. {step4}
+5. {step5}
+6. Write unit tests ({unit_test_count} tests)
+7. Run unit tests: `{unit_test_command}` (should pass: {unit_test_count}/{unit_test_count})
+8. Write integration tests ({int_test_count} tests)
+9. Run integration tests: `{int_test_command}` (should pass: {int_test_count}/{int_test_count})
+10. (Optional) Write E2E tests ({e2e_test_count} tests)
+11. (Optional) Run E2E tests: `{e2e_test_command}` (should pass: {e2e_test_count}/{e2e_test_count})
+12. Verify coverage: `npm run coverage` (should be ≥{overall_coverage}%)
+
+**TDD Workflow** (if TDD mode enabled):
+1. 📝 Write all {total_test_count} tests above (should fail)
+2. ❌ Run tests: `npm test` (0/{total_test_count} passing)
+3. ✅ Implement {feature_name} (steps 1-{impl_step_count} from Implementation)
+4. 🟢 Run tests: `npm test` ({total_test_count}/{total_test_count} passing)
+5. ♻️ Refactor if needed (maintain green tests)
+6. ✅ Final check: Coverage ≥{overall_coverage}%

package/plugins/specweave/agents/test-aware-planner/templates/tasks-frontmatter.md.template

@@ -0,0 +1,11 @@
+---
+increment: {increment_id}
+total_tasks: {total_tasks}
+completed_tasks: 0
+test_mode: {test_mode}
+coverage_target: {coverage_target}%
+---
+
+# Implementation Tasks
+
+{tasks_content}

package/plugins/specweave/commands/README.md

@@ -1,196 +1,121 @@
-# SpecWeave Slash Commands
+# SpecWeave Commands
 
-This directory contains all slash commands for SpecWeave.
+All SpecWeave commands are namespaced for brownfield safety and follow a consistent naming pattern.
 
-## Available Commands (v0.2.0)
+## ⚠️ CRITICAL: No Shortcuts Allowed
 
-**IMPORTANT**: All SpecWeave commands are now namespaced with `specweave.` notation to avoid collisions in brownfield projects.
+**IMPORTANT**: SpecWeave commands MUST be invoked with the `/specweave:*` namespace prefix.
 
-### Core Workflow Commands (Smart Workflow)
+**Why?** Shortcuts like `/inc`, `/do`, `/pause`, `/resume` conflict with Claude Code's native commands and break functionality.
 
-| Command | Shorthand via /specweave | Description |
-|---------|--------------------------|-------------|
-| `/specweave:increment` | `/specweave inc` | Plan increment (PM-led, auto-closes previous if ready) |
-| `/specweave:inc` | `/specweave inc` | Alias for /specweave:increment |
-| `/specweave:do` | `/specweave do` | Execute work (smart resume, hooks after every task) |
-| `/specweave:next` | `/specweave next` | Smart transition (close + suggest next) |
-| `/specweave:progress` | `/specweave progress` | Show status (task %, PM gates, next action) |
-| `/specweave:validate` | `/specweave validate` | Validate quality (rule-based + optional LLM judge) |
-| `/specweave:done` | `/specweave done` | Close explicitly (optional, /inc auto-closes) |
+**Always use**: `/specweave:increment`, `/specweave:do`, `/specweave:resume`, etc.
 
-### Supporting Commands
+## Command Naming Convention
 
-| Command | Shorthand via /specweave | Description |
-|---------|--------------------------|-------------|
-| `/specweave:list-increments` | `/specweave list-increments` | List all increments with status and WIP tracking |
-| `/specweave:sync-docs` | `/specweave sync-docs` | Review strategic docs vs implementation |
-| `/specweave:sync-github` | `/specweave sync-github` | Sync increment to GitHub issues with granular control |
-| `/specweave:sync-jira` | `/specweave sync-jira` | Sync increment to Jira epics/stories with granular control |
+**All command files**: `specweave-{command-name}.md`
+**YAML name field**: `{command-name}` (without `specweave-` prefix)
+**Invocation**: `/specweave:{command-name}` (namespace prefix required)
 
-### Master Router Command
+### Example:
+- **File**: `specweave-increment.md`
+- **YAML**:
+  ```yaml
+  ---
+  name: increment
+  description: Plan new Product Increment
+  ---
+  ```
+- **Usage**: `/specweave:increment` (ONLY form, no shortcuts)
 
-| Command | Description |
-|---------|-------------|
-| `/specweave` | Master router for all subcommands (use `/specweave <subcommand>`) |
+## All Available Commands
 
-## Smart Workflow Features (v0.2.0)
+### Core Lifecycle (7 commands)
+1. `specweave-increment.md` - Create increment → `/specweave:increment`
+2. `specweave-do.md` - Execute tasks → `/specweave:do`
+3. `specweave-done.md` - Close increment → `/specweave:done`
+4. `specweave-next.md` - Smart transition → `/specweave:next`
+5. `specweave-progress.md` - Current progress → `/specweave:progress`
+6. `specweave-validate.md` - Validate quality → `/specweave:validate`
+7. `specweave-sync-docs.md` - Sync documentation → `/specweave:sync-docs`
 
-**What makes the workflow "smart"?**
+### Status & Reporting (4 commands)
+8. `specweave-status.md` - All increments overview → `/specweave:status`
+9. `specweave-costs.md` - AI cost dashboard → `/specweave:costs`
+10. `specweave-update-scope.md` - Update completion report → `/specweave:update-scope`
+11. `specweave-qa.md` - Quality assessment → `/specweave:qa`
 
-1. ✅ **Auto-resume**: `/specweave do` automatically finds next incomplete task (no manual tracking)
-2. ✅ **Auto-close**: `/specweave inc` auto-closes previous increment if PM gates pass (seamless)
-3. ✅ **Suggest-not-force**: `/specweave inc` presents options if previous incomplete (user control)
-4. ✅ **Progress visibility**: `/specweave progress` shows exactly where you are anytime
-5. ✅ **Natural flow**: finish → start next without administrative overhead
+### State Management (3 commands)
+12. `specweave-pause.md` - Pause increment → `/specweave:pause`
+13. `specweave-resume.md` - Resume increment → `/specweave:resume`
+14. `specweave-abandon.md` - Abandon increment → `/specweave:abandon`
 
-## Typical Workflow
+### Testing & Quality (2 commands)
+15. `specweave-check-tests.md` - Validate test coverage → `/specweave:check-tests`
+16. `specweave-sync-tasks.md` - Sync tasks with GitHub → `/specweave:sync-tasks`
 
-**Natural append-only workflow** (0001 → 0002 → 0003):
+### TDD Workflow (4 commands)
+17. `specweave-tdd-red.md` - Write failing tests → `/specweave:tdd-red`
+18. `specweave-tdd-green.md` - Make tests pass → `/specweave:tdd-green`
+19. `specweave-tdd-refactor.md` - Refactor code → `/specweave:tdd-refactor`
+20. `specweave-tdd-cycle.md` - Full TDD cycle → `/specweave:tdd-cycle`
 
-```bash
-# 1. Initialize project (CLI, before any AI session)
-npx specweave init my-saas
+### Utilities (2 commands)
+21. `specweave-translate.md` - Batch translation → `/specweave:translate`
+22. `specweave.md` - Master router → `/specweave`
 
-# 2. Plan your first increment (PM-led planning)
-/specweave inc "AI-powered customer support chatbot"
-# PM creates: spec.md + plan.md + tasks.md (auto-generated!) + tests.md
+**Total**: 22 commands (down from 31, removed 8 duplicates/deprecated, removed 1 redundant)
 
-# 3. Build it (smart resume)
-/specweave do
-# Auto-resumes from next incomplete task
-# Hooks run after EVERY task completion
+## Command Categories
 
-# 4. Check progress anytime
-/specweave progress
-# Shows: 5/12 tasks (42%), next: T006, PM gates status
+- **ESSENTIAL**: increment, do, done, next, progress, validate, sync-docs
+- **IMPORTANT**: status, qa, check-tests, update-scope, costs, translate
+- **STATE MANAGEMENT**: pause, resume, abandon
+- **OPTIONAL**: TDD workflow commands, sync-tasks
 
-# 5. Continue building
-/specweave do
-# Picks up where you left off automatically
+## Removed/Deprecated Commands
 
-# 6. Start next feature (auto-closes previous!)
-/specweave inc "real-time chat dashboard"
-# Smart check:
-#   If 0001 complete (PM gates pass) → Auto-close, create 0002
-#   If 0001 incomplete → Present options (never forces)
+**Duplicates removed** (v0.7.0 refactoring):
+- ❌ `inc.md` → Use `/specweave:increment`
+- ❌ `status.md` → Use `/specweave:status`
+- ❌ `pause.md` → Use `/specweave:pause`
+- ❌ `resume.md` → Use `/specweave:resume`
+- ❌ `abandon.md` → Use `/specweave:abandon`
 
-# 7. Keep building
-/specweave do
-# Auto-finds active increment 0002
+**Deprecated commands**:
+- ❌ `validate-coverage.md` → Use `/specweave:check-tests` (NEW format)
+- ❌ `specweave-validate-coverage.md` → Use `/specweave:check-tests`
 
-# Repeat: /specweave inc → /specweave do → /specweave progress → ...
-```
+**Redundant commands**:
+- ❌ `list-increments.md` → Use `/specweave:status` (same functionality)
 
-## Namespaced Commands (Brownfield Safety)
+## Brownfield Safety
 
-**Design decision**: All commands use `specweave.` notation for collision avoidance.
+All commands are namespaced to prevent collisions with existing project commands:
+- ✅ **Namespace form**: `/specweave:increment` (ONLY way, always safe)
+- ❌ **No shortcuts**: Do NOT use `/inc`, `/do`, `/pause`, `/resume` etc.
 
-- ✅ No conflicts with existing project commands
-- ✅ Clear ownership (framework vs. project commands)
-- ✅ Use master router `/specweave` for convenience
-- ✅ Brownfield projects can adopt SpecWeave without risk
+## Command Usage Philosophy
 
-**Most used workflow**:
+**Correct usage** (namespace prefix required):
 ```bash
-/specweave inc "feature"     # ← Create new increment
-/specweave do             # ← Execute work
-/specweave progress          # ← Check status
-/specweave next              # ← Smart transition to next work
-```
-
-## Command Design Philosophy
-
-### 1. Natural Flow Without Overhead
-
-**Problem with traditional workflows**:
-- Manual task tracking ("which task am I on?")
-- Manual closure ("do I need to close this?")
-- Administrative overhead ("update project board")
-
-**SpecWeave solution**:
-- `/do` auto-resumes (no tracking needed)
-- `/inc` auto-closes if ready (no manual /done needed)
-- `/progress` shows status anytime (no board updates)
-
-### 2. Suggest, Never Force
-
-**Critical principle**: User always in control.
-
-**Example**: When starting new increment while previous incomplete:
+/specweave:increment "feature"   # Create increment
+/specweave:do                    # Execute tasks
+/specweave:status                # Check progress
+/specweave:qa 0007               # Quality check
+/specweave:done 0007             # Close increment
 ```
-/inc "new feature"
-
-📊 Checking previous increment 0001-authentication...
-   Status: in-progress
-   PM Gates: ❌ 2 P1 tasks remaining
-
-❌ Cannot auto-close 0001 (incomplete)
-
-Options:
-  A) Complete 0001 first (recommended)
-     → Finish remaining work before starting new
-
-  B) Move incomplete tasks to 0002
-     → Transfer T006, T007 to new increment
-     → Close 0001 as "completed with deferrals"
-
-  C) Cancel new increment
-     → Stay on 0001, continue working
-     → Retry /inc when ready
-
-Your choice? _
-```
-
-**Never**: "Auto-closed 0001 with incomplete work" (surprising, loses context)
 
-### 3. Progressive Disclosure
-
-**Only show complexity when needed**:
-- ✅ Happy path: `/inc` → Auto-close, create new (1 step)
-- ⚠️ Issues found: Show options, explain, let user decide
-
-## Installation
-
-Commands are automatically installed when you:
-- Run `specweave init` (new projects)
-- Install SpecWeave as dependency (`npm install specweave --save-dev`)
-
-For manual installation:
+**Incorrect usage** (DO NOT USE):
 ```bash
-npm run install:commands
+/inc "feature"       # ❌ Conflicts with Claude Code native commands
+/do                  # ❌ Conflicts with Claude Code native commands
+/status              # ❌ Conflicts with Claude Code native commands
+/pause 0007          # ❌ Conflicts with Claude Code native commands
+/resume 0007         # ❌ Conflicts with Claude Code native commands
 ```
 
-## Creating Custom Commands
-
-You can create project-specific commands:
-
-**1. Create `.claude/commands/custom.md`**:
-```markdown
----
-name: custom
-description: Your custom command description
----
-
-# Custom Command
-
-[Your command implementation]
-```
-
-**2. Use it**:
-```bash
-/custom
-```
-
-## Documentation
-
-- **Command Reference**: See `.claude/commands/` for all command implementations
-- **CLAUDE.md**: Quick reference table with all commands
-- **Official Docs**: https://spec-weave.com/docs/commands
-
----
-
-**💡 Pro Tip**: Master the smart workflow - natural append-only progression!
-
-**Core cycle**: `/inc` (plan) → `/do` (implement) → `/progress` (check) → `/inc` (next)
+## See Also
 
-**One alias to rule them all**: `/inc` (short for `/increment`)
+- **User Documentation**: https://spec-weave.com/docs/commands
+- **CLAUDE.md**: Project contributor guide with complete command reference
+- **Plugin Marketplace**: `.claude-plugin/marketplace.json`