// Execute the implementation plan — write code, make changes, build the deliverables. Use when the user says 'do it', 'implement', 'start coding', 'execute the plan', 'build it', or wants to begin actual implementation work after planning is complete.
| name | exec |
| description | Execute the implementation plan — write code, make changes, build the deliverables. Use when the user says 'do it', 'implement', 'start coding', 'execute the plan', 'build it', or wants to begin actual implementation work after planning is complete. |
| model_tier | heavy |
| auto_delegatable | false |
| triggers | {"keywords":{"zh":["执行","实现","开干","动手","开始做","写代码","跑起来"],"en":["execute","implement","start working","do it","write code","run the plan","build it"]},"phrases":{"zh":["开始执行","按计划做","动手实现","开始写代码","继续做","执行计划","修这个bug"],"en":["execute the plan","start implementing","carry out the plan","continue execution","fix this issue"]},"disambiguate":"Core intent: carry out the implementation plan by writing code / making changes. User says \"do it\" or \"start implementing\" → exec. User says \"plan how to do it\" → plan. User says \"run it automatically\" → auto.\n"} |
| arguments | [{"name":"step","description":"Execute a specific step number (optional, executes all if omitted)","required":false}] |
Execute the implementation plan for a task module that has passed evaluation.
Path Rule: All system files (
.status.json,.target.md,.plan.md, etc.) are in$TASKAI_WORK_DIR/(=$NB_WORK_DIR/.working/), NOT in$NB_WORK_DIR/directly. Seecommands/task-ai.md§System File Path Rule.
/task-ai:exec [--step N]
Notebook auto-detection: The notebook is automatically resolved from CWD (.status.json) or the current git branch (task/<notebook>). No manual notebook parameter needed.
review (post-plan check passed) or executing (NEEDS_FIX continuation).target.md should exist (warning if missing — provides requirements context).plan.md) must exist.analysis/ should contain a PASS evaluation file (warning if empty/missing)depends_on modules must meet their required status — simple string entries require satisfied, extended { module, min_status } entries require at-or-past min_status (see depends_on Format in commands/task-ai.md). If any dependency is not met, exec REJECTS with error listing blocking dependencies and their current statuses.plan.md in the task module.target.md for requirements context.type-profile.md if exists — "Implementation Patterns" and "Key tools" sections are the primary source for tool selection and implementation approach (see plan/references/type-profiling.md for type system details). If execution reveals the profile's patterns are inaccurate, update the relevant sections with findings.summary.md if exists (condensed context from prior plan/check/exec runs — primary context source).test/ latest criteria file for per-step verification criteria and acceptance standards.analysis/ latest file only for evaluation notes and approved approach.bugfix/ latest file only if exists for most recent issue and fix guidance.notes/ latest file only if exists for most recent research findingscommands/references/changelog-consumption-protocol.md)/task-ai:library search "<keywords>" with implementation keywords from the current step's technologies and APIs. Library search handles index reading, scoring, and ranked results — read high-scoring matches for domain-specific implementation guidance. Best Practice: prefer library search over direct file reads for multi-factor scoring, graph recommendations, and token budget control.type-profile.md lacks implementation guidance OR .references/ lacks knowledge for the current step's technologies/APIs, trigger research --scope gap --caller exec to collect missing references before proceeding. When encountering technical obstacles during execution, the agent may also invoke research --scope gap --caller exec for targeted research.plan.md (ordered by heading structure)Context management (exec): When .summary.md exists, read it as the primary context source for implementation instead of reading all files from .analysis/, .bugfix/, .notes/. Only read the latest file from each directory for the most recent assessment/issue/note. See also plan/SKILL.md for the equivalent plan-phase context rule.
Read the type field from .status.json to determine the task domain. Execution strategy adapts to the task type — software tasks follow RED→GREEN per step, while documentation tasks follow outline→draft→review. Different domains use fundamentally different tools, verification methods, and workflows.
For each implementation step:
Output directory: All non-system file output (code, configs, assets) goes to
$NB_WORK_DIR/.deliverables/— merge only copies this directory to main branch, so anything outside it won't be preserved. System files (.status.json,.plan.md, etc.) remain in$TASKAI_WORK_DIR/(.working/).
type contains software OR .type-profile.md contains ## Verification Cycle) AND .test/<date>-vh-stubs.test.* exists (with vh-baseline.md confirming initial failure state), run only the tests corresponding to the current step (identified by the [VH: ...] annotations in .plan.md) before implementing:
.notes/: "Step N: test X was Green before implementation — test may be trivially satisfied or implementation leaked from a prior step". Continue implementation but flag for reviewinit/references/seed-types/<type>.md for per-type seed methodology, or .type-profile.md for task-specific guidance)
/task-ai:security verify-cmd "<command>". If verdict is REJECT, execution is halted immediately, signal (mid-exec), state becomes NEEDS_FIX, and trigger lineage tracing to invalidate the source reference.auto/references/plugin-delegation.md to check if the current step matches a capability slot: type containing frontend/web/ui → frontend-design slot; type containing bugfix or NEEDS_FIX resumption → debugging slot; type containing software with .test/ criteria → tdd slot; otherwise → domain-* semantic scan. If matched, invoke via Task subagent — guidance is incorporated into the implementation approach. No match or failure → use existing inline methodsNEEDS_FIX, record failure details (which tests still fail and why). If minor, attempt a targeted fix and re-run. If unresolvable, signal (mid-exec) for verify → check evaluation.test/<date>-cumulative-green.jsonl. For human VH types, store approval snapshots in .test/hil-snapshots/. On regression → fix (≤1 attempt) → re-run; still failing → signal (mid-exec). Skip if step=1 or no VH stubs exist.test/ criteria using domain-appropriate verification (see per-type seed file or .type-profile.md for domain verification methods).notes/<YYYY-MM-DD>-<summary>-exec.md when implementation deviates from plan, an unexpected workaround is needed, or a non-obvious API behavior is discovered. Skip for straightforward steps that follow the plan exactly. For VFP-applicable types, include a VFP Cycle Summary section per step: Red (N failing) → Green (N passing) → Refactor (yes/no).summary.md (task-level) — overwrite with condensed summary including ALL notes from .notes/| Situation | Action |
|---|---|
| Step succeeds | Record in progress log, continue |
| Minor deviation needed | Adjust and document, continue |
| Significant issue | Stop execution, signal (mid-exec). Interactive: suggest verify --checkpoint mid-exec (then check). Auto: daemon routes to verify → check mid-exec evaluation |
| Blocking dependency | Set status to blocked, report which dependency |
.status.json — validate status is review or executingdepends_on from .status.json, check each dependency module's .status.json status against its required level (simple string → satisfied, extended object → at-or-past min_status). If any dependency is not met, REJECT with error listing blocking dependencies.status.json:
"status": "executing""phase": """updated" timestamp to current ISO-8601.status.json to confirm status is executing. If unchanged, retry or abort.plan.mdcompleted_steps field from .status.json to determine progress; skip steps ≤ completed_steps.bugfix/ and .analysis/ latest files. .bugfix/ contains actionable fix items with regression test specs (from both mid-exec and post-exec NEEDS_FIX); .analysis/ contains the full evaluation context. For each fix item in .bugfix/, follow the Regression Test Protocol from commands/references/test-strategy-by-type.md:
6a. Read the regression test specification from .bugfix/ (Category, Test approach, RED assertion, GREEN expectation)
6b. Write/locate the regression test (RED) — must fail against current codebase
6c. Run → confirm FAIL (RED)
6d. Apply the fix
6e. Run → confirm PASS (GREEN)
6f. Run full test suite → confirm zero regressions
Exemptions (pure typo ≤3 chars, comment-only, historical doc annotation) skip 6b-6e but still require 6f.
After all fix items are addressed, continue remaining stepsauto/references/plugin-delegation.md executor slot discovery. Semantic match against three signal sources (.status.json type, .target.md content, .plan.md step structure) — not rigid type-string comparison. Check plan-executor seed slot first, then domain-executor-* registry/semantic scan. If a matching executor plugin is found with health score >= 0.70:
plugin-delegation.md).status.json completed_steps, .summary.md to restore contextcompleted_steps + 1--step N is specified: proceed with native per-step loop below--step N specified, execute only that step; otherwise execute remaining incomplete steps in ordercumulative-green.jsonl, store hil-snapshots/ if applicable (VFP-applicable types only, see Per-Step step 5)
9.6. Refactor window — check for refactoring opportunities, run full suite to confirm no regressions (VFP-applicable types only, see Per-Step step 6)
9.7. Verify against .test/ criteria (diagnostics / build check). For domain-specific testing, can optionally invoke verify --checkpoint step-N
9.8. Record result (include VFP cycle summary for VFP-applicable types)
9.9. Update .status.json — Use Edit tool to set "completed_steps" to current step number and "updated" timestamp.status.json — Use Edit tool to set "updated" timestamp.summary.md with condensed context: current progress, steps completed, key decisions, issues encountered, remaining work (integrate from directory summaries)highlight/SKILL.md §3.1. Extract implementation experience from current execution context, write to library. Inline call failure should not block exec's main flow — highlight is an enhancement step, not a gating requirementhighlight/SKILL.md §3.3. Optional, encouraged (high-value). Capture implementation decisions and problem-solving reasoning. Inline call failure should not block exec's main flow (same fault isolation)/task-ai:check --checkpoint post-exec to evaluate the result."/task-ai:check --checkpoint mid-exec to evaluate and determine fix approach."| Current Status | After Exec | Condition |
|---|---|---|
review | executing | Execution starts |
executing | executing | NEEDS_FIX continuation (fix issues, stay executing) |
executing | blocked | Blocking dependency encountered |
Execution progress is tracked via .status.json fields:
completed_steps: integer, incremented after each step completes successfully. Reset to 0 when plan changes (by plan sub-command on re-plan). Validation: must be integer >= 0. If value is invalid (negative, non-integer), reset to 0 with warningupdated: timestamp of last execution activityFor long-running executions, intermediate progress can be observed by:
completed_steps in .status.json.summary.md for condensed contexttask-ai(<notebook>):exec execution startedtask-ai(<notebook>):feat <description>task-ai(<notebook>):fix <description>task-ai(<notebook>):exec step N/M donetask-ai(<notebook>):exec blockedfeat/fix type, state file changes use exec typeexecuting (NEEDS_FIX), exec reads both .bugfix/ (fix items with regression test specs, from mid-exec or post-exec) and .analysis/ (evaluation context). Each fix follows the RED→GREEN protocol (step 6a-6f) using the regression test specification provided by check in .bugfix/ — this is exec's binding to the Regression Test Protocol from commands/references/test-strategy-by-type.md--step N is used, the executor verifies prerequisites for that step are met, then signals (step-N) on completion for mid-exec checkpoint/task-ai:verify --checkpoint post-exec followed by /task-ai:check --checkpoint post-exec.test/ criteria is done during execution; full test suite / acceptance testing is part of the post-exec verify + check evaluationcommands/references/verification-first-protocol.md. Refer to that document for full VFP applicability rules, VH stub design patterns, and CGG thresholds<semantic>-impl.md, -verify.md, or -eval.md) provided guidance that contradicts actual runtime behavior (e.g., documented API signature doesn't match, performance claim is wrong), set quality_status: invalidated on that file — read file, update quality_status in frontmatter, then use library write to update: /task-ai:library write "<experience-path>" --content-file <modified-file> --notebook <notebook-name>.lock before proceeding and releases on completion (see Concurrency Protection in commands/task-ai.md)research sub-command before planning. During execution, if you discover valuable implementation details via web searches, you may still save findings to $NB_WORKSPACES_LIBRARY/.memory/.references/ — sanitize content (ten categories, references/injection-rules.md), apply source classification (references/blocked-sources.md), then use library write: /task-ai:library write ".memory/.references/<topic>.md" --content-file <sanitized-file> --notebook <notebook-name>/task-ai:verify integration: Per-step verification can optionally invoke verify --checkpoint step-N for domain-specific testing. For lightweight checks (build + lint), inline verification is sufficientauto mode (unattended), the following operations are PROHIBITED unless the plan explicitly calls for them: modifying .env or credential files, running destructive commands (rm -rf, git push --force, DROP TABLE), installing system-level packages (apt install, brew install), sending external requests (email, webhook, API calls to production). Violation → stop execution and signal (mid-exec) for human reviewProcess file annotations — triage, cross-impact assessment, and execution. Triggered automatically when annotations (Insert/Delete/Replace/Comment) are submitted from the file viewer UI via JSONL prompt.
Six-dimension gated review — evaluates plans, implementations, and skills through D1-D6 quality gates with convergence tracking. Use for post-plan review, mid-exec assessment, post-exec acceptance, or any time the user says 'check', 'review', 'audit', 'evaluate quality', or wants to know if deliverables are ready.
Cross-task knowledge library management — search, list, audit, maintain, and evolve the shared .library/ knowledge base. Includes security rules evolution loop (separate from task auto loop).
Generate step-by-step implementation plans with verification criteria. Use when the user asks 'how should we do this', 'make a plan', 'break this down into steps', 'what's the approach', or needs a roadmap before implementation.
Investigate requirements and domain knowledge to support any lifecycle phase. Default mode: autonomous objective refinement (O1→O2→O3) with background research, feasibility analysis, and goal synthesis — all three stages completed in one pass. Also callable from plan, exec, verify, or check for gap-only reference collection. Use when the user wants to understand before acting — 'research this', 'what are the options', 'feasibility analysis', or 'deepen the objective'.
Define task objectives and requirements in .target.md. Use when the user describes what they want to build, says 'I want to...', 'the goal is...', 'set the target', 'define requirements', or needs to clarify/refine what should be accomplished before planning.