SuperAPI AI Directory
Partner with us中文AI newsFavorites
Skillsspec-execute

spec-execute

Coding & development

View repository

Updated 10-16 08:49

About this skill

spec-execute (I2: Execute / plan.md + optional Task Pack)

Overview

The goal of I2 is to take the tasks in {FEATURE_DIR}/implementation/plan.md tasks inexecute in batches, run minimal verification, andwrite back status according to the mode(see design/aidlc_spec_implementation.md、design/aidlc_collaboration.md §3、design/aidlc_tooling_taskpack_skills.md）。

This skill is the Spec implementation-phase version of skills/executing-plans/SKILL.md :heavily reuse its "five-step execution + batch checkpoints + stop on blocker" skeleton, but align the semantics of the "plan file" as follows:

  • plan.md(required): Spec-level orchestration SSOT — scope, dependencies, sub-repos, NEEDS CLARIFICATION, task list andtask-levelcompletion check-off, merge-back to-dos, etc.
  • Task Pack mode (optional): if spec-context gives TASK_WORK_BRANCH=true and TASK_PACK_DIR is non-empty, or under {FEATURE_DIR}/implementation/tasks/ there exists a subdirectory with task.md/status.yaml , then:
    • the executable steps of the current tasktake precedence based on the corresponding {TASK_PACK_DIR}/task.md(or implementation/tasks/<TASK_DIR>/task.md);
    • high-frequency state(active phase, routing state, verification summary,updated_at , etc.) is written back to that directory's status.yaml；
    • when a task is completed, the corresponding Task must still be marked as plan.md in - [x] and asummary-levelaudit added (to avoid multiple people competing to modify the full text of plan.md ).
  • plan-only mode (no Task Pack): consistent with history — steps and statusonlyin plan.md。
  • By default, before each batch executionthe first 3 incomplete tasks
  • Any NEEDS CLARIFICATION / critical plan defect / blocker:stop immediately and report(do not make things up to push forward)
  • If decisions/contract changes arise during execution:only draft within {FEATURE_DIR} draft within, and append to plan.md append Merge-back to-do list(directly updating is prohibited at this stage project/*）
  • If the repository contains .gitmodules: before execution, you must verify based on plan.md whether the affected sub-repos that required have been switched to the Spec branch with the same name as the root project

At the start, announce:"I am using the spec-execute skill to execute in batches according to plan.md (and the Task Pack, if present) and write back to the SSOT."

When to use / not use

  • When to use
    • There is already {FEATURE_DIR}/implementation/plan.md(I1 is complete), and now enter I2 to implement by task.
    • You need to strictly do "batch checkpoint reporting" during execution, and write status/audit back to plan.md and/or the Task Pack status.yaml(depending on whether a Task Pack exists).
  • Do not use when
    • spec-context fails, FEATURE_DIRcannot be obtained (in this case you must stop).
    • plan.md does not exist, or the executable task list is missing (in this case go back to I1:spec-plan）。
    • plan.md of NEEDS CLARIFICATION are still unresolved, or a critical defect prevents starting (in this case you must first stop and propose clarification/revising the plan).

Gate / Stop (strictly enforced)

REQUIRED SUB-SKILL: executing spec-context to obtain context, and echo back in the conversation FEATURE_DIR=...(allowed (reuse)）。

Stop immediately (satisfying any one is sufficient):

  • Did not obtain FEATURE_DIR
  • The current branch is main/master(or you did not obtain the user's explicit consent to implement on the main branch)
  • {FEATURE_DIR}/implementation/plan.md does not exist or is unreadable
  • plan.md there are unresolved NEEDS CLARIFICATION, and they will block continued execution
  • The plan has critical defects: missing executable commands/missing minimal verification/unclear scope/unknown dependencies, making it impossible to start safely
  • plan.md sub-repositories marked as required have not created a Spec branch with the same name as the root project, or there are undeclared branch exceptions
  • The sub-repository is in detached HEAD, and plan.md has not declared it as an approved exception
  • Encountered a blocker during execution: missing dependencies/permissions/environment/data, repeated test failures, or an instruction that is not understood

Seek clarification, rather than guessing.

Inputs / Outputs (persistence conventions)

  • Read (progressive disclosure, minimum necessary)
    • {FEATURE_DIR}/implementation/plan.md(required; Spec-level SSOT)
    • Task Pack mode：spec-context output of TASK_PACK_DIR under task.md、status.yaml(if currently on a task branch); or read for each task in the batch implementation/tasks/<TASK_DIR>/task.md(if present)
    • plan.md referenced by {FEATURE_DIR}/requirements/*、{FEATURE_DIR}/design/*(read as needed, do not expand in full)
    • {FEATURE_DIR}/requirements/solution.md#impact-analysis(look up as needed: list of affected modules, invariants to follow, related ADRs, cross-module impact)
    • Project-level index (read-only, as needed):project/memory/*、project/contracts/、project/adr/(if .aidlc/project/ does not exist or the file is missing, mark CONTEXT GAP but do not block I2)
    • .gitmodules(if present; used to identify whether the sub-repository paths declared in the plan actually exist)
    • spec-context returned by SUBMODULE_SET_JSON(if present; used to verify branch consistency, detached HEAD, dirty worktree)
  • Write
    • Required write：{FEATURE_DIR}/implementation/plan.md — task-level - [x], summary audit, blockers, and Merge-back to-dos
    • Task Pack mode additionally writes: corresponding implementation/tasks/<TASK_DIR>/status.yaml(and as needed review.md) — high-frequency status, verification fields,activity_stage/routing_status(vocabulary see spec-plan/assets/collaboration_stages_and_states.md）
    • plan mode only: all status and step write-backs remain in plan.md
  • Code and configuration changes
    • Implement (create/modify/test) according to the path declared per task in plan.md Path implementation declared per task (create/modify/test)
  • Decision/contract drafts within Spec (if generated during execution)
    • ADR draft: preferably write to the "Decisions/Trade-offs" section of {FEATURE_DIR}/design/design.md ; if necessary add {FEATURE_DIR}/design/adr/*.md
    • Contract draft: write to {FEATURE_DIR}/design/contracts/
    • Sync requirement: in plan.md append/update the "Merge-back to-do list" (record only, do not directly modify in I2 project/*）

Command writing convention: default to PowerShell; for multiple commands on the same line use ; Separator (do not use &&）。

Flow (reuse the five-step skeleton of executing-plans)

Step 1: Load and review the plan (Review)

  1. Open and read {FEATURE_DIR}/implementation/plan.md
  2. Review strictly—identify any issues or concerns that would block execution, such as:
    • The task does not clearly state "which files to change / what commands to run / what signals to expect"
    • Missing a minimal verification method or the verification is not executable
    • The task is out of bounds (inconsistent with the scope / milestones of plan.md)
    • Dependencies/permissions/environment not satisfied
    • NEEDS CLARIFICATION not eliminated
    • plan.md The affected sub-repositories have been declared, but it is not clearly written required, same-name branch requirements, or exception_reason
    • .gitmodules / SUBMODULE_SET_JSON indicates that a certain required sub-repository has not been switched to the Spec branch with the same name as the root project, or is in detached HEAD / a dirty working tree
  3. If there are critical concerns:Stop before starting and report(write the problem clearly, provide the evidence-gathering path; if necessary, return to I1 to revise plan.md)
  4. If there are no concerns: proceed to batch execution

Step 2: Batch execute

Default: the first 3 unfinished tasks(may be adjusted based on risk and dependencies, but the reason must be explained).

Task Pack mode: Before executing a task, if its Task Pack exists,first open task.md to align the steps；plan.md that task block may be only a summary. Update at each step advance status.yaml(such as activity_stage: task-execute / routing_status: in_dev , etc.).

For each task:

  1. Mark as in_progress (plan.md and/or status.yaml）
  2. Execute strictly according to the task steps(source:task.md and plan.md merged into a single interpretation; do not skip steps; do not replace commands; do not secretly change acceptance)
  3. Run the minimal verification as declared by the task, and record key outputs/signals (PASS/FAIL criteria)
  4. Commit frequently (controlled by AUTO_COMMIT)
    • AUTO_COMMIT=true(default): execute at the commit points required by the plan git add + git commit(if the plan requires finer commit points, follow the plan first); Commit message must be in Chinese
    • AUTO_COMMIT=false: skip git add + git commit, in plan.md audit information, mark the commit field as "manual commit", and output "the following files have changed, please commit manually:" and the list of changed files
  5. Write back status:
    • Task Pack mode: first update status.yaml（verification、updated_at, routing/active phase); when the task is completed plan.md that item - [ ] → - [x] and writesummaryaudit (branch/commit/pr/changed_files may be listed in detail in task.md or status.yaml existing fields, to avoid repeatedly pasting large sections into plan.md）
    • only plan mode: still in plan.md complete the checkbox and full audit block
    • If blocked: in plan.md and/or status.yaml/task.md write the evidence-gathering path clearly, and stop proceeding to the next task
  6. Mark as completed (or blocked)

Step 3: Batch checkpoint report (Report checkpoint)

Must report when the batch is complete:

  • List of completed tasks (corresponding Task IDs)
  • Verification result summary (key commands + key outputs/signals)
  • plan.md and (if any)status.yaml written-back locations and audit/verification summary
  • Overview of incomplete tasks
  • List of blockers (if any)

then say: "Ready for feedback." andwait for feedbackbefore continuing to the next batch.

Step 4: Continue / Re-review

Based on the feedback:

  • If the plan has been updated or new key concerns have emerged: return to Step 1 to re-review
  • Otherwise: execute the next batch and repeat Steps 2–3 until the task list is fully processed

Step 5: Finish development (Finish)

When plan.md all planned tasks are complete and minimal verification passes:

  • This skill does not directly decide the "next step". Pleaseimmediately call using-aidlc to route to Finish:finishing-development(verification only, ensure tests/checks are all green).
  • Before entering Finish, ensure that plan.md 's audit information is complete and traceable (at least including commit and a summary of key verification results; if there is a PR, complete pr）

When to stop and seek help (Stop on block)

Stop execution immediately:

  • A blocker is encountered in the batch (missing dependency/permission/environment/data)
  • Tests or verification repeatedly fail (cannot be located or fixed under the current evidence)
  • Do not understand an instruction or acceptance criteria
  • Discover that plan.md has a critical defect (cannot continue safe execution)
  • Discover/add NEEDS CLARIFICATION will affect correctness or scope

Seek clarification rather than guessing.

When to return to earlier steps

When returning to review (Step 1):

  • The collaborator has updated based on your feedback plan.md
  • You need to adjust the task order/split to continue (must first make it explicit in plan.md before executing)
  • The fundamental approach needs to be reconsidered (stop first, then revise the plan/supplement evidence)

Keep in mind

  • Always first execute spec-context to obtain context, and get FEATURE_DIR=...(and TASK_PACK_DIR/TASK_WORK_BRANCH if it exists), stop on failure
  • Spec-levelOrchestration is governed by plan.md ;In Task Pack modetask steps and high-frequency status are governed by each package's task.md/status.yaml ,Prohibitedto fabricate implementation/tasks/ paths when there is no Task Pack
  • Strictly follow plan.md steps; do not skip verification
  • By default, the first 3 incomplete tasks per batch; between batches, only report and wait
  • Stop immediately when encountering blockers/clarification items; do not guess and push forward
  • ADRs/contracts generated during execution: only write drafts to disk in {FEATURE_DIR} , and in plan.md record Merge-back to-dos (I2 does not directly modify project/*）
  • When sub-repositories are involved, verify same-named branches before entering I2; after execution, write back audit information per repo; do not compress multiple repos' results into a single commit/pr/changed_files

Output and automatic routing after completion (must be executed)

At any of the following moments (after the batch checkpoint report ends / stopping due to a blockage / all tasks completed and preparing to enter Finish),mustcomplete the following actions (in order, without omission):

  1. Output ROUTER_SUMMARY(in YAML form, for the Router to make decisions; fill it in according to the current state, do not always hardcode the same value):

Filling rules:

  • Batch checkpoint (awaiting feedback)：needs_human_review=true，blocked=false
  • Blockage stop：needs_human_review=true，blocked=true, and clearly state block_reason
  • All tasks completed, preparing to enter Finish：needs_human_review=false，blocked=false
ROUTER_SUMMARY:
  stage: I2
  artifacts:
    - "{FEATURE_DIR}/implementation/plan.md"
    # Task Pack 模式下追加，例如：
    # - "{FEATURE_DIR}/implementation/tasks/T1-foo/status.yaml"
  needs_human_review: true
  blocked: false
  block_reason: ""
  notes: "示例：批次检查点已汇报，等待反馈后继续下一批"

  1. Immediately execute using-aidlc: pass the above ROUTER_SUMMARY as routing input to using-aidlc, let the Router determine the next step andautomatically advance(no need to wait for the user to say "continue").

    • If the Router determines that automatic continuation is possible: continue executing the next worker skill within the same conversation round (such as the next batch of I2, Finish, etc.)
    • If the Router triggers a hard interrupt: stop and output the blocking reason, required inputs, and candidate next steps

  2. Conversation output: before calling using-aidlc, you may briefly state "The deliverables of this phase have been persisted; now calling using-aidlc to route the next step."

Integration

Upstream / downstream skills:

  • spec-plan - Generate {FEATURE_DIR}/implementation/plan.md(Spec-level SSOT; optional Task Pack template/script)
  • finishing-development - Perform development wrap-up confirmation after all tasks are completed