Reconstruct

Reconstruct: repo → reconstruction PRDs

Turn any repository into a folder of PRDs an AI agent can follow to rebuild, recreate, clone, or scaffold the project from scratch — faithfully and optionally with improvements. A dependency-free Node script does the deterministic scaffold (facts + candidate hints); you (the agent) supply the framework-aware understanding — the interface surface, the data model, and the real features — for any stack. The deterministic scaffold is universal; the markdown is the program.

When to use

• "Rebuild / recreate / clone / scaffold this project from scratch."
• "Reverse-engineer this repo into a spec / PRDs."
• "Document this codebase so another team or agent can rebuild it."
• Greenfield — "build me a new project from scratch", "turn my idea into a build plan /

PRDs", "design a new app". There is no code yet: interview the user, then render the same tree. → jump to [From scratch](#from-scratch).

Skip it for tiny single-file scripts, or when the user wants a running app now, not a plan.

Inputs to confirm

1. Target repo (default: current dir) and output dir (default /reconstruction).
2. Mode — preserve (keep architecture) or redesign (same features, fresh architecture). Default preserve.
3. Level — light (faithful) or complex (also suggest improvements). Default light.
4. Fidelity — mirror / embed / describe. If unset, derived from mode+level.

Procedure

1. Run the analyzer (deterministic, no API key). Use the absolute path to

scripts/analyze.mjs inside the installed skill folder:

``bash node scripts/analyze.mjs --repo --out --mode --level [--fidelity ] [--granularity coarse|fine] [--merge] [--features] [--specs] [--summary] ``

Add --json to inspect the raw inventory first; --help for all flags (--include/--exclude globs scope large repos). --merge/--features/--specs/--summary are optional bundles — see Bundling the output below.

1. Read the scaffold: inventory.json (facts + hints + unknowns),

00-overview/PRD.md, architecture/ARCHITECTURE.md, the architecture/INTERFACES.md, architecture/DATA-MODEL.md, and (for a UI product) architecture/DESIGN-SYSTEM.md skeletons, and each features//PRD.md. Treat routes/i18n and everything under hints as candidates to verify, not truth. If inventory.warnings is present (a malformed manifest, a workspace dependency cycle), detection degraded there — verify those areas by hand before trusting the empty defaults.

1. Identify the stack & load its guide. Read inventory.stack. If a

references/stack-guides/.md matches, read it; otherwise use the generic method in references/analysis-playbook.md. For monorepos (inventory.workspaces — each entry carries its own stack, dependencies, dependsOn, routeCount, and hints), read references/stack-guides/monorepo.md and load the matching stack guide per workspace; verify the manifest-derived dependsOn graph and extend it with implicit edges. If the engine detected no workspaces but the layout looks like a monorepo (several apps/services with their own manifests), identify the workspaces yourself and scope re-runs with --include '/**'.

For a deep dive into one workspace, re-run the analyzer scoped to it: node scripts/analyze.mjs --repo --include '/**' --out -. Implicit edges to hunt for (manifest edges miss them): HTTP base-URLs pointing at a sibling app, queue/event topics one workspace publishes and another consumes, env vars consumed by two or more workspaces, and generated API clients. Cross-check the finished graph against architecture/diagram.md and REBUILD.md's tier order — and heed the analyzer's workspace dependency cycle warning: a cycle demotes the build order to path order, so break it (or document the bootstrap order) in REBUILD.md.

1. Map the interface surface → fill architecture/INTERFACES.md. Enumerate every

HTTP route, endpoint, tRPC/gRPC procedure, GraphQL operation, CLI command, and job — method · path/operation · handler file. Start from hints.routeCandidates/apiCandidates, then read the source to confirm. Cover the stack's real paradigm, not just file-based routing. hints.realtimeCandidates points at WebSocket/SSE surfaces (enumerate their channels, events, and message shapes — they rarely appear in route tables); hints.authCandidates points at the guards/middleware that carry each operation's auth rule. For each operation capture the contract: exact input shape, output shape, auth rule, and side effects (which entities it writes, transactional or not). See references/analysis-playbook.md (§Interface surface, §Contracts & buildability).

1. Extract the data model → fill architecture/DATA-MODEL.md. List entities/tables,

key fields + types, relations, indexes, and unique constraints from the ORM/schema in hints.schemaCandidates (raw copies in data/schema/), and fill the ## Enums & domain types section with the complete member list of every enum/status/role set. Then fill the architecture/ARCHITECTURE.md contract sections — External services & integrations (provider, request/response, timeout, failure), Cross-cutting policies (rate limits and format validations, quantified), and the i18n message catalog. For a UI product, also fill architecture/DESIGN-SYSTEM.md — design tokens with their exact values, theming (light/dark), typography, breakpoints, iconography, motion, the component-library contract (variants + states), and the accessibility target — from hints.designSystemCandidates (it self-degrades to a stub when there is no UI). See the playbook (§Data model, §Contracts & buildability) and references/buildability-checklist.md.

1. Group features semantically — and keep them small. Turn the path-based skeleton into real

product features; rename and merge truly trivial ones, but prefer many focused features over a few broad ones: if a unit carries more than ~5–7 user stories or touches more than ~3 entities, split it. Concrete signals — split when a unit serves two disjoint actor sets (admin vs end-user), when its route clusters share no interface rows or entities, when its halves could ship independently in either order, or when its honest name needs an "and". Merge a unit into its neighbor (or Core) when it has a single story with no entity or route of its own, or is pure glue (re-exports, wiring); config-only groups fold into project-setup. Every distinct capability earns its own PRD. Link each feature to its interfaces, data, and components. See the playbook (§Features).

1. Turn every features//PRD.md into a complete PRD. Each one ships with a fixed spine —

Context & goal · User stories · Functional requirements · Interfaces & data · Acceptance criteria · Edge cases & failure modes · Definition of done (plus Test plan under --tdd, and Improvements/Enhancements at complex). Resolve every > 🧠 callout exhaustively and delete it: enumerate every actor and story, number every requirement, write Given/When/Then for each (including the failure paths), and list every edge case. A 🧠 callout left in place means the unit is not done. Also write the product summary in 00-overview/PRD.md and cross-reference INTERFACES.md/DATA-MODEL.md.

At scale, run steps 4–7 as the map-reduce in references/orchestration.md: one drafting agent per feature (each reads its files + hints and proposes interface/entity rows), then a single reduce that merges those proposals into the canonical INTERFACES.md/DATA-MODEL.md — deduping and reconciling conflicts against source — so the parallel drafts never race on the shared docs.

1. Finalize REBUILD.md: confirm the dependency-tiered build order and validation

checklist, then tell the user how to drive the rebuild (feed feature PRDs to an agent one by one, using data/ and source/ as ground truth).

1. Validate buildability — two layers, both must pass.

• Layer 1 — the deterministic gate (structure). Run the consistency self-review (every

feature's entities/operations/enums/locales resolve against the architecture docs; every write is satisfiable; anonymous writes target anonymous-capable entities), then run:

``bash node scripts/analyze.mjs --check --out ``

It exits non-zero on: a missing required document (REBUILD.md, 00-overview/PRD.md, or any of the three architecture docs); unresolved 🧠 callouts or fill this in placeholders; a feature PRD missing a spine section or leaving one empty (a heading with no content); or an architecture doc emptied of its contract (no entities in DATA-MODEL.md, no operations in INTERFACES.md). On the scratch path it additionally enforces reference integrity — a feature must not reference an entity/operation absent from the architecture docs (on the code path the inventory carries no dataModel/interfaces, so the contract-substance check above is the operative gate instead). An uncovered locale — or a UI product whose DESIGN-SYSTEM.md is left empty — is a warning. Fix every error and resolve the warnings. See references/buildability-checklist.md.

• Layer 2 — the AI review (substance). The gate proves structure but cannot judge

whether the prose is actually buildable. Once --check passes, you (the agent) run a semantic self-review against references/ai-review-rubric.md — story completeness, testable requirements, real Given/When/Then (incl. failure paths), satisfiable write contracts, enum fidelity, cross-doc consistency, faithfulness, i18n, and the decisive rebuild self-test. This runs via the skill (no API key, no --ai flag — the model is the reviewer). node scripts/analyze.mjs --review --out writes the per-feature worklist (flagging only changed units); fan out one reviewer per flagged unit + one independent verifier per blocker, then --review --apply findings.json reduces them to REVIEW.json. A unit is done when it has zero blockers. Fix blockers in place, re-run --check, repeat until clean. See references/orchestration.md for the fan-out protocol.

• The semantic gate — fail-closed. Once the review converges, adjudicate the

requirement→source ledger too, then fold everything into the single final gate:

``bash node scripts/analyze.mjs --verify --out # requirement↔evidence worklist # adjudicate each pair against the original source → verdicts.json node scripts/analyze.mjs --verify --apply verdicts.json --out node scripts/analyze.mjs --check --semantic --out # the final gate ``

--check --semantic re-reduces BOTH persisted ledgers (VERIFY.json verdicts, REVIEW.json findings) and re-resolves every cited evidenceRef against the inventory — a stale or hand-edited ok: true never passes — and it fails closed: a missing or unreadable ledger is an error. --allow-unverified downgrades that to a warning; use it only deliberately, and say so in the final report.

1. Run the convergence loop — autonomously, to completion. A reconstruction is not done

when the scaffold is filled; it is done when it converges to buildable. You own this loop end-to-end: run it yourself, to the fixpoint, in one go. Do not hand rounds back to the user, do not ask "should I continue?", and do not stop at the first pass — the user invokes the skill once and expects a finished, buildable tree out the other side. Iterate both layers until the tree is clean — this loop is what turns "PRDs exist" into "a fresh agent rebuilds the right software":

`` round = 1 repeat: a. enrich (or fix) the changed units # write/repair the prose b. node scripts/analyze.mjs --check --out # Layer 1: structure — fix errors, repeat (b) c. node scripts/analyze.mjs --review --out # Layer 2 worklist: flags only what CHANGED d. review each flagged unit + verify each blocker # per references/ai-review-rubric.md → save findings.json (one finder/unit, one independent verifier/blocker) e. node scripts/analyze.mjs --review --apply findings.json --out # reduce → REVIEW.json f. when (b)–(e) are clean: node scripts/analyze.mjs --verify --out → adjudicate each requirement↔evidence pair → --verify --apply verdicts.json --out g. node scripts/analyze.mjs --check --semantic --out # the final, fail-closed gate until --check --semantic exits 0 (structure AND both semantic ledgers clean) or REVIEW.json.staleRounds >= 2 or round > 5 ``

The review ledger makes the loop terminate on a correct fixpoint without guesswork: --review content-hashes every unit so each round re-reviews only what changed; --review --apply reduces the findings to REVIEW.json — ok (zero unrefuted blockers), residual (the gating blockers, by stable id), and noProgress/staleRounds (the same blockers survived a fix round). The fan-out mechanics (finder/verifier roles, the finding schema, the enrichment map-reduce) live in references/orchestration.md.

Rules that make the loop terminate on a correct fixpoint, not a false one:

• A finding is resolved only when a fresh reviewer confirms it — keep the reviewer

separate from the author (an adversarial verifier prompted to refute buildability sets each blocker's verdict; a refuted blocker drops out of REVIEW.json.residual). Don't self-certify.

• Only re-review what changed: --review content-hashes each unit and flags needsReview,

so the loop shrinks instead of re-scanning a clean tree. Review exactly the flagged units.

• Ground every fix in source/data/ (code mode) or CONTEXT.md/ADRs (scratch mode) — a

fix that invents behaviour just trades one finding for another; faithfulness is the anchor.

• Stop at zero blockers, not zero findings. REVIEW.json.ok gates "buildable"; majors are

worth fixing, minors are optional polish — record what you deliberately leave.

• If the loop is not shrinking (REVIEW.json.noProgress — the same residual ids recur), the

contract in the architecture docs is wrong, not the feature PRD — fix INTERFACES.md/ DATA-MODEL.md first; the features that hang off it stop regressing.

At scale, drive the loop as a fan-out — one finder + one independent verifier per changed feature — per references/orchestration.md (which also covers the parallel map-reduce enrichment). Terminate on the ledger, not by feel: stop at REVIEW.json.ok (the fixpoint), or when staleRounds >= 2 (two rounds stuck on the same blockers) or after ≤ 5 rounds. When you stop not at ok, do not stop silently: the escalation ladder is re-edit the unit → fix the shared architecture contract those blockers share → record and report — write every remaining REVIEW.json.failures entry into REBUILD.md under a ## Known gaps / unresolved blockers list (owning unit, the finding, what was tried) and surface it to the user. If a residual blocker is a faithful property of the original (a real bug you're preserving), record it rather than looping on it. Report once, at the end — the final --check/REVIEW.json result, the zero-blocker confirmation (or the known-gaps list), and anything you deliberately left. The use

…

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: maxgfr
• Source: maxgfr/reconstruct
• License: MIT

Install and usage instructions live in the source repository linked above.