Codebase to Spec

Alpha feature. Output quality varies by codebase and we’re actively iterating on prompts. Try it, and please send what you learn to support@dotrequirements.io.

When code exists but its spec doesn’t, codebase-to-spec reads the code and writes one for you. It’s useful before you refactor a legacy system, while onboarding to an unfamiliar codebase, or any time you want a readable account of what the code does without having to piece it together file by file.

It’s not the right tool for new-feature design. For that, collaborate with AI on requirements first and let them drive implementation.

Quickstart

npx -y @popoverai/dotrequirements@latest cts skill-install

then, in Claude Code :

/codebase-to-spec

That’s the whole setup — it works on a machine with nothing but Node 20+ and Claude Code (a version with dynamic-workflow support). No global install, no account, no configuration: the first line drops the skill, its worker agent, and the workflow into .claude/, pinned to the CLI version that installed them. Add --global to the first line to install for every project (~/.claude/) instead of just this one.

And re-running that first line is the only maintenance there is: each run checks for a newer version at the start and offers the refresh if you’re behind. Hand-edited skill files are never replaced without asking.

Use it

Run /codebase-to-spec — or just ask, e.g. “spec the auth module.” Then:

1. You confirm the scope — a path like src/auth, or the whole thing.
2. The workflow runs on its own in the background (watch it in /workflows): it plans a behavioral-area outline, has an independent reviewer sign off on that decomposition, drafts the requirements for each area in parallel and converges each one through review, then assembles them into a single spec and runs a final cross-area review pass that removes duplication and reconciles terminology and personas across areas.
3. You review the result — the requirements land in .requirements/*.requirements.md, with a summary that flags any areas worth a closer look.

You weigh in at the start (scope) and the end (review); everything between is autonomous — no step-by-step babysitting.

Scope it

Point it at a coherent slice — a package, module, or directory — rather than a whole monorepo. There’s a working-context budget: if the compressed view of your scope is too large for a single planning pass, the skill tells you and asks you to narrow it. Large codebases are best done a package at a time.

Push it — imports are free

Pushing a generated spec to DotRequirements Cloud doesn’t count against your plan’s requirement limit, no matter how large it is. Each codebase-to-spec run stamps its output files with a run marker (the ctsRun line in the frontmatter); when those files are pushed, their requirements arrive marked as imported and are exempt from the limit — permanently. You can review them, edit them, share them with your team, and run tests against them without any of it metering. The limit counts only requirements you author yourself, so it matters when you start adding new behavior, not when you import what your code already does.

The marker travels with the files, so committing the spec to git keeps the exemption: a teammate who clones your repo and connects their own team imports it free too.

Two warnings you might see at push time, and what they mean:

• “import marker not recognized — your CLI may need updating” — the marker didn’t validate (often an older or newer CLI than the one that generated it). The push still succeeds; the requirements are just saved as authored, which means they count toward your limit. Updating the CLI and re-running codebase-to-spec produces a freshly stamped spec.
• “import marker was already used” — each marker is valid for a limited window after its first push to your team. Re-pushing the same stamped files much later (or after deleting and re-importing) lands the requirements as authored. Re-running codebase-to-spec produces a fresh marker.

After the spec: get it in front of your team

A spec nobody reads didn’t need writing. The run ends with a short consultation about what you want the spec to do — and the paths it offers are real, not aspirational:

• PR it into the repo. The files in .requirements/ are plain Markdown — commit them and the spec lives and evolves alongside the code it describes.
• Review it with your team. Say yes and the assistant connects your project to DotRequirements Cloud (a browser login is the only thing you do), syncs the spec, and hands you the link to each document in the web app — plus two ways to bring a teammate in:
  • an invite URL for someone who’ll review and edit in the web platform, and
  • a read-only sync command (npx -y @popoverai/dotrequirements@latest sync --share drt_...) for someone who just wants the spec in their IDE, no account required.
• Drive AI-first development from it. The assistant can configure itself (dotrequirements ai-setup) so future sessions search, read, and update this spec through the CLI while implementing.
• Test against it. The test harness binds your tests to requirements by key, so coverage is tracked behavior by behavior.

None of this runs without your say-so — the assistant describes what a yes will do before you give it.

Feedback

Output quality, prompt sensitivity, and any rough edges — we want to hear about all of it. Email support@dotrequirements.io with a short description of the codebase and what the run produced (or failed to produce). Real examples drive the next round of prompt iteration.