refactor!: carry out the simplification audit across gates, tests, plugins and docs #135
62
CONTEXT.md
62
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/<name>/apm.yml` plus the hand-auth
|
||||
`plugins/<name>/.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 <name>@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.
|
||||
|
||||
Reference in New Issue
Block a user