holocron/AGENTS.md

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. That is what apm install deploys and the only form this repo's own install produces — a project skill has no plugin to prefix (ADR-0018). Whether the <plugin>: form (gitea:gitea-prs) also resolves depends on native plugin installs at user scope, outside this repo; write the bare name either way.

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. The SessionStart entry already in it is exactly that: kyberforge authors it in plugins/kyberforge/.apm/hooks/hooks.json and apm merges it in, so it is apm's own output, it is what the replay expects, and it belongs in the commit — do not strip it (ADR-0019). 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 — and the corpus is now clean. All 39 skills clear both FAIL tiers: no description over 400 characters, no body over 900 words (counted body-only). Issue #99 retrofitted them plugin by plugin — kyberforge was the last plugin wave, followed by corpus-wide passes and two rounds of independent audit fixes. Because nothing is grandfathered, the gates now bite on first commit — a new skill, or an edit that pushes a description past 400, is blocked until it complies. No routing target dangles, and tests/test-adr0020-targets.sh pins that set as empty, so a new boundary clause naming a non-existent skill fails the suite rather than joining a backlog. Two blind spots survive: skill-size-check does not cover the Vale half, so Kyberforge.CompositionNote fires nowhere today but any new description can reintroduce it; and every references/ file is unlinted — which matters because the contract's own remedy is to move prose into references/, out of the prose gate's reach. That blind spot has two independent causes and closing either alone changes nothing: the Kyberforge style is scoped [**/SKILL.md], and the vale-audit-prefilter-skill hook filters on files: '^plugins/[^/]+/\.apm/skills/[^/]+/SKILL\.md$', so a reference file is never handed to Vale whatever the style says (#117). Check both gates: pre-commit run --all-files.
• Run bash tests/run-tests.sh --strict before considering any change done. Keep the flag: without it a suite whose dependency is missing exits 77 and is counted SKIPPED rather than failed, so the run goes green having verified less than it claims.
• Before pushing, rehearse the gate locally: pre-commit run --hook-stage pre-push --all-files. It runs the 14 pre-push hooks this repo authors itself plus pre-commit's 2 meta hooks, so it prints 16; check-release-needed passes without checking anything, because it needs a real push to main. docs/spec/gates.md reconciles both.
• 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.
• This repo and Gitea are the only source of truth. All project state, decisions, and working conventions live here. Do not use an external memory system for this project — cached state diverges from the repo and you get a split brain. Before answering any design or architecture question, check docs/adr/ for an existing decision.

Key documents

Read CONTEXT.md at the start of every session — it is this repo's domain glossary, and the terms it defines are used unglossed everywhere else. It is not exhaustive: terms it does not carry are defined at their point of use, mostly in docs/spec/.

Read these on demand:

• README.md — prerequisites, install, and test commands
• docs/VISION.md — the phased roadmap and where this is going; read when a decision turns on product direction
• LESSONS.md — patterns that went wrong once; read before repeating a class of change that has burned the repo before
• 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