dh-execute-plan-task
Execute a single sub-task from plan.md: select the active one (In Progress phase first), resolve its `Delegated to agent`, implement (TDD), validate via dh-execute-cli, update status; project-type aware. Use for the next sub-task or continuing work — not orchestration.
- License 许可
- MIT
- 最近更新
- 2026-11-10
- Stars
- ★ 8
- Forks
- 1
01 前言 Front Matter
- name
- dh-execute-plan-task
- license
- MIT
- metadata
- { "audience": "developers", "workflow": "development" }
- description
- Execute a single sub-task from plan.md: select the active one (In Progress phase first), resolve its `Delegated to agent`, implement (TDD), validate via dh-execute-cli, update status; project-type aware. Use for the next sub-task or continuing work — not orchestration.
- allowed-tools
- read, write, edit, bash
- compatibility
- opencode, copilot, antigravity
03 SKILL.md 正文
Execute one self-contained sub-task from ./docs/plans/<plan-slug>/plan.md.
Core Rules
- Read the plan with the
dh_plan_readtool ({ slug }→ structured JSON: meta, phases[].title/status, subTasks[].phase/title/status) to find the active sub-task. Fallback when the tool is unavailable: read./docs/plans/<plan-slug>/plan.mdmanually, following the phased template markers (## Phases→### Phase N: <title>→#### Sub-Task N.M: <title>with- **Status:**bullets). If the plan does not exist, stop and report that no plan was found — suggest running thedh-planningskill first. These tools are exposed by the project-scopedhMCP server; under Code Mode they are called astools.dh.<tool>, anddh_<tool>is the tool's normalized name (permission actions matchdh_*). - Treat the sub-task entry in plan.md as the full implementation brief.
- Resolve the sub-task's delegated agent: read
delegatedTofromdh_plan_readfor the active sub-task. It must name an agent recorded in## Agent Selection. If the field is missing, empty, or points to an unknown/unavailable agent, STOP and report the gap — never execute the sub-task or substitute an agent silently. - One responsible agent per sub-task: the
Delegated to agentvalue is the single executor for that sub-task. Implementation work normally names the selected implementation agent; documentation or test-only sub-tasks may name the documentation or testing/QA agent. There is no complexity- or type-based builder split. - Review stays separate: resolve the review agent from
## Agent Selection; the delegated agent does not review its own work. - Detect project type before the post-steps: it determines whether
dh-domain-check,dh-simplify, anddh-create-documentationrun (software projects only) — it does NOT change who implements. - For software projects: run
dh-domain-checkbefore complex implementation,dh-simplifyafter validation, anddh-create-documentationfor new modules/APIs. - For non-software projects: skip the
dh-simplify,dh-domain-check, anddh-create-documentationsteps entirely; implementation still goes to the sub-task's delegated agent. - Use the
dh-execute-cliskill for tests, linters, and builds. - Delegate review to the plan's selected review agent for code quality and acceptance criteria checks.
- Do not modify files outside the sub-task scope.
- Update the sub-task status only after review passes — via
dh_plan_update_status(target: "subtask", statusCompleted); fallback: manual plan.md edit per the marker rules. - If the sub-task has dependencies on earlier sub-tasks, verify they are Completed before starting.
Project Type Detection
Check the project root for software marker files to determine project type. This must be done before any agent delegation.
Software project markers (any of these files present in project root):
package.json, pyproject.toml, Cargo.toml, composer.json, go.mod, CMakeLists.txt, setup.py, setup.cfg, Gemfile, project.clj, deps.edn, mix.exs, pubspec.yaml, Build.scala, build.gradle, *.csproj, *.sln
Detection logic:
- Run
ls <project-root>/and check for any of the marker files above. - If a marker file is found → software project (run
dh-domain-checkbefore complex implementation,dh-simplifyafter validation,dh-create-documentationfor new modules/APIs). - If no marker files found → non-software project (skip
dh-domain-check,dh-simplify, anddh-create-documentation). - If uncertain (e.g., a
Makefilewith no other code), check for source code directories (src/,lib/,app/) as secondary indicators.
Delegation is IDENTICAL for both types: every sub-task is executed by its
Delegated to agent (normally the selected implementation agent).
Why this matters: Non-software projects (docs repos, config repos, design assets) don't benefit from architecture/engineering agents or code-level simplification. Using the wrong agent type wastes context and produces irrelevant findings.
Workflow
Step 0: Resolve the delegated agent
Read ## Agent Selection in plan.md and confirm the sub-task's Delegated to agent names one of its agents. If the section or the field is absent, empty, or stale, STOP and ask the planner/user to fix the plan — do not run the selection protocol as a substitute for the missing field. If the named agent is unavailable and no bundled capability covers the role, stop and report the gap.
Step 1: Select the active sub-task
Read the plan with the dh_plan_read tool ({ slug }) and find exactly one sub-task using this phase-aware order. Fallback when the tool is unavailable: read ./docs/plans/<plan-slug>/plan.md manually per the marker rules:
- Pick the FIRST phase marked
In Progress; within it, pick its FIRST sub-task markedIn ProgressorPending. If that sub-task is alreadyIn Progress(set by the orchestrator), skip marking and proceed directly to implementation. - If no phase is
In Progress, take the first sub-task of the firstPendingphase and mark itIn Progressviadh_plan_update_status(target: "subtask", statusIn Progress) — the phase follows the lifecycle (it becomesIn Progresswhen its first sub-task starts). Fallback: manual plan.md edit per the marker rules. - If multiple phases are
In Progress, or multiple sub-tasks within the active phase areIn Progress, stop and ask which to continue. - If no
In ProgressorPendingsub-tasks remain, report that the plan has no remaining work.
Step 2: Implement the sub-task
Follow the sub-task's instructions, in-scope list, and implementation suggestions. The sub-task's Delegated to agent is the single responsible executor:
- Delegate the FULL sub-task brief to that agent — for complex work (multi-file, architectural decisions, new modules), run the
dh-domain-checkskill first and include its findings in the delegation. When the project graph is indexed, usedh-code-queryon the affected symbols (definition,callers,importers,tests-reaching) to include impact and test evidence in the brief. - Route implementation work through the
dh-codingskill inside that agent's pass (test-first TDD;CODE_RULES.mdat project root when present). - Route documentation sub-tasks through
dh-create-documentationand test-only work through the project's testing guidance, still under the named agent. - TDD: the failing test is written first, then the minimal change to make it pass — performed inside the delegated agent's pass.
- Do NOT implement sub-task work directly and do NOT seek another builder: the
Delegated to agentis the only executor for this sub-task.
General rules:
- Stay within the sub-task's in-scope boundaries. Do not widen scope.
- Never mark a phase
Completedyourself while any sub-task in it is still open (phase coordination belongs to the orchestrator or the gated tool).
Step 3: Run validation
Use the dh-execute-cli skill to run the smallest relevant validation for the changed code:
- Run tests related to the changed files.
- Run linters and static analysis.
- Fix any failures before proceeding. If validation fails 3 consecutive times, stop and report the failure with full error output — do not proceed to review.
When stopping on a hard blocker, recommend dh-pause-plan so the phase/sub-task, git state, decisions, and next steps are preserved in handoff.md before the session ends.
Step 3a: Simplify code (software projects only)
For software projects only — after validation passes and before requesting review:
Run the dh-simplify skill to review all changed code for reuse opportunities, quality issues, and efficiency improvements. This ensures code is clean before it reaches review.
- Invoke the
dh-simplifyskill with the full diff context from the sub-task implementation. - Wait for all three simplify agents (code reuse, quality, efficiency) to report findings.
- Fix all P0/P1 issues found by simplify. For P2/P3 findings, use judgment — fix if meaningful, defer if low impact.
- If fixes were made, re-run validation via the
dh-execute-cliskill to ensure nothing broke. - For non-software projects: skip this entire step — the
dh-simplifyskill is code-focused and would produce irrelevant findings.
Step 3b: Generate documentation (software projects only)
For software projects only — after dh-simplify and before requesting review:
Run the dh-create-documentation skill to generate or update API references, module docs, architecture overviews, or any documentation relevant to the new or changed code.
- If the sub-task introduces new modules, APIs, public interfaces, or configuration schemas, invoke
dh-create-documentationto produce the corresponding docs. - If the sub-task modifies existing documented interfaces, update the related documentation rather than creating from scratch.
- If the sub-task has no public-facing changes (e.g., internal refactors, bug fixes), skip this step.
- For non-software projects: skip this entire step — documentation needs for config/docs repos are handled differently.
Step 4: Request review
(Orchestration note) When invoked from dh-execute-plan orchestrator, skip this step — the orchestrator runs the dh-review skill after this sub-task completes. When invoked standalone, ask the plan's selected review agent to review the changes against the active sub-task's acceptance criteria, scope boundaries, and done-when conditions. The reviewer writes findings to ./docs/plans/<plan-slug>/tasks/review.md.
Step 5: Address review feedback
Read the review and address findings:
- For P0/P1 (blocking/high): fix immediately, then proceed to Step 5a.
- For P2/P3: use judgment — fix if meaningful, defer if low impact.
- After fixes, re-run the relevant validation with the
dh-execute-cliskill. - Update
./docs/plans/<plan-slug>/tasks/review.mdmarking each finding asAddressedorNot Addressedwith a brief rationale. - If re-validation fails 2 additional times after initial fixes, stop and report the failure with full error output — do not proceed; recommend
dh-pause-planto preserve state inhandoff.md(resume withdh-resume-plan).
Step 5a: Confirm review resolution
- If the reviewer approved (no outstanding P0/P1 findings), proceed to Step 6.
- If P0/P1 findings remain unaddressed, fix them and request a re-review from the selected review agent (loop back to Step 4).
- If P0/P1 findings cannot be resolved in-session, recommend
dh-pause-planbefore stopping; do not mark the sub-task or phaseCompleted. - If only P2/P3 findings remain and you have addressed or explicitly deferred them with rationale, proceed to Step 6.
Step 6: Update plan status
- (Orchestration note) When invoked from
dh-execute-planorchestrator, skip both status updates — the orchestrator marks Complete after its external review passes and handles sequencing. When invoked standalone, mark the current sub-task asCompletedviadh_plan_update_status(target: "subtask", statusCompleted); fallback: manual plan.md edit per the marker rules. - Phase coordination: after the sub-task is
Completed, check whether ALL sub-tasks of its phase are nowCompleted. If so, tell the orchestrator (dh-execute-plan) that the phase is ready to close; when running standalone, close it viadh_plan_update_status(target: "phase", statusCompleted). Never mark a phaseCompletedyourself while any sub-task in it is still open. - When standalone: if a next sub-task exists and is
Pending, mark it asIn Progress. - When standalone: update
./docs/plans/index.mdwith the latest status if this was the final sub-task.
Execution Delegation Guide
Per-sub-task executor policy: every sub-task is implemented by its
Delegated to agent. Implementation sub-tasks normally name the plan's
selected implementation agent; documentation, test-only, and similar
sub-tasks name the matching selected role. There is no builder split beyond
that explicit field.
| Work | Delegate to | Post-steps |
|---|---|---|
| Software (complex, architectural) | sub-task's Delegated to agent |
dh-domain-check first, then dh-simplify + dh-create-documentation |
| Software (other) | sub-task's Delegated to agent |
dh-simplify after validation |
| Non-software | sub-task's Delegated to agent |
none (skip dh-simplify/dh-domain-check/dh-create-documentation) |
Validation always runs through the dh-execute-cli skill; review through the
plan's selected review agent.
Loop Integration (bundled)
This copy is bundled in the plugin; the harness runtime contract (full loop
1–5) lives in repo-root AGENTS.md and in dh-execute-plan's Loop Integration
section. Executing a sub-task sits inside loop step 2:
- 2.1 delegate code implementation through the
dh-codingskill (software work); rundh-domain-checkbefore complex implementation. - 2.2 run
dh-simplifyafter validation (software projects only). - 2.3
dh-review+dh-code-reviewverify the sub-task before it is markedCompleted. - 2.4 Hard blockers halt automation. Repeated validation failures (3
consecutive strikes), unresolved P0/P1 review findings, or missing
preconditions that cannot be worked around → STOP: report the blocker and
ask the user for guidance. Never silently continue, never skip the blocked
step, and never mark sub-tasks
Completedaround a blocker. A blocked sub-task also blocks its phase — do not mark the phaseCompletedaround a blocker. Before stopping for a hard blocker or ending the session, rundh-pause-planto preserve the phase/sub-task, git state, decisions, blockers, and next steps inhandoff.md; resume later withdh-resume-plan.
References
- Fast variant:
dh-execute-plan-task-fastexecutes one sub-task fromplan_fast.mdwith dual-plan status writes, per-task skipped-check rows, and no per-task gates. ../dh-planning/references/agent-selection.md: capability→agent resolution (discovery, ranking, fallback, re-validation).dh-execute-cliskill: runs commands, tests, linters, and builds with logged, compact output.dh-domain-checkskill: validates architecture against DDD bounded contexts and SOLID principles before complex implementation (software projects only).dh-simplifyskill: reviews changed code for reuse, quality, and efficiency after validation (software projects only).dh-create-documentationskill: generates docs for new modules, APIs, and interfaces after simplify (software projects only).
Doc search
Documentation management: delegate create / update / delete / retrieve of generated documents (excluding docs/plans) to the best available documentation agent (bundled documentation capability as fallback) — the main and only documentation owner (see dh-create-documentation).
Search generated documentation quickly: notesmd-cli search-content "<term>" --vault "<project-name>" or obsidian search query="<term>" (fallback: rg --glob '*.md' "<term>" docs/).
04 同仓库更多 Skills
dh-simplify
Review changed code for reuse, quality, and efficiency (three parallel reviews), then fix findings directly. Use after making changes or when asked to clean up, refactor, simplify, or improve this code.
dh-setup
Audit system software, configure user MCPs/plugins, scaffold project QA (hooks + per-stack tools), bootstrap docs/architecture with the selected architecture agent, and write harness directives into AGENTS.md. Use to check requirements or setup the environment.
dh-semver
Apply strict Semantic Versioning — analyze commits since the last tag to determine the bump type (major/minor/patch from conventional commit prefixes), generate an automated changelog grouped by breaking changes, features, fixes, and chores, and create a git tag locally without pushing until confirmed, handling both conventional commits and manual version decisions. Use when preparing a release, invoked by dh-execute-plan after plan completion and dh-final-review for release readiness, or when the user asks "what version is next?", "bump version", "generate changelog", "tag release", or "what changed since last release?".
dh-review
Verify a plan sub-task against acceptance criteria, scope, done-when; review diff, validation, regression risk; structured verdict to tasks/review.md. Plan Alignment Mode (fast execution) is a separate mode: no sub-task selection, no diff review, no code review — it compares plan.md with plan_fast.md and writes tasks/review-fast.md (pre-execution) or tasks/review-fast-final.md (plan-end). Use after implementation, to review/verify the sub-task, or to check fast-plan alignment.
dh-resume-plan
Resume a paused phased plan from docs/plans/<slug>/handoff.md: validate the contract, detect drift, rehydrate context, mark the handoff resumed, and continue via dh-execute-plan resume mode. Use when the user says "resume the plan", "continue where we stopped", "pick up the plan", or "resume after a pause".
dh-preflight
Run tests, linters, static analysis as a release gate: auto-detect tooling, check dirty state, pass/fail verdict with actionable failures (no auto-fixes). Use to run preflight, pre-release check, or validate before release.