Defame1297
061bb3d5b4
A five-agent review of718c79aandd2480b8found no skill, agent or hook regressions (39 skills before and after) and confirmed both hook removals are genuinely moot -- verified against the tree, not taken on the commit's word. It did find one functional regression (fixed separately) and this documentation drift. Counting errors, all from a git pathspec `*` crossing `/`: - 17 .bats files shipped to consumers is really 10; 17 counted tracked paths merely containing /tests/, one of them a template asset - "roughly 88s off every push" is ~92.4s; 88 omitted validate-plugins - "roughly 70% of each plugin remains live" holds only for kyberforge; the real spread is 44.3% (bin) to 70.6%, now a table - the pre-push enforcement row was half-corrected: 33 entries stood unstruck (now 27) and 14 -> 11 switched counting basis mid-sentence - the root .claude-plugin/plugin.json was described as "kept"; it has never been tracked gates.md said "Ten hooks" above a nine-row table (11 was decremented for one removal, not two), and "both need the claude CLI" for one remaining validator. Its pretty-format-json exclude rationale claimed six alternations expanding to sixteen files in a passage headed "Mind which number you are quoting" -- four alternations, two live files; the two dead ones are dropped from the pattern. check-useless-excludes could not catch this: it only flags an exclude matching nothing at all. ADR-0024 cited ADR-0006 for a patch-bump rule it does not contain and which ADR-0015 explicitly retired; stated apm's marketplace probe order backwards (.claude-plugin/ is the last candidate, not the first, so the earlier .github/plugin/ deletion only demoted resolution); undercounted apm's skill-deploying targets as seven when there are fifteen; and never recorded that validate-plugins was removed. The symlink hedge is resolved: apm_cli/security/gate.py's ignore_non_content() drops symlinks silently on deploy while apm_modules/ materialization dereferences them, so content survives that far and vanishes at install. Accepted with no replacement guard, per decision -- kyberforge/docs/hooks.md previously asserted a guard that had been deleted with its script. Four plugin READMEs still advertised `claude plugin install`; ADRs 0001, 0006, 0013, 0014, 0015 and 0019 described deleted machinery in the present tense, 0019 most consequentially as the live justification for the SessionStart hook's .apm/ path. CONTEXT.md's "apm package" entry forbade "plugin" while using it in its own body, and "Output profile" lost the antecedent for "one catalogue serves both". run-tests.sh gains the .claude/skills/ exclusion run-bats.sh already had. Latent today -- no test-*.sh lives under any .apm/skills/*/tests/ -- but apm now deploys those directories, so one would be discovered twice. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01YR2CjVumUbEGWcMikcoXBD
181 lines
9.3 KiB
Markdown
181 lines
9.3 KiB
Markdown
---
|
|
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/<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; `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
|
|
|
|
- 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**; `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/<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 `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.
|