import-codebase
Skill8 starsChanged 5 months agoMITView on GitHub
Use when retrofitting Product Wiki onto an existing codebase or drafting the first product wiki from current code, docs, tests, and agent instructions.
In this repository8 other files it gives its agents.
- AGENTS.mdAGENTS.md
- CLAUDE.mdCLAUDE.md
- apply-wiki-changeSkill
- compile-changeSkill
- generate-checksSkill
- propose-changeSkill
- reconcile-wikiSkill
- review-architectureSkill
The file
Show its rules and text
We split this skill into the rules it gives an agent
19 rules. About 0 are common, 12 are distinctive, and 7 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈12
Distinctive · estimate
This author's own choices. Worth a look.
7
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Distinctive: line 19
Do not edit application code, tests, or config.
- Distinctive: line 20
Do not claim inferred intent as fact (mark confidence: high / medium / low).
- Distinctive: line 21
Do not stop after one capability.
- Very specific: line 22
Do not write final wiki/ files.
- Distinctive: line 26
Before writing import artifacts, load:
- Very specific: line 32
If any path is missing, do not infer import structure from schemas or lints.
- Distinctive: line 35
Stop only if the canonical contract cannot be restored.
- Very specific: line 51
Write the result to intake/import-inventory.md using templates/import-inventory-template.md.
- Very specific: line 61
Run node scripts/import-coverage.mjs and show the user the inventory and the count of capabilities to import.
- Distinctive: line 70
Import one capability per proposal so each remains reviewable.
- Very specific: line 71
After the batch, run node scripts/import-coverage.mjs.
- Distinctive: line 72
Update the imported count, pending count, current batch, and next resume point.
- Distinctive: line 77
Read the code paths for that capability closely enough to support claims.
- Very specific: line 85
Run node scripts/proposal-lint.mjs and node scripts/proposal-traceability-lint.mjs.
- Distinctive: line 92
If context gets low, stop after updating the inventory and write the exact resume point.
- Distinctive: line 93
Do not leave the user guessing what remains.
- Very specific: line 97
Every entry in intake/import-inventory.md is [x].
- Distinctive: line 100
Every cross-cutting concern (auth, money, data ownership) is captured in a rule or decision.
- Distinctive: line 102
If the repo is genuinely huge, it is still not acceptable to silently cover a fraction.
≈ “Common” is an estimate: at least 1 in 5 of the 364,980 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
Import Codebase
Your job is to reverse-compile an EXISTING codebase into a complete product wiki. This is not a sample or a first-slice. A retrofit is finished only when the whole product is mapped: every significant surface, module, route, job, and data store is represented by at least one capability in the wiki, or is explicitly recorded as out of scope.
Code is evidence, not truth. It shows what the product does today; it usually cannot recover why it exists or which options were rejected. Mark inference honestly.
Do not
- Do not edit application code, tests, or config.
- Do not claim inferred intent as fact (mark confidence: high / medium / low).
- Do not stop after one capability. One capability is a unit of work, not the deliverable.
- Do not write final
wiki/files. Import produces proposals underintake/proposals/.
Template contract
Before writing import artifacts, load:
templates/import-inventory-template.mdtemplates/import-proposal-template.mdreferences/brownfield-import-rubric.md
If any path is missing, do not infer import structure from schemas or lints.
First run node scripts/repair-contracts.mjs --write, then re-run node scripts/template-lint.mjs and node scripts/skill-lint.mjs.
Continue if repair succeeds.
Stop only if the canonical contract cannot be restored.
Phase 1 — Inventory the WHOLE codebase (mandatory, do this first)
Survey the entire repository before importing anything. You are building a complete map, not reading every line. Cover, at minimum:
- Entry points and product surfaces: web routes, API endpoints, CLI commands, jobs, queues, cron tasks, webhooks, UI pages.
- Top-level source layout: every significant directory under the app's source roots
(e.g.
src/,app/,lib/,services/,packages/,cmd/). - Data model: schemas, migrations, persistent stores, key entities.
- Existing intent:
README,docs/,AGENTS.md,CLAUDE.md,PRODUCT.md, ADRs,wiki/overview.mdif present, design-system docs, and tests that reveal intended behaviour. - Cross-cutting concerns: auth, permissions, secrets, money, multi-tenancy, observability.
Write the result to intake/import-inventory.md using
templates/import-inventory-template.md. It is a checklist of every candidate capability
with the code paths it covers, a confidence level, and a status box [ ] (pending) /
[x] (imported). This file is the backbone of the retrofit: it makes coverage explicit
and lets the import resume across sessions.
Group the inventory into reviewable batches of 3-5 capabilities, smaller when a capability
is risky, cross-cutting, or unclear. Record the batch number and next resume point in
intake/import-inventory.md.
Run node scripts/import-coverage.mjs and show the user the inventory and the count of
capabilities to import. This is the only point where you pause before importing.
Phase 2 — Import every capability (chunked, complete, resumable)
Work through the inventory until nothing significant is unmapped. For each batch:
- Re-read
intake/import-inventory.md. - Select the next unchecked capabilities in the current batch.
- Import one capability per proposal so each remains reviewable.
- After the batch, run
node scripts/import-coverage.mjs. - Update the imported count, pending count, current batch, and next resume point.
- Report the next exact command or prompt that continues from the first unchecked item.
For each capability:
- Read the code paths for that capability closely enough to support claims.
- Draft a proposal under
intake/proposals/usingtemplates/import-proposal-template.mdwith actors, jobs, stories, acceptance criteria, rules, journeys, capabilities, outcomes, non-goals, assumptions, glossary terms, and decisions — each with source evidence (file paths) and a confidence level. - Include the overview impact: whether this capability changes the whole-product map, main journeys, capabilities, rules, boundaries, or key decisions.
- Tick the capability
[x]inintake/import-inventory.md. - Run
node scripts/proposal-lint.mjsandnode scripts/proposal-traceability-lint.mjs.
Token and context discipline: import one capability per proposal so each stays reviewable,
and so a large repo can be imported across several sessions. Re-read
intake/import-inventory.md at the start of each session and continue from the first
pending entry. Do not re-import completed capabilities.
If context gets low, stop after updating the inventory and write the exact resume point. Do not leave the user guessing what remains.
Completeness — the retrofit is done only when this holds
- Every entry in
intake/import-inventory.mdis[x]. node scripts/import-coverage.mjsreports 0 pending capabilities and no unmapped top-level source directory (or each unmapped area is listed as a deliberate non-goal).- Every cross-cutting concern (auth, money, data ownership) is captured in a rule or decision.
If the repo is genuinely huge, it is still not acceptable to silently cover a fraction. State the total, import in batches, and keep the inventory honest so the user can see exactly how much is mapped and what remains.
Output (report after each session)
- Inventory path and total capabilities discovered.
- Capabilities imported this session and proposal paths.
- Coverage so far (imported / total) from
import-coverage.mjs. - Current batch and next resume point.
- Remaining pending capabilities and any unmapped code areas.
- Whole-product overview gaps that need the owner to confirm.
- Gaps where code cannot reveal intent (the why), flagged for the owner.
Related skills
apply-wiki-change: after the human approves import proposals.reconcile-wiki: after import, to find drift between the new wiki and the code.propose-change: for new features once the retrofit baseline exists.
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

