holocron/AGENTS.md

Working in this repo

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

Structure

• plugins/ — installable plugin units; each is self-contained (skills, agents, hooks, MCP servers, bundled assets); install separately via claude plugin install <name>@holocron
• providers/claude-code/ — Claude Code adapter (deployed to ~/.claude/ via install.sh)

Setup

• Install git hooks: pre-commit install -t pre-commit -t pre-push -t commit-msg. .pre-commit-config.yaml uses all three stages and has no default_install_hook_types set, so a plain pre-commit install only wires the pre-commit stage and silently skips commit-msg (Conventional Commits check) and pre-push (test suite, manifest check).
• Install the vale binary — required by the vale-audit-prefilter pre-commit hook, which runs on every commit touching a SKILL.md or agent .md file. Without it, the hook fails with a bare "command not found" and no install pointer. Install via a package manager (brew install vale on macOS, snap install vale on Linux, choco install vale on Windows) or see https://vale.sh/docs/vale-cli/installation/; then run vale sync to pull the styles declared in .vale.ini.

Testing instructions

• Run bash tests/run-tests.sh before considering any change done, and fix failures — it runs every test-*.sh script in the repo plus the bats suite (tests/run-bats.sh).
• bash tests/run-tests.sh --bats-only runs just the bats suite.
• The bats suite auto-initializes its submodules (tests/bats, tests/test_helper/bats-support, tests/test_helper/bats-assert) on first run if the bats binary is missing — no manual git submodule update needed.

Commit / PR conventions

• Commit messages must follow Conventional Commits — enforced by the conventional-pre-commit hook at the commit-msg stage.
• Pushing runs the full test suite (tests/run-tests.sh) and scripts/check-manifests.sh (validates marketplace.json/plugin.json paths resolve) via pre-push hooks — run both locally first so a failing push isn't a surprise.

Key documents

Read CONTEXT.md at the start of every session in this repo.

Read these on demand:

• docs/VISION.md — purpose, goals, and long-term Management Application vision
• docs/spec/architecture.md — current 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

Working context

This repo is built by a junior developer as a homelab tool intended to scale to professional environments. Challenge ideas and reference industry standards rather than validate assumptions. Explain the why behind decisions — assume the user is learning, not just executing. Flag significant actions before taking them.

Subagent orchestration

• Forks stop when their assigned task is done. A fork inherits the coordinator's full context, including visibility into any shared TaskList. That visibility is not license to keep going: once a fork's assigned task is reported complete, it must stop rather than autonomously picking up further items from the list. Forks that keep pulling work race against the coordinator's own orchestration and can duplicate or conflict with tasks the coordinator has separately delegated.
• Don't hand a fork a TaskList that includes governance-gated actions (push, publish, merge) unless you are prepared for it to act on those items without a fresh confirmation round. A fork acting on its own initiative is not party to any pending human confirmation the coordinator is mid-flow on, so it can bypass a gate that was meant to hold.
• TaskGet/TaskUpdate/TaskList only work for forks. Fresh (non-fork) subagents cannot discover or call these tools. When delegating to a fresh subagent, the coordinator owns all task-list bookkeeping itself — claim and complete the entry on the agent's behalf — rather than instructing the fresh agent to self-claim or self-complete.
• Worktree/branch cleanup is part of closing out the PR, not a separate step. When a coordinator creates a worktree (Agent(isolation: "worktree") or git worktree add directly) to land a PR, merging that PR is not the end of the task. Immediately after verifying the merge: run git worktree remove --force --force <path> (the double -f is required whenever the worktree initialized submodules to run tests — assume it did, this repo has several), then git branch -d both the feature branch and any worktree-agent-<id> isolation branch the Agent tool auto-created for that worktree — git worktree remove deletes neither branch on its own. Do this without waiting for the user to notice stale branches/worktrees and ask.
• Agent(isolation: "worktree") may fork from main, not the branch you were on. Don't assume the isolated worktree is based on your current branch just because that's what you asked for — in practice it has forked from a stale main (missing commits the task depended on) even when the coordinator was on a feature branch at call time. Every affected agent has to notice (missing files, unexpected diff base) and self-correct with git merge --ff-only <target-branch> or a reset onto origin/<target-branch> before it can safely edit. Don't leave this to chance: tell the agent explicitly in the prompt which branch its worktree must be based on and to verify/rebase onto it as a first step before editing anything, and check for this yourself when reviewing a worktree agent's report.
• Don't route already-fully-specified corrective edits through kyberforge:forge. forge exists to classify ambiguous "what should I build" intent before routing to an author skill — it isn't needed when the coordinator already knows the exact file, line, and fix. Sending fully-specified fixes through forge adds a grill-and-delegate layer that can itself spawn further sub-delegation (forked sub-subagents), which has been observed to lose track of hard constraints handed down the chain (e.g. "don't commit yet," "edit in this worktree") because each hop re-derives instructions from a shorter brief. Call the target author skill (skill-author, plugin-author, etc.) directly for known fixes; reserve forge for genuinely undecided "which artifact type is this" questions.