# Regent Build

> Use when the user asks to rebuild a project from a REgent spec tree, run "spec → code + tests" roundtrip, or verify that a reverse-engineered spec is sufficient to reconstruct the original. Triggers on phrases like "按 spec 重建", "build from spec", "reconstruct from <spec_dir>", "verify spec sufficiency", or just "build". Pairs with `regent-reverse` — reverse produces the spec, this skill consumes it and produces runnable code graded against both `functional-checklist.md` (black-box) and `inventory/test-oracle.md` (white-box, per-function invariants). Works across languages via hermes subagent delegation.

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

---


# regent-build

Consume a REgent spec tree and produce runnable code that satisfies the spec's
`R-`/`S-` requirements, every line of `functional-checklist.md`, AND every
entry of `inventory/test-oracle.md`. The oracle is the second, white-box
grading key — it pins per-function invariants that a black-box checklist
cannot catch (e.g. `greet("  ")` must raise `ValueError`, not strip).
This is the second half of the roundtrip pipeline (the first half is
`regent-reverse`).

## When to Use

- A `spec/` tree exists (typically produced by `regent-reverse`) and the
  user wants to verify it is **sufficient** — i.e. an independent agent
  reading only the spec can rebuild the project.
- The user invokes `build`, `reconstruct from spec`, `verify spec`,
  `regent build <spec-dir>`, or similar.
- Bulk scenario: stress-test a spec without paying for a human rebuild.

**Don't use for**:
- Building from a fresh description (no spec yet) — use `regent-reverse`
  first to produce one.
- Modifying an existing project without a spec — that is refactor, not
  rebuild; do it manually or write a new skill for it later.
- Production deploys — the rebuild artifact is a research/verification
  output, not a release artifact.

## Inputs

- `spec_dir` — path to the spec tree (REQUIRED). Must contain
  `AGENTS.md`, `inventory/functional-checklist.md`, and `conventions/`.
- `out_dir` — where to put the rebuild. Default:
  `/tmp/rebuild-<repo-name>/`, taken from the spec's
  `README.md` first heading.
- `strategy` — `single-subagent` (default) | `multi-subagent`.
  Default is one subagent with the whole spec; multi-subagent only if
  the spec has 5+ `R-` heavy `specs/*.spec.md` files.

## Workflow (MUST follow in order)

Each step ends with a checkable condition. Do not advance until satisfied.

### 1. Verify the spec is buildable

Before spawning anything, check the spec itself is ready:

- `AGENTS.md` exists and is non-empty.
- `inventory/functional-checklist.md` exists and has at least 5
  `- [ ]` entries (fewer → spec too thin for a meaningful build;
  recommend running `regent-refine` first instead).
- `inventory/test-oracle.md` exists and contains at least one entry
  per public surface that the rebuild must satisfy on the white-box
  level (input/expects/pins triples). Without this, the rebuild's own
  tests are the only test set — and the roundtrip is self-graded.
- If `specs/_scope.md` exists, read it. Default strategy is
  scoped (not whole-repo).
- Target language/build-tool: read it from `conventions/dev-env.md`.

If any check fails, **stop**. Report the missing piece, do not
build.

### 2. Confirm the rebuilder cannot see the original source

This is the roundtrip property we are testing. The rebuilder MUST NOT
have access to the original repo tree (no path given, no clone hint).
Whitelist only the spec directory.

Explicit guard: when delegating, set the subagent's task to start with
"You may ONLY read files under `<spec_dir>`. Do NOT touch any path
outside it. The original repo exists at `<original_path_hint>` but is
not for reading."

(If a previous step accidentally left a copy of the repo under
`out_dir`, delete it before spawning.)

### 3. Spawn the rebuilder subagent

Use `delegate_task` with these properties:

- `role: leaf` (the rebuilder cannot delegate further; keeps the
  roundtrip tight).
- The subagent's goal MUST contain: the spec path, the out path,
  the language hint, the constraint to read-only the spec.
- Tell the subagent: read `AGENTS.md` first, then follow its
  rebuild order.
- Tell the subagent: do not invent CLI features, error messages,
  formats, or behavior NOT explicitly given in the spec.
  When in doubt, prefer omission over invention.
- Tell the subagent: when done, report in the response a bullet
  list of spec sections it had to invent beyond (so the spec author
  can patch).

### 4. Run the verification

After the subagent reports done:

- `cd <out_dir>`
- Read `conventions/dev-env.md` for the exact test/build commands.
- Run the test command. Capture exit code.
- Cross-check `functional-checklist.md` line by line against the
  rebuild artifact (run each command / import each module as the
  checklist prescribes).
- Read `inventory/test-oracle.md`. For each `### <symbol>` block,
  call the rebuilt function/method with the documented `input` and
  assert equality with the documented `expects`. Tick or fail with
  the actual vs expected.
- The two lists together (black-box checklist + white-box oracle)
  must BOTH be green before declaring PASS. A green checklist
  with a red oracle means the rebuild ships the right CLI but got
  the function semantics wrong (e.g. `greet("  ")` strips instead
  of raising) — the spec test-oracle catches what the behavioural
  checklist cannot.
- Tick or fail each item; record evidence (output, exit code, log
  line).

### 5. Decide

- **All green:** the spec is sufficient. Report.
- **Any red:** the spec has a hole. Report each failing item with
  the exact failure message. **Do not edit the rebuild to make it
  pass.** That would hide the spec gap. Recommend the spec author
  add the missing piece in `R-` and re-run this skill.
- **Re-builder invented something not in spec:** that is a separate
  signal — list it. It is not a fail (the build may still pass),
  but it is a spec-debt item to fix in the next reverse iteration.

### 6. Self-review

Before declaring done, verify:

- The rebuilder subagent received NO path to the original repo.
- The rebuild artifact was NOT mutated to mask failures.
- Every checklist item has a tick or a fail reason (no skipped).
- The spec-debt list is non-empty whenever the rebuilder reported
  invention.

## Common Pitfalls

1. **Letting the rebuilder peek at the original source.** Defeats the
   whole roundtrip. The whitelist is the contract.
2. **Patching the rebuild until tests pass.** You are testing the
   spec, not the rebuild. A green rebuild with a tweaked file is a
   false green; the spec still has the gap.
3. **Skipping `conventions/dev-env.md`.** The rebuild needs the
   project's build/test commands, not the agent's defaults. uv vs
   pip vs poetry, cargo vs rustup, go vs cgo — these matter.
4. **Treating the rebuild artifact as production code.** It is a
   research output. Burn it after the report if you want.
5. **Re-using the previous rebuild directory without cleaning.**
   Stale `.venv`, stale `Cargo.lock` target/ etc. produce false
   passes. Always start from an empty (or freshly `rm -rf`'d)
   out_dir.
6. **Running a multi-pass refine loop on spec-debt inside this
   skill.** That is a different skill. regent-build runs once,
   reports, exits.

## Verification Checklist

- [ ] `AGENTS.md` and `inventory/functional-checklist.md` both exist
      and are non-empty.
- [ ] Out directory was empty (or freshly cleaned) before the
      rebuilder started.
- [ ] The subagent received only the spec path; the original repo
      path was given as a "do not read" hint at most.
- [ ] Verification commands ran from `conventions/dev-env.md` (not
      agent defaults).
- [ ] Every `- [ ]` line in `functional-checklist.md` has tick or
      fail reason; nothing skipped silently.
- [ ] Every `### <symbol>` block in `inventory/test-oracle.md` has
      been executed against the rebuild with PASS or FAIL evidence;
      nothing skipped silently.
- [ ] Spec-debt list was produced even when the build passed.
- [ ] The rebuild artifact was NOT edited to mask failures.

## One-Shot Recipe

```bash
# After regent-reverse has produced spec at ./spec-out/<repo>/spec/
rm -rf /tmp/rebuild-<repo>
# Then invoke regent-build with:
#   spec_dir = ./spec-out/<repo>/spec
#   out_dir  = /tmp/rebuild-<repo>
#   strategy = single-subagent
# Expect a pass/fail report, a tick-by-tick checklist, and a
# spec-debt list.
```