aile-subagent-dev

Aile: Subagent-Driven Development (aile-subagent-dev)

Source Original Skill

• Source: superpowers subagent development capability (migrated to aile-only)
• Team rewrite: refactored into an execution skill for Codex subagent, with explicit input as analysis.md + selected plan file, with the main thread responsible for orchestration, review, and summarization

Overview

This skill is used for plan execution in team Phase 3, but it is not the "default execution mode."

• Input:docs/plans/{Story-Key}/analysis.md + selected plan file
• Output: implementation, verification, two-phase review, and final summarization completed according to the plan
• Role division: the main thread acts as controller; Codex subagents handle splittable work such as implementation, verification, and review

Core principles:

• Must read both analysis.md and the plan file, not just plan.md
• Only dispatch Codex subagents when the user explicitly requests subagent mode
• The controller is responsible for reading context, splitting tasks, determining parallel/serial execution, and summarizing results
• Subagents only receive the Task Package relevant to their own task, and do not read the entire plan on their own
• Perform specification compliance review first, then code quality review

Codex Subagents Alignment

This skill aligns with the official Codex subagent capabilities and usage principles:

• Subagents are suitable for complex, splittable, parallelizable execution tasks
• Whether to actually dispatch a subagent depends on whether the main thread explicitly initiates it
• Built-in roles prioritize using worker、explorer、default
• The main thread is responsible for orchestration, and subagents are responsible for bounded tasks

Therefore, the prerequisites for this skill are:

• The user explicitly requests the use of aile-subagent-dev
• or the user explicitly requests "execute the plan using subagent / subagent mode"
• The current task already has Phase 2 artifacts:analysis.md and the plan file

Workflow Overview

项目初始化：aile-docs-init（创建文档）
      ↓
需求分析：aile-requirement-analysis（输出 analysis.md）
      ↓
计划制定：aile-writing-plans（输出 plan.md / plan-{n}.md）
      ↓
执行开发：aile-executing-plans 或 aile-subagent-dev
      ↓
交付总结：aile-delivery-report

When to Use

Applicable scenarios:

• There is already an executable analysis.md and plan file
• The user explicitly requests the use of Codex subagent mode
• The plan can be split by responsibility, module, or file boundary
• The main thread is better suited to act as controller rather than personally completing all coding details serially

Inapplicable scenarios:

• The user has not explicitly requested subagent mode
• The task is strongly coupled and highly order-dependent, making it unsuitable for splitting
• analysis.md or the plan file is missing
• It is only a small change, and the main thread completing it directly is simpler

Boundary with aile-executing-plans boundaries of

Both belong to the Phase 3 "execute the plan" skill, but their execution modes differ.

aile-executing-plans：

• Single-main-agent mode
• The main thread advances tasks in batches
• Better suited for plans with strong coupling, obvious serial dependencies, and frequent manual checkpoints

aile-subagent-dev：

• Codex subagent orchestration mode
• The main thread reads analysis.md + plan file, constructs a Task Package, and then dispatches subagents
• Better suited for complex plans that can be split by responsibility and have room for parallelism

Selection principle:

• It is more direct for the main thread to complete it in batches itself: use aile-executing-plans
• Requires "controller + multiple subagents" collaborative execution: use aile-subagent-dev

Input contract

Required reading files

1. docs/plans/{Story-Key}/analysis.md
2. Plan file:
   • If the user explicitly specifies: use the specified file
   • If plan-{序号}.mdexists: use the file with the largest sequence number
   • Otherwise use plan.md

Controller reading requirements

• The controller reads analysis.md and the selected plan file once at the start
• Extract requirement boundaries, acceptance criteria, task breakdown, dependencies, and verification commands from the two files
• Afterward, distribute context to subagents through Task Packages to avoid each subagent repeatedly reading the full documents

Subagent role selection

By default, prioritize Codex built-in roles:

• worker
  • Responsible for coding, fixing, adding tests, and executing verification
  • By default serves as implementer
• explorer
  • Responsible for read-only analysis, specification checking, evidence extraction, and discrepancy checking
  • By default serves as spec reviewer
• default
  • Responsible for comprehensive judgment, cross-task quality review, and final summary
  • By default serves as code quality reviewer or final reviewer

If the current system also provides other available roles or custom subagents, the controller must first analyze their capabilities before deciding whether to use them. Do not mechanically fixate on using only the three built-in roles.

Role selection process:

1. First identify the subagent roles available in the current system
2. Determine the main capability boundaries of each role:
   • Whether it is good at writing code
   • Whether it is good at read-only analysis
   • Whether it is good at comprehensive review
   • Whether it has specific domain capabilities, such as frontend, testing, architecture, data, performance
3. Map task types to the most suitable roles
4. If there is no more suitable system role, fall back to the built-in worker / explorer / default
5. Roles may change, but responsibility boundaries must not change:
   • implementer is responsible for implementation and verification
   • spec reviewer is responsible for specification checking
   • code quality reviewer is responsible for quality review

Selection principles:

• Writing code, modifying tests, fixing defects: prioritize worker
• Reading code, checking implementation against analysis.md / plan file: prioritize explorer
• Making comprehensive conclusions, global quality judgment, final closure: prioritize default
• If the system has a more specialized role whose capability boundaries better match the task, prioritize selecting the "better-matching system role"

Example:

• If the system has a dedicated test reviewer or QA reviewer, it can preferentially take on quality review
• If the system has an architecture reviewer, it can preferentially handle cross-module design consistency checks
• If the system has frontend/backend/data-oriented implementers, tasks can be dispatched to the corresponding roles by task domain

If the repository later provides custom subagents, the default roles can be replaced, but responsibility boundaries must not change.

Task Package specification

Before dispatching each subagent, the controller must construct a minimal sufficient Task Package, containing at least:

• Task number and title
• Task objective and scope
• From analysis.md requirement boundaries, risks, acceptance criteria
• Task steps, dependencies, and constraints from the plan file
• Allowed file modification scope
• Areas that are prohibited from modification or require careful handling
• Verification commands and completion criteria
• Artifacts or dependency descriptions from preceding tasks

Task Package principles:

• Give the subagent "the complete context needed to do the work," but do not stuff in the entire plan
• The controller is responsible for trimming context to avoid task drift
• Parallel tasks must have clear file boundaries or write boundaries

Execution flow

Step 1: Load context

1. Read analysis.md
2. Select and read the plan file
3. Verify whether the two files are consistent:
   • Whether requirement boundaries conflict
   • Whether the tasks cover the acceptance criteria
   • Whether the verification commands are sufficient to support the completion criteria
4. Establish an execution board, marking dependencies, parallelizable items, and blockers

Step 2: Decide the scheduling strategy

Judge in the following order:

1. Whether there are prerequisite dependencies
2. Whether the same file set will be written
3. Whether it is suitable for parallelization
4. Which subagent should be used for each task, and whether there is a system role that matches better than the built-in roles

If multiple implementation tasks will modify the same file set, they must be serialized.

Step 3: Dispatch the implementer

For each executable task:

1. Construct the Task Package
2. Dispatch worker implementer
3. Require the implementer to:
   • If there are blocking questions, ask first before starting work
   • Implement only what is within the task scope
   • Run the verification required by the plan
   • After completion, perform a self-check first, then report the results

Step 4: Spec compliance review

After the implementer reports back, the controller dispatches the spec reviewer:

• Use by default explorer
• Check against analysis.md, the plan file, acceptance criteria, and testing requirements
• Must directly read the code and verification results, and not trust the implementer's verbal report

If problems are found:

• Send back to the same implementer for fixes
• After fixes, perform spec review again
• Until spec compliance passes

Step 5: Code quality review

After spec compliance passes, dispatch the code quality reviewer:

• Use by default default
• If it is only a narrow-scope difference check, you may also use explorer
• Focus on maintainability, consistency, test effectiveness, implementation complexity, and boundary handling

If problems are found:

• Send back to the implementer for fixes
• After fixes, perform quality review again
• Until quality passes

Step 6: Task completion and wrap-up

After each task passes:

• Update the execution board status
• Record verification evidence
• Decide whether to release subsequent dependent tasks

After all tasks are completed:

• Depending on complexity, decide whether to dispatch a final reviewer once
• Summarize implementation results, verification results, and residual risks
• Enter aile-delivery-report

Subagent prompt templates

It is recommended to dispatch according to the following templates:

• implementer-prompt.md
• spec-reviewer-prompt.md
• code-quality-reviewer-prompt.md

These templates are intended for spawn_agent / send_input message orchestration, rather than the old-style approach of "letting the subagent read the files itself."

Related skills

• aile-writing-plans: generate analysis.md and the plan file
• aile-executing-plans: a non-subagent plan execution mode
• aile-delivery-report: delivery wrap-up after execution is complete

Red flags

Never do this:

• The user did not explicitly request subagents, yet you dispatch Codex subagents on your own
• Read only the plan file, not analysis.md
• Have the subagent read through analysis.md or the entire plan file on its own
• Advance to code quality review before spec compliance has passed
• Dispatch multiple implementers in parallel that will write to the same set of files
• A subagent claims completion without running verification
• Substitute implementer self-checks for formal review
• Skip re-review after rework

Stop and reassess when you encounter the following:

• analysis.md conflicts with the plan file
• The task cannot be broken down into clear boundaries
• Parallel decomposition would cause obvious conflicts
• The verification command cannot prove the task is complete

Remember

• aile-subagent-dev is "Codex subagent execution mode," not the default execution mode
• The main thread is the controller, responsible for reading analysis.md and the plan file, constructing the Task Package, dispatching, and summarizing
• Subagents should receive tailored context rather than reading the full document themselves
• Spec compliance comes before code quality
• The difference from aile-executing-plans is not "whether the plan is executed," but "whether Codex subagent orchestration is used"