Reverse-engineer a codebase into a full CRISP project skeleton.
"Your codebase is the brief."
A companion to CRISP — the open-source framework for scoping and speccing AI projects. Archaeology is the entry point for projects that already have code but no docs.
Most real-world projects have code but no discovery artifacts. Inherited repos, dev handovers, agencies picking up mid-project, founders who built fast and now need to plan the next phase properly. Running CRISP from scratch on an existing project is wasteful — half the work is already encoded in the code.
CRISP Archaeology reads the codebase and recovers what it can. Then it asks targeted questions for the rest.
For stakeholders, consultants, and future developers:
- System Overview — what it does, who uses it, what breaks if it dies
- Architecture Map — components, responsibilities, external dependencies
- Tech Stack Inventory — ground truth from manifests, not the README
- Domain Glossary — the private language of the codebase, defined
- Business Context Memo — who pays, why, what matters most
- Risk & Constraint Register — technical debt, SPOFs, known constraints, the graveyard
- Feature Inventory — every route, endpoint, and feature with its current status
- Decision Log — why things are the way they are
- Open Questions Log — everything that couldn't be recovered, with owners
- Runbook Skeleton — deploy, rollback, failure modes
For Claude Code and other LLM coding agents:
CLAUDE.md— orientation, conventions, what never to touchARCHITECTURE.md— structured for grepping, not readingSECURITY.md— auth model, PII rules, hard constraintsDEPLOYMENT.md— environments, deploy commands, rollbackCONVENTIONS.md— naming, error handling, testing patterns, unwritten rules- Per-directory
CLAUDE.md— local context for every module
Four phases across multiple conversation turns:
- Solo recon — Claude reads the repo (git log, manifests, entry points, CI config, tests, folder structure) without asking a single question
- Strawman — Claude presents a deliberately incomplete skeleton. You correct it. Much faster than Q&A.
- Elicitation — Claude resolves every gap. Presents assumptions for confirmation. Never saves anything as truth without your sign-off. Parks what you don't know as open questions.
- Output — Full
docs/folder + agent-ready context files
After Archaeology completes, the project is in the same state as a project that completed CRISP Phase I. Phase S or Sprint sessions pick up from there.
| Marker | Meaning |
|---|---|
| ✅ | Confirmed from code or by you |
| ❓ | Inferred — needs confirmation |
| ❌ | Cannot recover from code — needs human |
| 🔓 | Open question — nobody could answer it yet |
Standard CRISP: Phase R → Phase I → Phase S → Sprints
CRISP Archaeology: Scan → Elicitation → docs/ → Phase S or Sprints
- CRISP — the main framework
- CRISP Archaeology (this repo) — entry point for existing codebases
CRISP Archaeology is part of the CRISP open-source ecosystem, built by Mileva — an AI automation agency that builds workflow systems replacing entire operational teams.
Questions, PRs, or war stories from the field: open an issue or find me on X @radekamirko.
🚧 v1.0 — skill and templates complete, not yet battle-tested on a real repo.
Outcome first. Always.