From 617d4a970f908583c6c1747450b973f80bba5d3a Mon Sep 17 00:00:00 2001 From: MrSphay Date: Fri, 15 May 2026 02:51:28 +0200 Subject: [PATCH] Add context token conservation guidance --- README.md | 1 + agent-quickstart.md | 5 +++++ existing-project.md | 2 ++ files/AGENTS.md | 1 + manifest.json | 1 + new-repository.md | 2 ++ 6 files changed, 12 insertions(+) diff --git a/README.md b/README.md index 5950fe4..15deabf 100644 --- a/README.md +++ b/README.md @@ -127,6 +127,7 @@ When applying this kit, an agent should: - read `manifest.json` first, - choose `new-repository.md` or `existing-project.md`, - read matching `profiles/*.md` guidance after detecting the stack, +- conserve context tokens by searching first, reading only relevant files, summarizing large outputs, and avoiding generated folders, dependency folders, build outputs, or full logs unless directly relevant, - at the start of each user-requested task, check for upstream repository updates and apply them immediately with a safe fast-forward pull when the working tree is clean, - check `git status --short` before editing, - preserve unrelated user changes, diff --git a/agent-quickstart.md b/agent-quickstart.md index bc10946..b7f38e7 100644 --- a/agent-quickstart.md +++ b/agent-quickstart.md @@ -9,6 +9,7 @@ Read manifest.json first. Use its copyMap for file destinations. Use new-repository.md or existing-project.md as the task workflow. Use matching profiles/*.md guidance after detecting the stack. +Conserve context tokens: search first, read only relevant files, summarize large outputs, and avoid generated folders, dependency folders, build outputs, or full logs unless directly relevant. At the start of each user-requested task, check for upstream repository updates and apply them immediately with a safe fast-forward pull when the working tree is clean. If local changes exist, do not overwrite them; fetch or report the blocker before editing. For releasable projects, add or preserve scheduled security automation. @@ -72,6 +73,10 @@ Does a stack profile match? yes -> read the matching profiles/*.md file and adapt commands carefully no -> continue with universal rules only +Can you answer the next question with targeted search or a small file slice? + yes -> use that instead of loading whole directories or long logs + no -> read the smallest complete file set that preserves correctness + Does the project already have README structure? yes -> preserve it; only add blueprint files if useful no -> add blueprint.md and blueprint.json with the rainbow section-line divider diff --git a/existing-project.md b/existing-project.md index b57a2cb..93d08e0 100644 --- a/existing-project.md +++ b/existing-project.md @@ -33,6 +33,8 @@ git pull --ff-only If local changes exist, do not overwrite them. Fetch or report the blocker before editing. +Conserve context tokens while inspecting: start with targeted searches and file lists, then read only files that affect the retrofit decision. Do not load generated folders, dependency folders, build outputs, or full logs unless they are directly relevant. + Read: ```text diff --git a/files/AGENTS.md b/files/AGENTS.md index df95a60..a52ee40 100644 --- a/files/AGENTS.md +++ b/files/AGENTS.md @@ -8,6 +8,7 @@ PROJECT_NAME: PROJECT_DESCRIPTION - Start by reading `manifest.json`, then the workflow file that matches the task: `new-repository.md` for fresh repos or `existing-project.md` for retrofit work. - Use the matching `profiles/*.md` file when the repository stack is detected. Profiles are guidance, not permission to ignore existing project conventions. +- Conserve context tokens: search with `rg` or targeted file lists first, read only the files needed for the task, summarize large outputs instead of pasting them, and avoid loading generated folders, dependency folders, build outputs, or full logs unless they are directly relevant. - Follow the `manifest.json` copy map for source and target paths. Do not invent alternate locations unless the target repository already has an equivalent convention. - Prefer existing project patterns over new abstractions. - Keep changes scoped to the user's request. diff --git a/manifest.json b/manifest.json index a9abb67..8485c36 100644 --- a/manifest.json +++ b/manifest.json @@ -5,6 +5,7 @@ "agentResponsibilities": [ "Read manifest.json before copying files.", "Use copyMap target paths unless the repository already has an equivalent convention.", + "Conserve context tokens by searching first, reading only relevant files, summarizing large outputs, and avoiding generated folders, dependency folders, build outputs, or full logs unless directly relevant.", "At the start of each user-requested task, check for upstream repository updates and apply them immediately with a safe fast-forward pull when the working tree is clean.", "Check git status before editing and before finishing.", "Preserve unrelated user changes.", diff --git a/new-repository.md b/new-repository.md index 3efb258..ac6006c 100644 --- a/new-repository.md +++ b/new-repository.md @@ -30,6 +30,8 @@ git pull --ff-only If local changes exist, do not overwrite them. Fetch or report the blocker before editing. +Conserve context tokens while inspecting: start with targeted searches and file lists, then read only files that affect the baseline decision. Do not load generated folders, dependency folders, build outputs, or full logs unless they are directly relevant. + Identify: - repository name,