AGENTS.md

Universal entry point for AI coding agents working with this skill pack — Claude Code, Codex, OpenCode, Cline, Continue, Cursor (agents mode), and any agent that reads AGENTS.md.

Scope: This file orients agents using the engineering-skills pack. The reusable assets are the skills under skills/; this file routes work to them and loads the shared discipline.

What this pack is

Skills organized by the software development lifecycle, including a meta router. Each skill is a folder skills/<phase>/<name>/SKILL.md with YAML frontmatter (name, description, optional disable-model-invocation) and four sections: When to use / Steps / Verify / References. Encyclopedic data lives in per-skill references/ (progressive disclosure).

Read the engineering principles first

Once per session, unless these rules are already loaded, read references/engineering-principles.md (repo-relative path — resolves in every framework). It defines shared decision boundaries, scope discipline, verification, document consent and publication control.

Claude Code gets these injected automatically at session start (SessionStart hook). Other frameworks — read the file above once per session.

Intent → skill routing

When a task arrives, identify the phase and reach for the matching skill. If unsure, the using-skills skill (in skills/meta/) maps the task to a phase.

Several skills carry sub-task references for focused scenarios — the main SKILL.md links a references/ file for depth:

• context-engineering → explains existing code / codebase tours (references/code-explanation.md)
• debugging → log triage without full reproduction (references/log-triage.md)
• implement → lightweight changes: small edits, renames, scaffolding (references/lightweight-changes.md)
• documentation-audit → writing new docs from scratch (references/writing-docs.md)
• purity-audit → per-category auditor subagent dispatch (references/subagent-dispatch.md)
• deprecation-migration → dependency upgrades (references/dependency-upgrade.md)

Every skill's ## When to use states a negative boundary (NOT for → the adjacent skill it isn't), so adjacent tasks route to the right skill instead of two firing at once.

Invocation model — user-invoked vs model-invoked

Every skill is either model-invoked (default — the agent reaches for it autonomously on trigger match) or user-invoked (only fires when the human types its name). Two skills are user-typed: brainstorm and handoff (set disable-model-invocation: true). The rest are model-invoked. See .agents/invocation.md for the full model and how it syncs across Claude Code (disable-model-invocation) and Codex (agents/openai.yaml → policy.allow_implicit_invocation).

Planning

Scale planning to the task. Use the harness planning facility when available, otherwise an inline plan. Use breakdown when durable dependency-aware tasks are useful. Do not force clear small edits through formal specifications.

Install

See .agents/install-block.md for the canonical install commands (Claude Code plugin, Codex, and other agents).

Conventions

• Skills live under skills/<phase>/<name>/SKILL.md (uppercase SKILL.md).
• Frontmatter: name + description (+ optional disable-model-invocation). Nothing else.
• Every skill's ## References links the shared engineering principles (source-relative links; standalone installation bundles shared resources). PM-side skills also link references/product-principles.md; UIUX skills also link references/design-principles.md.
• Doc-producing skills declare **Output:** (see references/skill-anatomy.md). Artifact paths are suggestions until confirmed. PRD/TECH/PLAN normally have one owner; separate release detail only when independently maintained scopes justify it. Human review uses references/human-audit.md.
• Validate: bash scripts/validate-skills.sh; installation: python -m unittest discover -s test -v.