name: regent-build
description: 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.
version: 0.2.0
author: REgent contributors
license: GPL-3.0-or-later
metadata:
hermes:
tags: [regent, build, subagent, reverse-roundtrip, test-oracle]
related_skills: [regent-reverse, plan, executing-plans]---
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
- Letting the rebuilder peek at the original source. Defeats the
whole roundtrip. The whitelist is the contract.
- 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.
- 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.
- Treating the rebuild artifact as production code. It is a
research output. Burn it after the report if you want.
- 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.
- 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
One-Shot Recipe
rm -rf /tmp/rebuild-<repo>
