--- name: ckb-code-map description: Read a source repository under src/ and write what it IS into wiki/entities/ — a `type: repository` page (remote, default branch, language, build and test commands, owner) plus `type: component` pages for its significant modules/services, cross-linked into the graph and stamped with the commit they were generated from so staleness is detectable. Use when the user says "map the code", "map src/", "refresh the code map", "index the repo", "add this repo to the wiki", or after cloning a new repo into src/. Distinct from `ckb-ingest` (which processes raw/inbox/ material and never reads code) and from reading code to answer a question (that is `ckb-retrieve` using src/ as evidence). Part of the opt-in `software` module. --- # Code map skill ## Purpose `src/` clones are gitignored: they are not in this KB's history and may be absent entirely from a fresh checkout. So the *knowledge* about a repository has to live in `wiki/`, or it doesn't survive. This skill produces that knowledge. It is deliberately **not** a code-to-prose dump — a wiki page restating what any reader could get by opening the file is pure liability, because it goes stale silently. What this skill records is what you cannot get by reading one file: how to obtain the repo, how to build and test it, what its pieces are, who owns it, and how those pieces connect to entities the wiki already knows about. ## Trigger phrases - "map the code" / "map `src/`" / "index the repo" - "refresh the code map" / "the code map is stale" - "add this repo to the wiki" / "I cloned a new repo into src" ## Scope rule Reads `src/`. Writes only `wiki/`. Never writes, commits, or pushes anything inside `src/` — those are independent repos with their own remotes. ## How to run this skill ### Step 0 — Confirm the module is installed and the repo exists Check `ckb.yaml` lists the `software` module. If `src/` is empty or the named repo isn't there, say so and stop — don't guess which repo was meant when several are present, ask. ### Step 1 — Gather the facts that don't come from reading code From inside the repo, cheaply: ```bash git -C src/ remote -v git -C src/ rev-parse --abbrev-ref HEAD git -C src/ rev-parse --short HEAD git -C src/ log -1 --format=%cI git -C src/ status --short ``` Then read the manifest and entry docs — `README`, `package.json`, `pyproject.toml`, `go.mod`, `Cargo.toml`, `Makefile`, CI config. Build and test commands come from here, not from inference. **Do not run the build, the tests, or any script from the repo** to find out what it does. Mapping is a read-only activity. ### Step 2 — Identify components, and be ruthless about what counts A component is a part of the system a person would name in conversation: a service, a CLI, a published package, a long-lived subsystem. A directory is not automatically a component. **Ten honest component pages beat a hundred mirroring the folder tree** — the second kind makes the wiki look thorough while making it useless to search. If you cannot write a one-sentence `tldr` for a candidate that says what it *does* (not where it lives), it isn't a component. Leave it out. ### Step 3 — Consult the cascade before creating anything Per the cascade rule, check whether pages already exist for this repo or its components — in `wiki/` first, then `linked/`, then `libs/`. Refreshing an existing page is the normal case, not the exception: update it, keep its history, and don't renumber or re-slug it just because a directory was renamed. ### Step 4 — Write the repository page `wiki/entities/.md`: ```markdown --- type: repository tldr: One sentence on what this software does — not "the repo for X". resource: https://git.example.com/me/thing repo: thing commit: a1b2c3d confidence: 0.9 quality: 0.8 last_updated: YYYY-MM-DD freshness_window_days: 90 retention: high --- # thing **Remote:** `git@git.example.com:me/thing.git` · **Default branch:** `main` · **Local path:** `src/thing` · **Mapped at:** `a1b2c3d` (YYYY-MM-DD) ## What it is Two or three sentences. What problem it solves and for whom. ## Getting it git clone git@git.example.com:me/thing.git src/thing ## Build and test ## Components * [[thing-api]] / [thing-api](/wiki/entities/thing-api.md) — ## Specs KB-root specs this repo implements, and the repo-level specs that implement them. Written by `ckb-spec`; leave the section here even when empty. ## Sources `src/thing` at `a1b2c3d`, mapped YYYY-MM-DD. README, `pyproject.toml`, CI config. ``` The `commit` field and the **Mapped at** line are what make this page auditable — they let a reader and `ckb-lint` tell how far the page has drifted from the code. Never write them from memory; take them from Step 1. ### Step 5 — Write component pages Same shape, `type: component`, with `repo: ` pointing home. Keep them thin and link upward to the repository page and sideways to whatever the wiki already knows — a component that talks to a system with an existing entity page should link to it rather than re-describing it. ### Step 6 — Graph, indexes, log - `wiki/graph/edges.json` — `part_of` (component → repository), `depends_on` (repo/component → an external library or a system that has a page), `owns` (person → repo, **only** on stated ownership, never inferred from commit counts). - `wiki/entities/index.md` — add or refresh a row per page. - `wiki/log.md` — one entry per run, per Rule B, naming the repo and commit. ### Step 7 — Report State the repo and commit mapped, pages created vs. refreshed, components deliberately skipped and why, anything you couldn't determine (no build command in the manifest — say so rather than inventing one), and whether the working tree was dirty at map time (a map taken from uncommitted work is fine, but should be labelled as such). Close with the standard reminder: on disk, not committed. ## Edge cases - **Dirty working tree** — map it, but record the commit *plus* a note that uncommitted changes were present. Don't refuse, and don't silently pretend the tree was clean. - **Repo with no remote** (local-only) — record `resource:` as absent and say plainly in **Getting it** that this repo exists only locally. That's a real finding: a gitignored, remote-less repo is one disk failure from gone. - **Monorepo** — one repository page, components per package. Don't create a repository page per package. - **Several repos, user said "map the code"** — ask which, or offer to do all; don't pick one. - **Repo that's mostly vendored/generated code** — map what's authored here. Note the vendored portion once, on the repository page. - **A component page already exists as `type: concept`** from an earlier ingest — don't create a duplicate. Update the existing page and change its type, noting the change in the log entry. --- *Licensed under the Apache License, Version 2.0 — see [LICENSE](../../../../LICENSE) at the repository root, or .*