{"id":51079054,"url":"https://github.com/maxgfr/reconstruct","last_synced_at":"2026-06-23T16:33:07.302Z","repository":{"id":361897400,"uuid":"1256317198","full_name":"maxgfr/reconstruct","owner":"maxgfr","description":"Analyze any repo and generate reconstruction PRDs to rebuild it from scratch","archived":false,"fork":false,"pushed_at":"2026-06-22T21:36:06.000Z","size":674,"stargazers_count":2,"open_issues_count":2,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-06-22T23:17:16.357Z","etag":null,"topics":["agent-skill","ai-agents","anthropic","claude","claude-code","cli","code-generation","developer-tools","nextjs","prd","reconstruct","reverse-engineering","scaffolding","skills","typescript"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/maxgfr.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-06-01T16:59:44.000Z","updated_at":"2026-06-16T07:01:53.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/maxgfr/reconstruct","commit_stats":null,"previous_names":["maxgfr/reconstruct"],"tags_count":21,"template":false,"template_full_name":null,"purl":"pkg:github/maxgfr/reconstruct","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/maxgfr%2Freconstruct","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/maxgfr%2Freconstruct/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/maxgfr%2Freconstruct/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/maxgfr%2Freconstruct/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/maxgfr","download_url":"https://codeload.github.com/maxgfr/reconstruct/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/maxgfr%2Freconstruct/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34698696,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-23T02:00:07.161Z","response_time":65,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["agent-skill","ai-agents","anthropic","claude","claude-code","cli","code-generation","developer-tools","nextjs","prd","reconstruct","reverse-engineering","scaffolding","skills","typescript"],"created_at":"2026-06-23T16:33:06.740Z","updated_at":"2026-06-23T16:33:07.294Z","avatar_url":"https://github.com/maxgfr.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# reconstruct\n\n[![CI](https://github.com/maxgfr/reconstruct/actions/workflows/ci.yml/badge.svg)](https://github.com/maxgfr/reconstruct/actions/workflows/ci.yml)\n\n\u003e Turn any repository — or a greenfield idea — into **reconstruction PRDs** an AI agent can\n\u003e rebuild the project from: faithful to the original (logic, routes, translations, schema,\n\u003e config), optionally improved, and **buildable enough that a fresh agent gets the contracts\n\u003e right** — enforced by a `--check` gate.\n\n`reconstruct` is an [Agent Skill](https://www.skills.sh/) (the open agent-skills\necosystem by Vercel). It pairs a **thin deterministic scaffold** with a **thick AI\nplaybook**: a bundled, dependency-free Node script extracts universal facts, resolves routes\n(with their HTTP method) for the major frameworks, and surfaces *candidate hints* for\neverything else; the AI agent that runs the skill supplies the deeper framework-aware\nunderstanding — the full interface surface, the data model, and the real features — for\n**any** stack.\n\n\u003e 📖 **Full documentation:** [`DOCUMENTATION.md`](./DOCUMENTATION.md) — concept, CLI\n\u003e reference, the analyzer pipeline, how to extend it, and FAQ.\n\n## Install\n\n```bash\n# into the current project (committed, team-shared)\nnpx skills add maxgfr/reconstruct\n\n# or globally for all your projects\nnpx skills add -g maxgfr/reconstruct\n```\n\nThis installs the skill into your agent (Claude Code, Cursor, Codex, …). Then just ask:\n\n\u003e \"Use the reconstruct skill on this repo in redesign + complex mode.\"\n\n## What it produces\n\n```\nreconstruction/\n├── REBUILD.md                 # master plan: build order + validation checklist\n├── RECONSTRUCTION.md          # (--merge) the whole tree in one markdown, WITH embedded source\n├── SPECS.md                   # (--specs) the whole spec, code-free — the file to implement from\n├── FEATURES.md                # (--features) every feature PRD only, in build order\n├── SUMMARY.md                 # (--summary) one-page digest of the reconstruction\n├── 00-overview/PRD.md         # product summary, stack, metrics, feature index\n├── architecture/\n│   ├── ARCHITECTURE.md        # architecture + external services, cross-cutting policies, i18n message catalog\n│   ├── INTERFACES.md          # interface surface (method · path · kind · handler) + per-op input/output/side-effect contracts\n│   ├── DATA-MODEL.md          # entities, fields, relations, indexes + enums \u0026 domain types\n│   └── diagram.md             # mermaid module diagram\n├── features/\n│   └── NN-\u003cslug\u003e/PRD.md       # one PRD per feature/module (build-order tiered)\n├── data/                      # ground truth, copied verbatim\n│   ├── translations/          # i18n files\n│   ├── schema/                # DB schema / models\n│   └── config/                # build/lint/env config\n├── source/                    # (fidelity=mirror) copied real source, per feature\n└── inventory.json             # machine-readable manifest\n```\n\n## Two axes + fidelity\n\n| Axis | Values | Effect |\n| --- | --- | --- |\n| **Mode** | `preserve` \\| `redesign` \\| `scratch` | Keep the current architecture, design a fresh one for the same features, or build **greenfield** from an interview (see [From scratch](#from-scratch-greenfield)). |\n| **Level** | `light` \\| `complex` | Faithful \u0026 concise, or also suggest improvements the agent folds in. |\n| **Fidelity** | `mirror` \\| `embed` \\| `describe` | Copy real files / inline key code / text-only. |\n\nFidelity defaults are derived (override with `--fidelity`):\n\n| Mode + Level | Fidelity |\n| --- | --- |\n| preserve + light | `mirror` |\n| preserve + complex | `embed` |\n| redesign + light | `embed` |\n| redesign + complex | `describe` |\n\n\u003e Translations, schema, and config are **always** copied into `data/` verbatim,\n\u003e regardless of fidelity — you can't faithfully \"rewrite\" data.\n\n## Standalone CLI\n\nThe deterministic engine also runs on its own (no agent, no API key):\n\n```bash\nnode scripts/analyze.mjs --repo ./my-app --out ./my-app/reconstruction \\\n  --mode preserve --level light --fidelity mirror\n\n# inspect the raw inventory without writing anything\nnode scripts/analyze.mjs --repo ./my-app --json\n```\n\nRun `node scripts/analyze.mjs --help` for all flags.\n\n## Bundling: one file or a digest\n\nFour optional, combinable flags collapse the multi-file tree:\n\n- `--merge` → **`RECONSTRUCTION.md`**: the whole tree in one coherent markdown\n  (single H1, linked table of contents, headings demoted one level; ordered\n  overview → architecture → features → build order), **with the embedded original\n  source**. The complete archive.\n- `--specs` → **`SPECS.md`**: the **same whole tree** as `--merge` — overview,\n  architecture (interfaces + data model), every feature PRD, build order — but\n  with each document's `## Source material` section (the embedded original source\n  code) **stripped**. Self-sufficient (it carries the contracts the feature PRDs\n  reference) yet code-free, so it's the single file you hand an agent to\n  **(re)implement the project from**.\n- `--features` → **`FEATURES.md`**: every feature PRD only — the product\n  functionality — in build order, in one file (single H1 + table of contents).\n  The features-only counterpart to `--merge`.\n- `--summary` → **`SUMMARY.md`**: a one-page digest from the inventory (stack,\n  libraries, size, features in build order, interface/data counts, locales,\n  unknowns, next steps).\n\n```bash\n# inline: produce the tree and the bundles in one run\nnode scripts/analyze.mjs --repo ./my-app --out ./my-app/reconstruction --merge --specs --features --summary\n\n# standalone post-step: (re)build the bundles from an existing output, no --repo\nnode scripts/analyze.mjs --merge --specs --features --summary --out ./my-app/reconstruction\n\n# just the code-free spec to implement from, from an existing reconstruction:\nnode scripts/analyze.mjs --specs --out ./my-app/reconstruction\n```\n\nThe standalone form reads `\u003cout\u003e/inventory.json` + the `.md` files, is idempotent,\nand errors clearly if the directory holds no `inventory.json`.\n\n## Validation: is it actually buildable?\n\nA reconstruction is only useful if a fresh agent can rebuild each unit **correctly** from\nthe PRD + architecture docs alone. Once the PRDs are enriched, run the buildability gate:\n\n```bash\nnode scripts/analyze.mjs --check --out ./my-app/reconstruction\n```\n\nIt exits non-zero on the structural failures — unresolved `🧠` callouts or `fill this in`\nplaceholders, a feature that references an undocumented entity/operation, a feature PRD\nmissing its spine, an uncovered locale, and a **gutted** data model / interface surface /\nfeature PRD (an emptied contract fails too, not just a callout-laden one).\n\n`--check` covers structure; the **nine contract categories** a PRD must actually carry —\nfield-level data model, fully-enumerated enums, operation \u0026 write contracts (a public write\ncan't require an owner foreign key), format validations, external services, quantified\npolicies, the i18n message catalog, and shared/owned UI components — are in\n[`references/buildability-checklist.md`](./references/buildability-checklist.md). In\ngreenfield mode the engine also **validates the plan's consistency** before rendering, so\ndangling references and anonymous-write-to-owner-FK contradictions are caught up front.\n\n### Two validation layers: deterministic gate + AI review\n\n`--check` is **deterministic** — it proves *structure* (no leftover callouts, the docs\ndeclare entities/operations, every PRD keeps its spine). It can't judge *substance*: a PRD\ncan pass the gate and still be unbuildable (vague requirements, happy-path-only criteria, an\nunsatisfiable write contract, an enum value that contradicts the data model). That second\njudgement is the **AI review** — performed **via the skill**, not the script: there is no\n`--ai` flag and no API key, because the agent running the skill *is* the reviewer. After\n`--check` passes, the agent re-reads the tree and applies\n[`references/ai-review-rubric.md`](./references/ai-review-rubric.md) (story completeness,\ntestable requirements, real Given/When/Then incl. failure paths, satisfiable write contracts,\nenum fidelity, cross-doc consistency, faithfulness, i18n, and the rebuild self-test), fixing\nevery **blocker** in place. Layer 1 is fast and CI-friendly; layer 2 is where a smart model\nearns its keep.\n\nThe layer-2 review is itself orchestrated by a **review ledger** so it terminates instead of\nlooping by feel. `--review` writes a per-feature worklist (`REVIEW.todo.json`), flagging only\nthe units whose content hash changed since the last round; an agent fans out one reviewer per\nflagged unit plus one **independent verifier** per blocker, then `--review --apply\nfindings.json` reduces the structured findings to `REVIEW.json` (`ok`, `residual`,\n`noProgress`/`staleRounds`):\n\n```bash\nnode scripts/analyze.mjs --review --out ./my-app/reconstruction\nnode scripts/analyze.mjs --review --apply findings.json --out ./my-app/reconstruction\n```\n\n`--check --semantic` folds both semantic gates into the structural one — `VERIFY.json`\n(requirements that don't trace to source) and `REVIEW.json` (unresolved blockers) — additively,\nnever relaxing `--check`. For larger trees the enrichment and the review/fix loop both fan out\nacross subagents; the protocol (map-reduce + the ledger) is in\n[`references/orchestration.md`](./references/orchestration.md).\n\n## From scratch (greenfield)\n\nNo repo yet? Turn an **idea** into the same reconstruction tree. Just ask your agent:\n\n\u003e \"Use reconstruct to turn my idea into a build plan.\"\n\n**You don't write `plan.json` by hand — the agent does.** Following [`SKILL.md`](./SKILL.md) →\n[`references/scratch-playbook.md`](./references/scratch-playbook.md), it **interviews you**\n(grill-with-docs style: one question at a time, recommending an answer each time), writes the\ndomain docs (`CONTEXT.md`, `docs/adr/`) and a **`plan.json`** — the structured transcript of the\ninterview — then runs the engine and enriches the PRDs:\n\n```bash\n# the agent runs this for you, once the interview has produced plan.json\nnode scripts/analyze.mjs --scratch --plan plan.json --out ./reconstruction --level complex --tdd\n```\n\n`plan.json` is an intermediate artifact the agent generates from your answers. You *can*\nhand-write one if you prefer — the schema and a worked example are in\n[`references/scratch-plan-schema.md`](./references/scratch-plan-schema.md).\n\nGreenfield collapses two axes — mode is always `scratch`, fidelity is forced to `describe`\n(there is no source to mirror) — while `--level` still applies (`complex` = a deeper interview\nthat also proposes alternatives and more ADRs). On top of the usual tree it also writes the\ninterview's domain docs, and `INTERFACES.md` / `DATA-MODEL.md` come **pre-filled** from the plan —\nalong with the enums, external services, cross-cutting policies, and i18n message catalog the\ninterview captures, so the from-scratch tree is as buildable as the reverse-engineered one:\n\n```\nreconstruction/\n├── …                         # the same REBUILD / overview / architecture / features tree\n├── CONTEXT.md                # the glossary (from plan.glossary + data-model relations)\n└── docs/adr/NNNN-*.md        # one terse ADR per recorded decision\n```\n\n`CONTEXT.md` and `docs/adr/` are written **if-absent**, so a richer version you authored during\nthe interview is never clobbered. Add `--tdd` (here or in any mode) to make every feature PRD and\n`REBUILD.md` drive the build **test-first** (red → green → refactor).\n\n- **The interview:** [`references/scratch-playbook.md`](./references/scratch-playbook.md)\n- **The `plan.json` contract + example:** [`references/scratch-plan-schema.md`](./references/scratch-plan-schema.md)\n- **A full worked plan:** [`tests/fixtures/scratch-plan/example.plan.json`](./tests/fixtures/scratch-plan/example.plan.json)\n  (`pnpm run parity` renders this plan and checks it is buildable-by-construction; pass\n  `-- --repo \u003crepo\u003e` to also check the code path and the from-scratch path converge).\n\n## How the rebuild works\n\n1. Read `00-overview/PRD.md`, `architecture/ARCHITECTURE.md`, `architecture/INTERFACES.md`,\n   and `architecture/DATA-MODEL.md`.\n2. Follow the dependency-tiered build order in `REBUILD.md`, implementing one\n   `features/\u003cslug\u003e/PRD.md` at a time.\n3. Use `data/` (and `source/` when present) as ground truth.\n\n**Any stack.** The deterministic scaffold is universal (tree, deps, env, i18n, stack/library\ndetection, plus *candidate hints* for routes/API/schema/entry points — so a stack without a\ndedicated adapter is never invisible). On top of that, **route adapters resolve the real\nroutes — with their HTTP method — for ten framework families** (Next.js, Express, Fastify,\nHono, Flask, FastAPI, NestJS, Django, Rails, Go) through a small pluggable registry. The deeper\nframework-aware depth — the full interface surface and data model — comes from the AI playbook\nin [`SKILL.md`](./SKILL.md) + [`references/`](./references), with per-stack cheat-sheets in\n[`references/stack-guides/`](./references/stack-guides) (Next.js, Remix, Nuxt, SvelteKit,\nAstro, Express/Fastify/Hono, NestJS, Django/Flask/FastAPI, Rails, Laravel, Go, Spring Boot,\ntRPC/gRPC, GraphQL, mobile). Adding agent guidance for a stack is just markdown; adding a\ndeterministic route adapter is a small, self-contained code PR — see\n[`references/adapters.md`](./references/adapters.md).\n\n**Monorepos too.** Workspaces are detected across ecosystems (npm/yarn/pnpm — with Lerna and\nNx as fallbacks —, Cargo `[workspace]`, `go.work`) and the analysis is attributed per\nworkspace: each entry of `inventory.workspaces` carries its own stack, dependencies, hints,\nand the manifest-derived `dependsOn` graph; features group per workspace and the build order\nfollows the workspace topological order (shared packages before the apps that consume them).\nSee [`references/stack-guides/monorepo.md`](./references/stack-guides/monorepo.md).\n\n## Development\n\n```bash\npnpm install\npnpm run build      # bundles src/ -\u003e scripts/analyze.mjs (committed, zero-dep)\npnpm test           # vitest unit + integration over multi-stack fixtures\npnpm run typecheck\n```\n\n## Security\n\nThe analyzer only **reads** the target repo's filesystem and **copies** files into the\noutput. It never executes the analyzed project's code. Review `scripts/` before running\non untrusted repositories.\n\n## License\n\nMIT © maxgfr\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmaxgfr%2Freconstruct","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmaxgfr%2Freconstruct","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmaxgfr%2Freconstruct/lists"}