gh-aw

When to Use

• Creating new .github/workflows/*.md agentic workflows
• Modifying frontmatter (triggers, permissions, safe-outputs, tools, MCP servers)
• Creating or importing .github/agents/*.md Copilot Custom Agents
• Debugging gh aw compile errors or warnings
• Configuring network access, rate limits, or footer templates

---

File Layout

.github/
├── workflows/
│   ├── {name}.md              # Frontmatter + thin context dispatcher
│   └── {name}.lock.yml        # Auto-generated — NEVER edit manually
├── agents/
│   └── {name}.md              # Full agent persona (reusable)
└── aw/
    └── actions-lock.json      # Action SHA pinning — commit this

See references/ for existing workflow and agent examples in this repo.

---

Critical Patterns

AGENTS.md Is the Source of Truth

Agent personas MUST NOT hardcode codebase layout, file paths, skill names, tech stack versions, or project conventions. All of this lives in the repo's AGENTS.md files and WILL go stale if duplicated.

Instead: Instruct the agent to READ AGENTS.md at runtime:

# In the agent persona:
Read `AGENTS.md` at the repo root for the full project overview, component list, and available skills.

For monorepos with component-specific AGENTS.md files, include a routing table that tells the agent WHICH file to read based on context — but never copy the contents of those files into the agent:

| Component | AGENTS.md | When to read |
|-----------|-----------|-------------|
| Backend   | `api/AGENTS.md`    | API errors, endpoint bugs |
| Frontend  | `ui/AGENTS.md`     | UI crashes, rendering bugs |
| Root      | `AGENTS.md`        | Cross-component, CI/CD |

Why this matters: Agent personas are deployed as workflow files. When AGENTS.md updates (new skills, renamed paths, version bumps), agents that READ it at runtime get the update automatically. Agents that HARDCODE it require a separate PR to stay current — and they won't.