diff --git a/README.md b/README.md index e0df645..db37aa4 100644 --- a/README.md +++ b/README.md @@ -19,4 +19,5 @@ A collection of agent skills (slash commands and behaviors) loaded into Steve Be - [forge-interaction](common/engineering/forge-interaction/SKILL.md) — Work safely with GitHub and Gitea repositories, issues, pull requests, releases, and remote forge state. - [forge-preferences](common/personal/forge-preferences/SKILL.md) — Apply Steve's personal or project-specific GitHub/Gitea forge preferences. - [grilling](common/productivity/grilling/SKILL.md) — Interview the user relentlessly about a plan or design. +- [project-context-pack](common/engineering/project-context-pack/SKILL.md) — Build and refresh a bounded repo context memory file so agents use disciplined search instead of repeated browsing. - [research-engineering](common/deprecated/dsp-research-dispatcher/SKILL.md) — Route DSP hardware and software research-engineering requests to the best specialist workflow and return a unified, decision-ready output. diff --git a/common/README.md b/common/README.md index e88ce9f..bfa5448 100644 --- a/common/README.md +++ b/common/README.md @@ -19,4 +19,5 @@ Skills that work in all CLI agents. - [forge-interaction](engineering/forge-interaction/SKILL.md) — Work safely with GitHub and Gitea repositories, issues, pull requests, releases, and remote forge state. - [forge-preferences](personal/forge-preferences/SKILL.md) — Apply Steve's personal or project-specific GitHub/Gitea forge preferences. - [grilling](productivity/grilling/SKILL.md) — Interview the user relentlessly about a plan or design. +- [project-context-pack](engineering/project-context-pack/SKILL.md) — Build and refresh a bounded repo context memory file so agents use disciplined search instead of repeated browsing. - [research-engineering](deprecated/dsp-research-dispatcher/SKILL.md) — Route DSP hardware and software research-engineering requests to the best specialist workflow and return a unified, decision-ready output. diff --git a/common/engineering/README.md b/common/engineering/README.md index 12c6b13..7267b1f 100644 --- a/common/engineering/README.md +++ b/common/engineering/README.md @@ -7,3 +7,4 @@ _None yet._ ## Model-invoked - [forge-interaction](forge-interaction/SKILL.md) — Work safely with GitHub and Gitea repositories, issues, pull requests, releases, and remote forge state. +- [project-context-pack](project-context-pack/SKILL.md) — Build and refresh a bounded repo context memory file so agents use disciplined search instead of repeated browsing. diff --git a/common/engineering/project-context-pack/SKILL.md b/common/engineering/project-context-pack/SKILL.md new file mode 100644 index 0000000..b784ca0 --- /dev/null +++ b/common/engineering/project-context-pack/SKILL.md @@ -0,0 +1,101 @@ +--- +name: project-context-pack +description: Use when the user wants a bounded repo context pack, project map, codebase index, cached memory file, or fewer repeated codebase searches. +--- + +# Project Context Pack + +Create or refresh a bounded project memory file, then use it as the navigation map for the repo. + +## Target + +Default cache path: `.agent/project-context.md` at the project root. + +Use a user-named path when provided. If the user did not explicitly ask for a cache file, ask before the first write into the repo. Never write secrets, credentials, private keys, tokens, browser data, personal data, or raw `.env*` content into the cache. + +## Procedure + +1. **Root.** Prefer `git rev-parse --show-toplevel`; otherwise use `pwd`. Completion: the pack records the absolute root and current relative working directory. +2. **Survey.** Use `fd` and `rg` first; fall back to `find` and `grep`. Respect ignore files by default. Exclude `.git`, dependency directories, build outputs, caches, generated files, binaries, and large artifacts. Completion: the pack has a bounded file inventory and top-level tree before broad file reads. +3. **Classify.** Detect language, framework, package manager, build/test tools, docs, agent guidance, and likely entry points from filenames and small config reads. Completion: every project-type claim cites at least one file. +4. **Read selectively.** Read only high-value files by default: README, agent guidance, package/build config, docs index, main entry points, and files directly relevant to the user's current request. Cap per-file and total content. Completion: every included file has a recorded reason. +5. **Index before browsing.** For code questions, prefer tree-sitter or LSP when available. Otherwise use `rg` for definitions, exports, imports, routes, tests, commands, TODOs, and error strings. Completion: the pack has search or symbol notes before any broad source reading. +6. **Cache.** Create or update the memory file with the template below. Completion: the file records timestamp, root, status, commands/searches used, files inspected, exclusions, and next navigation rules. +7. **Reuse.** Before future exploration, read the cache first. If stale or insufficient, refresh the smallest relevant section instead of rebuilding everything. Completion: subsequent work uses the cache or explains why it was bypassed. + +## Navigation discipline + +- Do not wander file-by-file. Start with the cache, `fd`, `rg`, tree-sitter, or LSP. +- Track inspected files in the memory file. +- Prefer narrow searches over whole-file reads. +- Prefer symbol outlines and matching snippets over full content. +- Re-read a file only when it changed, the cache is stale, or exact details are needed. +- Ask before full-content extraction, large scans, or sensitive-file inspection. + +## Useful command patterns + +```bash +root=$(git rev-parse --show-toplevel 2>/dev/null || pwd) +cd "$root" + +date -Iseconds + +# Inventory +fd --type f --hidden --exclude .git 2>/dev/null || find . -type f -not -path './.git/*' +tree -a -I '.git|node_modules|dist|build|target|.venv|__pycache__|vendor|coverage' -L 3 + +# Project signals +fd '^(README|AGENTS|CLAUDE|GEMINI|package.json|pyproject.toml|Cargo.toml|go.mod|Makefile|justfile|docker-compose.yml)$' + +# Search before reading +rg -n "TODO|FIXME|HACK|XXX" +rg -n "^(export |class |def |function |interface |type |trait |struct |enum )" +rg -n "main\(|if __name__ == .__main__.|export default|module.exports" +``` + +## Memory file template + +```markdown +# Project Context Pack + +Generated: +Root: +Working directory: +Status: + +## Purpose + + +## Project type + + +## Structure + + +## Important files +- — + +## Commands +- Build: +- Test: +- Lint/typecheck: +- Run/dev: + +## Entry points +- — + +## Search and symbol notes + + +## Files inspected +- — — + +## Exclusions + + +## Navigation rules for future agents + + +## Refresh notes + +```