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/<name>/.apm/ is the only authoring source for plugin content. .claude/skills/ and .claude/agents/ are gitignored apm install output — never edit them.
• providers/claude-code/ is the Claude Code adapter, deployed to ~/.claude/ by scripts/install.sh.

Repo layout table: README.md. Deployment mechanics and plugin boundaries: 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 keeps the install current on launch and rewrites the lock in the process (ADR-0019). On main, commit or discard it deliberately. On a feature branch, discard it (git checkout -- apm.lock.yaml, then apm install). This keeps unrelated lock churn out of the branch diff and keeps apm pack --check-clean consistent with the committed lock. The session then runs the older main that the lock records, which is accepted on a branch, and the next session start refreshes again.
• A .apm/ edit is not live until it is on the remote's main. The six dependencies resolve from the holocron remote, unpinned against the default branch, so pushing a feature branch does not deploy it (ADR-0019). apm install deploys from the lock; apm update is what re-resolves refs.
• No pre-push hook needs the network. Root apm.yml's marketplace has no remote package entries, so every hook resolves locally.
• 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