sequant 1.11.0 → 1.12.0

package/templates/skills/_shared/references/prompt-templates.md

@@ -0,0 +1,350 @@
+# Sub-Agent Prompt Templates
+
+Reference for task-specific prompt templates when spawning sub-agents via the `Task` tool during parallel execution.
+
+## Overview
+
+When spawning sub-agents for implementation tasks, use these templates to provide structured, task-specific guidance. Templates include:
+- Task-specific requirements and constraints
+- Best practices for that task type
+- Expected deliverables and reporting format
+
+## Template Selection
+
+### Automatic Selection (Keywords)
+
+The template is selected based on keywords in the task description:
+
+| Keywords | Template |
+|----------|----------|
+| `component`, `Component`, `React` | [Component Template](#component-template) |
+| `type`, `interface`, `types/` | [Type Definition Template](#type-definition-template) |
+| `CLI`, `command`, `script`, `bin/` | [CLI/Script Template](#cliscript-template) |
+| `test`, `spec`, `.test.` | [Test Template](#test-template) |
+| `refactor`, `restructure`, `migrate` | [Refactor Template](#refactor-template) |
+| (none matched) | [Generic Template](#generic-template) |
+
+### Explicit Annotation Override
+
+You can force a specific template using the `[template: X]` annotation at the start of the task:
+
+```
+[template: component] Create UserCard in components/admin/
+[template: cli] Add export command to scripts/
+[template: type] Define MetricEvent interface
+```
+
+**Annotation takes precedence** over keyword detection.
+
+---
+
+## Task Templates
+
+### Component Template
+
+**Use for:** React components, UI elements, admin panels
+
+```markdown
+## Task: Create React Component
+
+**Component:** [name]
+**Location:** [path]
+
+**Requirements:**
+- [ ] TypeScript with proper prop types (interface or type)
+- [ ] Follow existing component patterns in the codebase
+- [ ] Include displayName for debugging: `Component.displayName = 'ComponentName'`
+- [ ] No inline styles - use existing CSS/Tailwind patterns
+- [ ] Export component as named export
+
+**Best Practices:**
+- Check `components/` for similar components to follow patterns
+- Use existing hooks from `lib/hooks/` if applicable
+- Prefer composition over prop drilling
+- Keep components focused - single responsibility
+
+**Constraints:**
+- Working directory: [worktree path]
+- Do NOT create test files (handled separately)
+- Do NOT add new dependencies without explicit approval
+
+**Deliverable:**
+Report: files created, component name, props interface
+```
+
+---
+
+### Type Definition Template
+
+**Use for:** TypeScript types, interfaces, enums, type utilities
+
+```markdown
+## Task: Create Type Definitions
+
+**File:** [path]
+**Types needed:** [list]
+
+**Requirements:**
+- [ ] Export all types (no internal-only types)
+- [ ] Use strict types - avoid `any`, prefer `unknown` if needed
+- [ ] Add JSDoc comments for complex types explaining purpose
+- [ ] Match database schema if types represent DB entities
+- [ ] Use consistent naming: `PascalCase` for types/interfaces
+
+**Best Practices:**
+- Check `types/` for existing type patterns
+- Prefer interfaces for object shapes (extendable)
+- Use type aliases for unions, intersections, utilities
+- Export from index file if creating new type module
+
+**Constraints:**
+- Working directory: [worktree path]
+- Verify types compile: `npx tsc --noEmit [file]`
+
+**Deliverable:**
+Report: types created, file path, any dependencies on other types
+```
+
+---
+
+### CLI/Script Template
+
+**Use for:** CLI commands, scripts, automation tools
+
+```markdown
+## Task: Implement CLI Command/Script
+
+**Command:** [name]
+**File:** [path]
+
+**Requirements:**
+- [ ] Use commander.js patterns from existing commands (if CLI)
+- [ ] Include descriptive --help text
+- [ ] Handle errors gracefully with appropriate exit codes
+- [ ] Add to command index if this is a new CLI command
+- [ ] Support both programmatic and CLI usage if applicable
+
+**Best Practices:**
+- Check `scripts/` or `src/cli/` for existing patterns
+- Use `process.exit(0)` for success, `process.exit(1)` for errors
+- Log errors to stderr: `console.error()`
+- Provide progress feedback for long-running operations
+
+**Constraints:**
+- Working directory: [worktree path]
+- Scripts should be executable: `chmod +x [file]`
+- Add shebang for shell scripts: `#!/usr/bin/env bash` or `#!/usr/bin/env node`
+
+**Deliverable:**
+Report: script created, command usage, exit codes
+```
+
+---
+
+### Test Template
+
+**Use for:** Unit tests, integration tests, test utilities
+
+```markdown
+## Task: Create Tests
+
+**Test file:** [path]
+**Testing:** [component/module being tested]
+
+**Requirements:**
+- [ ] Use existing test framework patterns (vitest/jest)
+- [ ] Include setup and teardown if needed
+- [ ] Test both success and error cases
+- [ ] Use descriptive test names: `it('should X when Y')`
+- [ ] Mock external dependencies appropriately
+
+**Best Practices:**
+- Check `__tests__/` or `*.test.ts` files for patterns
+- Group related tests with `describe()` blocks
+- Test behavior, not implementation details
+- Aim for meaningful coverage, not 100% line coverage
+
+**Constraints:**
+- Working directory: [worktree path]
+- Run tests after creation: `npm test [file]`
+- Do NOT skip or disable existing tests
+
+**Deliverable:**
+Report: test file created, number of test cases, pass/fail status
+```
+
+---
+
+### Refactor Template
+
+**Use for:** Code restructuring, file reorganization, pattern migrations
+
+```markdown
+## Task: Refactor Code
+
+**Target:** [file or module]
+**Goal:** [what the refactor achieves]
+
+**Requirements:**
+- [ ] Preserve all existing functionality (no behavior changes)
+- [ ] Maintain or improve type safety
+- [ ] Update all imports/exports affected by moves
+- [ ] Ensure tests still pass after refactor
+
+**Best Practices:**
+- Make incremental changes, verify after each step
+- Use IDE rename features when available
+- Update barrel exports (index.ts) if file locations change
+- Check for circular dependencies after restructuring
+
+**Constraints:**
+- Working directory: [worktree path]
+- Run full test suite after refactor: `npm test`
+- Run type check: `npx tsc --noEmit`
+
+**Deliverable:**
+Report: files changed, imports updated, test results
+```
+
+---
+
+### Generic Template
+
+**Use for:** Tasks that don't fit other categories
+
+```markdown
+## Task: [Task Description]
+
+**Goal:** [what needs to be accomplished]
+**Files involved:** [expected files]
+
+**Requirements:**
+- [ ] Complete the task as specified
+- [ ] Follow existing codebase patterns
+- [ ] Maintain type safety
+- [ ] Do not break existing functionality
+
+**Constraints:**
+- Working directory: [worktree path]
+- Run relevant checks after completion
+
+**Deliverable:**
+Report: files created/modified, summary of changes
+```
+
+---
+
+## Error Recovery Template
+
+**Use for:** Retrying failed tasks with enhanced context
+
+When a task fails, use this template to provide diagnostic context for the retry:
+
+```markdown
+## RETRY: Previous Attempt Failed
+
+**Original Task:** [task description]
+**Attempt:** [N] of [max]
+**Previous Error:**
+```
+[error message from TaskOutput]
+```
+
+**Diagnosis Checklist:**
+- [ ] Check imports are correct and files exist
+- [ ] Verify file paths use the worktree directory
+- [ ] Confirm types match expected signatures
+- [ ] Look for typos in identifiers
+- [ ] Check for missing dependencies
+
+**Fix Strategy:**
+1. Read the failing file to understand current state
+2. Identify the specific error location (line number if available)
+3. Apply minimal, targeted fix
+4. Verify fix compiles: `npx tsc --noEmit [file]`
+
+**Critical Constraints (re-emphasized):**
+- You MUST use the worktree path: [worktree path]
+- Do NOT edit files outside the worktree
+- Complete the task with fewer tool calls than previous attempt
+- If the same error occurs, report it clearly rather than retrying
+
+**Deliverable:**
+Report: fix applied, verification result, files changed
+```
+
+---
+
+## Template Customization
+
+### Adding New Templates
+
+To add a custom template:
+
+1. Define the template in this file following the structure above
+2. Add keywords for automatic selection to the keyword table
+3. Document the use case and best practices
+
+### Overriding Templates
+
+Projects can override templates by:
+
+1. Creating `.claude/skills/_shared/references/prompt-templates.local.md`
+2. Defining custom templates with the same headers
+3. Local templates take precedence over defaults
+
+### Template Variables
+
+Templates support these placeholders:
+
+| Variable | Description |
+|----------|-------------|
+| `[name]` | Component/module name from task |
+| `[path]` | File path from task |
+| `[worktree path]` | Current worktree directory |
+| `[task description]` | Original task text |
+
+---
+
+## Usage Example
+
+**Task:** "Create MetricsCard component in components/admin/metrics/"
+
+**Keyword detected:** "component" → Component Template
+
+**Rendered prompt:**
+```markdown
+## Task: Create React Component
+
+**Component:** MetricsCard
+**Location:** components/admin/metrics/MetricsCard.tsx
+
+**Requirements:**
+- [ ] TypeScript with proper prop types (interface or type)
+- [ ] Follow existing component patterns in the codebase
+- [ ] Include displayName for debugging: `MetricsCard.displayName = 'MetricsCard'`
+- [ ] No inline styles - use existing CSS/Tailwind patterns
+- [ ] Export component as named export
+
+**Best Practices:**
+- Check `components/` for similar components to follow patterns
+- Use existing hooks from `lib/hooks/` if applicable
+- Prefer composition over prop drilling
+- Keep components focused - single responsibility
+
+**Constraints:**
+- Working directory: /path/to/worktrees/feature/123-metrics/
+- Do NOT create test files (handled separately)
+- Do NOT add new dependencies without explicit approval
+
+**Deliverable:**
+Report: files created, component name, props interface
+```
+
+---
+
+## References
+
+- [Subagent Types](./subagent-types.md) - Valid subagent types for Task tool
+- `/exec` skill - Parallel execution documentation
+- `/spec` skill - Parallel groups format

package/templates/skills/_shared/references/subagent-types.md

@@ -0,0 +1,131 @@
+# Claude Code Subagent Types
+
+Reference for valid subagent types when spawning agents via the `Task` tool.
+
+## Valid Types
+
+Claude Code supports exactly **4 subagent types**:
+
+| Type | Purpose | Tools Available |
+|------|---------|-----------------|
+| `Bash` | Command execution, git operations, terminal tasks | Bash only |
+| `general-purpose` | Multi-step tasks needing file access + commands | All tools |
+| `Explore` | Codebase exploration, file search, pattern finding | Read-only tools |
+| `Plan` | Architecture planning, implementation design | Read-only tools |
+
+## When to Use Each
+
+### `Bash`
+Best for: Single command execution, git operations, build commands
+
+```
+Task(subagent_type="Bash", prompt="Run npm test and report results")
+```
+
+### `general-purpose`
+Best for: Implementation tasks, quality checks, multi-file operations
+
+```
+Task(subagent_type="general-purpose",
+     prompt="Run type safety checks on the diff. Report: type issues, verdict.")
+```
+
+**Use cases:**
+- Quality checks (type safety, security scan, scope analysis)
+- Implementation tasks requiring edits
+- Tasks needing both file reading and command execution
+
+### `Explore`
+Best for: Codebase search, pattern discovery, schema inspection
+
+```
+Task(subagent_type="Explore",
+     prompt="Find similar components in components/admin/. Report patterns.")
+```
+
+**Use cases:**
+- Finding existing patterns before implementing new features
+- Searching for file locations
+- Understanding codebase structure
+- Schema and database inspection
+
+### `Plan`
+Best for: Designing implementation approaches, architectural decisions
+
+```
+Task(subagent_type="Plan",
+     prompt="Design the implementation approach for adding user auth.")
+```
+
+**Use cases:**
+- Creating implementation plans
+- Evaluating architectural trade-offs
+- Breaking down complex features
+
+## Model Selection
+
+| Model | When to Use | Cost |
+|-------|-------------|------|
+| `haiku` | Quick tasks, exploration, quality checks | Low |
+| `sonnet` | Complex implementation, nuanced decisions | Medium |
+| `opus` | Critical analysis, complex architecture | High |
+
+**Default:** Use `haiku` unless the task requires deep reasoning.
+
+```
+Task(subagent_type="general-purpose",
+     model="haiku",
+     prompt="...")
+```
+
+## Common Patterns
+
+### Parallel Quality Checks
+```
+Task(subagent_type="general-purpose", model="haiku",
+     prompt="Check type safety on diff vs main. Report issues count.")
+
+Task(subagent_type="general-purpose", model="haiku",
+     prompt="Check for deleted tests in diff. Report count.")
+
+Task(subagent_type="general-purpose", model="haiku",
+     prompt="Run security scan on changed files. Report findings.")
+```
+
+### Context Gathering (Spec Phase)
+```
+Task(subagent_type="Explore", model="haiku",
+     prompt="Find similar features in components/. Report patterns.")
+
+Task(subagent_type="Explore", model="haiku",
+     prompt="Explore database schema for user tables. Report structure.")
+```
+
+### Background Execution
+```
+Task(subagent_type="general-purpose",
+     model="haiku",
+     run_in_background=true,
+     prompt="Implement the UserCard component...")
+```
+
+Use `TaskOutput(task_id="...", block=true)` to wait for completion.
+
+## Invalid Types (Do Not Use)
+
+These types do **not exist** and will cause silent failures:
+
+- ~~`quality-checker`~~ → Use `general-purpose`
+- ~~`pattern-scout`~~ → Use `Explore`
+- ~~`schema-inspector`~~ → Use `Explore`
+- ~~`code-reviewer`~~ → Use `general-purpose`
+- ~~`implementation`~~ → Use `general-purpose`
+
+See issue #170 for context on this fix.
+
+## References
+
+- [Claude Code Task Tool Documentation](https://docs.anthropic.com/claude-code)
+- [Prompt Templates](./prompt-templates.md) - Task-specific prompt templates for sub-agents
+- `/exec` skill parallel execution: `templates/skills/exec/SKILL.md`
+- `/qa` skill quality checks: `templates/skills/qa/SKILL.md`

package/templates/skills/exec/SKILL.md

@@ -497,6 +497,7 @@ Fall back to sequential execution (standard implementation loop).
 - Run Prettier on all modified files after each group (agents skip auto-format)
 - On any agent failure: stop remaining agents, log error, continue with sequential
 - File locking prevents concurrent edits to the same file
+- **Use prompt templates** for each agent — see [Section 4c](#4c-prompt-templates-for-sub-agents)
 
 **Error Handling with Automatic Retry:**
 
@@ -536,6 +537,87 @@ Parse the agent's output text for these patterns to detect failures:
 | `blocked by hook` | Operation was blocked by pre-tool hook |
 | `I'm unable to` | Agent hit a blocking constraint |
 
+### 4c. Prompt Templates for Sub-Agents
+
+When spawning sub-agents for implementation tasks, use task-specific prompt templates for better results. See [prompt-templates.md](../_shared/references/prompt-templates.md) for the full reference.
+
+**Template Selection:**
+
+Templates are selected automatically based on keywords in the task description:
+
+| Keywords | Template |
+|----------|----------|
+| `component`, `Component`, `React` | Component Template |
+| `type`, `interface`, `types/` | Type Definition Template |
+| `CLI`, `command`, `script`, `bin/` | CLI/Script Template |
+| `test`, `spec`, `.test.` | Test Template |
+| `refactor`, `restructure`, `migrate` | Refactor Template |
+| (none matched) | Generic Template |
+
+**Explicit Override:**
+
+Use `[template: X]` annotation to force a specific template:
+
+```
+[template: component] Create UserCard in components/admin/
+[template: cli] Add export command to scripts/
+```
+
+**Example with Template:**
+
+Instead of a generic prompt:
+```
+Task(subagent_type="general-purpose",
+     model="haiku",
+     prompt="Create MetricsCard component in components/admin/")
+```
+
+Use a structured template prompt:
+```
+Task(subagent_type="general-purpose",
+     model="haiku",
+     prompt="## Task: Create React Component
+
+**Component:** MetricsCard
+**Location:** components/admin/metrics/MetricsCard.tsx
+
+**Requirements:**
+- [ ] TypeScript with proper prop types
+- [ ] Follow existing component patterns
+- [ ] Include displayName for debugging
+- [ ] No inline styles
+
+**Constraints:**
+- Working directory: [worktree path]
+- Do NOT create test files
+
+**Deliverable:**
+Report: files created, component name, props interface")
+```
+
+**Error Recovery with Enhanced Context:**
+
+When retrying a failed agent, use the error recovery template from [prompt-templates.md](../_shared/references/prompt-templates.md#error-recovery-template):
+
+```markdown
+## RETRY: Previous Attempt Failed
+
+**Original Task:** [task]
+**Previous Error:** [error from TaskOutput]
+
+**Diagnosis Checklist:**
+- [ ] Check imports are correct
+- [ ] Verify file paths use worktree directory
+- [ ] Confirm types match expected signatures
+- [ ] Look for typos in identifiers
+
+**Fix Strategy:**
+1. Read the failing file
+2. Identify the specific error location
+3. Apply minimal fix
+4. Verify fix compiles
+```
+
 ## Implementation Quality Standards
 
 Before each commit, self-check against these standards:

package/templates/skills/fullsolve/SKILL.md

@@ -328,7 +328,16 @@ while qa_iteration < 2:
     if verdict == "READY_FOR_MERGE":
         break
 
-    # Parse issues
+    if verdict == "AC_MET_BUT_NOT_A_PLUS":
+        # Good enough, proceed with notes
+        break
+
+    if verdict == "NEEDS_VERIFICATION":
+        # ACs are met but pending external verification
+        # Proceed to PR - verification can happen post-PR
+        break
+
+    # Parse issues (AC_NOT_MET)
     issues = parse_qa_issues()
 
     # Fix each issue
@@ -430,6 +439,13 @@ Track iterations to prevent infinite loops:
 - QA verdict: `AC_MET_BUT_NOT_A_PLUS`
 - PR created with notes
 
+**Pending Verification:**
+
+- All AC met or pending
+- External verification required (CI, manual test)
+- QA verdict: `NEEDS_VERIFICATION`
+- PR created, verification can happen post-PR
+
 **Failure (manual intervention needed):**
 - Max iterations reached on test or QA loop
 - Blockers discovered
@@ -584,7 +600,8 @@ Each issue gets its own worktree, PR, and quality validation.
 - [ ] **AC Coverage** - Each AC marked MET/PARTIALLY_MET/NOT_MET
 - [ ] **Quality Metrics** - Tests passed, build status, type issues
 - [ ] **Iteration Summary** - Test loop and QA loop iteration counts
-- [ ] **Final Verdict** - READY_FOR_MERGE, AC_MET_BUT_NOT_A_PLUS, or AC_NOT_MET
+- [ ] **Final Verdict** - READY_FOR_MERGE, AC_MET_BUT_NOT_A_PLUS, NEEDS_VERIFICATION,
+  or AC_NOT_MET
 - [ ] **PR Link** - Pull request URL (if created)
 - [ ] **Final GitHub Comment** - Summary posted to issue
 

package/templates/skills/loop/SKILL.md

@@ -54,7 +54,8 @@ cat /tmp/claude-issue-<issue-number>.log
 
 Parse the log to find:
 - **Last phase executed:** `/test` or `/qa`
-- **Verdict:** `READY_FOR_MERGE`, `AC_NOT_MET`, `AC_MET_BUT_NOT_A_PLUS`
+- **Verdict:** `READY_FOR_MERGE`, `AC_MET_BUT_NOT_A_PLUS`, `NEEDS_VERIFICATION`,
+  or `AC_NOT_MET`
 - **Test results:** PASS/FAIL/BLOCKED counts
 - **Issues to fix:** Numbered recommendations or bug descriptions
 
@@ -87,6 +88,7 @@ Extract:
 
 **Exit loop if:**
 - Verdict is `READY_FOR_MERGE` - Nothing to fix!
+- Verdict is `NEEDS_VERIFICATION` - Pending external verification
 - No actionable issues found
 - Max iterations reached (3 by default)