From de632ba6cc64a97eebded077c36da2c870db7225 Mon Sep 17 00:00:00 2001 From: Andrey Oblivantsev Date: Thu, 13 Aug 2026 17:55:41 +0100 Subject: [PATCH] docs: delete agent-cost; rename kb-search skill to brain (#14) * docs: delete agent-cost; rename kb-search skill to brain. bin/agents/cost does not exist. CI unittest now fails if a SKILL.md names a missing bin/ path. * test: gate SKILL.md bin/ paths; name the brain skill brain. Follow-up to the agent-cost delete: unittest fails if a skill names a missing tool. Frontmatter name is brain, not kb-search. --- PLAN.md | 4 ++-- bin/tools/test_published_docs.py | 2 +- bin/tools/test_skills_bin_paths.py | 33 +++++++++++++++++++++++++++ skills/agent-cost/SKILL.md | 34 ---------------------------- skills/{kb-search => brain}/SKILL.md | 4 ++-- 5 files changed, 38 insertions(+), 39 deletions(-) create mode 100644 bin/tools/test_skills_bin_paths.py delete mode 100644 skills/agent-cost/SKILL.md rename skills/{kb-search => brain}/SKILL.md (97%) diff --git a/PLAN.md b/PLAN.md index 1c534fc..666245c 100644 --- a/PLAN.md +++ b/PLAN.md @@ -49,7 +49,7 @@ detective method: **a fact needs ≥2 independent sources or it is 2dph/ PLAN.md / AGENTS.md docs/ published docs (this conversation → docs/ as md) - skills/ in-project skills (web-search, db-yaml, kb-search, agent-cost, diataxis-docs, …) + skills/ in-project skills (web-search, db-yaml, brain, diataxis-docs) bin/ facts/extract auto-pair 2 sources → lexicon yaml + graph facts/audit ["self"|"facts"|"info"|"stale"] 2-source + staleness gate @@ -140,7 +140,7 @@ Feedback loop: every commit → PR → CI → green/gate → merge. Same discipl 1. scaffold repo (:done after this file + AGENTS.md + .gitignore + ci) 2. gh repo create eSlider/2dph --private + initial commit + CI -3. vendored skill integration (web-search, db-yaml, kb-search, agent-cost, diataxis-docs) — no remote links +3. vendored skill integration (web-search, db-yaml, brain, diataxis-docs) — no remote links 4. .venv: ladybug + model2vec + mistune 5. schema + tools with TDD (kb + md + facts + brain) 6. ~/.config/brain config diff --git a/bin/tools/test_published_docs.py b/bin/tools/test_published_docs.py index 0facabe..02dca93 100644 --- a/bin/tools/test_published_docs.py +++ b/bin/tools/test_published_docs.py @@ -43,7 +43,7 @@ class PublishedDocsTest(unittest.TestCase): paths = [ ROOT / "README.md", ROOT / "docs" / "design.md", - ROOT / "skills" / "kb-search" / "SKILL.md", + ROOT / "skills" / "brain" / "SKILL.md", ROOT / "skills" / "diataxis-docs" / "SKILL.md", ] # Command-style `--hop 1` / `--hop N` plus follow/walk = the old lie. diff --git a/bin/tools/test_skills_bin_paths.py b/bin/tools/test_skills_bin_paths.py new file mode 100644 index 0000000..96d0e52 --- /dev/null +++ b/bin/tools/test_skills_bin_paths.py @@ -0,0 +1,33 @@ +"""Every bin/ path named in skills/ must exist on disk.""" +from __future__ import annotations + +import re +import unittest +from pathlib import Path + +ROOT = Path(__file__).resolve().parents[2] +BIN_PATH = re.compile(r"\b(bin/[A-Za-z0-9_./-]+)") + + +class SkillsBinPathsTest(unittest.TestCase): + def test_agent_cost_skill_is_gone(self) -> None: + self.assertFalse( + (ROOT / "skills" / "agent-cost").exists(), + "skills/agent-cost documents bin/agents/cost which does not exist", + ) + + def test_brain_skill_replaces_kb_search(self) -> None: + self.assertTrue((ROOT / "skills" / "brain" / "SKILL.md").is_file()) + self.assertFalse((ROOT / "skills" / "kb-search").exists()) + + def test_skill_bin_paths_exist(self) -> None: + missing: list[str] = [] + for skill in sorted((ROOT / "skills").rglob("SKILL.md")): + text = skill.read_text() + for match in BIN_PATH.findall(text): + rel = match.rstrip("`'.,") + if rel.endswith(".go") or Path(rel).suffix == "" or Path(rel).suffix in {".go", ".py"}: + p = ROOT / rel + if not p.exists(): + missing.append(f"{skill.relative_to(ROOT)}: {rel}") + self.assertEqual(missing, [], "SKILL.md names bin/ paths that do not exist") diff --git a/skills/agent-cost/SKILL.md b/skills/agent-cost/SKILL.md deleted file mode 100644 index fc7cf19..0000000 --- a/skills/agent-cost/SKILL.md +++ /dev/null @@ -1,34 +0,0 @@ ---- -name: agent-cost -description: >- - Measure what an agent session actually costs in tokens using bin/agents/cost. - Use before and after changing documentation, skills or context layout, and when - a session feels unexpectedly expensive. ---- - -# agent-cost - -```bash -bin/agents/cost # every project, YAML -bin/agents/cost --repo 2dph # only sessions whose cwd matches -bin/agents/cost --json | jq .cursor.by_tool -bin/agents/cost --snapshot after-x --repo 2dph # append a row to docs/CONTEXT-BUDGET.md -``` - -Reads local session storage from OpenCode and Cursor transcripts. Reports the -always-loaded baseline, cache hit/miss/thrash, and which tools moved the most -bytes. - -## How to read it - -- **Baseline** is what every single message pays for: `AGENTS.md` plus anything - eagerly linked from it. Keep it small; it multiplies by message count. -- **Cache thrash** matters more than raw size. Editing a file that sits early in - the context invalidates the prompt cache for the whole session. -- **by_tool bytes** shows where the real spend is. Usually it is unfiltered - command output, not documentation. - -## Rule - -Measure before and after. A claim that something "reduces tokens" without a -before and an after number is an opinion, not a result. diff --git a/skills/kb-search/SKILL.md b/skills/brain/SKILL.md similarity index 97% rename from skills/kb-search/SKILL.md rename to skills/brain/SKILL.md index 8aa1a5f..0944f3b 100644 --- a/skills/kb-search/SKILL.md +++ b/skills/brain/SKILL.md @@ -1,5 +1,5 @@ --- -name: kb-search +name: brain description: >- Deduction search over the 2dph brain (Ladybug graph: ops corpus, portfolio, ssh hosts) with bin/brain/search.go instead of reading files or grepping @@ -8,7 +8,7 @@ description: >- documentation. --- -# kb-search — deduction over facts and info +# brain — deduction over facts and info One embedded Ladybug graph (`var/kb.lbug`, read-only when queried) holding two roots: