gh-aw: Instructions file for Codex

GitHub Agentic Workflows (gh-aw)

GitHub Agentic Workflows (gh-aw) is a GitHub CLI extension that compiles markdown workflows into GitHub Actions.

Important Note: gh-aw vs GitHub Copilot CLI

• gh-aw is the gh aw CLI extension.
• copilot is a separate CLI used as one possible runtime engine.
• Use gh aw commands for workflow authoring/compilation (gh aw compile, gh aw run, gh aw audit).

Ambient Context (First Invocation)

To keep first-turn context small, only these repository root instruction files should be considered ambient:

Everything else should be loaded lazily through skills only when needed.

Critical Rules (Always Applicable)

1. If you changed files, use report_progress to commit and push.
2. Before intermediate report_progress calls, run make agent-report-progress-no-test (fast, no tests). Before the final report_progress, run make agent-report-progress (includes test-unit).
   • test-unit is impacted-first by default (~30s target). Use TEST_UNIT_RUN_FULL=1 make test-unit or make test-unit-all when full-suite coverage is required.
   • Run test-unit only once per PR — at the final push, not on every intermediate save.
3. After Go changes, run make fmt.
4. After workflow markdown changes (.md under .github/workflows/), run make recompile.
5. Do not add .lock.yml files to .gitignore.
6. Copilot cloud agents may dispatch a workflow only when the user explicitly requests a dry-run test and the exact published source and lock revision has passed the review, compilation, and live-execution gates in .github/aw/debug-agentic-workflow.md. Compile with --dry-run and dispatch that reviewed revision; compilation alone does not start a run, and dispatch alone does not enable dry-run protections. Dry-run suppresses compiler-managed mutations, not arbitrary script effects. Non-dry-run dispatch remains prohibited. On an authorization error, stop and report it; never retry with different credentials, bypass protections, or ask the user to run it manually.
7. Large-file guard: before reading any file with github-mcp-server-get_file_contents, check its size. Files larger than 20 KB must be read with targeted tools (grep, glob, bash, or view with view_range) instead of full-file reads. See token-optimization.md for the full technique.
8. Never ask the user to confirm the plan. Always execute the plan.
9. Autopilot mode: Never ask for confirmation before taking action. Never prompt the user with "Should I proceed?", "Do you want me to…?", or any equivalent. Always act immediately and autonomously.
10. Grading contract: Follow .github/skills/operational-value-designer/SKILL.md. Built-ins compute over the in-memory unified session in conclusion; custom graders.<distinct-id>.script JavaScript and repository-owned graders.operational-value.run Bash run only in the separate graders job. Bash reads session JSONL from $1 / GH_AW_SESSION_FILE, config JSON from GH_AW_GRADER_CONFIG, and returns legacy metric arrays; detected file writes are rejected. Shell is trusted code, not yet microVM-isolated. Never add user code or steps to conclusion. Adopt workflow semantics and grader acceptance rules together at the same workflow path and commit; corrections are prospective and prior results are never rewritten.