# Spec Execute

> Executes a planned spec through parallel subagents, one testable slice each, gates re-run until dry. Refuses while any question on the spec stays open.

- Skill: `ainova-systems/spec-execute` (Agent Skill)
- Install (CLI): `npx skillmds@latest add ainova-systems/spec-execute`
- Raw SKILL.md: https://api.skillmd.com/api/skills/ainova-systems/spec-execute/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: ainova-systems (https://skillmd.com/u/ainova-systems)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/ainova-systems/spec-execute

---


# Execute a Spec

Orchestrate a planned spec to done. **You delegate; subagents write code.** Your leverage is prompt quality, sibling references, and consistency gates - not hand-writing code.

## Prime directive - consistency

The spec is the contract. Two sessions executing the same spec must produce convergent output; the mechanism is both reading the same plan phase + the same skill files + the same sibling files, never orchestrator-authored instructions. Speed and creative variants are bugs. Full doctrine: `spec-orchestration` rule.

## Preconditions (refuse, don't work around)

- **No open question stands.** Read the plan's `## Open questions`; one standing question stops the whole run and the refusal names each - `spec-answer` is the path. An ambiguity that can be resolved is not a question; it is unfinished work.
- The spec is approved for its mode: `supervised` - plan present, coverage complete; `autonomous` - `status: approved` via `spec-approve`.
- Clean tree (`git status --porcelain`); dirty - stop and surface, never sweep foreign work in.

## Phase A - Deep learning (never skip)

1. Read the spec end-to-end (requirements + plan), multiple passes. Read the feature doc it changes.
2. Read the project rules and the profile (branch model, verification commands, PR platform, `execution_mode`).
3. Inventory siblings: for every artefact in the plan, pin the concrete sibling file path. No sibling for an artefact - halt and ask the owner; never improvise a new pattern.
4. Reconcile plan vs reality: stubs already wired, helpers that already exist, rules the plan contradicts (rules win - flag and override).

## Phase B - Branch

1. `git fetch origin && git switch <base> && git pull --ff-only && git switch -c feature/<spec-slug>` where `<base>` is the integration branch when one exists, else the default branch. One spec = one branch.
2. `autonomous` mode only: set the spec's `status: in-progress` (the queue reads written status; in `supervised` mode status is read from the ticked steps and nothing is written).

## Phase C - Execute (parallel subagents)

1. **Unit of work = a testable slice** (backend entity + endpoints + tests in one shot; a full frontend feature in one shot) - never split by layer.
2. **Parallel by default**: disjoint file sets spawn subagents in one batch; serialize only on real dependencies.
3. **Prompts are pointers, not instructions.** Each prompt: goal (one sentence) + read-first list (rule files, feature-doc section, plan phase, sibling paths with the verbatim line "Start by reading `<sibling>`. Copy its structure verbatim. Adapt only fields / labels / types.") + skills to invoke + scope fence (in/out files). Re-explaining what a skill or sibling already says is the #1 divergence source, so a prompt that grew long is usually one that started explaining.
4. **Cross-cutting consistency gate before every commit point**: grep every removed/renamed symbol across the whole tree (backend, frontend, tests, docs, spec). Subagents see only their scope; only the orchestrator catches cross-layer drift.
5. **Verify per slice** via `dev-run-tests` (scoped); full suite at phase boundaries. **A work step is ticked only when a re-run of its gate comes back dry.** Each within-scope rework is one line in the plan's `## Corrections` - what was wrong, what was done, its source (`auto` from a gate, `dev` from a review comment naming an in-scope defect), and the root cause. A beyond-scope observation goes to `## Review findings` for the developer; a comment that changes a requirement is drift and goes back through the intake.
6. **Tick `## Work steps` boxes in the plan** as slices land - ticked progress is what makes execution resumable.
7. **Milestones, by mode.** `autonomous`: commit at milestones via `git-commit-push` - one commit = one shippable-for-testing unit; reactive CI wait (push freely between tasks; block on CI only at phase boundaries or when the baseline is red). `supervised`: no commits - work accumulates on the branch for the developer's review.
8. **Top-down reasoning on surprises** (red pipeline, failing test, odd diff): what is happening - what changed since last green - fix or delete per the feature doc - does an existing primitive already cover this. Trivial 1-2 line fixes are yours; larger ones go to a subagent.

## Phase D - Docs reconciliation

Apply every needed doc update automatically (via `spec-document` conventions) so the substrate matches the shipped behavior - never leave it stale or for a human.

1. Update the feature doc to the new behavior - it must describe TODAY after this change; fold the spec's one-off requirements into the feature doc's durable EARS criteria.
2. Reconcile the model and glossary when aggregates or terms changed; extract durable business rules into the project's rules area; conventions into intelligence rules; decisions via `spec-decision`.
3. Append new lessons to the spec's MUST READ FIRST so the next spec inherits them.
4. `spec-audit-docs` over the touched docs.

## Phase E - Hand-off, by mode

**`supervised`** (default): STOP here. Changes stay **uncommitted on the feature branch** - no commit, no push, no PR. Report: work steps ticked, gates green, `## Corrections` summary, `## Review findings` for the developer, and the diff stat. The developer reviews the diff by hand and runs the git flow (`git-commit-push` -> `git-open-pr`) himself.

**`autonomous`**:

1. Push, then open the PR via `git-open-pr` - it resolves the target, fills the project's own template when one exists, else the pack default, and refuses to leave the verification section empty.
2. Run `git-finalize-pr` - it drives the rounds until CI is green and every success factor the project declares holds on one head commit (`git-verify-pr`, `git-review-pr`), then hands to `git-complete-pr` for the threads and the one outcome. A stage that fails sends the PR back into a round; it never ends "green but unverified".
3. Report: PR URL, outcome label, the factors present, anything that needs the owner. Never merge. Final close (`spec-close`) runs after the owner accepts and the PR merges, not here.

## Verify

- Plan `## Work steps` fully ticked with every tick's gate re-run dry; feature doc matches shipped behavior; supervised - unstaged diff reported to the developer; autonomous - the PR carries an outcome label plus every declared success factor, fresh at head.

## Scope / hand-off

- No spec yet - `spec-pull` / `spec-create` first. Requirements but no plan - `spec-plan`. Plan not yet fact-checked - `spec-validate`. Open questions - `spec-answer`.
- Resuming a half-done spec - `spec-continue`.
- Merging - `git-merge-pr`, only after owner accept.

## Constraints
- Refuse to start while any open question stands; name each.
- Never push to the integration/default branch; never merge; never amend or force-push pushed commits.
- No new patterns without a sibling citation or explicit owner approval.
- Phase A is mandatory - silence there causes most rework.
- Black boxes (DB rows, deploy internals) are out of reach: solve via code analysis or escalate; never probe infra blindly.