build

Files (1)

• SKILL.md

SKILL.md (first lines)

> [← Skills index](../../README.md)

## What it does

Executes `phases/<name>/step{1..N}.md` end-to-end by spawning one non-interactive agent per step inside an isolated per-step git worktree, persisting real `step<N>-output.json` (subprocess exit code, stdout, stderr, measured duration), and emitting the 2-commit protocol on the per-step branch. Claude is the default; set `DEV_KIT_BUILD_AGENT=codex` to use `codex exec`. Every step has a bounded timeout from `DEV_KIT_AGENT_TIMEOUT_SECONDS` (default 1 hour, max 24 hours). Honors MUST-36 (one sub-agent per step), MUST-37 (3-cycle self-fix guard), MUST-38 (per-step worktree isolation).

## Session-scoped gate mode (workflow-fast-mode-lean)

Run `/dev-kit:harness-mode fast|full|custom` before (or during) a build to
control which optional local gates run this session — `full` (the default,
reset every session by a SessionStart hook) runs everything; `fast` skips
`slop_detector`; `custom` picks each gate individually.
Correctness gates (`stop_verify`, `secret_scan`, `intent_integrity`-high) never
turn off, regardless of mode — see `skills/harness-mode/SKILL.md`. Every step
preamble is appended with a one-line gate summary
(`lib/execute.py:_gate_summary_line`) so the per-step sub-agent knows what it
is and is not responsible for that step.

## Optional Linear preflight

At the start of a new build task, invoke `/dev-kit:linear` once when Linear is
enabled or available. Continue normally on `LINEAR_SKIP` or an implicit
`LINEAR_ERROR`; do not invoke it per step, retry, or sub-agent. See
`skills/linear/SKILL.md` for the reconciliation contract.

## Pre-flight gate

Refuses to start if `.dev-kit/ci-config.json` is absent. Run `/dev-kit:ci-setup` (or `/dev-kit:ci-setup --force` to refresh stale templates) first. No version comparison — presence of the marker is the only precondition; dev-kit does not gate consumer builds on a plugin-version floor.

## Composition with /dev-kit:research

For net-new feature ideas that need cited evidence before planning,
run `/dev-kit:research` directly, then `/dev-kit:plan` — Gate 2.1
(evidence) reads the cited claims straight from that research output.
No binder skill sits between them; `/dev-kit:plan` is a single
`Skill` hop away from a research result.

For bug reports that need a root-cause investigation instead of a quick
self-fix, invoke `mattpocock-skills:diagnosing-bugs` (it ships the same
reproduce → isolate → root-cause phases). Like the research path, it
**never invokes `/dev-kit:build`** — that stays a separate, explicit,
user-typed command, reached only after `/dev-kit:plan`'s Gate 5/5
auto-renders `proposal.html` and the user reviews it.

For single-session, non-bug work, `/dev-kit:build` runs the direct
`plan -> build` path — no binder. `/dev-kit:plan` emits the canonical
`phases/<name>/index.json` + `step<N>.md` artifacts either way; the
build runner reads those (NOT any binder-owned file).

## Behavior

1. `lib/execute.py:main` reads `phases/<name>/index.json` and calls
   `lib/dispatch_classifier.classify(steps)` to decide parallel vs.
   sequential. The decision + reason are emitted as the first stderr
   line (`dispatch: <mode> — <reason>`) so the user can audit why
   parallelism was rejected.

   **Classifier priority order** (first match wins):
   1. **Dependency edge** between any pair (`depends_on` / `consumes`) → sequential.
   2. **Vague scope** (TODO/FIXME/TBD/maybe/perhaps/either in preamble or AC) → sequential.
   3. **Overlapping writes** between two steps → sequential.
   4. **N ≥ 4** AND clean worktree isolation (every step with non-empty
      `writes` has an explicit `partition`) → parallel.
   5. **Otherwise** → sequential.

   The previous `--parallel N` / `--allow-parallel-build` flags are
   removed. There is no user-facing toggle; the harness reasons about
   dispatch, the user audits the decision.

2. Read `phases/<name>/index.json` (must contain `worktree: "<branch-base>"`; emitted by `/dev-kit:plan` as `<prefix>-<phase>`, e.g. `plan/plugin-harness-v3-0-mvp`); derive per-step branch = `<branch-base>-step<N>` and worktree path = `<root>/.worktrees/<phase>-step<N>`. Falls back to `feat/<phase>` when the field is absent (defense-in-depth, not the contract).
3. Skip entries where `status` ∈ `SKIPPABLE_STATUSES` (`completed`, `unimplemented`).
4. Bail with exit 2 if any step has `status == "blocked"` (no implicit resume).
   Override: `--skip-blocked` lets the runner continue past `blocked` steps, running only `pending | error | in_progress`. Skipped blocked steps are listed in `.dev-kit/hand-off/build→review.md` after the run.
5. For each RESUMABLE step:
   - `git worktree add -B <branch> <wt> origin/main` (MUST-38).
   - Read `step<N>.md` as preamble; append AC guard + `3-cycle self-fix max`.
   - `update_step_status(... status="in_progress")` (stamps `started_at`).
   - Spawn the selected agent command (`claude -p` or `codex exec`) with a bounded timeout (MUST-36).
   - Write `phases/<name>/step<N>-output.json` with REAL `exit_code`, `stdout`, `stderr`, `duration_seconds` (no fake `0.01` or `stub completed`).
   - On non-zero exit: `status="error"`, stash `error_message`, return non-zero — no commits.
   - On success: 2 commits on the per-step branch — `feat({phase}): step {N}[ — <name>]` then `chore({phase}): step {N} output`. Push the per-step branch to `origin` if `--push`.

## Status state machine (lib/execute.py)

SSOT: `lib/execute.py:VALID_STATUSES` (+ `SKIPPABLE_STATUSES`, `RESUMABLE_STATUSES`,
`--skip-blocked` override). The plan/build contract: plan emits `pending`,
build drives `in_progress`/`completed`/`error`/`blocked` per the source
constants.

## Hook integration (Stage B)

| Hook | Mode |
|---|---|
| tdd-guard | ON (when methodology=tdd) |
| bash-guard | ON |
| secret-scan | ON (PostToolUse) |
| slop-detector | ON |
| stop-verify | ON |

## Output

- `phases/<name>/step<N>-output.json` per step with `{exit_code, stdout, stderr, duration_seconds, timestamp}` — real subprocess output.
- `.dev-kit/hand-off/build→review.md` auto.
- 2-commit protocol on per-step branch: `feat({phase}): step {N} — {name}` + `chore({phase}): step {N} output`.

## Long-running session templates (>1 session tasks)

When a build phase is expected to span more than one Claude Code session
(typical signal: step count >= 5, or the user explicitly says "this is a
multi-day effort"), `build` is meant to copy the four-template artifact
bundle from `templates/` into the working tree of the build's per-step
worktree before the first step starts. The templates implement Pattern 2
from `docs/proposals/playbook-application/02-reanalysis.yaml` — the
cold-start recovery cost is the dominant per-session waste, and shipping a
fixed file layout removes the "what did the last session do?" discovery
loop.

| Template | Purpose |
|---|---|
| `templates/init.sh` | Bootstrap: verify env, read feature list, pick next failing feature, run baseline test. Idempotent — re-run every session open. |

From sh-ai-x/dev-harness-kit, MIT.

More from sh-ai-x/dev-harness-kit