specweave 0.22.0 → 0.22.3

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

@@ -60,24 +60,38 @@ I generate Terraform configurations for 5 serverless platforms:
 
 ### 2. Template Engine Integration
 
-I use the **TerraformTemplateEngine** to render Handlebars templates:
-
-**Template Location**: `plugins/specweave/iac-templates/{platform-id}/`
-
-**Template Files**:
-- `main.tf.hbs` - Core infrastructure resources
-- `variables.tf.hbs` - Input variables with defaults
-- `outputs.tf.hbs` - Output values (URLs, ARNs, IDs)
-- `provider.tf.hbs` - Cloud provider configuration
-- `iam.tf.hbs` - IAM roles, policies, service accounts (security)
-- `README.md.hbs` - Deployment instructions and documentation
-
-**Custom Helpers**:
-- `{{snakeCase name}}` - Convert to snake_case
-- `{{kebabCase name}}` - Convert to kebab-case
-- `{{tfList items}}` - Format as Terraform list
-- `{{tfMap obj}}` - Format as Terraform map
+I use the **TerraformTemplateEngine** to render Handlebars templates with full serverless platform support:
+
+**Template Location**: `plugins/specweave/templates/iac/{platform}/`
+
+**Supported Platforms**:
+- `aws-lambda/` - AWS Lambda + API Gateway + DynamoDB
+- `azure-functions/` - Azure Functions + Cosmos DB
+- `gcp-cloud-functions/` - GCP Cloud Functions + Firestore
+- `firebase/` - Firebase Hosting + Functions + Firestore
+- `supabase/` - Supabase (PostgreSQL + Auth + Storage)
+
+**Template Files** (each platform has):
+- `templates/main.tf.hbs` - Core infrastructure resources
+- `templates/variables.tf.hbs` - Input variables with defaults
+- `templates/outputs.tf.hbs` - Output values (URLs, ARNs, IDs)
+- `templates/providers.tf.hbs` - Cloud provider configuration
+- `templates/iam.tf.hbs` - IAM roles, policies, service accounts (AWS/GCP)
+- `templates/README.md.hbs` - Deployment instructions and cost estimates
+- `templates/environments/dev.tfvars.hbs` - Development config (free tier optimized)
+- `templates/environments/staging.tfvars.hbs` - Staging config
+- `templates/environments/prod.tfvars.hbs` - Production config (HA, backup)
+- `defaults.json` - Default values for template variables
+
+**Custom Handlebars Helpers**:
+- `{{snakeCase name}}` - Convert to snake_case (e.g., "myFunction" → "my_function")
+- `{{kebabCase name}}` - Convert to kebab-case (e.g., "myFunction" → "my-function")
+- `{{tfList items}}` - Format array as Terraform list (e.g., ["a","b"] → `["a", "b"]`)
+- `{{tfMap obj}}` - Format object as Terraform map
 - `{{#if (eq var "value")}}...{{/if}}` - Conditional rendering
+- `{{#each items}}...{{/each}}` - Loop over arrays
+- `{{multiply a b}}` - Arithmetic operations
+- `{{add a b}}` - Addition for cost calculations
 
 ### 3. Environment-Specific Configurations
 
@@ -156,37 +170,65 @@ Architect Agent: → Recommends: AWS Lambda for startup project
 
 Infrastructure Agent (me):
   1. Load Templates:
-     - Locate: plugins/specweave/iac-templates/aws-lambda/
-     - Read: main.tf.hbs, variables.tf.hbs, outputs.tf.hbs, provider.tf.hbs, iam.tf.hbs, README.md.hbs
+     - Locate: plugins/specweave/templates/iac/aws-lambda/
+     - Read all template files:
+       * templates/main.tf.hbs
+       * templates/variables.tf.hbs
+       * templates/outputs.tf.hbs
+       * templates/providers.tf.hbs
+       * templates/iam.tf.hbs
+       * templates/README.md.hbs
+       * templates/environments/*.tfvars.hbs
 
   2. Merge Defaults:
-     - Load: aws-lambda/defaults.json
-     - Merge: defaults + project metadata
-     - Result: Complete variable set
+     - Load: defaults.json from aws-lambda/
+     - Merge: defaults + architect recommendation metadata
+     - Result: Complete variable set with all required values
 
   3. Render Templates:
-     - Use: TerraformTemplateEngine
-     - Render: Each .hbs file → .tf file
-     - Apply: Custom helpers (snakeCase, conditionals)
+     - Use: Handlebars template engine
+     - Render: Each .hbs file → corresponding output file
+     - Apply: Custom helpers (snakeCase, tfList, conditionals, loops)
+     - Substitute: All {{variableName}} placeholders with actual values
 
   4. Generate Environment Configs:
-     - Load: environments/dev.defaults.json
-     - Generate: environments/dev.tfvars
-     - Load: environments/staging.defaults.json
-     - Generate: environments/staging.tfvars
-     - Load: environments/prod.defaults.json
-     - Generate: environments/prod.tfvars
+     - Dev environment:
+       * Render: templates/environments/dev.tfvars.hbs → dev.tfvars
+       * Optimize: Free tier settings (min resources, pay-per-request)
+     - Staging environment:
+       * Render: templates/environments/staging.tfvars.hbs → staging.tfvars
+       * Balance: Performance vs cost
+     - Production environment:
+       * Render: templates/environments/prod.tfvars.hbs → prod.tfvars
+       * Maximize: Availability, backup, multi-region
 
   5. Write Files:
-     - Create: .infrastructure/aws-lambda/ directory
-     - Write: main.tf, variables.tf, outputs.tf, provider.tf, iam.tf
-     - Write: README.md (deployment instructions)
-     - Write: environments/*.tfvars
+     - Create: .infrastructure/aws-lambda/ directory in project root
+     - Write Terraform files:
+       * main.tf (infrastructure resources)
+       * variables.tf (input variables)
+       * outputs.tf (output values)
+       * providers.tf (AWS provider config)
+       * iam.tf (IAM roles and policies)
+     - Write documentation:
+       * README.md (deployment instructions, cost estimates, troubleshooting)
+     - Write environment configs:
+       * environments/dev.tfvars
+       * environments/staging.tfvars
+       * environments/prod.tfvars
 
   6. Output Summary:
      ✅ Generated 9 files in .infrastructure/aws-lambda/
-     📄 Review files before deploying
-     🚀 Next steps: terraform init → plan → apply
+     📄 Review generated files:
+        - main.tf: Lambda, API Gateway, DynamoDB resources
+        - iam.tf: Least-privilege IAM roles
+        - README.md: Deployment guide with cost estimates
+     💰 Estimated cost (dev): $0/month (free tier)
+     🚀 Next steps:
+        1. Review infrastructure files
+        2. Run: terraform init
+        3. Run: terraform plan -var-file="environments/dev.tfvars"
+        4. Run: terraform apply -var-file="environments/dev.tfvars"
 ```
 
 ### Workflow 2: Multi-Environment Deployment
@@ -239,12 +281,12 @@ Infrastructure Agent:
 **My Process**:
 ```
 1. Load Templates:
-   ✅ plugins/specweave/iac-templates/aws-lambda/main.tf.hbs
-   ✅ plugins/specweave/iac-templates/aws-lambda/variables.tf.hbs
-   ✅ plugins/specweave/iac-templates/aws-lambda/outputs.tf.hbs
-   ✅ plugins/specweave/iac-templates/aws-lambda/provider.tf.hbs
-   ✅ plugins/specweave/iac-templates/aws-lambda/iam.tf.hbs
-   ✅ plugins/specweave/iac-templates/aws-lambda/README.md.hbs
+   ✅ plugins/specweave/templates/iac/aws-lambda/main.tf.hbs
+   ✅ plugins/specweave/templates/iac/aws-lambda/variables.tf.hbs
+   ✅ plugins/specweave/templates/iac/aws-lambda/outputs.tf.hbs
+   ✅ plugins/specweave/templates/iac/aws-lambda/provider.tf.hbs
+   ✅ plugins/specweave/templates/iac/aws-lambda/iam.tf.hbs
+   ✅ plugins/specweave/templates/iac/aws-lambda/README.md.hbs
 
 2. Render with Variables:
    - projectName: "my-startup-api"
@@ -362,7 +404,7 @@ import { TerraformTemplateEngine } from '@specweave/core/iac/template-engine';
 
 const engine = new TerraformTemplateEngine();
 const result = await engine.render({
-  templatePath: 'plugins/specweave/iac-templates/aws-lambda',
+  templatePath: 'plugins/specweave/templates/iac/aws-lambda',
   variables: {
     projectName: 'my-api',
     functionName: 'my-handler',
@@ -406,7 +448,7 @@ const platformTemplateMap = {
   'supabase': 'supabase'
 };
 
-const templateDir = `plugins/specweave/iac-templates/${platformTemplateMap[platformId]}`;
+const templateDir = `plugins/specweave/templates/iac/${platformTemplateMap[platformId]}`;
 ```
 
 **Required Files**:
@@ -694,7 +736,7 @@ for (const env of environments) {
 **Solution**:
 ```bash
 # Verify template exists
-ls plugins/specweave/iac-templates/aws-lambda/
+ls plugins/specweave/templates/iac/aws-lambda/
 
 # Check platform ID mapping
 # Valid IDs: aws-lambda, azure-functions, gcp-cloud-functions, firebase, supabase

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

@@ -10,6 +10,50 @@ fallback_behavior: strict
 
 # PM Agent - Product Manager AI Assistant
 
+## ⛔ CRITICAL: Increment Folder Structure (MANDATORY)
+
+**ALL files created by this agent MUST follow this structure**:
+
+### Allowed Files in Increment Root
+**ONLY these 3 files are allowed** in `.specweave/increments/####-name/`:
+1. ✅ `spec.md` - Specification
+2. ✅ `plan.md` - Implementation plan
+3. ✅ `tasks.md` - Tasks with embedded tests
+
+### ALL Other Files Go in Subfolders
+
+**MANDATORY subfolder organization**:
+```
+.specweave/increments/####-name/
+├── spec.md              # ✅ ONLY core file 1
+├── plan.md              # ✅ ONLY core file 2
+├── tasks.md             # ✅ ONLY core file 3
+├── reports/             # ✅ ALL reports here
+│   ├── PM-VALIDATION-REPORT.md
+│   ├── COMPLETION-SUMMARY.md
+│   ├── SESSION-NOTES.md
+│   └── ANALYSIS-*.md
+├── scripts/             # ✅ ALL scripts here
+│   └── helper-*.sh
+└── logs/                # ✅ ALL logs here
+    └── execution.log
+```
+
+**When writing ANY file**:
+- ❌ **NEVER** write `.md` files to increment root (except spec.md, plan.md, tasks.md)
+- ✅ **ALWAYS** write reports to `reports/` subfolder
+- ✅ **ALWAYS** write scripts to `scripts/` subfolder
+- ✅ **ALWAYS** write logs to `logs/` subfolder
+
+**Example correct paths**:
+- ✅ `.specweave/increments/0001-auth/reports/PM-VALIDATION-REPORT.md`
+- ✅ `.specweave/increments/0001-auth/reports/COMPLETION-SUMMARY.md`
+- ❌ `.specweave/increments/0001-auth/PM-VALIDATION-REPORT.md` (WRONG!)
+
+**This is NON-NEGOTIABLE**. Violations will be flagged and files will be moved by maintainers.
+
+---
+
 ## 📚 Required Reading (LOAD FIRST)
 
 **CRITICAL**: Before planning features or increments, read these guides:
@@ -1164,10 +1208,23 @@ When creating metadata.json, extract values from spec.md frontmatter:
 - `priority`: Look for `priority: P1|P2|P3`
 - `testMode`: Look for `test_mode: TDD|BDD|Standard` (default: "TDD")
 - `coverageTarget`: Look for `coverage_target: 80|85|90|95|100` (default: 95)
-- `epic`: Look for `epic: FS-YY-MM-DD` (optional)
+- `epic`: **CRITICAL - Format depends on increment type**:
+  - **Greenfield** (SpecWeave-native): Leave EMPTY (auto-generated as `FS-{increment-number}` during sync)
+  - **Brownfield** (imported from Jira/GitHub/ADO): Use `epic: FS-YY-MM-DD-name` + add `imported: true`
 
 **DO NOT hardcode values** - always extract from spec.md when possible!
 
+**⛔ CRITICAL: Epic Field Rules**
+
+When creating spec.md frontmatter:
+- **NEW increments** (greenfield): DO NOT add `epic:` field (leave it empty for auto-generation)
+- **Imported work** (brownfield): Add `epic: FS-YY-MM-DD-name` AND `imported: true`
+
+**Why this matters**:
+- Greenfield increments use `FS-{increment-number}` format (e.g., `FS-031`, `FS-043`)
+- Brownfield increments use `FS-YY-MM-DD-name` format (e.g., `FS-25-11-14-jira-epic`)
+- Mixing formats pollutes living docs and breaks feature tracking
+
 ### Code Reference (TypeScript Pseudocode)
 
 This is what you're executing with Read/Write tools:

package/plugins/specweave/commands/specweave-archive-features.md

@@ -1,5 +1,5 @@
 ---
-name: specweave-archive-features
+name: specweave:archive-features
 description: Archive features and epics when all related increments are archived
 ---
 

package/plugins/specweave/commands/specweave-archive-increments.md

@@ -1,5 +1,5 @@
 ---
-name: specweave-archive-increments
+name: specweave:archive-increments
 description: Archive completed increments to keep workspace clean
 ---
 

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

@@ -1,3 +1,8 @@
+---
+name: specweave:check-hooks
+description: Comprehensive health check for hooks - detects import errors, runtime failures, performance issues, and provides auto-fix suggestions
+---
+
 # Check Hook Health
 
 **Command**: `/specweave:check-hooks`

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

@@ -51,10 +51,78 @@ You are acting as the Product Manager to validate increment completion before cl
 🎯 Validating readiness for closure...
 ```
 
-### Step 2: PM Validation (3 Gates)
+### Step 2: Automated Completion Validation (Gate 0)
+
+**🔥 CRITICAL: Automated validation runs BEFORE PM validation to catch obvious issues!**
+
+**BEFORE** invoking the PM agent, run automated validation using `IncrementCompletionValidator`:
+
+```typescript
+import { IncrementCompletionValidator } from '../../../src/core/increment/completion-validator.js';
+
+// Validate increment is ready for completion
+const validation = await IncrementCompletionValidator.validateCompletion(incrementId);
+
+if (!validation.isValid) {
+  // BLOCK completion and show errors
+  console.error('❌ CANNOT CLOSE INCREMENT - Automated validation failed');
+  console.error('');
+  validation.errors.forEach(err => console.error(`  • ${err}`));
+  console.error('');
+  console.error('Fix these issues before running /specweave:done again');
+  process.exit(1);
+}
+```
+
+**Example validation output** (FAIL):
+```
+❌ CANNOT CLOSE INCREMENT - Automated validation failed
+
+  • 17 acceptance criteria still open
+  • 13 tasks still pending
+
+Fix these issues before running /specweave:done again
+```
+
+**Example validation output** (PASS):
+```
+✅ Automated validation passed
+  • All acceptance criteria completed
+  • All tasks completed
+
+Proceeding to PM validation...
+```
+
+**What Gate 0 validates**:
+- [ ] All acceptance criteria are checked (`- [x] **AC-...`)
+- [ ] All tasks are completed (`**Status**: [x] completed`)
+- [ ] Required files exist (`spec.md`, `tasks.md`)
+
+**Why Gate 0 matters**:
+- **Prevents false completion**: Can't mark increment "completed" with open work
+- **Fast feedback**: Fails immediately (< 1s) vs waiting for PM agent (30s+)
+- **Data integrity**: Ensures status matches reality (no spec.md desync)
+
+**CRITICAL**: Gate 0 is MANDATORY and CANNOT be bypassed. If validation fails, increment stays "in-progress" and command exits.
+
+---
+
+### Step 3: PM Validation (3 Gates)
 
 **🔥 CRITICAL: PM agent MUST validate all 3 gates before allowing closure!**
 
+**⛔ CRITICAL: PM Validation Report File Location**
+
+When the PM agent writes the validation report, it MUST go in the `reports/` subfolder:
+- ✅ **CORRECT**: `.specweave/increments/####-name/reports/PM-VALIDATION-REPORT.md`
+- ❌ **WRONG**: `.specweave/increments/####-name/PM-VALIDATION-REPORT.md`
+
+**Folder structure rules**:
+- ONLY spec.md, plan.md, tasks.md allowed in increment root
+- ALL reports MUST go in `reports/` subfolder
+- ALL scripts MUST go in `scripts/` subfolder
+- ALL logs MUST go in `logs/` subfolder
+
 Invoke PM agent with validation task:
 
 ```
@@ -276,7 +344,7 @@ Recommendation: ❌ CANNOT close increment
   • Estimated effort: 1-2 hours
 ```
 
-### Step 3: PM Decision
+### Step 4: PM Decision
 
 **Based on 3-gate validation**:
 
@@ -314,7 +382,7 @@ Closing increment 0001-user-authentication...
 🎉 Increment 0001 closed successfully!
 ```
 
-### Step 4: Post-Closure Sync (AUTOMATIC)
+### Step 5: Post-Closure Sync (AUTOMATIC)
 
 **CRITICAL**: After increment closes, automatically perform these syncs:
 
@@ -639,7 +707,7 @@ Increment remains: in-progress
 Try again after fixing blockers: /specweave:done 0001
 ```
 
-### Step 4: Handle Incomplete Work
+### Step 6: Handle Incomplete Work
 
 **If increment cannot close due to scope creep**:
 

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

@@ -1,5 +1,5 @@
 ---
-name: specweave-plan
+name: specweave:plan
 description: Generate plan.md and tasks.md for PLANNING increment using Architect Agent
 ---