sequant 2.0.1 → 2.1.1

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

@@ -1,10 +1,10 @@
 # Claude Code Subagent Types
 
-Reference for valid subagent types when spawning agents via the `Task` tool.
+Reference for valid subagent types when spawning agents via the `Agent` tool.
 
-## Valid Types
+## Built-in Types
 
-Claude Code supports exactly **4 subagent types**:
+Claude Code supports exactly **4 built-in subagent types**:
 
 | Type | Purpose | Tools Available |
 |------|---------|-----------------|
@@ -13,55 +13,122 @@ Claude Code supports exactly **4 subagent types**:
 | `Explore` | Codebase exploration, file search, pattern finding | Read-only tools |
 | `Plan` | Architecture planning, implementation design | Read-only tools |
 
-## When to Use Each
+## Custom Agents (Sequant)
 
-### `Bash`
-Best for: Single command execution, git operations, build commands
+Sequant defines **4 custom agents** in `.claude/agents/`. These centralize model, permissions, effort, and tool restrictions that were previously duplicated inline.
+
+| Agent Name | Based On | Model | Permission Mode | Used By |
+|------------|----------|-------|-----------------|---------|
+| `sequant-explorer` | Explore | haiku | (default) | `/spec` |
+| `sequant-qa-checker` | general-purpose | haiku | bypassPermissions | `/qa` |
+| `sequant-implementer` | general-purpose | (inherits) | bypassPermissions | `/exec` |
+| `sequant-testgen` | general-purpose | haiku | (default) | `/testgen` |
+
+### sequant-explorer
+
+Read-only codebase exploration for the `/spec` phase. No Bash, Edit, or Write access.
 
 ```
-Task(subagent_type="Bash", prompt="Run npm test and report results")
+Agent(subagent_type="sequant-explorer",
+     prompt="Find similar features in components/. Report patterns.")
 ```
 
-### `general-purpose`
-Best for: Implementation tasks, quality checks, multi-file operations
+### sequant-qa-checker
+
+Quality check agent for the `/qa` phase. Has `bypassPermissions` for Bash access (git diff, npm test). Effort: low.
 
 ```
-Task(subagent_type="general-purpose",
+Agent(subagent_type="sequant-qa-checker",
      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
+### sequant-implementer
+
+Implementation agent for `/exec` parallel groups. Inherits model from parent (user-configurable). Has `bypassPermissions` for full tool access.
+
+```
+Agent(subagent_type="sequant-implementer",
+     prompt="Implement the UserCard component in components/admin/...")
+```
+
+### sequant-testgen
 
-### `Explore`
-Best for: Codebase search, pattern discovery, schema inspection
+Test stub generator for the `/testgen` phase. Has Write access but no Bash access.
 
 ```
-Task(subagent_type="Explore",
-     prompt="Find similar components in components/admin/. Report patterns.")
+Agent(subagent_type="sequant-testgen",
+     prompt="Generate test stubs for AC-1: User authentication...")
+```
+
+### Agent Definition Location
+
+Custom agents are defined in `.claude/agents/*.md` with YAML frontmatter:
+
+```markdown
+---
+name: sequant-qa-checker
+description: Quality check agent for sequant QA phase.
+model: haiku
+permissionMode: bypassPermissions
+effort: low
+maxTurns: 15
+tools:
+  - Read
+  - Grep
+  - Glob
+  - Bash
+  - Edit
+---
+
+[Agent behavioral instructions here]
+```
+
+### Agent Resolution Priority
+
+Claude Code resolves agent names in this order:
+1. Managed settings
+2. `--agents` CLI flag
+3. `.claude/agents/` (project-level) — sequant's agents live here
+4. `~/.claude/agents/` (user-level) — users can override here
+5. Plugin agents
+
+## When to Use Each
+
+### Built-in `Bash`
+Best for: Single command execution, git operations, build commands
+
+```
+Agent(subagent_type="Bash", prompt="Run npm test and report results")
+```
+
+### Built-in `general-purpose`
+Best for: Custom tasks that don't fit a sequant agent profile
+
+```
+Agent(subagent_type="general-purpose",
+     prompt="Analyze the error logs and suggest fixes.")
 ```
 
 **Use cases:**
-- Finding existing patterns before implementing new features
-- Searching for file locations
-- Understanding codebase structure
-- Schema and database inspection
+- One-off tasks outside the sequant workflow
+- Tasks needing a specific model/permission combination
 
-### `Plan`
+### Built-in `Explore`
+Best for: Ad-hoc codebase search outside the `/spec` workflow
+
+```
+Agent(subagent_type="Explore",
+     prompt="Find all API routes in the project.")
+```
+
+### Built-in `Plan`
 Best for: Designing implementation approaches, architectural decisions
 
 ```
-Task(subagent_type="Plan",
+Agent(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 |
@@ -72,60 +139,103 @@ Task(subagent_type="Plan",
 
 **Default:** Use `haiku` unless the task requires deep reasoning.
 
+Custom agents set their model in the agent definition, so you don't need to specify it inline:
+
 ```
-Task(subagent_type="general-purpose",
-     model="haiku",
+# Model comes from .claude/agents/sequant-qa-checker.md (haiku)
+Agent(subagent_type="sequant-qa-checker",
      prompt="...")
 ```
 
 ## Common Patterns
 
-### Parallel Quality Checks
+### Parallel Quality Checks (via /qa)
 ```
-Task(subagent_type="general-purpose", model="haiku",
+Agent(subagent_type="sequant-qa-checker",
      prompt="Check type safety on diff vs main. Report issues count.")
 
-Task(subagent_type="general-purpose", model="haiku",
+Agent(subagent_type="sequant-qa-checker",
      prompt="Check for deleted tests in diff. Report count.")
 
-Task(subagent_type="general-purpose", model="haiku",
+Agent(subagent_type="sequant-qa-checker",
      prompt="Run security scan on changed files. Report findings.")
 ```
 
-### Context Gathering (Spec Phase)
+### Context Gathering (via /spec)
 ```
-Task(subagent_type="Explore", model="haiku",
+Agent(subagent_type="sequant-explorer",
      prompt="Find similar features in components/. Report patterns.")
 
-Task(subagent_type="Explore", model="haiku",
+Agent(subagent_type="sequant-explorer",
      prompt="Explore database schema for user tables. Report structure.")
 ```
 
-### Background Execution
+### Background Execution (via /exec)
 ```
-Task(subagent_type="general-purpose",
-     model="haiku",
+Agent(subagent_type="sequant-implementer",
      run_in_background=true,
      prompt="Implement the UserCard component...")
 ```
 
 Use `TaskOutput(task_id="...", block=true)` to wait for completion.
 
+**IMPORTANT: Background agents and permissions**
+
+Background agents cannot prompt for permission interactively. Custom agents with
+`permissionMode: bypassPermissions` in their definition handle this automatically.
+For built-in types, set `mode` explicitly when spawning background agents.
+
+### Permission Mode Reference
+
+| Mode | Edit/Write | Bash | When to Use |
+|------|------------|------|-------------|
+| `"acceptEdits"` | ✅ Auto-approved | ❌ **Denied** (prompts) | File-editing agents that don't need Bash |
+| `"bypassPermissions"` | ✅ Auto-approved | ✅ Auto-approved | **Agents that need Bash** (quality checks, git commands) |
+| (omitted) | ❌ Prompts | ❌ Prompts | Only if parent already auto-approves |
+
+**Note:** Sequant's custom agents (`sequant-qa-checker`, `sequant-implementer`) have
+`permissionMode` set in their agent definitions, so you don't need to specify `mode`
+inline when spawning them.
+
+### Choosing the Right Agent
+
+| Task | Recommended Agent | Why |
+|------|-------------------|-----|
+| Quality checks (git diff, npm test) | `sequant-qa-checker` | bypassPermissions + haiku + effort:low |
+| Codebase exploration | `sequant-explorer` | Read-only, haiku, focused tools |
+| Implementation subtask | `sequant-implementer` | Full access, inherits model |
+| Test stub generation | `sequant-testgen` | Write access, no Bash, haiku |
+| One-off custom task | `general-purpose` | Flexible, specify model/mode inline |
+
+**CRITICAL:** If your background agent runs `git diff`, `npm test`, `git status`, or any shell command, use `sequant-qa-checker` or `sequant-implementer` (both have bypassPermissions). Do NOT use `general-purpose` without `mode="bypassPermissions"` — Bash calls will silently fail.
+
+### Security Considerations
+
+`bypassPermissions` is safe when:
+- Agent only reads/analyzes (quality checks, security scans)
+- Agent runs in an isolated worktree
+- Agent output is reviewed before any further action
+
+`bypassPermissions` requires caution when:
+- Agent could write to production files
+- Agent could push to remote repositories
+- Agent has access to secrets or credentials
+
 ## 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`
+- ~~`quality-checker`~~ → Use `sequant-qa-checker` or `general-purpose`
+- ~~`pattern-scout`~~ → Use `sequant-explorer` or `Explore`
+- ~~`schema-inspector`~~ → Use `sequant-explorer` or `Explore`
+- ~~`code-reviewer`~~ → Use `sequant-qa-checker` or `general-purpose`
+- ~~`implementation`~~ → Use `sequant-implementer` or `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
+- [Claude Code Custom Subagents](https://code.claude.com/docs/en/sub-agents)
+- Agent definitions: `.claude/agents/*.md`
 - `/exec` skill parallel execution: `templates/skills/exec/SKILL.md`
 - `/qa` skill quality checks: `templates/skills/qa/SKILL.md`

package/templates/skills/exec/SKILL.md

@@ -39,7 +39,7 @@ allowed-tools:
   - mcp__context7__*  # Library documentation lookup - falls back to web search if unavailable
   - mcp__sequential-thinking__*  # Complex reasoning - falls back to standard analysis if unavailable
   # Task management
-  - Task(general-purpose)
+  - Agent(sequant-implementer)
   - TodoWrite
 ---
 
@@ -1507,11 +1507,43 @@ Look in the issue comments (especially from `/spec`) for:
 
 **If Parallel Groups exist:**
 
+0. **Check isolation mode (AC-20):**
+   ```bash
+   # Check env var first (set by --isolate-parallel CLI flag via phase-executor),
+   # then fall back to settings.json
+   ISOLATE="${SEQUANT_ISOLATE_PARALLEL:-}"
+   if [ -z "$ISOLATE" ]; then
+     ISOLATE=$(cat .sequant/settings.json 2>/dev/null | grep -o '"isolateParallel":[^,}]*' | grep -o 'true\|false' || echo "false")
+   fi
+   echo "Parallel isolation mode: ${ISOLATE}"
+   ```
+
+   **If isolation is enabled (`isolateParallel: true` or `--isolate-parallel`):**
+   - Create sub-worktrees BEFORE spawning agents (see step 1b below)
+   - Each agent gets its own working directory
+   - After agents complete, merge changes back (see step 5b below)
+
+   **If isolation is disabled (default):**
+   - All agents share the issue worktree (current behavior)
+   - Skip steps 1b and 5b
+
 1. **Create group marker before spawning agents:**
    ```bash
    touch /tmp/claude-parallel-group-1.marker
    ```
 
+1b. **Create sub-worktrees (isolation mode only):**
+   ```bash
+   # Uses the tested TypeScript API via CLI wrapper.
+   # Creates sub-worktree, symlinks node_modules, copies env files from .worktreeinclude.
+   WORKTREE_PATH="[issue worktree path]"
+   for i in 0 1 2; do  # adjust for number of agents
+     result=$(npx tsx scripts/worktree-isolation.ts create "${WORKTREE_PATH}" $i)
+     AGENT_PATH=$(echo "$result" | jq -r '.path')
+     echo "Agent ${i}: ${AGENT_PATH}"
+   done
+   ```
+
 2. **Determine model for each task:**
 
    Check for model annotations in the task line: `[model: haiku]` or `[model: sonnet]`
@@ -1522,15 +1554,24 @@ Look in the issue comments (especially from `/spec`) for:
    3. Default to `haiku` if no annotation
 
 3. **Spawn parallel agents with the appropriate model in a SINGLE message:**
+   Note: `sequant-implementer` intentionally omits `model` in its agent definition
+   so the skill can override per-invocation (e.g., `model="haiku"` for subtasks).
+
+   **Working directory:** Use the sub-worktree path when isolation is enabled,
+   otherwise use the issue worktree path.
+
    ```
-   Task(subagent_type="general-purpose",
+   Agent(subagent_type="sequant-implementer",
         model="haiku",
         run_in_background=true,
         prompt="Implement: Create types/metrics.ts with MetricEvent interface.
-                Working directory: [worktree path]
-                After completion, report what files were created/modified.")
+                Working directory: [sub-worktree path or issue worktree path]
+                After completion, commit your changes and report what files were created/modified.")
    ```
 
+   **Important (isolation mode):** Tell agents to commit their changes in the
+   sub-worktree. This is required for merge-back to work.
+
 4. **Wait for all agents to complete:**
    ```
    TaskOutput(task_id="...", block=true)
@@ -1542,6 +1583,31 @@ Look in the issue comments (especially from `/spec`) for:
    npx prettier --write [files modified by agents]
    ```
 
+5b. **Merge back and clean up sub-worktrees (isolation mode only):**
+   ```bash
+   WORKTREE_PATH="[issue worktree path]"
+
+   # Merge all agent branches back into the issue branch.
+   # Uses the tested TypeScript API — handles conflict detection,
+   # partial merges, and structured error reporting.
+   MERGE_RESULT=$(npx tsx scripts/worktree-isolation.ts merge-all "${WORKTREE_PATH}")
+   MERGED=$(echo "$MERGE_RESULT" | jq -r '.merged')
+   CONFLICTS=$(echo "$MERGE_RESULT" | jq -r '.conflicts')
+   echo "Merge-back: ${MERGED} merged, ${CONFLICTS} conflicts"
+
+   if [ "$CONFLICTS" -gt 0 ]; then
+     echo "⚠️ Conflicts detected — flagged for next iteration:"
+     echo "$MERGE_RESULT" | jq -r '.results[] | select(.success == false) | "  Agent \(.agentIndex): \(.error)"'
+   fi
+
+   # Clean up sub-worktrees and orphaned branches
+   npx tsx scripts/worktree-isolation.ts cleanup "${WORKTREE_PATH}"
+   ```
+
+   **If all merges succeed:** Proceed normally.
+   **If conflicts occur:** Report conflicting files. The next `/exec` iteration
+   can resolve them. Non-conflicting agents' changes are preserved.
+
 6. **Proceed to next group or sequential tasks**
 
 **If no Parallel Groups section exists:**
@@ -1626,14 +1692,14 @@ Use `[template: X]` annotation to force a specific template:
 
 Instead of a generic prompt:
 ```
-Task(subagent_type="general-purpose",
+Agent(subagent_type="sequant-implementer",
      model="haiku",
      prompt="Create MetricsCard component in components/admin/")
 ```
 
 Use a structured template prompt:
 ```
-Task(subagent_type="general-purpose",
+Agent(subagent_type="sequant-implementer",
      model="haiku",
      prompt="## Task: Create React Component