SuperAPI AI Directory
Partner中文AI newsFavorites
Skillsspec-execute

spec-execute

General & other

View repository

Updated 10-16 05:04

About this skill

spec-execute (I2: execution / plan.md SSOT)

Overview

The goal of I2 is to take the tasks in {FEATURE_DIR}/implementation/plan.md tasks inexecute them in batches, and write the execution status and minimal audit informationback only to plan.md(as the sole execution checklist and status SSOT).

This skill is the skills/executing-plans/SKILL.md Spec implementation-phase version:heavily reusing its "five-step execution + batch checkpoints + stop on blockers" skeleton, but replacing the semantics of the "plan file" with the hard constraints of the implementation-phase SOP (see design/aisdlc_spec_implementation.md):

  • plan.md plan.md is thesoleexecution checklist and status source (checkbox + audit information + verification result summary)
  • by default, execute each batchthe first 3 incomplete tasks
  • any NEEDS CLARIFICATION / critical plan defect / blocker:stop immediately and report(no making things up to push forward)
  • if decisions/contract changes arise during execution:draft only within {FEATURE_DIR} draft in, and append to plan.md a Merge-back to-do list(directly updating is prohibited at this stage project/*）
  • if the repository has .gitmodules: before execution, you must verify based on plan.md whether the affected and required sub-repositories have 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 write back to the SSOT."

When to use / not use

  • When to use
    • already exists {FEATURE_DIR}/implementation/plan.md(I1 is complete), and now you are entering I2 to implement by task.
    • you need to strictly perform "batch checkpoint reporting" during execution, and write status/audit back to plan.md。
  • Do not use when
    • spec-context fails, cannot obtain FEATURE_DIR(in this case you must stop).
    • plan.md does not exist, or lacks an executable task list (in this case return to I1:spec-plan）。
    • plan.md 's NEEDS CLARIFICATION has still not been eliminated, or there are critical defects that make it impossible to start (in this case you must first stop and propose clarification/plan fixes).

Gates / Stop (strictly enforced)

REQUIRED SUB-SKILL: executing spec-context to obtain context, and echo in the conversation FEATURE_DIR=...(allowing (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 is an uneliminated NEEDS CLARIFICATIONin
  • the plan has critical defects: missing executable commands/missing minimal verification/unclear scope/unclear 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
  • Blocked during execution: missing dependencies/permissions/environment/data, repeated test failures, or an instruction that is not understood

Seek clarification rather than guessing.

Input / Output (persistence conventions)

  • Read (progressive disclosure, minimum necessary)
    • {FEATURE_DIR}/implementation/plan.md(required; SSOT)
    • plan.md referenced by {FEATURE_DIR}/requirements/*、{FEATURE_DIR}/design/*(read on demand, do not expand in full)
    • {FEATURE_DIR}/requirements/solution.md#impact-analysis(look up on demand: list of affected modules, invariants to follow, related ADRs, cross-module impact)
    • Project-level index (read-only, on demand):project/memory/*、project/contracts/、project/adr/
    • .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 (single source of state)
    • Write back only state/audit {FEATURE_DIR}/implementation/plan.md: check off tasks, fill in by repo branch/commit/pr/changed_files, record summaries of key verification results and evidence paths for blockers
  • Code and configuration changes
    • Implement according to plan.md the paths declared per task (create/modify/test)
  • Decision/contract drafts within the Spec (if produced during execution)
    • ADR draft: preferentially write to {FEATURE_DIR}/design/design.md the "Decisions/Trade-offs" section; add if necessary {FEATURE_DIR}/design/adr/*.md
    • Contract draft: write to {FEATURE_DIR}/design/contracts/
    • Sync requirement: in plan.md append/update the "Merge-back TODO list" (record only, do not directly modify in I2 project/*）

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

Process (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. Strictly review—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 signal is expected"
    • Missing a minimal verification method or verification is not executable
    • Task out of bounds (inconsistent with the scope/milestones of plan.md)
    • Dependencies/permissions/environment not satisfied
    • NEEDS CLARIFICATION not eliminated
    • plan.md has declared affected sub-repositories, but does not clearly state required, same-name branch requirement, or exception_reason
    • .gitmodules / SUBMODULE_SET_JSON indicates that a certain required sub-repository is not switched to the Spec branch with the same name as the root project, or is in detached HEAD / dirty worktree
  3. If there are key concerns:Stop and report before starting(state the problem clearly, provide evidence paths; 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 incomplete tasks(may be adjusted based on risk and dependencies, but the reason must be explained).

For each task:

  1. Mark as in_progress
  2. Execute strictly according to the task steps(do not skip steps; do not replace commands; do not secretly change acceptance criteria)
  3. Run the minimal verification declared by the task, and record key outputs/signals (PASS/FAIL criteria)
  4. Commit frequently(If the plan requires more granular submission points, prioritize the plan)
    • Commit message Must be in Chinese
  5. Write back to plan.md(single source of truth):
    • - [ ] → - [x]
    • Complete according to the repo branch/commit/pr/changed_files
    • Record a summary of the key verification results for this task (including commands and key signals)
    • If blocked: clearly state "what is missing, how to complete it, and from whom/where to obtain evidence," and stop before proceeding to the next task
  6. Mark as completed (or blocked)

Step 3: Batch checkpoint report (Report checkpoint)

When the batch is complete, you must report:

  • List of completed tasks (corresponding Task IDs)
  • Summary of verification results (key commands + key output/signals)
  • plan.md Locations written back and audit information (according to the repo's branch/commit/pr/changed_files)
  • 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 (Continue / Re-review)

Based on the feedback:

  • If the plan has been updated or new key concerns have arisen: 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 completed and minimal verification passes:

  • This skill does not directly decide the "next step." Pleaseimmediately call using-aisdlc to route to Finish:finishing-development(verification only, ensuring tests/checks are all green).
  • Before entering Finish, ensure that plan.md 's audit information is complete and traceable (including at least 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)
  • You do not understand an instruction or acceptance criterion
  • Discover that plan.md has a critical defect (cannot continue safely)
  • Discover/newly add NEEDS CLARIFICATION will affect correctness or scope

Seek clarification rather than guessing.

When to return to an earlier step

When returning to review (Step 1):

  • The collaborator has updated plan.md
  • based on your feedback; you need to adjust the task order/split to continue (must first clarify 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, get FEATURE_DIR=..., and stop if it fails
  • plan.md is the only execution checklist and status SSOT:Do not create another "source of status"
  • 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
  • ADR/contracts generated during execution: only write draft files within {FEATURE_DIR} and in plan.md Record Merge-back to-dos (I2 does not directly modify project/*）
  • When sub-repositories are involved, validate branches with the same name before entering I2; after execution, write back audit information by repo, and do not compress the results of multiple repos into a single entry commit/pr/changed_files

After completion, output and automatic routing (must be executed)

At any of the following moments (after the batch checkpoint report ends / stopping due to a blocker / all tasks completed and preparing to enter Finish),mustcomplete the following actions (in order, none may be omitted):

  1. Output ROUTER_SUMMARY(YAML form, for Router decision-making; fill in according to the current state, do not always hard-code the same value):

Filling rules:

  • Batch checkpoint (waiting for feedback)：needs_human_review=true，blocked=false
  • Blocked and stopped：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"
  needs_human_review: true
  blocked: false
  block_reason: ""
  notes: "示例：批次检查点已汇报，等待反馈后继续下一批"

  1. Immediately execute using-aisdlc: pass the above ROUTER_SUMMARY as routing input to using-aisdlc, and the Router determines the next step andautomatically advances(no need to wait for the user to say "continue").

    • If the Router determines that it can automatically continue running: continue executing the next worker skill in the same conversation turn (such as the next batch of I2, Finish, etc.)
    • If the Router triggers a hard interruption: stop and output the blocking reason, required inputs, and candidate next steps

  2. Conversation output: before calling using-aisdlc, you may briefly state "the artifacts for this phase have been persisted, and using-aisdlc is being called to route the next step."

Integration

Upstream / downstream skills:

  • spec-plan - Generate {FEATURE_DIR}/implementation/plan.md（SSOT）
  • finishing-development - After all tasks are completed, perform the development wrap-up confirmation