Maintain a compact, evidence-backed repository-intelligence layer (context.md, architecture.md, index.json, manifest.json) and run a deterministic multi-stage task resolver to locate target code with minimum token and context overhead.
Source code remains authoritative. Generated knowledge is an index and navigation aid, never a substitute for verifying implementation details.
Execution Rules
- Check Freshness First: Run
python scripts/cli.py statusbefore initial exploration. - Run Resolver for Tasks: Execute
python scripts/cli.py resolve "<task>"before conducting broad repository searches. - Read Minimum Source Slice: Follow the resolver's ordered read plan. Read only high-confidence candidates first.
- Verify Implementation: Verify behavior and dynamic details in primary source files before making implementation decisions.
- Incremental Refresh After Writes: Call
python scripts/cli.py refresh --changed-file <file>immediately after finishing edits. - No-Op Protection: Do not regenerate fresh artifacts. Do not read every file listed in
index.json.
Skill Directory Resolution
Execute runtime scripts with process cwd set to the active skill directory (containing this SKILL.md) or pass absolute paths:
skill-root: absolute path toskills/engineering/build-codebase-knowledge/repo-root: absolute target repository path
Workflow
1. Artifact Generation
When artifacts are missing or stale, build initial knowledge:
python scripts/build_knowledge.py --repo-root /absolute/path/to/repo
Outputs in .agent/knowledge/:
context.md: High-density orientation (stack, entry points, commands, boundaries). Target <= 120 lines.architecture.md: Component matrix, dependency rules, runtime flow, risk points. Target <= 220 lines.index.json: Schema-validated index of subsystems, files, symbols, entry points, tests, configs.manifest.json: Revision metadata, git status, file hashes, freshness state.
2. Task Resolution Pipeline
When assigned an engineering task, query the resolver:
python scripts/resolve_task.py --repo-root /absolute/path/to/repo --task "Add rate limiting to password reset" --format human
The resolver executes 7 deterministic pipeline stages:
- Stage A (Signal Extraction): Extracts exact symbols (
AuthService), paths (src/auth/service.py), domain terms (password,reset,rate), and action verbs. - Stage B (Intent Classification): Classifies intent (
feature,bug,security,tests,configuration,refactor). - Stage C & D (Candidate Generation & Scoring): Weighted scoring (
exact_path,exact_symbol,filename,subsystem,entry_point,test_relation,config_relation). Returns explicit reason for every score. - Stage E (Confidence Estimation): Computes
high,medium, orlowbased on signal agreement and score separation. - Stage F (Progressive Expansion):
high: Primary targets + direct tests + direct configs.medium: 1st-order dependencies + adjacent tests.low: Subsystem neighbors + extra entry points + targeted grep.
- Stage G (Read Plan): Returns step-by-step reading plan and explicit skip list.
3. Source Verification
Read top-ranked files from the read plan. Verify implementation contracts in primary source code.
4. Incremental Refresh
After implementing code changes, refresh knowledge incrementally:
python scripts/refresh_knowledge.py --repo-root /absolute/path/to/repo --changed-file /absolute/path/to/repo/src/auth/service.py --changed-file /absolute/path/to/repo/tests/auth/test_service.py
Re-indexes modified files and updates hashes. Triggers full rebuild automatically if change ratio > 20% or schema changed.
5. Validation & Benchmark
Validate knowledge integrity:
python scripts/validate_knowledge.py --repo-root /absolute/path/to/repo
Run benchmark harness to measure exploration and token reduction:
python scripts/benchmark_knowledge.py --repo-root /absolute/path/to/repo --tasks /absolute/path/to/repo/tests/fixtures/benchmark_tasks.json