--- 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//.apm/skills//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//`, consisting of that directory's `apm.yml` plus the hand-authored `plugins//.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//.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//` 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.