Skip to main content
GeneralSteveGJones

kb-codeindex

Parse all `# implements:` annotations in source code and emit `library/_code-index.md` as a shelf-index. Also extracts cross-module import edges and writes `library/_dependency-edges.md`. Idempotent — re-running produces byte-identical output if no annotations or imports changed.

Stars
38
Source
SteveGJones/ai-first-sdlc-practices
Updated
2026-05-11
Slug
SteveGJones--ai-first-sdlc-practices--kb-codeindex
View on GitHubRaw SKILL.md

// install — copy + paste into any project

mkdir -p .claude/skills && curl -fsSL https://raw.githubusercontent.com/SteveGJones/ai-first-sdlc-practices/HEAD/plugins/sdlc-assured/skills/kb-codeindex/SKILL.md -o .claude/skills/kb-codeindex.md

Drops the SKILL.md into .claude/skills/kb-codeindex.md. Works with Claude Code, Cursor, and any agent that loads SKILL.md files from .claude/skills/.

Skill: kb-codeindex

Use this skill to build or refresh the project's code index. The output is structurally a KB shelf-index, queryable by the research-librarian agent like the regular library files. Run after adding/changing # implements: annotations or modifying import structure.

Inputs

  • (no arguments — operates on the whole project)

Steps

  1. Load the project root. Detect from .git/.

  2. Walk source files. Glob **/*.{py,js,ts,go,rs,java} excluding standard ignored paths (.venv/, node_modules/, .git/, etc.).

  3. Parse annotations. Use parse_code_annotations to extract every # implements: line.

  4. Verify cited IDs. For each citation, look it up in library/_ids.md. Report unresolved citations as warnings (not errors — annotation_format_integrity blocks at pre-push).

  5. Render the index. Use render_code_index to produce shelf-index-shaped markdown.

  6. Write to library/_code-index.md. If the file already exists, compare byte-for-byte; only write if different.

  7. Extract dependency edges. For each language detected in the project paths, invoke the registered DependencyExtractor adapter:

    • Python paths → PythonAstExtractor (uses ast.parse for precise cross-module import resolution)
    • All other paths → GenericRegexExtractor (regex-based; configured per language via make_swift_extractor() or equivalent)

    Accumulate all returned ImportEdge objects across languages. Resolve each edge against the Decomposition module paths so edges carry qualified module IDs (e.g. P1.SP1.M1 → P1.SP1.M2). Edges that cannot be resolved to a known module are silently dropped (same policy as unresolved annotation citations).

  8. Write to library/_dependency-edges.md. Use render_dependency_edges(edges, library_handle=<library-handle>) to produce the artefact. If the file already exists, compare byte-for-byte; only write if different. The file is consumed by visibility_rule_enforcement during decomposition validation.

  9. Report. Print: number of annotations processed, number of unresolved citations, number of import edges extracted, whether either index file changed.

Done criteria

  • library/_code-index.md is up to date.
  • library/_dependency-edges.md is up to date.
  • Idempotent (re-running with no changes produces no diff on either file).
  • Unresolved citations and unresolvable edges reported but not failed.