Imported from derio-net/frank (AGENTS.md). Install upstream with npx skills add derio-net/frank. Copyright stays with the author.

Agent Configuration & Mandates

This file is the canonical entry point for all AI agents operating in this repository. Agent-specific files may adapt these instructions for a particular runtime, but they must not define a competing source of truth.

Load Order

Before making non-trivial changes, agents should read these files in order:

1. AGENTS.md — this canonical contract.
2. agents/rules/repo-principles.md — declarative-only policy and maintenance rules.
3. agents/rules/repo-architecture.md — repository layout and naming conventions.
4. agents/rules/repo-workflows.md — standard layer and fix/extension workflows.
5. agents/rules/frank-identity.md — project voice and persona.
6. Cluster-specific rules on demand:
   • Frank: agents/rules/frank-infrastructure.md, agents/rules/frank-commands.md, agents/rules/frank-argocd.md, agents/rules/frank-gotchas.md
   • Hop: agents/rules/hop-infrastructure.md, agents/rules/hop-commands.md, agents/rules/hop-gotchas.md
   • Browser automation: agents/rules/browser-harness.md (machine-global browser-harness setup; host-specific transport injected per environment). On the macOS workstation, the SessionStart adapter also injects the Mac-only overlay agents/browser-harness-mac.md (Brave-Clawdia + uv-clobber caveat).
7. Task-specific skills or reviewer profiles from agents/skills/, agents/reviewers/, and agents/commands/.

Shared Rule Registry

Agent-neutral rules live in agents/rules/:

• browser-harness.md
• frank-argocd.md
• frank-commands.md
• frank-gotchas.md
• frank-identity.md
• frank-infrastructure.md
• hop-commands.md
• hop-gotchas.md
• hop-infrastructure.md
• plan-checkbox-tracking.md
• plan-post-deploy-checklist.md
• repo-architecture.md
• repo-blog.md
• repo-manual-ops.md
• repo-papers.md
• repo-principles.md
• repo-workflows.md
• third-party-privacy.md

Shared Skills

Repo-local skills are stored in agents/skills/. When a task matches a skill, read that skill's SKILL.md before acting.

• awx-onboard-hosts: agents/skills/awx-onboard-hosts/SKILL.md
• bump-image: agents/skills/bump-image/SKILL.md
• deploy-app: agents/skills/deploy-app/SKILL.md
• expose-service: agents/skills/expose-service/SKILL.md
• falco-triage: agents/skills/falco-triage/SKILL.md
• frank-alert-triage: agents/skills/frank-alert-triage/SKILL.md
• hop-trace-analysis: agents/skills/hop-trace-analysis/SKILL.md
• oidc-onboard: agents/skills/oidc-onboard/SKILL.md
• post-deploy: agents/skills/post-deploy/SKILL.md
• sync-runbook: agents/skills/sync-runbook/SKILL.md
• update-readme: agents/skills/update-readme/SKILL.md

Blog authoring lives in the blog-craft plugin (enabled via .claude/settings.json), not agents/skills/: /blog-craft:blog-post, /blog-craft:media, /blog-craft:papers — all driven by the repo's .blog-craft.yaml.

Slash-command references are aliases for the repo-local skills above. For example, /sync-runbook means agents/skills/sync-runbook/SKILL.md.

Shared Reviewers And Commands

Reusable reviewer profiles live in agents/reviewers/:

• code-reviewer.md
• k8s-manifest-reviewer.md

Reusable command runbooks live in agents/commands/ (currently empty — update-openrouter-models.md was retired when the cluster went local-only inference, see #461 and derio-net/agent-skills#1).

Machine-Readable Configuration

• Layer registry: docs/layers.yaml
• Plan profile: docs/superpowers/plan-config.yaml
• Manual operations runbook: docs/runbooks/manual-operations.yaml

Safety And Enforcement

• Do not edit sensitive files such as .env_devops, .sops.yaml, or files under .talos/ without explicit user confirmation.
• This repo is fr-enabled: writes must happen inside an fr-isolation workspace, never the base clone. Read-only work is unaffected. See "Write Isolation (fr)" in agents/rules/repo-workflows.md before your first edit.
• Cluster state should be reproducible from this repo. See agents/rules/repo-principles.md for the narrow manual-operation exception.
• Validate agent configuration with scripts/validate-agent-config.sh.
• Validate plans with scripts/validate-plans.sh.
• The shared Git pre-commit hook runs both validators for relevant changes.
• Claude Code hooks in .claude/settings.json are adapters only. Other agents are not protected by those hooks, so portable checks must live in scripts.

Agent-Specific Adapters

• CLAUDE.md is the Claude Code adapter and should point back here.
• GEMINI.md is the Gemini adapter and should point back here.
• .claude/settings.json may wire Claude-specific hooks, permissions, and plugins, but canonical behavior belongs in AGENTS.md, agents/, docs/, and scripts/.
• Compatibility symlinks: .claude/skills, .claude/rules, .claude/agents, and .claude/commands point into agents/.
• .claude/settings.local.json is local operator state and must not be treated as shared policy.