sequant 2.0.0 → 2.1.0

package/templates/skills/testgen/SKILL.md

@@ -17,7 +17,7 @@ allowed-tools:
   - Bash(git worktree list:*)
   - Bash(ls:*)
   - Bash(mkdir:*)
-  - Task(general-purpose)
+  - Agent(sequant-testgen)
 ---
 
 # Test Generation Command
@@ -39,6 +39,116 @@ When invoked as `/testgen <issue-number>`, your job is to:
 - `/testgen 123` - Generate test stubs for issue #123 based on /spec comment
 - `/testgen` - Generate stubs for the most recently discussed issue in conversation
 
+## Token Optimization with Haiku Sub-Agents
+
+**Purpose:** Test stub generation is highly mechanical and benefits from using haiku sub-agents to minimize token cost.
+
+**Pattern:** Use `Agent(subagent_type="sequant-testgen")` for:
+1. Parsing verification criteria from /spec comments
+2. Generating individual test stubs from templates
+3. Writing test file content
+
+**Benefits:**
+- 90% token cost reduction for mechanical generation
+- Faster execution for templated operations
+- Main agent focuses on orchestration and decisions
+
+### Sub-Agent Usage
+
+**Step 1: Parse Verification Criteria (use haiku)**
+
+```javascript
+Agent(subagent_type="sequant-testgen", prompt=`
+Parse the following /spec comment and extract verification criteria.
+
+For each AC, extract:
+- AC number and description
+- Verification method (Unit Test, Integration Test, Browser Test, Manual Test)
+- Test scenario (Given/When/Then)
+- Integration points
+- Assumptions to validate
+
+Return as JSON:
+{
+  "criteria": [
+    {
+      "acNumber": "AC-1",
+      "description": "...",
+      "verificationMethod": "Unit Test",
+      "scenario": { "given": "...", "when": "...", "then": "..." },
+      "integrationPoints": ["..."],
+      "assumptions": ["..."]
+    }
+  ]
+}
+
+/spec comment:
+${specComment}
+`)
+```
+
+**Step 2: Generate Test Stubs (use haiku for each AC)**
+
+```javascript
+// For each AC with Unit Test or Integration Test verification method
+Agent(subagent_type="sequant-testgen", prompt=`
+Generate a Jest test stub for the following verification criteria.
+
+AC: ${ac.acNumber}: ${ac.description}
+Verification Method: ${ac.verificationMethod}
+Test Scenario:
+- Given: ${ac.scenario.given}
+- When: ${ac.scenario.when}
+- Then: ${ac.scenario.then}
+
+Use the template format:
+- Include Given/When/Then as comments
+- Add TODO markers where implementation is needed
+- Include failure path stubs based on the action verb
+- Use throw new Error('Test stub - implement this test')
+
+Return ONLY the test code, no explanation.
+`)
+```
+
+**Step 3: Write Test Files (main agent)**
+
+The main agent handles file operations to ensure proper coordination:
+- Check if files exist (don't overwrite)
+- Create directories if needed
+- Write generated stubs to correct locations
+
+### When to Use Sub-Agents vs Main Agent
+
+| Task | Agent | Reasoning |
+|------|-------|-----------|
+| Parse /spec comment | haiku | Mechanical text extraction |
+| Generate test stub code | haiku | Templated generation |
+| Identify failure scenarios | haiku | Pattern matching |
+| Decide file locations | main | Requires codebase context |
+| Write files | main | File system coordination |
+| Post GitHub comment | main | Session context needed |
+
+### Parallel Sub-Agent Execution
+
+When multiple ACs need test stubs, spawn haiku agents in parallel:
+
+```javascript
+// Spawn all stub generation agents in a single message
+const stubPromises = criteria
+  .filter(ac => ac.verificationMethod === 'Unit Test' || ac.verificationMethod === 'Integration Test')
+  .map(ac => Agent(subagent_type="sequant-testgen", prompt=`Generate test stub for ${ac.acNumber}...`))
+
+// Collect results
+// Main agent writes all files
+```
+
+**Cost savings example:**
+- 5 AC items with Unit Test verification
+- Without haiku: ~50K tokens (main agent generates all)
+- With haiku: ~5K tokens (main orchestrates, haiku generates)
+- Savings: ~90%
+
 ## Workflow
 
 ### Step 1: Read Verification Criteria from GitHub Issue
@@ -562,6 +672,33 @@ Generated with [Claude Code](https://claude.com/claude-code)
 
 ---
 
+## State Tracking
+
+**IMPORTANT:** Update workflow state when running standalone (not orchestrated).
+
+### State Updates (Standalone Only)
+
+When NOT orchestrated (`SEQUANT_ORCHESTRATOR` is not set):
+
+**At skill start:**
+```bash
+npx tsx scripts/state/update.ts start <issue-number> testgen
+```
+
+**On successful completion:**
+```bash
+npx tsx scripts/state/update.ts complete <issue-number> testgen
+```
+
+**On failure:**
+```bash
+npx tsx scripts/state/update.ts fail <issue-number> testgen "Failed to generate test stubs"
+```
+
+**Note:** `/testgen` is an optional skill that generates test stubs. State tracking is informational - it doesn't block subsequent phases.
+
+---
+
 ## Output Verification
 
 **Before responding, verify your output includes ALL of these:**