agentleFS
omarismailbomarismailb/product-wiki/.agents/skills/import-codebase/SKILL.md

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.

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
  1. Distinctive:

    Do not edit application code, tests, or config.

    line 19
  2. Distinctive:

    Do not claim inferred intent as fact (mark confidence: high / medium / low).

    line 20
  3. Distinctive:

    Do not stop after one capability.

    line 21
  4. Very specific:

    Do not write final wiki/ files.

    line 22
  5. Distinctive:

    Before writing import artifacts, load:

    line 26
  6. Very specific:

    If any path is missing, do not infer import structure from schemas or lints.

    line 32
  7. Distinctive:

    Stop only if the canonical contract cannot be restored.

    line 35
  8. Very specific:

    Write the result to intake/import-inventory.md using templates/import-inventory-template.md.

    line 51
  9. Very specific:

    Run node scripts/import-coverage.mjs and show the user the inventory and the count of capabilities to import.

    line 61
  10. Distinctive:

    Import one capability per proposal so each remains reviewable.

    line 70
  11. Very specific:

    After the batch, run node scripts/import-coverage.mjs.

    line 71
  12. Distinctive:

    Update the imported count, pending count, current batch, and next resume point.

    line 72
  13. Distinctive:

    Read the code paths for that capability closely enough to support claims.

    line 77
  14. Very specific:

    Run node scripts/proposal-lint.mjs and node scripts/proposal-traceability-lint.mjs.

    line 85
  15. Distinctive:

    If context gets low, stop after updating the inventory and write the exact resume point.

    line 92
  16. Distinctive:

    Do not leave the user guessing what remains.

    line 93
  17. Very specific:

    Every entry in intake/import-inventory.md is [x].

    line 97
  18. Distinctive:

    Every cross-cutting concern (auth, money, data ownership) is captured in a rule or decision.

    line 100
  19. Distinctive:

    If the repo is genuinely huge, it is still not acceptable to silently cover a fraction.

    line 102

≈ “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.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

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 under intake/proposals/.

Template contract

Before writing import artifacts, load:

  • templates/import-inventory-template.md
  • templates/import-proposal-template.md
  • references/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.md if 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:

  1. Re-read intake/import-inventory.md.
  2. Select the next unchecked capabilities in the current batch.
  3. Import one capability per proposal so each remains reviewable.
  4. After the batch, run node scripts/import-coverage.mjs.
  5. Update the imported count, pending count, current batch, and next resume point.
  6. Report the next exact command or prompt that continues from the first unchecked item.

For each capability:

  1. Read the code paths for that capability closely enough to support claims.
  2. Draft a proposal under intake/proposals/ using templates/import-proposal-template.md with 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.
  3. Include the overview impact: whether this capability changes the whole-product map, main journeys, capabilities, rules, boundaries, or key decisions.
  4. Tick the capability [x] in intake/import-inventory.md.
  5. Run node scripts/proposal-lint.mjs and node 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.md is [x].
  • node scripts/import-coverage.mjs reports 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.

Download now (ZIP)

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
What did you use it for? e.g. Reviewing pull requests in a Rails app

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.