Files

Defame1297 1929ffd2da docs: slim AGENTS.md to per-session context only

Why: AGENTS.md is preloaded into every session via CLAUDE.md's @AGENTS.md
import, so every word is a tax paid whether or not it is relevant. It had
grown to 3,371 words (~4,550 tokens), 75% of it a single "Setup and testing"
section that was mostly neither: roughly 1,600 words were gate forensics —
why a hook is shaped the way it is, what was tried and rejected, verification
numbers — and only ~390 words were genuine one-time setup.

Implementation notes: split three ways by audience rather than by heading.
One-time setup, prerequisites and test commands move to a new root README.md,
which did not previously exist. The gate forensics move to a new
docs/spec/gates.md, preserving every constant, hook ID, error string and
tried-and-rejected note (policy.fetch_failure_default, the removed fallback
frontmatter reader, extending skill-size-check's files: pattern to agents,
tidying .claude/settings.json out of the pretty-format-json exclude list) —
these exist to stop settled decisions being re-litigated, so none were
dropped. AGENTS.md keeps only what applies every session, at one clause of
rationale per rule. The .apm/-mirror section collapses to a pointer because
docs/spec/architecture.md already covers it in full. The hot ADR-0020 gate
counts stay in AGENTS.md deliberately: they block any skill edit today.

Also corrects docs/spec/architecture.md's stale claim of 19 ADRs; ADR-0020
landed without updating the count.

Impact: per-session preload drops from ~4,550 to ~1,116 tokens, a 75% cut.
agentsmd-audit passes: secrets clean, drift clean, 4 informational findings
for sections deliberately relocated to the README.

2026-08-17 08:56:37 +00:00

6.0 KiB

Raw Blame History

Working in this repo

The global AI development configuration repository — the authoritative source for agent definitions, skills, workflows, and prompts across all projects.

This file carries only what applies to every session. Setup, prerequisites, and test commands are in README.md; the reasoning behind each enforcement gate is in docs/spec/gates.md.

Structure

plugins/ — six installable plugin units, each an apm package (apm.yml + .apm/). Root apm.yml declares all six as dependencies.apm; apm install deploys them into .claude/skills/ and .claude/agents/, both gitignored install output.
providers/claude-code/ — Claude Code adapter, deployed to ~/.claude/ via scripts/install.sh.

Edit `.apm/`, never the flat mirror

plugins/<name>/.apm/ is the only hand-edited source for plugin content. The flat plugins/<name>/{skills,agents,commands,instructions,extensions}/ directories, the merged plugins/<name>/hooks/hooks.json, and both plugin.json manifests are generated — nothing marks them as generated, so check the path before you edit. An edit to the mirror is discarded by the next sync and reported as drift by the check-plugin-content-sync pre-push hook.

Not everything in a plugin root is generated. README.md, docs/, bin/, sources.md, .mcp.json and per-plugin extras are hand-authored there with no .apm/ source — edit those in place. The rule is per-path, not per-directory. But a file placed inside a mirrored directory is deleted on the next sync (sync_dir runs rm -rf before every copy), so plugin-root documentation goes in docs/, never in hooks/ or skills/.

Full model: docs/spec/architecture.md.

Prefer plugin skills over raw shell

This repo dogfoods its own plugins. Before shelling out, check whether a skill already owns the operation — it usually does:

Commits, branches, history, worktrees, remotes → git-commits, git-branches, git-history, git-worktrees, git-remotes
Pre-commit hook install/config/troubleshooting → pc-run / pc-author
Issues, PRs, labels, milestones → gitea-issues, gitea-prs, gitea-labels-milestones; also gitea-branches, gitea-files, gitea-releases, or gitea-workflow when the domain is ambiguous
Vale prose linting → vale-config / vale-run
This repo's own AGENTS.md → agentsmd-author / agentsmd-audit

Use the bare, unnamespaced names. The <plugin>: form (gitea:gitea-prs) also still resolves, because user-scope native installs were left enabled on purpose (ADR-0018) — a working namespaced call is not evidence that anything is broken and is not something to "fix". Prefer the bare name anyway: it is what apm install deploys, and what survives those user-scope installs eventually being converted.

Fall back to raw shell only when no skill covers it.

Session rules

Do not add repo-owned keys to .claude/settings.json. apm treats it as its own deployed artifact and apm audit --ci replays the install and diffs, so anything apm would not have written is permanent drift that fails the apm-audit-ci pre-push hook. A hook you want here is authored in plugins/<name>/.apm/hooks/ and deployed by apm, never hand-written into that file. Machine-specific settings go in the gitignored .claude/settings.local.json; shared enforcement goes in .pre-commit-config.yaml.
apm.lock.yaml turning up modified is expected, not a bug. kyberforge's SessionStart hook runs apm outdated at startup and apm update --yes when something is behind, which rewrites the lock. Commit or discard it deliberately.
A .apm/ edit is not live in this session until it is pushed. The six dependencies resolve from the holocron remote, unpinned against the default branch. apm install deploys from the lock; apm update is what re-resolves refs.
The ADR-0020 skill gates ship hot, with no baseline. 26 of 39 descriptions and 9 of 39 bodies exceed their FAIL tier, and the Kyberforge.CompositionNote Vale rule fires 10 errors across gitea-issues, gitea-labels-milestones, gitea-prs and gitea-workflow. Editing any of those skills for any reason means retrofitting it to the contract first — a one-line fix cannot be committed until the skill complies. Deliberate; tracked as Gitea issue #99. skill-size-check will not warn you about the Vale half, so check both: pre-commit run --all-files.
Run bash tests/run-tests.sh before considering any change done.
Before pushing, run the whole gate locally: pre-commit run --hook-stage pre-push --all-files. Pushing runs 14 repo-defined hooks, not just the test suite.
Pushing without a network needs SKIP=apm-marketplace-check,apm-pack-check-clean git push — those two resolve a remote marketplace entry via git ls-remote. Skip only those two; the rest are real local checks, and adding one to SKIP disarms it silently.
Author commits with git-commits — it validates Conventional Commits, which commit-msg enforces.

Key documents

Read CONTEXT.md at the start of every session.

Read these on demand:

README.md — prerequisites, install, and test commands
docs/spec/gates.md — what each pre-commit and pre-push hook enforces and why; read when a gate fails or before changing hook config
docs/spec/architecture.md — directory structure, install pipeline, provider model
docs/adr/ — architectural decisions; read before answering design questions or proposing structural changes
docs/ai-constitution.md — full governance evidence base; read when a governance decision needs justification
docs/research/ai-coding-factory/ai-coding-factory-principles.md — factory design rationale; read when implementing, auditing, or reviewing skills or factory structure
docs/notes/factory-integration-decisions.md — decisions from the factory integration grill; read when making skill authoring or factory design decisions
Governance rules are always in effect — core/instructions/governance.md (agent rules); docs/research/governance_principles/CONTROLS.md

6.0 KiB Raw Blame History