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

• core/ — provider-agnostic source of truth (plain language, no tool-specific references)
• .agents/skills/ — directly-deployed skills (Agent Skills standard); deployed to ~/.agents/skills/ via install.sh; marketplace and factory skills live in plugins/kyberforge/ instead
• .agents/evals/ — eval.yaml files for skills not bundled into a plugin
• .claude-plugin/ — marketplace manifest (marketplace.json); read by both Claude Code and Copilot CLI
• 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)
• docs/ — project documentation, PRDs, and issues
• scripts/ — install.sh (sync.sh and init-project.sh come in Chunk 6)
• tests/ — test scripts

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/overview.md — current deployed state; what works today
• docs/spec/architecture.md — current directory structure, install pipeline, provider model
• docs/ROADMAP.md — chunk status table and open questions; read this to orient on where work stands
• 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
• docs/HUMANS.md — human practitioner checklist; applies when working with AI tools in this repo
• Governance rules are always in effect — core/instructions/governance.md (agent rules); docs/research/governance_principles/CONTROLS.md (Phase 2 enforcement spec, Chunk 6)

Key rules

• core/ content must use plain imperative language — no tool names, provider APIs, or format assumptions
• Never edit files deployed by sync.sh directly in a project; put customizations in override files
• providers/claude-code/CLAUDE.md is the deployed global config — edit it there, not here
• Governance constraints from core/instructions/governance.md apply when building content in this repo — hard prohibitions on secrets and data, HITL requirements before irreversible actions, sycophancy resistance, and deterministic execution preference are always in effect

Chunk development workflow

Each chunk follows this sequence:

1. /grill-with-docs — grill vision/context before writing anything
2. /to-prd — write the PRD from the grilling output
3. /to-issues — break PRD into issues (docs/issues/ until Gitea is set up)
4. /tdd — implement each issue using TDD
5. /improve-codebase-architecture — architecture review after implementation
6. Start a new session before the next chunk

Don't skip /tdd — it's the easy one to forget.

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.