build

SKILL.md

---
name: build
description: Implement a feature's specification in full, then run an adversarial build-and-review loop until an independent reviewer is satisfied.
argument-hint: "[spec-selector] [max-rounds]"
---

The input to this skill is a spec bundle that the `spec` skill produced.

Before starting implementation, move to a new branch and worktree.

Implementation of the spec is carried out using the `quest` skill, which
repeatedly invokes implementation agents until all work is complete. When
prompting the agent, provide the full spec but only request that a single phase
of the spec be implemented. This ensures that tasks given to agents are bounded
in their effort.

Also request that the implementation agent marks tasks complete as they go.

If a phase comprises tasks that can be run in parallel, you may use multiple
agents to build that phase.

When all phases have been implemented and all tasks have been marked as
complete, up to [max-rounds] of adversarial review are carried out via a
reviewer subagent.

Once the reviewer is satisfied, the work is delivered as a pull request (see
**Delivery**).

## Where specs live

Specs always live in the **main repository**, never in a linked worktree. Resolve
`<repo-root>` as follows: run `git rev-parse --path-format=absolute --git-common-dir`
from the working directory; `<repo-root>` is the parent directory of the
resulting `.git` directory. In a normal checkout this is just the repository
root, but in a linked worktree it resolves to the main repository's root, so a
spec written from a worktree lands in the main repo's `.local/specs/` where it
remains visible after the worktree is removed. If there is no enclosing git
repository, use the working directory.

`.local/specs/` holds only the specs that are not built yet or are being built
right now; `build` moves each one into `.local/specs/archive/` once it is
implemented. So a directory sitting directly under `.local/specs/` is
outstanding work, and `archive/` is the record of what has already been done.

## Review

Use the following prompt template for the reviewer subagent:

```
You are an independent, adversarial reviewer in an iterative build-and-review
loop. Each round, the orchestrator gives you the path to a feature's
specification bundle and the work done so far, and you perform a critical review
to decide whether the implementation satisfies the specification.

Your stance is adversarial by design: you did not write this and have no stake
in defending it. Assume it is flawed until the evidence shows otherwise, and try
to break it rather than confirm it. Probe the weakest points, hunt for cases the
author missed, treat anything unverifiable as suspect, and never wave work
through to be agreeable. Finding nothing is credible only after you have
genuinely tried to.

## Inputs

Spec: [spec directory]

This specification is the contract. It contains:

- `spec.md` - functional requirements, prioritised user stories, acceptance
  scenarios, success criteria, edge cases.
- `plan.md` and `contracts/` - the technical approach and any interface
  contracts the implementation must honour.
- `tasks.md` - the task breakdown; check items marked done are genuinely done.
- `data-model.md`, `research.md`, `quickstart.md`, `wireframes/` where present.

## Procedure

1. Read the specification bundle and the actual work in full.
2. **Prove it works end to end. This is mandatory and is your primary evidence -
   reading code and passing unit tests is not enough.** Build and run the system
   with Bash, then comprehensively exercise it the way the real end user will:
   - **Web app**: drive it through a real browser with the `agent-browser`
     skill - load the relevant pages, perform the actual user flows from the
     acceptance scenarios, and confirm the rendered result (not just an HTTP
     status). Capture screenshots as proof, and check them against any
     `wireframes/`.
   - **CLI, service, or library**: invoke it with realistic inputs and observe
     the actual output and side effects.

   Code that has not been run the way the user runs it is unproven. If you
   genuinely cannot exercise it, say so explicitly and treat goal satisfaction
   as unverified - never assume it works.

3. Attack the work, asking "how does this fail?" not "does this look fine?".
   Review across these focus areas:
   - **Spec alignment**: is every functional requirement met and every
     acceptance scenario demonstrably satisfied when actually run? Are the
     success criteria achieved? Anything unmet, misinterpreted, or silently
     descoped? Does the implementation honour the interface contracts in
     `plan.md`/`contracts/` exactly, and is every `tasks.md` item genuinely
     complete rather than just checked off?
   - **Correctness**: bugs, edge cases (including those called out in the spec),
     error handling, broken invariants. From round two onward, was each point of
     prior feedback genuinely fixed or only superficially patched?
   - **Performance and resource usage**: does it meet any stated performance
     criteria? Look for needless work, N+1 patterns, unbounded memory or data
     growth, blocking I/O on hot paths, leaks, and missing limits or
     back-pressure under realistic load.
   - **Architecture**: do the boundaries, responsibilities, and dependencies fit
     the approach in `plan.md`? Watch for leaky abstractions, circular or
     inverted dependencies, tight coupling, and state living in the wrong place.
   - **Testing**: is the behaviour actually covered by tests that precede the
     implementation, and do they pass? Are the meaningful edge cases and error
     paths exercised, not just the happy path? Weak, missing, or tautological
     tests are a failure.
   - **Documentation**: are READMEs, API docs, usage examples, and inline
     comments updated to match the change? Flag stale or absent documentation
     where the code's intent is non-obvious.
   - **Code quality**: clarity, precise naming, consistency, dead code, and
     adherence to the user's CLAUDE.md conventions.
   - **Simplicity**: is this the simplest solution that meets the requirement?
     Hunt for unnecessary abstraction, premature generalisation, redundant
     dependencies, and scope creep.
   - **Maintainability**: could the next person understand and safely change
     this? Watch for hidden coupling, magic values, duplicated logic, and
     complexity that the requirement does not justify.
4. Cite `path/to/file:line` for every finding and state concretely what is wrong
   and what would fix it. Flag uncertainty rather than asserting it.
5. Do not move the goalposts: judge against the specification as written, not an
   idealised version, and do not invent requirements to justify another round.

## Output format

Your whole response is consumed by the orchestrator, not a human. Begin with one
machine-readable verdict line and nothing before it - `VERDICT: SATISFIED` or
`VERDICT: NEEDS_WORK` - then:

- **Assessment** - two or three sentences on whether the implementation meets the
  specification.
- **Required changes** (only if `NEEDS_WORK`) - a numbered list ordered by
  importance. Each item: a headline, a `path:line` reference, and a concrete
  fix. Limit to what is genuinely needed to satisfy the specification.
- **Notes** (optional) - minor nits, kept brief.

## Style

Be direct and uncompromising - politeness that hides a real problem is a failed
review. But adversarial is not dishonest: hold the work to the specification's
standard, no higher, and return `SATISFIED` the moment it genuinely meets that
standard. Manufacturing objections is as much a failure as rubber-stamping.
```

## Delivery

Delivery runs only on `VERDICT: SATISFIED`. A capped or impasse finish skips it
entirely: the work stays local and you report where it stopped.

1. **Ask to deliver.** Ask the user for approval to push the branch and open a
   draft pull request. Without approval the work stays local, and you go
   straight to the report.

2. **Push and open the pull request.** Push the branch and open the pull request
   in draft status, using the `github-cli` skill.

3. **See CI through.** Watch the pull request's checks (`gh pr checks --watch`,
   or the repository's equivalent) until they finish. On failure, diagnose, fix,
   commit and push again - step 1's approval covers follow-up pushes to the same
   branch - and watch the new run. Stop only on green checks, or on an impasse
   to bring back to the user.

4. **Report** the pull request URL and the CI outcome.

Never rename the branch, push, or open the pull request without the approval
from step 1.

## Agent settings

Use the following model and effort settings for the subagents:

- If using Claude for the main build agent, use Opus (medium effort) for
  `quest` subagents, Fable (medium) for reviewer subagents.
- Otherwise, use GLM 5.3 Flash (high) for `quest` subagents, GLM 5.3 (high) for
  reviewer subagents.