--- 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 pays no preload tax 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//.apm/skills//SKILL.md`. _Avoid_: command, prompt, macro **Plugin**: The deployable unit — one or more skills, agents, hooks, commands, and MCP servers bundled into a single installable directory under `plugins//`, compiled from that plugin's `.apm/` source. _Avoid_: package, bundle, module **apm package**: The unit apm builds and installs — `plugins//apm.yml` plus the hand-authored `plugins//.apm/` tree it compiles from (ADR-0015). _Avoid_: plugin directory, source 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 `.agents/plugins/marketplace.json`), and none for `.github/plugin/marketplace.json` (Copilot CLI's legacy path), which a sync script mirrors instead. 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; `skill-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: `skill-audit/references/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 ## Relationships - A **Plugin** bundles one or more **Skills** and agents; a **Plugin marketplace** lists **Plugins**; **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**; `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. ## 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 pays no **preload tax** at all and the description is human-facing text." > **Dev:** "Then the body can be as long as it needs to be?" > **Maintainer:** "Different budget. The **skill context contract** gates 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//.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. - "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 `forge`'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.