Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
44 changes: 44 additions & 0 deletions skills/subagent-driven-development/SKILL.md
Original file line number Diff line number Diff line change
Expand Up @@ -99,6 +99,45 @@ Use the least powerful model that can handle each role to conserve cost and incr
- Touches multiple files with integration concerns → standard model
- Requires design judgment or broad codebase understanding → most capable model

## External Delegate (Optional)

When configured in AGENTS.md (`external-delegate: <cli-name>`), mechanical implementation tasks can be delegated to an external CLI tool instead of a same-provider subagent. This extends the "least powerful model" principle across providers - when a cheaper, faster tool can handle the task, use it.

**When to delegate externally:**
- Task is cheap-model tier (1-2 files, complete spec, isolated function)
- External CLI is available and responding
- The delegate hasn't failed 3+ times this session

**When NOT to delegate externally:**
- Integration tasks touching multiple files with coordination concerns
- Architecture or design decisions
- Review tasks - spec compliance and code quality reviews always use same-provider subagents
- The external CLI has hit the circuit breaker (3 consecutive failures)

**How it works:**

The controller's responsibilities stay the same. Only the implementer dispatch changes:

1. Check delegate availability: `which <cli-name> >/dev/null 2>&1`
2. Build the implementation prompt using `./external-delegate-prompt.md` (a streamlined implementer prompt without self-review or escalation sections - the controller handles those)
3. Write the prompt to a temp file and pipe it to the delegate: `cat /tmp/sp-delegate-prompt.md | <cli-name> <flags>`
4. Review the diff: verify it's non-empty, in-scope, and contains no rogue operations
5. If the diff looks good, proceed to spec compliance review (same as the normal flow)
6. If the diff is empty or out-of-scope, fall back to a same-provider subagent for this task
7. The controller always commits - the delegate should not touch git

**Circuit breaker:** If the external delegate fails 3 consecutive times in one session, disable it for the remainder and use same-provider subagents for all remaining tasks. Reset the counter on any successful delegation.

**Configuration example in AGENTS.md:**

```markdown
## External Delegate

external-delegate: codex
```

The controller reads this at session start. If the key is absent or empty, all tasks use same-provider subagents (the default behavior, unchanged).

## Handling Implementer Status

Implementer subagents report one of four statuses. Handle each appropriately:
Expand All @@ -120,6 +159,7 @@ Implementer subagents report one of four statuses. Handle each appropriately:
## Prompt Templates

- `./implementer-prompt.md` - Dispatch implementer subagent
- `./external-delegate-prompt.md` - Dispatch external delegate (streamlined implementer prompt)
- `./spec-reviewer-prompt.md` - Dispatch spec compliance reviewer subagent
- `./code-quality-reviewer-prompt.md` - Dispatch code quality reviewer subagent

Expand Down Expand Up @@ -230,6 +270,7 @@ Done!
- Controller does more prep work (extracting all tasks upfront)
- Review loops add iterations
- But catches issues early (cheaper than debugging later)
- With external delegate: mechanical tasks use the delegate's token budget instead of the controller's, reducing same-provider token consumption on sessions with many implementation tasks

## Red Flags

Expand All @@ -246,6 +287,9 @@ Done!
- Let implementer self-review replace actual review (both are needed)
- **Start code quality review before spec compliance is ✅** (wrong order)
- Move to next task while either review has open issues
- Delegate review tasks to an external CLI (reviews must use same-provider subagents)
- Skip the diff review after external delegation (verify before proceeding)
- Ignore the circuit breaker (3 consecutive delegate failures = disable for session)

**If subagent asks questions:**
- Answer clearly and completely
Expand Down
43 changes: 43 additions & 0 deletions skills/subagent-driven-development/external-delegate-prompt.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,43 @@
# External Delegate Prompt Template

Use this template when dispatching a task to an external CLI tool configured via `external-delegate` in AGENTS.md. This is a streamlined version of the implementer prompt - it removes self-review and escalation sections that the controller handles.

```
Implement Task N: [task name]

## Task Description

[FULL TEXT of task from plan - paste it here]

## Context

[Scene-setting: where this fits, dependencies, architectural context]

## Your Job

1. Implement exactly what the task specifies
2. Write tests (following TDD if task says to)
3. Verify implementation works

Work from: [directory]

## Code Organization

- Follow the file structure defined in the task
- Each file should have one clear responsibility
- In existing codebases, follow established patterns
- Do not restructure code outside your task scope

## Rules

- Do NOT run git commit, git push, or git add
- Do NOT create pull requests or branches
- Do NOT modify files outside the scope of this task
- After implementation, run: git status && git diff --stat
```

**Notes for the controller:**

- The delegate does not self-review or escalate. The controller handles both via the spec compliance and code quality review subagents.
- The delegate should not commit. The controller reviews the diff and commits after validation.
- If the delegate produces no changes or out-of-scope changes, fall back to a same-provider subagent for this task.