md-index-init

md-index-init — one-time bootstrap of the MD index system

The system's sole purpose (write this into every artifact)

Let Claude, on receiving a request, locate the relevant code with the fewest possible reads — fast and precise — and see the key points' hierarchy and the location of related modules. The MDs do NOT describe requirements and do NOT record history: requirements keep changing, while code is "dead" — it sits at a fixed location. Every index file answers exactly two questions: "where is X" and "what is X related to".

Tier responsibilities (tier count is elastic, see the rules template):

1. Tier 1 = fast location: a big inventory, module/feature → owning location.
2. Tier 2 = location + hierarchy: features aggregated, pointing to lower-tier READMEs; modules that span directories are located one hop further from here.
3. Tier 3 = per-file description & associations: one line per file + cross-reference pointers.

Interaction language (questions only)

Every question, confirmation, modification plan, and the final report you address to the user uses the user's own language (the language they are chatting in — e.g. a user writing in Chinese gets Chinese questions and a Chinese final report). This is purely about talking to the user. It does NOT change what gets written into the MDs: generated MDs and injected rules still follow the Documentation-language rule in Step 1 (English by default; match an existing file's language when editing it). Keep the two separate — user-facing prose in the user's language, on-disk artifacts per the doc-language rule.

Workflow

Step 0 — inventory & classify existing MDs (mandatory for mid-stage projects)

Check git status first: if the working tree is dirty, suggest the user commit first or allow running on a fresh branch — everything this skill produces is new files plus appends, so a clean starting point means one git checkout . rolls everything back.

A mid-stage project almost certainly has MDs already. Run find . -name "*.md" (excluding artifact dirs) to inventory every existing file and classify each one. Non-conflicting items execute silently; lossy items are gathered into ONE modification plan and confirmed with the user in a single ask — never interrupt per file, and never delete existing content.

Modification plan format (only when C/D items exist; if there are no conflicts, skip the ask, go to Step 1, and note it in the final report):

| File | Current role | Proposed action | Fallback if declined |
|---|---|---|---|
| src/core/README.md | Architecture manual (~200 lines, has history narrative) | Add index section at top; move manual to docs/core-design.md with pointer | Index section only; manual stays below a --- divider (self-check exempts that part) |
| CLAUDE.md | Existing rule "all docs go in docs/, no doc files in code dirs" contradicts this system | Append an exception sub-item under that rule: directory READMEs are part of the index system, not "scattered doc files" | Don't inject the README-sync rule; system degrades to INDEX-only (not recommended — the location chain breaks) |

Show the full table once, wait for approval, then execute. If the user declines a row, apply the fallback or skip that file (skipped files are flagged "not on the index chain" in the final report).

Three iron laws across all types: 1) never delete existing content (append or relocate only); 2) every relocation leaves a pointer; 3) when unsure which type, treat as C (into the plan — let the user decide).

Step 1 — detect project shape (decides initial tier count)

Detect with ls / glob — do not scan file contents wholesale:

After deciding, confirm shape and tier count with the user in one sentence, then continue.

Also record during detection:

• •Source extensions of all languages (multi-language monorepos: miss none — this defines "code directory");
• •Build-artifact exempt dirs (node_modules/dist/bin/obj/target/… — prefill by stack convention; they need not exist);
• •Non-human-written code exemption: generated code, vendored third-party code, git submodules — these dirs are not indexed per file; one line in the parent README ("generated code, source is X, do not hand-edit"). Signals: path/naming (__generated__/, *.gen.*, protobuf/ORM output, migrations, vendor/) or file-header markers (AUTO-GENERATED / DO NOT EDIT / @generated);
• •Documentation language: newly created MDs and the injected rules text default to English, regardless of the project's main language. Exception — editing an existing MD: match that file's own existing language (a Chinese README stays Chinese on edit; an existing CLAUDE.md/AGENTS.md gets its appended rules in that file's language). Translations keep clauses one-to-one. When a project is heavily non-English and the user would clearly prefer indexes in that language, confirm before overriding the English default.

Small monoliths (≤ ~5 code dirs): the Tier-1 INDEX adds little — still generate it, but minimal (single flat list, no forced grouping). Structure stays consistent; no shape change needed when the project grows.

Greenfield projects (no code yet, or scaffold only): skip Step 2 generation. Instead ask the user for the intended directory structure → inject rules only + write the baseline tree (marked "planned") + create a root INDEX skeleton; READMEs get built by the rules as code grows.

Step 2 — generate the skeleton (bottom-up)

Order must be bottom-up: Tier 3 (directory READMEs) first, then Tier 2, then Tier 1 — upper tiers aggregate lower ones; writing top-down fabricates.

1. Tier 3: for each code directory, read file names + skim file heads when needed (exports/class names/comments), write the README per templates/readme-dir.md. One line per file, ≤120 chars (CJK counts double). Describe "what this file is in charge of", not implementation detail. Container dirs (e.g. `src/`) with loose code files (e.g. `src/index.ts`) need a README too: index own files + one pointer line per subdir — "every code dir has a README" applies to containers. A container with no loose files but with exempt subdirs that need a one-liner (generated/vendored/submodule) also gets a README to carry that line.
2. Associations: cross-directory dependencies discovered while generating (A calls B's service, shared types) go into both READMEs' ## Cross-refs section. Multi-deliverable projects: data shapes shared across deliverables get promoted to /contracts/<name>.{md,ts} (per templates/contracts.md), with both sides' READMEs pointing at them.
3. Tier 2 (multi-deliverable / large monorepo only): per templates/index-deliverable.md, aggregate that deliverable's directory READMEs by user-perceivable feature (not by directory layout — the READMEs already cover that).
4. Tier 1: per templates/index-global.md (multi-deliverable: feature × deliverable table; monolith: module → directory list).

Scale strategy: > ~20 dirs → fan out subagents per subtree to generate Tier-3 READMEs (every agent gets the same style constraints); Tiers 1–2 are written by the main session for a consistent aggregate view. > ~100 dirs → report scale and estimated effort first, propose batching: batch 1 = core business paths (entry → main domains → shared layers); fringe dirs (scripts, tooling, experiments) in batch 2 or as placeholder READMEs (one purpose line, file list marked "TBD"); start only after the user confirms.

Test dirs are coarse-grained: tests/fixtures/snapshots dirs are not indexed per file — the README covers them one line per suite/fixture group ("integration tests + fixtures for module X"); the test ↔ tested-code mapping lives in the tested directory's README cross-refs.

Step 3 — inject the rules (this skill's most important output)

Inject the content of rules-template.md into the target project's CLAUDE.md:

• •Placeholder substitution: <source extensions>, <exempt dirs>, deliverable list, <layering list> (the modularity rule's layer table), <directory structure baseline> (the architecture baseline tree) — fill the last two from the actual structure observed while writing READMEs in Step 2; never copy the examples. Draw the baseline tree as-is: existing structural mess (junk dirs, mixed-responsibility dirs) must not be beautified into the baseline — record it honestly and put "should split / should relocate" into the final report's to-do list (changing structure is the user's call; this skill never moves code). Monolith projects: delete every block tagged [multi-deliverable only].
• •Existing CLAUDE.md → append; none → create (rules only — don't write anything else into it).
• •Ensure a standard title first line so the mirror's "change only the header line" stays stable: if the CLAUDE.md being created/appended does not already start with a top-level title, prepend # CLAUDE.md as line 1 (append case: only insert it when no # heading exists at the top; never duplicate an existing one). The mirror gets the same line as # AGENTS.md.
• •AGENTS.md mirror (for Codex / other agents): after CLAUDE.md is finalized, produce AGENTS.md as its mirror so non-Claude agents get the same index rules.

- If AGENTS.md already exists → treat as type D (append the rules section, never touch existing content). - If it does not exist → copy `CLAUDE.md` verbatim to `AGENTS.md` (a plain file copy — do not re-derive or re-think the content, that wastes tokens), then change only the header declaration line: rename # CLAUDE.md → # AGENTS.md and adjust any "Claude"-specific self-reference in the first heading/intro line. Everything below stays byte-for-byte identical. - The two are bidirectional mirrors: each file's Mirror sync rule names the other as its mirror, so whichever agent edits its own file syncs the change to the other in the same edit.

• •Inject in English by default; when appending to an existing CLAUDE.md/AGENTS.md, match that file's existing language (translate clause-for-clause when needed). See the Documentation-language rule in Step 1.

After injecting, this skill's job ends: README sync, tier growth/shrink, contract upkeep — all of it is driven by these rules in everyday sessions.

Step 4 — self-check (violations = rework)

1. Coverage: every source-bearing dir has a README (including containers carrying exemption lines); every INDEX pointer resolves.
2. Style constraints: check scope = generated READMEs / INDEXes. Two exemptions: CLAUDE.md is out of scope (it's the rules source; dates quoted as counter-examples are not violations); manual sections kept in place for type C (below the `---` divider) are exempt — check only the index section above the divider; manuals moved to docs/ are type E, naturally out of scope. Run on READMEs/INDEXes:

grep -rnE "20[0-9]{2}-[01][0-9]" --include="README.md" --include="INDEX.md" (dates)

Any hit gets cleaned (dates inside referenced file paths excepted).

1. Location drill: pick 3 real features at random, walk "Tier 1 → … → exact file" reading at most one file per tier; if a walk fails, the aggregation or pointers are wrong — fix and retry.

Final report

Report to the user: shape & tier decision, files generated, contract count (if any), self-check results, structural to-do list (junk dirs / mixed-responsibility dirs found while writing READMEs, with suggested splits — report only, never touch code), plus one closing line: "ongoing maintenance is now owned by the CLAUDE.md rules; this skill does not need to be invoked again."