holocron/CONTEXT.md

---
name: AI Development Repo
description: The domain language of the global AI development config repository
---

# AI Development Repo

The bounded context of this repo is **how agent instructions are authored, packaged, distributed, and
kept small**. Terms here name concepts specific to that problem. Mechanics live elsewhere:
`docs/spec/architecture.md` for structure, `docs/spec/gates.md` for enforcement, `docs/adr/` for
decisions.

## Language

### Context cost

**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
cannot take. Dangling is a blocking ERROR in route notation (`/name`, `→ name`) and a SUGGESTION for
a bare name nothing else in the sentence corroborates. Verdicts and the resolution walk:
`docs/spec/gates.md`.
_Avoid_: route, pointer, cross-reference

**Dispatch body**:
The body pattern a skill with two or more mutually exclusive flows must use — the body carries only
the dispatch table and the gates common to every branch, and each flow lives in its own
self-contained `references/` file. Exemplar: `apm-workflow`.
_Avoid_: router body, thin body

**Hand-invoked skill**:
A skill reached only by typing its slash command, declared `disable-model-invocation: true`. The host
withholds it from the model-visible listing entirely, so it costs nothing in always-on context and
its description becomes human-facing text. The flag also hard-blocks the Skill tool, so **no other
skill can route to a hand-invoked skill** — a `` Call `x` `` step in another skill's body stops
working the moment `x` takes the flag. Check inbound routes before declaring one. Exemplar: `zoom-out`.
_Avoid_: manual skill, disabled skill

**Delegation discipline**:
The agent-side counterpart to the dispatch body. A plugin-scope agent is a single `.agent.md` file
with no sibling `references/` directory, so it cannot disclose to itself — it can only delegate to
skills. Its characteristic defect is therefore restatement, not length.
_Avoid_: agent hygiene

### Distribution

**Skill**:
A reusable slash command defined as a `SKILL.md` file following the
[Agent Skills open standard](https://agentskills.io), authored at
`plugins/<plugin>/.apm/skills/<skill>/SKILL.md`.
_Avoid_: command, prompt, macro

**apm package**:
The deployable unit apm builds and installs — one or more skills, agents, hooks, commands, and MCP
servers under a single directory `plugins/<name>/`, consisting of that directory's `apm.yml` plus
the hand-authored `plugins/<name>/.apm/` tree it deploys from (ADR-0015).
_Avoid_: bundle, module, source tree; and bare "plugin" for the *installable artifact*, which since
ADR-0024 is an apm package and not a Claude Code plugin. "Plugin" stays correct as a modifier in the
repo's settled compounds — **Plugin marketplace**, "plugin units", `plugins/`.

**Output profile**:
A named ecosystem format `apm pack` can compile the marketplace manifest into, declared per profile
under root `apm.yml`'s `marketplace.outputs:`. apm defines `claude` and `codex`; each writes to its
own default path unless overridden. Mechanics: `docs/spec/architecture.md`.
_Avoid_: build target, export format

**Plugin marketplace**:
A Git repository carrying a `marketplace.json` manifest that lists installable plugins. There is no
backend, registry, or SaaS — the Git repo is the marketplace.
_Avoid_: registry, store, catalogue

**holocron**:
This repository, in its role as a plugin marketplace and as the remote the six plugin dependencies
resolve against.
_Avoid_: the marketplace, upstream

**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
`references/sources.md` and `source_keys` frontmatter; `factory-audit` validates the chain is complete
and internally consistent.
_Avoid_: sources, citations, attribution

### Governance

**HITL** (human-in-the-loop):
The agent pauses before a consequential action and a human approves before execution. Required for
irreversible or high-stakes actions — architecture changes, production deployments, security
configuration.
_Avoid_: manual approval, gated action

### Documents

**AGENTS.md**:
The provider-agnostic always-on instruction file, in plain markdown with no provider-specific syntax
(ADR-0003). Two exist: repo-level, and the global `core/AGENTS.md` deployed to `~/.agents/AGENTS.md`.
_Avoid_: instructions file, system prompt

**Thin adapter**:
A provider-specific instruction file (`CLAUDE.md`, `.cursor/rules/*.mdc`, `copilot-instructions.md`)
that imports its `AGENTS.md` and adds only that provider's syntax, carrying no original always-on
content of its own (ADR-0002, ADR-0003).
_Avoid_: wrapper, shim, provider file

**LESSONS.md**:
The long-loop feedback log for patterns observed across sessions, at the repo root.
_Avoid_: changelog, retro, postmortem

### Quality

**Skill composition**:
A skill calling another skill by name to delegate a sub-task — the caller owns the orchestration
decision ("when to do X"), the callee owns the mechanics ("how to do X").
_Avoid_: chaining, nesting, sub-skill

**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
`.git`. The walk: `docs/spec/gates.md`.
_Avoid_: repo root, project root

**Near-miss**:
A query that shares keywords with this skill but needs a different one — and, by extension, the
sibling that would wrongly answer it; boundary clauses exist to exclude genuine near-misses rather
than to enumerate siblings. Detail: `factory-audit/references/skill-description-quality.md`.
_Avoid_: overlap, similar skill

**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.
_Avoid_: ticket, card, task

**Family prefix**:
The shared first segment of a skill name (`git-`, `gitea-`, `apm-`, `agentsmd-`) marking a group of
siblings. No bare skill name is a **Family prefix** of another: `forge` exists, so no skill is named
`forge-*`, because a prefix that matches a live sibling reads as ownership rather than membership.
_Avoid_: namespace, category

## Relationships

- An **apm package** bundles one or more **Skills** and agents; a **Plugin marketplace** lists
  **apm packages**; **holocron** is this repo wearing that hat.
- **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.
- A **Skill** built on research carries a **Provenance chain**; `factory-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.

## Example dialogue

> **Dev:** "This one only fires when someone types the slash command. Does its description still need
> trigger words?"
> **Maintainer:** "No — that's a **hand-invoked skill**. The host withholds it from the model-visible
> listing, so it costs nothing in always-on context and the description is human-facing text."
> **Dev:** "Then the body can be as long as it needs to be?"
> **Maintainer:** "Different budget. ADR-0020's authoring rules gate the body whether or not the
> skill is model-invoked — the description competes with every other skill's description, the body
> competes with the caller's live conversation. Four mutually exclusive flows means a **dispatch
> body**: table in `SKILL.md`, one `references/` file per flow."
> **Dev:** "And if I split it into an agent instead?"
> **Maintainer:** "Then you're in **delegation discipline** territory. An agent has no `references/`
> to disclose to, so the failure mode flips — it stops being length and starts being restatement of
> a procedure some skill already owns."

## Flagged ambiguities

- "skill" was used for both the authored `SKILL.md` under `plugins/<name>/.apm/skills/` and the
  deployed copy under `.claude/skills/` — resolved: the authoring source is the **Skill**; the
  deployed copy is gitignored `apm install` output and is never edited.
- Skills can answer to two names, bare (`gitea-prs`) and namespaced (`gitea:gitea-prs`), depending on
  whether a native install exists at user scope alongside the apm one (ADR-0018) — resolved: write
  the bare name, which is the only form `apm install` produces.
- "plugin" was used both for the installable artifact under `plugins/<name>/` and as a modifier in
  settled compounds (**Plugin marketplace**, "plugin units", the `plugins/` directory itself) —
  resolved: the installable artifact is an **apm package**, because ADR-0024 ended native
  `claude plugin install` support and it is no longer a Claude Code plugin in any operative sense;
  the compounds keep the word and are not being renamed.
- "context" means both the model's live token window and the bounded domain this file describes —
  resolved: unqualified "context" in this repo means the token window.
- "audit" was used for both an author skill's inline closeout and the audit skill's independent
  clean-context recheck — resolved: these are two distinct layers, kept separate precisely because
  an audit running in the same context as the work it checks shares that work's blind spots. The
  recheck belongs to `factory-audit`, not to `forge`, which routes only to the author
  skills and never to an audit.