AGENTS.md — Working on the mak Plugin Repository

This repository IS the Claude Code plugin mak (repo root = plugin root; manifest at .claude-plugin/plugin.json). Everything is Markdown / JSON (plus eval fixture scripts under evals/, check scripts under scripts/, and hook scripts under hooks/) — no build, no unit tests.

Development rules are split across two files: CLAUDE.md holds the reference rules and the always-run verification commands (plus the triggers for the conditional ones, whose procedures live in docs/maintenance.md); this file restates the invariants you must not break and owns §Git.

Language policy

• skills/*/SKILL.md and agents/*.md instructions/descriptions: English
• skills/*/assets/ templates and doc sets: English (output language is delegated to "follow the user's language" notes in skills)
  • Exception: skills/setup/assets/claude-md-snippet.ko.md / .en.md — a Korean/English mirror pair injected verbatim into ~/.claude/CLAUDE.md (mak:setup picks by the user's language). Edit both together; markers must stay identical across the pair
• evals/: case, grader, and script code English; prompt.md bodies and seeded fixture text may be Korean
• README.md / docs/guide.md are Korean with English twins (README.en.md, docs/guide.en.md) — edit both sides together

Consistency invariants

• Cross-references between skills/agents always use the mak: prefix (mak:dev-kickoff), never bare names
• Agent availability is phrased as "if the agent is in the available agent list", never as a .claude/agents/*.md file-existence check
• The design-doc save-path rule has ONE home: skills/design-doc-template/SKILL.md §Save location (default .claude/mak/plan/). Skills/agents attribute it to that rule and may restate the default for readability; user-facing docs (README, guide) may state the default plainly — the rule text itself lives only in the home
• An agent that loads a companion skill via frontmatter skills: must not restate that skill's procedure or report format — point at it instead
• The task grades and the four coding principles have ONE home: docs/guide.md §2.1 / §2.2. The setup snippets inject copies of both (the principle copy drops the Enforcement gates column) — a change to any column the snippet copies must be synced across 4 places: guide ko/en + snippet ko/en; a change confined to Enforcement gates syncs guide ko/en only; skills/agents keep the "project/global Coding Rules take precedence" phrasing
• Frontmatter description carries trigger conditions only (loaded into every session); detailed criteria go in the body. Agent descriptions are the exception — the orchestrator selects on that text, so capability/constraint wording stays
• Use ${CLAUDE_PLUGIN_ROOT} for referencing files inside the plugin
• Adding or removing a skill/agent is a multi-file sync — follow docs/maintenance.md §Adding or Removing a Skill / Agent, which owns the point list. This file intentionally carries no counts or component lists, so it stays out of that sync

Verification

1. claude plugin validate .
2. bash scripts/check.sh — consistency, size, snippet-mirror, and git-guard hook checks; must print OK (exit 0). CI runs this on push and PR

Conditional checks (graph connectivity, local smoke, setup/teardown round-trip, doc-set closure, behavior eval, snippet probe) live in docs/maintenance.md §Conditional Verification; CLAUDE.md §Verification Commands lists their triggers. Graph connectivity is the only check that catches a component nothing routes into — run it on every skill/agent add, remove, or rewire.

Git

Commit/push only when the user explicitly says "commit"/"push".