sequant 1.11.0 → 1.13.0

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)
 

package/templates/skills/qa/SKILL.md

@@ -16,6 +16,9 @@ allowed-tools:
   - Bash(gh pr view:*)
   - Bash(gh pr diff:*)
   - Bash(gh pr comment:*)
+  - Bash(semgrep:*)
+  - Bash(npx semgrep:*)
+  - Bash(npx tsx scripts/semgrep-scan.ts:*)
   - Task
   - AgentOutputTool
 ---
@@ -120,11 +123,11 @@ If no feature worktree exists (work was done directly on main):
 
 **Spawn ALL THREE agents in a SINGLE message:**
 
-1. `Task(subagent_type="quality-checker", model="haiku", prompt="Run type safety and deleted tests checks on the current branch vs main. Report: type issues count, deleted tests, verdict.")`
+1. `Task(subagent_type="general-purpose", model="haiku", prompt="Run type safety and deleted tests checks on the current branch vs main. Report: type issues count, deleted tests, verdict.")`
 
-2. `Task(subagent_type="quality-checker", model="haiku", prompt="Run scope and size checks on the current branch vs main. Report: files count, diff size, size assessment.")`
+2. `Task(subagent_type="general-purpose", model="haiku", prompt="Run scope and size checks on the current branch vs main. Report: files count, diff size, size assessment.")`
 
-3. `Task(subagent_type="quality-checker", model="haiku", prompt="Run security scan on changed files in current branch vs main. Report: critical/warning/info counts, verdict.")`
+3. `Task(subagent_type="general-purpose", model="haiku", prompt="Run security scan on changed files in current branch vs main. Report: critical/warning/info counts, verdict.")`
 
 **Add RLS check if admin files modified:**
 ```bash
@@ -133,10 +136,52 @@ admin_modified=$(git diff main...HEAD --name-only | grep -E "^app/admin/" | head
 
 See [quality-gates.md](references/quality-gates.md) for detailed verdict synthesis.
 
-### Using MCP Tools (Optional)
+### MCP Tools (Optional - Graceful Degradation)
 
-- **Sequential Thinking:** For complex multi-step analysis
-- **Context7:** For broader pattern context and library documentation
+MCP tools enhance `/qa` but are **not required**. The skill works fully without them.
+
+#### MCP Availability Check
+
+Before using MCP tools, verify they are available. If unavailable, use the fallback strategies.
+
+| MCP Tool | Purpose | Fallback When Unavailable |
+|----------|---------|---------------------------|
+| Sequential Thinking | Complex multi-step analysis | Use explicit step-by-step reasoning in response |
+| Context7 | Library documentation lookup | Use WebSearch or codebase pattern search |
+
+#### Sequential Thinking Fallback
+
+**When to use Sequential Thinking:**
+- Complex architectural trade-offs during code review
+- Multi-dimensional quality assessment
+- Analyzing interconnected issues across files
+
+**If unavailable:**
+1. Structure your analysis with explicit numbered steps
+2. Document each concern systematically before synthesizing verdict
+3. Use a pros/cons format for trade-off decisions
+
+```markdown
+## Analysis Steps (Manual Sequential Thinking)
+
+**Step 1:** [Analyze first dimension - correctness]
+**Step 2:** [Analyze second dimension - maintainability]
+**Step 3:** [Analyze third dimension - performance]
+**Step 4:** [Synthesize findings into verdict]
+```
+
+#### Context7 Fallback
+
+**When to use Context7:**
+- Verifying implementation matches library best practices
+- Checking if API usage follows recommended patterns
+- Understanding framework-specific conventions in reviewed code
+
+**If unavailable:**
+1. Search codebase with Grep for existing usage patterns
+2. Use WebSearch for official library documentation
+3. Check similar implementations in the codebase as reference
+4. Review library's README or documentation in node_modules
 
 ### 1. Context and AC Alignment
 
@@ -180,9 +225,32 @@ See [testing-requirements.md](references/testing-requirements.md) for edge case
 
 Provide an overall verdict:
 
-- `READY_FOR_MERGE` — AC met and code quality is high ("A+")
-- `AC_MET_BUT_NOT_A_PLUS` — AC met, but meaningful improvements recommended
-- `AC_NOT_MET` — AC not fully met; additional implementation needed
+- `READY_FOR_MERGE` — ALL ACs are `MET` and code quality is high ("A+")
+- `AC_MET_BUT_NOT_A_PLUS` — ALL ACs are `MET`, but meaningful improvements recommended
+- `NEEDS_VERIFICATION` — ALL ACs are `MET` or `PENDING`, at least one requires external verification
+- `AC_NOT_MET` — One or more ACs are `NOT_MET` or `PARTIALLY_MET`
+
+**Verdict Determination Algorithm (REQUIRED):**
+
+```text
+1. Count AC statuses:
+   - met_count = ACs with status MET
+   - partial_count = ACs with status PARTIALLY_MET
+   - pending_count = ACs with status PENDING
+   - not_met_count = ACs with status NOT_MET
+
+2. Determine verdict (in order):
+   - IF not_met_count > 0 OR partial_count > 0:
+       → AC_NOT_MET (block merge)
+   - ELSE IF pending_count > 0:
+       → NEEDS_VERIFICATION (wait for verification)
+   - ELSE IF improvement_suggestions.length > 0:
+       → AC_MET_BUT_NOT_A_PLUS (can merge with notes)
+   - ELSE:
+       → READY_FOR_MERGE (A+ implementation)
+```
+
+**CRITICAL:** `PARTIALLY_MET` is NOT sufficient for merge. It MUST be treated as `NOT_MET` for verdict purposes.
 
 See [quality-gates.md](references/quality-gates.md) for detailed verdict criteria.
 
@@ -221,9 +289,11 @@ Produce a Markdown snippet for the PR/issue:
 ### 7. Update GitHub Issue
 
 Post the draft comment to GitHub and update labels:
+
 - `AC_NOT_MET`: add `needs-work` label
 - `READY_FOR_MERGE`: add `ready-for-review` label
 - `AC_MET_BUT_NOT_A_PLUS`: add `needs-improvement` label
+- `NEEDS_VERIFICATION`: add `needs-verification` label
 
 ### 8. Documentation Reminder
 

package/templates/skills/qa/references/quality-gates.md

@@ -9,14 +9,56 @@ Combine agent outputs into a unified quality assessment:
 | Type Safety Checker | Type issues count, verdict | High - blocking if issues > 3 |
 | Scope/Size Checker | Files changed, LOC, assessment | Medium - warning if very large |
 | Security Scanner | Critical/warning/info counts | High - blocking if criticals > 0 |
+| Semgrep Static Analysis | Critical/warning findings | High - blocking if criticals > 0 |
 | RLS Checker (conditional) | Violations found | High - blocking if violations |
 
 **Synthesis Rules:**
 - **Any FAIL verdict** → Flag as blocker in manual review
-- **Security criticals** → Block merge, require fix before proceeding
+- **Security criticals (including Semgrep)** → Block merge, require fix before proceeding
 - **All PASS** → Proceed with confidence to manual review
 - **WARN verdicts** → Note in review, verify manually
 
+## Semgrep Integration
+
+Semgrep provides static analysis for security vulnerabilities and anti-patterns.
+
+### Verdict Mapping
+
+| Semgrep Result | QA Verdict Impact |
+|----------------|-------------------|
+| Critical findings > 0 | **BLOCKING** - `AC_NOT_MET` |
+| Warning findings only | Non-blocking - note in review |
+| No findings | Pass - no impact |
+| Semgrep not installed | Skipped - graceful degradation |
+| Semgrep error | Non-blocking - log error |
+
+### Output Format
+
+```markdown
+## Static Analysis (Semgrep)
+
+✅ No critical findings
+⚠️ 2 warnings:
+  - src/api/users.ts:47 - Potential SQL injection (user input in query)
+  - src/utils/exec.ts:12 - Command injection risk (unsanitized shell arg)
+```
+
+### Stack-Aware Rulesets
+
+Semgrep uses stack-specific rulesets for targeted analysis:
+
+| Stack | Rulesets |
+|-------|----------|
+| Next.js | p/typescript, p/javascript, p/react, p/security-audit, p/secrets |
+| Python | p/python, p/django, p/flask, p/security-audit, p/secrets |
+| Go | p/golang, p/security-audit, p/secrets |
+| Rust | p/rust, p/security-audit, p/secrets |
+| Generic | p/security-audit, p/secrets |
+
+### Custom Rules
+
+Projects can add custom rules in `.sequant/semgrep-rules.yaml`. These are loaded alongside stack rules automatically.
+
 ## Verdict Criteria
 
 ### `READY_FOR_MERGE`
@@ -43,6 +85,17 @@ AC met, but one or more issues:
 
 **Action:** List specific improvements, but don't block merge if working
 
+### `NEEDS_VERIFICATION`
+
+All AC items are `MET`, but one or more items have `PENDING` status requiring external verification:
+
+- ⏳ CI/CD verification pending
+- ⏳ Manual testing not yet performed
+- ⏳ External dependency verification needed
+- ⏳ Production environment validation required
+
+**Action:** Complete pending verification, then re-run `/qa`
+
 ### `AC_NOT_MET`
 
 Any of:
@@ -55,6 +108,37 @@ Any of:
 
 **Action:** Block merge, list required fixes
 
+## Verdict Determination Algorithm
+
+**CRITICAL:** Follow this algorithm exactly when determining the verdict. Do NOT give `READY_FOR_MERGE` unless ALL conditions are met.
+
+```text
+1. Count AC statuses:
+   - met_count = ACs with status MET
+   - partial_count = ACs with status PARTIALLY_MET
+   - pending_count = ACs with status PENDING
+   - not_met_count = ACs with status NOT_MET
+
+2. Determine verdict (in order):
+   - IF not_met_count > 0 OR partial_count > 0:
+       → AC_NOT_MET (block merge)
+   - ELSE IF pending_count > 0:
+       → NEEDS_VERIFICATION (wait for verification)
+   - ELSE IF improvement_suggestions.length > 0:
+       → AC_MET_BUT_NOT_A_PLUS (can merge with notes)
+   - ELSE:
+       → READY_FOR_MERGE (A+ implementation)
+```
+
+| Verdict                  | When to Use                                              |
+|--------------------------|----------------------------------------------------------|
+| `READY_FOR_MERGE`        | ALL ACs are `MET`, no improvements needed                |
+| `AC_MET_BUT_NOT_A_PLUS`  | ALL ACs are `MET`, but minor improvements suggested      |
+| `NEEDS_VERIFICATION`     | ALL ACs are `MET` or `PENDING`, at least one is `PENDING`|
+| `AC_NOT_MET`             | ANY AC is `NOT_MET` or `PARTIALLY_MET`                   |
+
+**Important:** `PARTIALLY_MET` is NOT sufficient for merge. It must be treated as `NOT_MET` for verdict purposes.
+
 ## Code Review Decision Framework
 
 ### 1. Purpose Test