subagent-driven-development
Use when executing implementation plans with independent tasks in the current session
- Installs
- 92
- Last 24h
- —
- Trending rank
- —
- Security
- Not audited
Install
Works with every agent the skills CLI supports.
npx skills add https://github.com/osmontero/opencode-skills --skill subagent-driven-development- 01
Install
Run the command in your project. The CLI asks which agents to install for.
- 02
Describe the task
Ask your agent for something this skill covers. It loads subagent-driven-development automatically when relevant.
- 03
Review the result
The agent follows the SKILL.md steps, scripts and references bundled with the skill.
SKILL.md
The instructions your agent reads when the skill is triggered.
Subagent-Driven Development
Execute plan by dispatching fresh sub-agent per task using the subagent tool, with a spec-compliance review first, then a code-quality review, then — when the task touches security-relevant code — a blocking security review.
Why sub-agents: You delegate tasks to specialized agents with isolated context. By precisely crafting their instructions and context, you ensure they stay focused and succeed at their task. They should never inherit your session's context or history — you construct exactly what they need. This also preserves your own context for coordination work.
Core principle: Fresh sub-agent per task + spec review, then quality review, then security review (when the task touches security-relevant code) = high quality, fast iteration
When to Use
digraph when_to_use {
"Have implementation plan?" [shape=diamond];
"Tasks mostly independent?" [shape=diamond];
"Stay in this session?" [shape=diamond];
"subagent-driven-development" [shape=box];
"executing-plans" [shape=box];
"Manual execution or brainstorm first" [shape=box];
"Have implementation plan?" -> "Tasks mostly independent?" [label="yes"];
"Have implementation plan?" -> "Manual execution or brainstorm first" [label="no"];
"Tasks mostly independent?" -> "Stay in this session?" [label="yes"];
"Tasks mostly independent?" -> "Manual execution or brainstorm first" [label="no - tightly coupled"];
"Stay in this session?" -> "subagent-driven-development" [label="yes"];
"Stay in this session?" -> "executing-plans" [label="no - parallel session"];
}
vs. Executing Plans (parallel session):
- Same session (no context switch)
- Fresh sub-agent per task (no context pollution)
- Review after each task: spec compliance first, then code quality, then security when the task touches security-relevant code
- Faster iteration (no human-in-loop between tasks)
The Process
digraph process {
rankdir=TB;
subgraph cluster_per_task {
label="Per Task";
"Dispatch implementer sub-agent (@implementer)" [shape=box];
"Implementer sub-agent asks questions?" [shape=diamond];
"Answer questions, provide context" [shape=box];
"Implementer sub-agent implements, tests, commits, self-reviews" [shape=box];
"Dispatch spec reviewer sub-agent (@spec-reviewer)" [shape=box];
"Spec reviewer sub-agent confirms code matches spec?" [shape=diamond];
"Implementer sub-agent fixes spec gaps" [shape=box];
"Dispatch code quality reviewer sub-agent (@code-quality-reviewer)" [shape=box];
"Code quality reviewer sub-agent approves?" [shape=diamond];
"Implementer sub-agent fixes quality issues" [shape=box];
"Task touches security-relevant code?" [shape=diamond];
"Dispatch security reviewer sub-agent (@security-reviewer)" [shape=box];
"Security reviewer sub-agent: no Critical or High open?" [shape=diamond];
"Implementer sub-agent fixes security findings" [shape=box];
"Mark task complete in the task list" [shape=box];
}
"Read plan, extract all tasks with full text, note context, create a task list" [shape=box];
"More tasks remain?" [shape=diamond];
"Dispatch final code reviewer sub-agent for entire implementation" [shape=box];
"Use finishing-a-development-branch" [shape=box style=filled fillcolor=lightgreen];
"Read plan, extract all tasks with full text, note context, create a task list" -> "Dispatch implementer sub-agent (@implementer)";
"Dispatch implementer sub-agent (@implementer)" -> "Implementer sub-agent asks questions?";
"Implementer sub-agent asks questions?" -> "Answer questions, provide context" [label="yes"];
"Answer questions, provide context" -> "Dispatch implementer sub-agent (@implementer)";
"Implementer sub-agent asks questions?" -> "Implementer sub-agent implements, tests, commits, self-reviews" [label="no"];
"Implementer sub-agent implements, tests, commits, self-reviews" -> "Dispatch spec reviewer sub-agent (@spec-reviewer)";
"Dispatch spec reviewer sub-agent (@spec-reviewer)" -> "Spec reviewer sub-agent confirms code matches spec?";
"Spec reviewer sub-agent confirms code matches spec?" -> "Implementer sub-agent fixes spec gaps" [label="no"];
"Implementer sub-agent fixes spec gaps" -> "Dispatch spec reviewer sub-agent (@spec-reviewer)" [label="re-review"];
"Spec reviewer sub-agent confirms code matches spec?" -> "Dispatch code quality reviewer sub-agent (@code-quality-reviewer)" [label="yes"];
"Dispatch code quality reviewer sub-agent (@code-quality-reviewer)" -> "Code quality reviewer sub-agent approves?";
"Code quality reviewer sub-agent approves?" -> "Implementer sub-agent fixes quality issues" [label="no"];
"Implementer sub-agent fixes quality issues" -> "Dispatch code quality reviewer sub-agent (@code-quality-reviewer)" [label="re-review"];
"Code quality reviewer sub-agent approves?" -> "Task touches security-relevant code?" [label="yes"];
"Task touches security-relevant code?" -> "Dispatch security reviewer sub-agent (@security-reviewer)" [label="yes"];
"Task touches security-relevant code?" -> "Mark task complete in the task list" [label="no"];
"Dispatch security reviewer sub-agent (@security-reviewer)" -> "Security reviewer sub-agent: no Critical or High open?";
"Security reviewer sub-agent: no Critical or High open?" -> "Implementer sub-agent fixes security findings" [label="no"];
"Implementer sub-agent fixes security findings" -> "Dispatch security reviewer sub-agent (@security-reviewer)" [label="re-review"];
"Security reviewer sub-agent: no Critical or High open?" -> "Mark task complete in the task list" [label="yes"];
"Mark task complete in the task list" -> "More tasks remain?";
"More tasks remain?" -> "Dispatch implementer sub-agent (@implementer)" [label="yes"];
"More tasks remain?" -> "Dispatch final code reviewer sub-agent for entire implementation" [label="no"];
"Dispatch final code reviewer sub-agent for entire implementation" -> "Use finishing-a-development-branch";
}
Model Selection
Use the least powerful model that can handle each role to conserve cost and increase speed.
Mechanical implementation tasks (isolated functions, clear specs, 1-2 files): use a fast, cheap model. Most implementation tasks are mechanical when the plan is well-specified.
Integration and judgment tasks (multi-file coordination, pattern matching, debugging): use a standard model.
Architecture, design, and review tasks: use the most capable available model.
Task complexity signals:
- Touches 1-2 files with a complete spec → cheap model
- Touches multiple files with integration concerns → standard model
- Requires design judgment or broad codebase understanding → most capable model
Handling Implementer Status
Implementer sub-agents report one of four statuses. Handle each appropriately:
DONE: Proceed to spec compliance review.
DONE_WITH_CONCERNS: The implementer completed the work but flagged doubts. Read the concerns before proceeding. If the concerns are about correctness or scope, address them before review. If they're observations (e.g., "this file is getting large"), note them and proceed to review.
NEEDS_CONTEXT: The implementer needs information that wasn't provided. Provide the missing context and re-dispatch.
BLOCKED: The implementer cannot complete the task. Assess the blocker:
- If it's a context problem, provide more context and re-dispatch with the same model
- If the task requires more reasoning, re-dispatch with a more capable model
- If the task is too large, break it into smaller pieces
- If the plan itself is wrong, escalate to the human
Never ignore an escalation or force the same model to retry without changes. If the implementer said it's stuck, something needs to change.
Agent References
implementer(global agent) - Dispatch implementer sub-agentspec-reviewer(global agent) - Dispatch spec compliance reviewer sub-agentcode-quality-reviewer(global agent) - Dispatch code quality reviewer sub-agentsecurity-reviewer(global agent) - Dispatch security reviewer sub-agent (when the task touches security-relevant code)
Example Workflow
You: I'm using Subagent-Driven Development to execute this plan.
[Read plan file once: docs/plans/feature-plan.md]
[Extract all 5 tasks with full text and context]
[Create a task list with all tasks]
Task 1: Hook installation script
[Get Task 1 text and context (already extracted)]
[Dispatch implementation sub-agent using the `subagent` tool with full task text + context]
Implementer: "Before I begin - should the hook be installed at user or system level?"
You: "User level (~/.config/opencode/hooks/)"
Implementer: "Got it. Implementing now..."
[Later] Implementer:
- Implemented install-hook command
- Added tests, 5/5 passing
- Self-review: Found I missed --force flag, added it
- Committed
[Dispatch spec compliance reviewer]
Spec reviewer: APPROVED - Spec compliant - all requirements met, nothing extra
[Get git SHAs, dispatch code quality reviewer]
Code reviewer: Strengths: Good test coverage, clean. Issues: None. Approved.
[Mark Task 1 complete]
Task 2: Recovery modes
[Get Task 2 text and context (already extracted)]
[Dispatch implementation sub-agent using the `subagent` tool with full task text + context]
Implementer: [No questions, proceeds]
Implementer:
- Added verify/repair modes
- 8/8 tests passing
- Self-review: All good
- Committed
[Dispatch spec compliance reviewer]
Spec reviewer: ISSUES:
- Missing: Progress reporting (spec says "report every 100 items")
- Extra: Added --json flag (not requested)
[Implementer fixes issues]
Implementer: Removed --json flag, added progress reporting
[Spec reviewer reviews again]
Spec reviewer: APPROVED - Spec compliant now
[Dispatch code quality reviewer]
Code reviewer: Strengths: Solid. Issues (Important): Magic number (100)
[Implementer fixes]
Implementer: Extracted PROGRESS_INTERVAL constant
[Code reviewer reviews again]
Code reviewer: APPROVED
[Mark Task 2 complete]
Task 3: Token signing key (touches security-relevant code)
[Spec APPROVED, quality APPROVED]
[Dispatch security reviewer]
Security reviewer: Critical open — signing key from env, no check it is
non-empty (fails open to unsigned tokens). Path traced, fix named.
[Implementer fixes, security reviewer re-reviews]
Security reviewer: APPROVED - no Critical or High open
[Mark Task 3 complete]
...
[After all tasks]
[Dispatch final code-reviewer]
Final reviewer: All requirements met, ready to merge
Done!
Advantages
vs. Manual execution:
- Sub-agents follow TDD naturally
- Fresh context per task (no confusion)
- Parallel-safe (sub-agents don't interfere)
- Sub-agent can ask questions (before AND during work)
vs. Executing Plans:
- Same session (no handoff)
- Continuous progress (no waiting)
- Review checkpoints automatic
Efficiency gains:
- No file reading overhead (controller provides full text)
- Controller curates exactly what context is needed
- Sub-agent gets complete information upfront
- Questions surfaced before work begins (not after)
Quality gates:
- Self-review catches issues before handoff
- Review: spec compliance first, then code quality, then security for security-relevant tasks
- Review loops ensure fixes actually work
- Spec compliance prevents over/under-building
- Code quality ensures implementation is well-built
- Security review traces attacker paths before they ship
Cost:
- More sub-agent invocations (implementer + 2 reviewers per task, + security reviewer for security-relevant tasks)
- Controller does more prep work (extracting all tasks upfront)
- Review loops add iterations
- But catches issues early (cheaper than debugging later)
Red Flags
Never:
- Start implementation on main/master branch without explicit user consent
- Skip reviews (spec compliance AND code quality, both required; security review required when the task touches security-relevant code)
- Proceed with unfixed issues
- Skip the security reviewer on a task that touches untrusted input, authn/authz, secrets, injection sinks, subprocess/plugin boundaries, or new dependencies (see
reviewing-securitytriggers) - Dispatch multiple implementation sub-agents in parallel (conflicts)
- Make sub-agent read plan file (provide full text instead)
- Skip scene-setting context (sub-agent needs to understand where task fits)
- Ignore sub-agent questions (answer before letting them proceed)
- Accept "close enough" on spec compliance (spec reviewer found issues = not done)
- Skip review loops (reviewer found issues = implementer fixes = review again)
- Let implementer self-review replace actual review (both are needed)
- Start code quality review before spec compliance is passed (wrong order)
- Start security review before spec compliance and code quality have passed (wrong order)
- Move to next task while any review has open issues
If sub-agent asks questions:
- Answer clearly and completely
- Provide additional context if needed
- Don't rush them into implementation
If reviewer finds issues:
- Implementer (same sub-agent) fixes them
- Reviewer reviews again
- Repeat until approved
- Don't skip the re-review
If sub-agent fails task:
- Dispatch fix sub-agent with specific instructions
- Don't try to fix manually (context pollution)
Integration
Required workflow skills:
- using-git-worktrees - REQUIRED: Set up isolated workspace before starting
- writing-plans - Creates the plan this skill executes
- requesting-code-review - Code review workflow for reviewer sub-agents
- code-quality-reviewer - Global agent for code quality review
- security-reviewer - Global agent for security review of security-relevant tasks
- finishing-a-development-branch - Complete development after all tasks
Sub-agents should use:
- test-driven-development - Sub-agents follow TDD for each task
Alternative workflow:
- executing-plans - Use for parallel session instead of same-session execution
FAQ
What does the subagent-driven-development skill do?
Use when executing implementation plans with independent tasks in the current session
How do I install subagent-driven-development?
Run npx skills add https://github.com/osmontero/opencode-skills --skill subagent-driven-development in your project. The skills CLI detects the agents you use and copies the skill into the right folder. For Claude Code you can also place the skill folder at ~/.claude/skills/subagent-driven-development/ (personal) or .claude/skills/subagent-driven-development/ (project).
Which AI agents can use subagent-driven-development?
Any agent that supports the open Agent Skills format (a folder with a SKILL.md file), including Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, Windsurf, Cline, OpenCode and more.
Is subagent-driven-development safe to install?
No partner security audit is available yet. Skills can run commands and scripts, so read the SKILL.md and any bundled files before installing.
Who maintains subagent-driven-development?
It is published by osmontero in osmontero/opencode-skills. It has 92 recorded installs.
More from osmontero/opencode-skills
designing-frontend-interfaces
osmontero/opencode-skills
Use when building or restyling any web interface — landing pages, dashboards, marketing sites, web apps, React/Vue components, HTML/CSS layouts, artifacts, posters — or when asked to make a UI look better, more polished, more distinctive, less generic, or less "AI-generated". Also use when a design brief, art direction, visual identity, type scale, or color system is needed before implementation.
designing-user-experience
osmontero/opencode-skills
Open the skill to read its SKILL.md instructions.
reviewing-interface-quality
osmontero/opencode-skills
Open the skill to read its SKILL.md instructions.
building-accessible-interfaces
osmontero/opencode-skills
Use when building or auditing any web UI for accessibility — keyboard navigation, screen readers, focus management, ARIA, color contrast, form labels and error announcements, reduced motion, or touch target size. Triggers include "is this accessible", "WCAG", "a11y", "screen reader", "keyboard navigation", "focus trap", "contrast ratio", "aria-label", or building modals, menus, tabs, comboboxes, toasts, and custom controls that must work without a mouse.
systematic-debugging
osmontero/opencode-skills
Use when encountering any bug, test failure, or unexpected behavior, before proposing fixes
verifying-before-completion
osmontero/opencode-skills
Open the skill to read its SKILL.md instructions.
Popular ai & agents skills
google-agents-cli-publish
google/agents-cli
This skill should be used when the user wants to "publish an agent", "publish my ADK agent", "register an agent with Gemini", "publish to Gemini" (formerly Gemini Enterprise), or needs guidance on the agents-cli publish gemini command. Also use when the user wants to "manage agents in Agent Registry", "list/update/delete registered agents", or "register an MCP server". Covers ADK vs A2A registration modes, programmatic and interactive usage, flag reference, auto-detection from deployment metadata, Agent Registry fleet management, and troubleshooting. Part of the agents-cli skills suite. Do NOT use for deployment (use google-agents-cli-deploy).
google-agents-cli-eval
google/agents-cli
This skill should be used when the user wants to "run an evaluation", "evaluate my agent", "evaluate my ADK agent", "write an eval dataset", "analyze eval failures", "compare eval results", "optimize agent", or needs guidance on the Gemini platform eval methodology and the Quality Flywheel. Covers eval metrics, dataset schema, LLM-as-judge scoring, and common failure causes. Applies to any agents-cli project, whatever framework the agent is written in. Do NOT use for agent API code patterns (ADK: use google-agents-cli-adk-code), deployment (use google-agents-cli-deploy), or project scaffolding (use google-agents-cli-scaffold).
skill-creator
anthropics/skills
Create new skills, modify and improve existing skills, and measure skill performance. Use when users want to create a skill from scratch, edit, or optimize an existing skill, run evals to test a skill, benchmark skill performance with variance analysis, or optimize a skill's description for better triggering accuracy.
codex-pet
prime-skills/runcomfy-agent-skills
Codex Pet generator on RunComfy. Build a Codex-compatible Codex Pet spritesheet.webp + pet.json from a single reference image, drop it into ${CODEXHOME:-$HOME/.codex}/pets/ / and Codex picks it up as a custom Codex Pet next to the 8 built-ins. This skill produces the exact Codex Pet atlas Codex expects (1536x1872 PNG/WebP, 8 cols x 9 rows, 192x208 cells, 9 animation states — idle, running-right, running-left, waving, jumping, failed, waiting, running, review). Calls OpenAI GPT Image 2 edit ONCE via the local RunComfy CLI as runcomfy run openai/gpt-image-2/edit to produce a canonical Codex Pet pose, then assembles all 9 animation rows programmatically with ImageMagick micro-transforms — no Codex Pro, no $imagegen, no OPENAIAPIKEY required, only RUNCOMFYTOKEN. Triggers on "codex pet", "create codex pet", "make codex pet", "hatch codex pet", "/hatch image", "desktop pet codex", "codex pets", "spritesheet.webp", or any explicit ask to build a custom pet for OpenAI Codex.
full-output-enforcement
leonxlnx/taste-skill
Overrides default LLM truncation behavior. Enforces complete code generation, bans placeholder patterns, and handles token-limit splits cleanly. Apply to any task requiring exhaustive, unabridged output.
executing-plans
obra/superpowers
Use when executing an implementation plan in the current session as the implementer yourself — your human partner chose inline execution, or no subagent tool is available