diff --git a/README.md b/README.md new file mode 100644 index 0000000..3447bf7 --- /dev/null +++ b/README.md @@ -0,0 +1,153 @@ +# Codespaces Skill + +> **Install:** `npx skills add diskd-ai/codespaces` | [skills.sh](https://skills.sh) + +Query a `.belief_map.sexp` graph to discover module boundaries, dependencies, and blast radius before reading source -- so you read the minimal set of files, never whole directories. + +--- + +## Scope & Purpose + +This skill bundles a belief-map query engine and graph builders for architecture discovery, covering: + +* Module boundary and ownership discovery +* Dependency and reverse-dependency (blast-radius) tracing +* Architecture-layer and boundary-violation checks +* Naming-convention (invariant) checks +* Call-chain and data-flow tracing +* Cross-language analysis (Python, TypeScript, TSX) +* Infrastructure topology from Kustomize, Helm, and Terraform + +--- + +## When to Use This Skill + +**Triggers:** +* "How does X call Y?" or "Where is this stored?" +* "What breaks if I change Z?" +* Root-cause investigations mentioning services, APIs, jobs, events, or UI flows +* Architecture reviews, impact analysis, or public-contract changes +* Before any non-trivial code change (boundary check first) + +**Use cases:** +* Scoping the minimal files to read before implementing a change +* Blast-radius analysis before a refactor +* Detecting architecture-layer and naming violations +* Tracing call chains and data flow across modules +* Mapping infrastructure topology to source code + +--- + +## Quick Reference + +### Core Commands + +Run from the skill's base directory: `python3 scripts/belief_search.py ` + +| Command | Purpose | +|---------|---------| +| `search ""` | Regex grep on the graph to find module IDs | +| `analyze ` | Full module analysis (PRIMARY command) | +| `quick ` | Search + analyze the first match (shortcut) | +| `boundary ` | Files to read for a change | +| `deps [depth]` | Outgoing dependency tree | +| `rdeps [depth]` | Blast radius (who depends on this) | +| `flow ` | Trace call/data flow | +| `boundaries [id\|all]` | Check architecture violations | +| `invariants [id\|all]` | Check naming-convention violations | +| `layers` | Show all modules grouped by layer | +| `query ''` | Composable Scheme query | +| `repl` | Interactive Scheme REPL | + +### Output Notation + +All output is S-expression facts, one per line. + +| Fact | Meaning | +|------|---------| +| `(boundary :lang :file :purpose)` | Module boundary file | +| `(boundary-dep :relation)` | Outgoing dependency edge | +| `(boundary-rdep :relation)` | Reverse-dependency edge | +| `(entity-def cls )` | Type/class definition | +| `(violation :src-layer :tgt-layer)` | Architecture violation | + +`:lang` values: `py` (Python), `ts` (TypeScript), `tsx` (TSX). + +--- + +## Workflow + +1. **Locate or build the map**: check for `.belief_map.sexp`; if absent, build it + ```bash + pip3 install tree-sitter tree-sitter-typescript tree-sitter-python + python3 scripts/build_belief_map.py # incremental ~5s + python3 scripts/build_belief_map.py --full # full rebuild ~30s + ``` +2. **Find the module ID**: `search "keyword"` or `entity EntityName` (IDs are full relative paths, never short codes -- never guess them) +3. **Analyze**: `analyze ` returns boundary files, deps, rdeps, layer, and violations +4. **Read only the boundary files** listed in the analyze output -- not entire directories +5. **Verify after changes**: re-run `boundaries ` to confirm no new violations + +--- + +## Skill Structure + +``` +codespaces/ + SKILL.md # Skill definition and mandatory workflow + README.md # This file (overview) + LOG.md # Goal-completion change log + scripts/ # Bundled Python tools + belief_search.py # Query the belief-map graph + build_belief_map.py # Generate the belief map from source + build_infra_topology.py # Extract Kustomize/Helm/Terraform topology + git_descendants.py # Find commits descending from a ref + references/ # Supporting documentation + sexp-notation.md # S-expression fact format + scheme-queries.md # Scheme query language reference + tests/ + test_belief_search.py + .agents/designs/ + infra-topology-builders.md # Design notes for the topology builder +``` + +--- + +## Usage Guidelines + +* **Query before you read.** Run a belief-map query before `rg`, `find`, `cat`, or opening directories -- the skill only helps as the first scoping step. +* **Never guess module IDs.** They are full relative paths (e.g. `pki-service/src/modules/ca/ca.service`); always `search` first. +* **`analyze` is primary.** Run it immediately after finding the ID -- it returns the full change context in one step. +* **Read boundary files only.** When the boundary shows 2-3 files, read only those; ignore the rest of the directory. +* **Use the bundled scripts.** Never use project-local copies -- they may be outdated and emit JSON instead of sexp. +* **Rebuild after structural changes** (added/removed files, changed imports, new classes). + +--- + +## Best Practices + +### Finding Modules +* Use `search` with a broad regex first, then narrow with the returned full path. +* On `(error no-match ...)`, do not retry the same ID -- broaden the search and use the `:suggestions` field if present. + +### Analyzing Impact +* Use `rdeps ` to size the blast radius before a refactor. +* Use `boundaries ` and `layers` to confirm a change respects architecture layers. + +### Composing Queries +* Build an analysis plan from Scheme primitives (`boundary`, `deps`, `rdeps`, `intersect`, `filter`, `files`, `count`) before touching code. +* Re-run `violations ` after changes to verify the boundary still holds. + +--- + +## Resources + +* **Skill definition**: [SKILL.md](SKILL.md) +* **S-expression notation**: [references/sexp-notation.md](references/sexp-notation.md) +* **Scheme query language**: [references/scheme-queries.md](references/scheme-queries.md) + +--- + +## License + +MIT