ai-build
$
npx mdskill add arcasilesgroup/ai-engineering/ai-buildExecution engine for approved plans. Reads plan.md and tasks.md, dispatches one subagent per task (fresh context); each task self-validates via TDD; a single final quality loop runs verify+review plus one bounded quality-remediation pass on the full changeset before /ai-pr. If stuck: STOP and re-plan.
SKILL.md
.github/skills/ai-buildView on GitHub ↗
---
name: ai-build
description: "Canonical implementation gateway: reads approved plan.md, resolves stack from manifest, deterministic-routes each task to its adapter, dispatches the build agent in an isolated worktree, runs TDD self-validation per task, then a single final quality loop with one bounded quality-remediation pass on the full changeset before /ai-pr. Trigger for 'go', 'start building', 'execute the plan', 'implement it', 'lets do this', 'build the plan', 'resume', 'continue'. Not without an approved plan; run /ai-plan first. Not for multi-concern specs needing decomposition; use /ai-autopilot instead. Not for a single function or subcomponent; use /ai-code."
effort: cheap
argument-hint: "[spec-NNN | --resume | --no-hitl]"
mode: agent
model_tier: haiku
mirror_family: copilot-skills
generated_by: ai-eng sync
canonical_source: .claude/skills/ai-build/SKILL.md
edit_policy: generated-do-not-edit
---
# Build
## Purpose
Execution engine for approved plans. Reads plan.md and tasks.md, dispatches one subagent per task (fresh context); each task self-validates via TDD; a single final quality loop runs verify+review plus one bounded quality-remediation pass on the full changeset before /ai-pr. If stuck: STOP and re-plan.
## When to Use
- After `/ai-plan` produces an approved plan
- To resume execution: `/ai-build --resume`
- Never without an approved plan (run `/ai-plan` first)
## Process
0. **Preflight dependencies** -- verify `.ai-engineering/specs/plan.md`, `.github/skills/_shared/execution-kernel.md`, `.github/skills/ai-build/handlers/quality.md`, and `.github/skills/ai-build/handlers/deliver.md` exist. If any are missing: STOP and report the exact missing path(s). Never improvise missing orchestration logic.
0b. **Executor route gate (spec-145)** -- read plan frontmatter `status` and `execution_route.executor`. If `status` is not `approved`, STOP for operator approval. If `executor: autopilot`, refuse this `/ai-build` run, print `execution_route.safe_next_command` (normally `/ai-autopilot`), and STOP. If route metadata is absent, continue with legacy behavior.
1. **Board sync (in_progress)** -- read `.ai-engineering/specs/spec.md` frontmatter `refs`; for each work item ref where the hierarchy rule is not `never_close` (i.e., user_stories, tasks, bugs, issues), invoke `/ai-board sync in_progress <work-item-ref>`. Fail-open: do not block DAG construction if this fails. Then read `<spec_id>` from `spec.md` frontmatter `spec:` and call `python .ai-engineering/scripts/spec_lifecycle.py start <spec_id>` to transition the canonical sidecar APPROVED→IN_PROGRESS (mirrors `status: in-progress` into spec.md frontmatter). Fail-open: a non-zero exit logs and does NOT block DAG construction.
2. **Advise advisory** -- before dispatching any build task, invoke the Advise agent (`ai-advise`) in `gate` mode for governance advisory. Fail-open: if advise is unavailable or errors, log warning and continue -- never block dispatch.
2b. **Stack overrides routing (D-127-06 / sub-008, spec-128 D-128-01)** -- per task, call `tools.skill_app.deterministic_router.resolve_adapter(task_path, spec_stack)` to obtain the overrides directory under `.ai-engineering/overrides/<stack>/`. Pass the resolved path to the build agent so it loads `conventions.md`, `tdd_harness.md`, `security_floor.md`, and `examples/` into context before writing code. `spec_stack` precedence: spec frontmatter `stack:` field over file-extension inference. `UnknownStackError` halts the task with a clear "no overrides for this stack" message.
2c. **Model dispatch routing (D-131-08 / sub-003, §10.4 DRY)** -- per task, inspect the plan.md task block to pick the model tier. Decision matrix:
* `Patch (deterministic):` present AND no synthesis-required hint → dispatch with `model_tier=haiku, effort=cheap` (cheap-tier, mechanical execution).
* Patch absent OR synthesis hint present → dispatch with `model_tier=sonnet, effort=mid` (mid-tier, judgment required).
* Operator opt-in `--max-effort` flag OR plan task tagged `architecture: true` → dispatch with `model_tier=opus, effort=high` (deep-architecture override).
Pass the resolved tier to the build agent via env var `AIENG_MODEL_TIER`. Log the decision via `emit_agent_dispatched(..., metadata={"model_tier": <tier>, "effort": <effort>, "patch_present": <bool>})`. Investing in `/ai-plan` (high-tier, exhaustive patch-ready output) is what unlocks cheap-tier execution everywhere downstream (brief §2.6 / spec D-131-08).
2d. **No-HITL Contract (D-134-03)** -- if `--no-hitl` is set, read `handlers/no-hitl.md` and apply its contract: single-concern gate, `NEEDS_CONTEXT → BLOCKED` promotion, `quality_loop_blocked → exit 78`, `--no-watch` implied for delivery, no auto-retry. Default `/ai-build` behavior is unchanged when the flag is absent.
3. **Execute kernel**: see `.github/skills/_shared/execution-kernel.md`. Build wraps each task with the kernel (Sub-flow 1 dispatch -> Sub-flow 2 build self-validation (TDD RED/GREEN/REFACTOR) -> Sub-flow 3 artifact collection -> Sub-flow 4 board sync). As each task reaches a terminal state, update `.ai-engineering/specs/plan.md` immediately before dispatching the next task. Do not defer checkbox/status writes to the end of the phase or the end of the spec. The pre/post wrappers above and below remain build-specific.
4. **Quality check** -- read `handlers/quality.md` and execute: Verify+Review on full changeset, single round, fail-loud with one bounded quality-remediation pass. Blocker/critical/high findings may be fixed once when scoped to quality-loop evidence; remaining blocker/critical/high findings → STOP + escalate (no second remediation pass).
5. **Deliver** -- read `handlers/deliver.md` and execute: PR via ai-pr with quality report.
## Resume Protocol
When invoked with `--resume`, use observable evidence only. Never guess hidden state. The build skill is the canonical implementation gateway (D-127-11) — replaces the legacy `/ai-build` slash command:
1. **Missing or placeholder plan**: if `.ai-engineering/specs/plan.md` is missing or still contains the placeholder `# No active plan`, STOP and run `/ai-plan`.
2. **Incomplete task execution**: if `.ai-engineering/specs/plan.md` still has unchecked task checkboxes, resume at the first incomplete phase. Skip completed tasks.
3. **Quality evidence missing**: if all task checkboxes are complete but `.ai-engineering/specs/plan.md` does not contain a `## Quality Outcome` section, resume at the Quality Check step. Read `handlers/quality.md`.
4. **Quality evidence present**: resume at the Deliver step. `handlers/deliver.md` is responsible for detecting whether an open PR already exists and either entering the watch-and-fix loop or creating/updating the PR.
5. **Conflicting evidence**: choose the earliest safe step and log why. Safety wins over convenience.
## Handler Dispatch Table
| Phase | Handler | Agent Pattern |
| ------------- | --------------------- | ----------------------------------- |
| Quality Check | `handlers/quality.md` | Verify + Review parallel |
| Deliver | `handlers/deliver.md` | PR pipeline + cleanup |
| No-HITL | `handlers/no-hitl.md` | deterministic / single-concern only |
## Common Mistakes
- Dispatching without an approved plan.
- Giving subagents the entire codebase context (scope them tightly).
- Skipping the final quality loop after task execution.
- Continuing past a BLOCKED task without user input.
- Batch-updating `plan.md` only at the end instead of updating it when each task closes.
- Modifying test files from a RED phase during a GREEN phase task.
- Skipping the quality check after task execution.
- Invoking `--no-hitl` on a multi-concern plan; use `/ai-autopilot` instead.
## Examples
### Example 1 — start fresh execution
User: "the plan is approved, go"
```
/ai-build
```
Reads `plan.md`, dispatches one agent per task with fresh context; each task self-validates via TDD; final quality loop verifies the full changeset and may consume one bounded quality-remediation pass before handing off to `/ai-pr` for delivery.
### Example 2 — resume after interruption
User: "resume the build from where we crashed"
```
/ai-build --resume
```
Reads `plan.md`, identifies the next un-checked task, re-enters at the correct state.
## Integration
Called by: user directly post-`/ai-plan` approval. Calls: `ai-build` agent, `ai-verify`, `ai-review`, `/ai-pr`, `/ai-board sync`. Reads: `_shared/execution-kernel.md`. Transitions to: PR merge, or back to `/ai-plan`. See also: `/ai-autopilot` (multi-concern + `--backlog` for backlog), `/ai-resolve-conflicts`.
$ARGUMENTS
More from arcasilesgroup/ai-engineering
- ai-adviseProactive governance advisor — checks standards, decisions, and quality trends during development. Always advisory, NEVER blocks. Three modes: `advise` (post-edit), `gate` (pre-dispatch), `drift` (on-demand decision audit). Trigger for 'governance check', 'advise on this change', 'check for drift', 'is this aligned with active decisions', 'shift-left advisory'. Not for blocking gates — use /ai-verify. Not for narrative code review — use /ai-review.
- ai-analyze-permissionsUse when Claude Code keeps asking to approve commands you have already approved, when settings.local.json has grown large, or when you want to consolidate permission grants into wildcard patterns. Trigger for 'too many permission prompts', 'clean up permissions', 'audit my settings', 'consolidate allow rules'. Claude Code only — not available in GitHub Copilot, Antigravity, or Codex.
- ai-animationDesigns motion, transitions, and micro-interactions for UI components: spring animations, gestures, easing, staggers — taste-driven detail compounding. Trigger for 'animate this', 'add transitions', 'micro-interactions for', 'gesture design', 'swipe to dismiss', 'easing for this', 'stagger the'. Not for design systems; use /ai-design instead. Not for visual art; use /ai-visual instead. Not for testing animation code; use /ai-test instead.
- ai-autopilotDelivers large multi-concern specs and backlog runs autonomously: decomposes specs into sub-specs (or normalizes work items into a backlog DAG), deep-plans with parallel agents, builds a dependency DAG, implements in waves, runs a single final quality loop with one bounded quality-remediation pass (verify+guard+review on full changeset), delivers via PR. Trigger for 'implement spec-NNN end to end', 'autopilot this', 'autonomous delivery', 'decompose and ship', 'run the backlog', 'execute these GitHub issues', 'process the sprint backlog'. Invocation is the approval gate. Not for small or single-concern tasks; use /ai-build instead. Not for ambiguous requirements; use /ai-brainstorm first.
- ai-boardOperates the project board (GitHub Projects v2 or Azure DevOps): discovers configuration after install (fields, state mappings, process templates) and syncs work-item state at lifecycle transitions. Trigger for 'set up the board', 'configure our ADO board', 'discover board fields', 'move this issue to in-review', 'update the board', 'mark as in progress', 'sync the work item state'. Two subcommands: `discover` (post-install configuration write) and `sync` (lifecycle state transitions). Auto-invoked via `sync` by /ai-brainstorm, /ai-build, and /ai-pr; fail-open. Not for backlog execution; use /ai-autopilot --backlog instead.
- ai-brainstormForces rigorous design interrogation BEFORE any code: explores approaches, surfaces ambiguity, gathers evidence, produces an approved spec that becomes the contract for /ai-plan. Trigger for 'lets add X', 'how should we handle Y', 'whats the best approach', 'I am thinking about', 'what should we build for'. Not for existing approved specs; use /ai-plan instead. Not for execution; use /ai-build instead.
- ai-branch-cleanupCleans branches safely: switches to the default branch, prunes merged and squash-merged branches, syncs to remote, sweeps stale specs, rotates `.ai-engineering/runtime/` per retention policy. Trigger for 'tidy up', 'tidy branches', 'sync to main', 'delete old branches', 'start fresh', 'rotate runtime'. Auto-invoked by /ai-pr after merge. Not for committing changes; use /ai-commit instead. Not for code-level dead-code removal; use /ai-simplify instead.
- ai-codeWrites production code that satisfies stack-context standards on the first pass: interface-first design, backward-compatibility checks, lightweight self-review. Trigger for 'implement this', 'write the code for', 'add X to Y', 'build this function', 'make this work'. Not for tests; use /ai-test instead. Not for debugging; use /ai-debug instead. Not for refactoring; use /ai-simplify instead. Not for executing an approved plan end-to-end; use /ai-build (the gateway).
- ai-commitRuns the governed commit pipeline: auto-branches from protected, stages selectively, formats and lints, scans for secrets, gates docs, composes a conventional message, pushes. Trigger for 'commit my changes', 'save my work', 'push this to remote', 'stage these files', 'ship it'. Not for opening a PR; use /ai-pr instead. Not for branch hygiene; use /ai-branch-cleanup instead.
- ai-constitutionInterviews the operator to produce a project-identity CONSTITUTION.md (Mission / Stakeholders / Vocabulary / Prohibitions / Compliance gates / Anti-goals / Boundaries / Escalation / Language / Lifecycle phase). Trigger for 'set up the constitution', 'define project identity', 'who is this project for', 'what does this project never do', 'amend the constitution'. Not for AI-behaviour rules — those live in CANONICAL.md / AGENTS.md. Not for spec governance; use /ai-governance instead.