diff --git a/CONTEXT.md b/CONTEXT.md index 5e9754d..8a3ae04 100644 --- a/CONTEXT.md +++ b/CONTEXT.md @@ -14,22 +14,6 @@ decisions. ### Context cost -**Preload tax**: -The always-on context cost of every installed skill's `name` and `description`, charged from the -first token of every session whether the skill is invoked or not. Measurement method: ADR-0020. Its -**23,427 characters is the pre-retrofit baseline, not a current reading** — measured at the decision -commit, before #99. Across the same 39 skills it is **10,478 characters** (~2,620 tokens) as of -2026-09-01. Both figures move with the corpus, so re-derive rather than quote either: sum -`len(name) + len(description)` over the frontmatter of every `plugins/*/.apm/skills/*/SKILL.md`, -folding block scalars as `scripts/skill-size-check.sh` does. -_Avoid_: context cost, token overhead - -**Skill context contract**: -The ADR-0020 authoring rules that hold the preload tax and body size down — a description carries a -trigger clause, at most one capability clause, and a boundary clause, and nothing else. Thresholds -and the target-resolution walk: `docs/spec/gates.md`. -_Avoid_: skill budget, size limit - **Routing target**: The skill or agent name a boundary clause sends work to. It **resolves** when a skill or agent of that name is reachable from the file being checked, and **dangles** when none is — a route the router @@ -76,12 +60,6 @@ The unit apm builds and installs — `plugins//apm.yml` plus the hand-auth `plugins//.apm/` tree it compiles from (ADR-0015). _Avoid_: plugin directory, source tree -**Content mirror**: -The generated flat `skills/`, `agents/`, `commands/`, `instructions/`, `extensions/` directories and -merged `hooks/hooks.json` at a plugin root — also called the flat mirror — compiled from that -plugin's `.apm/` tree so hosts that convention-scan those paths discover the content (ADR-0017). -_Avoid_: generated copy, duplicate tree - **Output profile**: An `apm pack` target format for a generated *marketplace* manifest; apm has `claude` (`.claude-plugin/marketplace.json`) and `codex` (the differently-shaped @@ -99,12 +77,6 @@ This repository, in its role as a plugin marketplace and as the remote the six p resolve against. _Avoid_: the marketplace, upstream -**apm-consumed install**: -How this repo installs its own plugins as of 2026-08-14 — six `dependencies.apm` entries in the root -`apm.yml` deployed by `apm install`, rather than `claude plugin install @holocron`. Its -consequences: ADR-0018. -_Avoid_: apm install, dependency install - **Provenance chain**: The three-stage traceability record linking a skill back to its research inputs: `/research` produces topic docs and a `sources.md`; the author skill records which sources informed which files in @@ -120,18 +92,6 @@ irreversible or high-stakes actions — architecture changes, production deploym configuration. _Avoid_: manual approval, gated action -**HOTL** (human-on-the-loop): -The agent acts and a human monitors, able to intervene after the fact. Acceptable only for -low-stakes, bounded, reversible actions where the cost of pausing exceeds the blast radius of an -error. -_Avoid_: autonomous, unsupervised - -**Sycophancy**: -The failure mode where an RLHF-trained model prioritises approval over accuracy — changing a correct -answer to a wrong one under user pressure, then persisting in the wrong answer. Treated here as a -first-class reliability risk, not a quality-of-life concern. -_Avoid_: agreeableness, people-pleasing - ### Documents **AGENTS.md**: @@ -149,12 +109,6 @@ _Avoid_: wrapper, shim, provider file The long-loop feedback log for patterns observed across sessions, at the repo root. _Avoid_: changelog, retro, postmortem -**Management Application**: -A separate product in a separate repo for browsing, editing, and configuring AI development configs -through a product UI, with Git as an invisible persistence layer. Repo-agnostic; this repo is its -canonical default content. Roadmap: `docs/VISION.md`. -_Avoid_: the UI, the dashboard, the app - ### Quality **Skill composition**: @@ -162,11 +116,6 @@ A skill calling another skill by name to delegate a sub-task — the caller owns decision ("when to do X"), the callee owns the mechanics ("how to do X"). _Avoid_: chaining, nesting, sub-skill -**Vale audit prefilter**: -The deterministic Vale pass that runs ahead of `skill-audit`/`agent-audit`'s Description dimension, -so LLM judgment is spent only on what a pattern cannot catch. Mechanics: `docs/spec/gates.md`. -_Avoid_: linting, style check - **Authoring root**: The directory a gate resolves against — the nearest ancestor of the file being checked holding `plugins/*/.apm/skills` or `plugins/*/.apm/agents`, falling back to the nearest ancestor holding @@ -179,11 +128,6 @@ sibling that would wrongly answer it; boundary clauses exist to exclude genuine than to enumerate siblings. Detail: `skill-audit/references/description-quality.md`. _Avoid_: overlap, similar skill -**Vacuous green**: -A check that reports success because it measured nothing — zero files scanned, an unparsed value read -as empty, a conditional branch that never armed. -_Avoid_: false pass, clean run - **Issue**: The cross-provider term for a tracked unit of work. Gitea is this repo's canonical tracker (ADR-0007), but skills say "linked issue" generically rather than naming a provider. @@ -193,18 +137,12 @@ _Avoid_: ticket, card, task - A **Plugin** bundles one or more **Skills** and agents; a **Plugin marketplace** lists **Plugins**; **holocron** is this repo wearing that hat. -- Every model-invocable **Skill** pays the **Preload tax**. A **Hand-invoked skill** does not — which - is the first question to settle when authoring one. -- The **Skill context contract** bounds both the **Preload tax** (description) and the body. - A **Dispatch body** is how a skill stays inside it; **Delegation discipline** is how an agent does. - **AGENTS.md** is the source of always-on rules; a **Thin adapter** imports it and originates nothing. - **Skill composition** is the caller/callee split. `forge` routes a genuinely *undecided* artifact type to the matching author skill — an already-specified fix (file, line, and change known) calls that author skill directly, because each routing hop re-derives instructions from a shorter brief and has been observed to drop hard constraints handed down the chain. -- **HITL** and **HOTL** are exclusive per action class, and the choice must be explicit and - documented. **Sycophancy** is why HOTL is not the safe default. - A **Skill** built on research carries a **Provenance chain**; `skill-audit` fails it when broken. - **LESSONS.md** feeds the standing files: three or more entries on one pattern graduate the pattern into the relevant standing document.