archaeology

archaeology is a local software archaeology CLI. It surveys a complex project and produces a navigable map of its areas, artifacts, actions, guides, procedures, prompts, menus, evidence, and uncertainty.

It is inspired by SCUMM/MUD/MOO interfaces, but repurposed for software systems that have become too large, too agent-built, or too implicit for a human to comfortably hold in memory.

npm i -g archaeology
cd bootstrap-5.3.8
archaeology

For local development before publishing:

cd archaeology
npm link
cd ../bootstrap-5.3.8
archaeology

Why this exists

Modern AI-assisted projects can accumulate hidden powers: scripts, helpers, assistant prompts, procedures, tests, generated features, and forgotten workflows. archaeology makes those powers visible.

It asks:

• What kind of software site is this?
• What areas exist?
• What artifacts matter?
• What actions are safe?
• What guides should exist?
• What procedures operate the system?
• What evidence proves an action worked?
• What remains uncertain?

Current status

This is a strong initial project scaffold. It has:

• A dependency-free Node CLI.
• An interactive two-line menu.
• A project survey pass.
• XML generation for the software site survey.
• SOTA capture prompt generation.
• Guide prompt artifacts.
• Procedure and menu scaffolds.

Commands

archaeology                 # open interactive menu in the current directory
archaeology survey [path]   # survey a project and write .archaeology artifacts
archaeology menu [path]     # print generated menu XML if present
archaeology sota [path]     # refresh SOTA capture bundle
archaeology [path]          # shorthand for survey path

Generated files

Running archaeology survey . creates:

.archaeology/
  archaeology.xml
  survey.xml
  map.xml
  artifacts.xml
  actions.xml
  guides.xml
  prompts.xml
  procedures.xml
  menu.xml
  evidence.xml
  uncertainty.xml
  index.json
  reports/
    survey.md
    sota-capture.md
  workorders/

Two-line menu law

Every menu item must display as:

Title
Description

Example:

A) Look Around
   Show the generated site map, areas, artifacts, actions, guides, and next safe actions.

Philosophy

Every system must reveal its areas, artifacts, actions, guides, procedures, evidence, and uncertainty.

No hidden powers.
No invisible helpers.
No parser guessing.
No unexplained workflows.
The menu is the treaty between human and machine.

Project structure

bin/archaeology.mjs       # executable entrypoint
src/cli.mjs               # command routing and readline menu
src/survey.mjs            # project survey and XML generation
src/menu.mjs              # menu model and rendering
src/prompts.mjs           # generated SOTA/local guide prompts
src/classify.mjs          # heuristic file and domain classification
src/fswalk.mjs            # dependency-free filesystem walker
src/xml.mjs               # tiny XML writer helpers
examples/bootstrap-mini/  # small demo fixture

First implementation priorities

1. Bind submenus to artifact selection.
2. Add archaeology ask to query a selected generated guide prompt.
3. Add archaeology workorder to produce bounded local-agent tasks.
4. Add archaeology teach to promote a SOTA capture back into XML.
5. Add project-specific detectors for CSS frameworks, Web Components, agent systems, and build systems.

Safety model

The first version only reads the target project and writes .archaeology/. Future commands that modify project files should declare:

• write scope
• risk level
• evidence required
• human confirmation requirement