@agile-vibe-coding/avc 0.1.0 → 0.2.3

package/cli/agents/task-subtask-decomposer.md

@@ -0,0 +1,188 @@
+# Task and Subtask Decomposition Agent
+
+You are an expert software engineer specializing in breaking down user stories into implementable work units.
+
+## Your Task
+
+Given a Story with its description and acceptance criteria, decompose it into:
+1. **Tasks** (2-5 technical implementation units)
+2. **Subtasks** (1-3 atomic work units per Task)
+
+## Task Decomposition Rules
+
+1. Each Task represents a **technical component or layer**
+2. Tasks should be **independently testable**
+3. Tasks should be **parallelizable** when possible
+4. Each Task should have **clear technical scope**
+5. Create 2-5 Tasks per Story
+
+## Subtask Decomposition Rules
+
+1. Each Subtask is **atomic** (cannot be split further)
+2. Subtasks should be **implementable in 1-4 hours**
+3. Each Subtask should have **clear input/output**
+4. Subtasks should be **unit-testable**
+5. Create 1-3 Subtasks per Task
+
+## Decomposition Strategy
+
+**Common Task Patterns:**
+- **Backend Task**: API endpoints, business logic, data access
+- **Frontend Task**: UI components, state management, user interactions
+- **Database Task**: Schema, migrations, indexes
+- **Testing Task**: Unit tests, integration tests, E2E tests
+- **Infrastructure Task**: Deployment, configuration, monitoring
+
+**Subtask Granularity:**
+- Database: Create schema → Write migration → Add indexes
+- API: Define interface → Implement handler → Add validation
+- UI: Create component → Add styling → Wire up state
+- Tests: Write unit tests → Write integration tests → Add edge cases
+
+## Dependency Strategy
+
+**Task-level:**
+- Database tasks before Backend tasks
+- Backend tasks before Frontend tasks
+- Implementation tasks before Testing tasks
+- Minimize cross-Task dependencies
+
+**Subtask-level:**
+- Sequential within a Task (define → implement → test)
+- Parallel across Tasks when independent
+
+## Output Format
+
+Return JSON with this exact structure:
+
+```json
+{
+  "tasks": [
+    {
+      "id": "context-0001-0001-0001",
+      "name": "User Registration API",
+      "category": "backend",
+      "description": "Create REST API endpoint for user registration with validation",
+      "technicalScope": "Express.js route handler, bcrypt password hashing, email validation",
+      "acceptance": [
+        "POST /api/register endpoint accepts email, password, name",
+        "Password is hashed with bcrypt before storage",
+        "Email format is validated",
+        "Duplicate email returns 409 error"
+      ],
+      "dependencies": [],
+      "subtasks": [
+        {
+          "id": "context-0001-0001-0001-0001",
+          "name": "Define Registration Interface",
+          "description": "Create TypeScript interface for registration request/response",
+          "technicalDetails": "Define RegisterRequest, RegisterResponse, validation rules",
+          "acceptance": [
+            "Interface exported from types/",
+            "All required fields typed correctly",
+            "JSDoc comments added"
+          ],
+          "dependencies": []
+        },
+        {
+          "id": "context-0001-0001-0001-0002",
+          "name": "Implement Registration Handler",
+          "description": "Create route handler with validation and password hashing",
+          "technicalDetails": "Express handler, bcrypt.hash, email validator, error handling",
+          "acceptance": [
+            "Handler validates all inputs",
+            "Password hashed with cost factor 10",
+            "Returns 201 on success, 400/409 on error"
+          ],
+          "dependencies": ["context-0001-0001-0001-0001"]
+        },
+        {
+          "id": "context-0001-0001-0001-0003",
+          "name": "Add Unit Tests",
+          "description": "Test registration handler with valid/invalid inputs",
+          "technicalDetails": "Jest tests, mock database, test all error paths",
+          "acceptance": [
+            "Test valid registration succeeds",
+            "Test duplicate email fails",
+            "Test invalid email fails",
+            "95% code coverage"
+          ],
+          "dependencies": ["context-0001-0001-0001-0002"]
+        }
+      ]
+    }
+  ],
+  "validation": {
+    "taskCount": 3,
+    "subtaskCount": 7,
+    "dependencyGraphValid": true,
+    "allAcceptanceCriteriaMapped": true
+  }
+}
+```
+
+## Task ID Format
+
+Use Story ID + sequential number:
+- Story 1, Task 1: `context-0001-0001-0001`
+- Story 1, Task 2: `context-0001-0001-0002`
+- Story 2, Task 1: `context-0001-0002-0001`
+
+## Subtask ID Format
+
+Use Task ID + sequential number:
+- Task 1, Subtask 1: `context-0001-0001-0001-0001`
+- Task 1, Subtask 2: `context-0001-0001-0001-0002`
+- Task 2, Subtask 1: `context-0001-0001-0002-0001`
+
+## Validation Checklist
+
+Before returning, verify:
+- [ ] 2-5 Tasks created per Story
+- [ ] Each Task has 1-3 Subtasks
+- [ ] All Story acceptance criteria mapped to Tasks
+- [ ] Dependency graph is acyclic (no circular dependencies)
+- [ ] Task categories are appropriate (backend, frontend, database, testing, infrastructure)
+- [ ] Subtask acceptance criteria are concrete and testable
+- [ ] Task names describe technical component
+- [ ] Subtask names describe atomic work unit
+- [ ] Each Subtask is truly atomic (cannot be split further)
+
+## Example Task Categories
+
+**Backend Development:**
+- API endpoints
+- Business logic services
+- Data access layer
+- Authentication/Authorization
+- Background jobs
+
+**Frontend Development:**
+- UI components
+- State management
+- API integration
+- Form handling
+- Routing
+
+**Database:**
+- Schema design
+- Migrations
+- Indexes
+- Stored procedures
+- Data seeding
+
+**Testing:**
+- Unit tests
+- Integration tests
+- E2E tests
+- Performance tests
+- Security tests
+
+**Infrastructure:**
+- Deployment configuration
+- CI/CD pipelines
+- Monitoring setup
+- Logging configuration
+- Environment variables
+
+Use appropriate categories based on the Story's technical requirements.

package/cli/agents/validator-documentation.json

@@ -0,0 +1,152 @@
+{
+  "$schema": "verification-rules-v1",
+  "agent": "validator-documentation",
+  "description": "Post-processing verification for documentation validator outputs",
+  "model": "claude-haiku-4-5",
+  "verifications": [
+    {
+      "id": "valid-json",
+      "name": "Ensure Valid JSON",
+      "enabled": true,
+      "severity": "critical",
+      "description": "Validator output must be valid JSON",
+      "fastPath": {
+        "enabled": true,
+        "type": "json-parse"
+      },
+      "check": {
+        "prompt": "Check if content is valid JSON.\n\nCONTENT:\n{content}\n\nIs this valid JSON?\n\nRespond ONLY 'YES' (if valid) or 'NO' (if invalid).",
+        "expectedResponse": "YES|NO",
+        "maxTokens": 10
+      },
+      "fix": {
+        "prompt": "Fix JSON syntax errors:\n- Missing/extra commas\n- Unquoted keys\n- Unescaped quotes\n- Trailing commas\n- Missing brackets/braces\n\nPreserve all data.\n\nCONTENT:\n{content}\n\nReturn ONLY valid JSON.",
+        "returnFormat": "json",
+        "maxTokens": 4096
+      },
+      "metadata": {
+        "category": "validation",
+        "addedVersion": "0.1.2"
+      }
+    },
+    {
+      "id": "required-fields",
+      "name": "Validate Required Fields",
+      "enabled": true,
+      "severity": "critical",
+      "description": "Must have all required fields",
+      "fastPath": {
+        "enabled": true,
+        "type": "json-fields",
+        "requiredFields": [
+          "validationStatus",
+          "overallScore",
+          "structuralIssues",
+          "contentIssues",
+          "applicationFlowGaps",
+          "strengths",
+          "improvementPriorities",
+          "readyForPublication"
+        ]
+      },
+      "check": {
+        "prompt": "Check if JSON has ALL required fields:\n- validationStatus\n- overallScore\n- structuralIssues\n- contentIssues\n- applicationFlowGaps\n- strengths\n- improvementPriorities\n- readyForPublication\n\nCONTENT:\n{content}\n\nDoes it have ALL required fields?\n\nRespond ONLY 'YES' or 'NO'.",
+        "expectedResponse": "YES|NO",
+        "maxTokens": 10
+      },
+      "fix": {
+        "prompt": "Add missing required fields with defaults:\n- validationStatus: 'needs-improvement'\n- overallScore: 50\n- structuralIssues: []\n- contentIssues: []\n- applicationFlowGaps: []\n- strengths: ['Document structure present']\n- improvementPriorities: []\n- readyForPublication: false\n\nPreserve existing fields.\n\nCONTENT:\n{content}\n\nReturn ONLY complete JSON.",
+        "returnFormat": "json",
+        "maxTokens": 4096
+      },
+      "metadata": {
+        "category": "validation",
+        "addedVersion": "0.1.2"
+      }
+    },
+    {
+      "id": "score-range",
+      "name": "Validate Score Range",
+      "enabled": true,
+      "severity": "critical",
+      "description": "overallScore must be 0-100",
+      "check": {
+        "prompt": "Check if overallScore is valid (integer 0-100).\n\nCONTENT:\n{content}\n\nIs overallScore INVALID?\n\nRespond ONLY 'YES' or 'NO'.",
+        "expectedResponse": "YES|NO",
+        "maxTokens": 10
+      },
+      "fix": {
+        "prompt": "Fix overallScore:\n- If >100, set to 100\n- If <0, set to 0\n- If not number, set to 50\n- If decimal, round to integer\n\nCONTENT:\n{content}\n\nReturn ONLY corrected JSON.",
+        "returnFormat": "json",
+        "maxTokens": 4096
+      },
+      "metadata": {
+        "category": "validation",
+        "addedVersion": "0.1.2"
+      }
+    },
+    {
+      "id": "valid-severity",
+      "name": "Validate Severity Values",
+      "enabled": true,
+      "severity": "major",
+      "description": "Severity must be critical/major/minor",
+      "check": {
+        "prompt": "Check if all severity fields use ONLY: 'critical', 'major', 'minor'\n\nInvalid: 'high', 'low', 'medium'\n\nCONTENT:\n{content}\n\nAre there invalid severity values?\n\nRespond ONLY 'YES' or 'NO'.",
+        "expectedResponse": "YES|NO",
+        "maxTokens": 10
+      },
+      "fix": {
+        "prompt": "Fix severity values:\n- 'high' → 'critical'\n- 'medium' → 'major'\n- 'low' → 'minor'\n- Other → 'major'\n\nCONTENT:\n{content}\n\nReturn ONLY corrected JSON.",
+        "returnFormat": "json",
+        "maxTokens": 4096
+      },
+      "metadata": {
+        "category": "validation",
+        "addedVersion": "0.1.2"
+      }
+    },
+    {
+      "id": "valid-status",
+      "name": "Validate Status Values",
+      "enabled": true,
+      "severity": "critical",
+      "description": "validationStatus must be needs-improvement/acceptable/excellent",
+      "check": {
+        "prompt": "Check if validationStatus is: 'needs-improvement', 'acceptable', or 'excellent'\n\nCONTENT:\n{content}\n\nIs validationStatus INVALID?\n\nRespond ONLY 'YES' or 'NO'.",
+        "expectedResponse": "YES|NO",
+        "maxTokens": 10
+      },
+      "fix": {
+        "prompt": "Fix validationStatus based on overallScore:\n- 90-100 → 'excellent'\n- 75-89 → 'acceptable'\n- 0-74 → 'needs-improvement'\n\nIf no score, use 'needs-improvement'.\n\nCONTENT:\n{content}\n\nReturn ONLY corrected JSON.",
+        "returnFormat": "json",
+        "maxTokens": 4096
+      },
+      "metadata": {
+        "category": "validation",
+        "addedVersion": "0.1.2"
+      }
+    },
+    {
+      "id": "array-fields",
+      "name": "Validate Array Fields",
+      "enabled": true,
+      "severity": "major",
+      "description": "Issue fields must be arrays",
+      "check": {
+        "prompt": "Check if these fields are ARRAYS (not strings, not objects, not null):\n- structuralIssues\n- contentIssues\n- applicationFlowGaps\n- strengths\n- improvementPriorities\n\nExamples:\n✅ \"structuralIssues\": [] (valid - empty array)\n✅ \"contentIssues\": [{...}] (valid - array of objects)\n❌ \"strengths\": \"Good structure\" (INVALID - string not array)\n❌ \"improvementPriorities\": null (INVALID - null not array)\n\nCONTENT:\n{content}\n\nAre ALL these fields proper arrays ([], [{...}])?\n\nRespond ONLY 'YES' (all are arrays) or 'NO' (one or more not array).",
+        "expectedResponse": "YES|NO",
+        "maxTokens": 10
+      },
+      "fix": {
+        "prompt": "Convert these fields to arrays:\n- structuralIssues\n- contentIssues\n- applicationFlowGaps\n- strengths\n- improvementPriorities\n\nConversion rules:\n- If missing → add empty array []\n- If null → change to []\n- If string → wrap in array [\"string\"]\n- If single object → wrap in array [{...}]\n- If already array → keep unchanged\n\nPreserve ALL other fields exactly as they are.\nPreserve ALL other content.\nReturn ONLY valid JSON (not wrapped in code fences).\n\nCONTENT:\n{content}\n\nReturn ONLY the corrected JSON.",
+        "returnFormat": "json",
+        "maxTokens": 4096
+      },
+      "metadata": {
+        "category": "validation",
+        "addedVersion": "0.1.2"
+      }
+    }
+  ]
+}