Developer Instructions

Use this reference for gh-aw technical specs and development guidelines across code organization, validation, security, and implementation patterns.

Table of Contents

• Operational Command Playbook
• Capitalization Guidelines
• Sub-Skills

Operational Command Playbook

Use this section for the detailed day-to-day command flow that was intentionally removed from AGENTS.md to keep first-run ambient context small.

Validation checkpoints

Run validation in tiers — catch compile errors early, defer slow tests to the final pass only.

1. After each significant code edit (fast, <5s — catch compile errors immediately)

   make build && make fmt
   

2. Before every intermediate report_progress call (fast, <30s — no tests)

   make agent-report-progress-no-test
   

3. Before the FINAL report_progress call (change-scoped, includes impacted Go tests)

   make agent-report-progress
   

4. Before final handoff when time allows

   make agent-finish
   

Key rule: Run test-unit only before the final report_progress call, not before intermediate saves. The pre-PR targets scope formatting, linting, tests, and workflow drift checks to the branch changes.

Timeout budget: make agent-report-progress should normally finish in under 30 seconds. Workflow source or compiler changes additionally run the full workflow drift check. Set TEST_UNIT_RUN_FULL=1 only when the full Go suite is required.

Change-type command matrix

• Go file changes: make fmt
• Workflow markdown changes: make recompile
• JavaScript (*.cjs) changes: make fmt-cjs && make lint-cjs

Common focused checks from recent repository work

• pkg/workflow/ edits: run go test ./pkg/workflow -count=1 during iteration; narrow with -run when only one workflow behavior is under active change.
• actions/setup/js/ edits: after make fmt-cjs && make lint-cjs, run the targeted actions/setup/js/*.test.cjs suites for the files you touched. Gateway changes commonly validate with npx vitest run actions/setup/js/start_mcp_gateway.test.cjs.
• Workflow source changes that also touch compiler or runtime code: run make recompile, then rerun the affected focused Go or JavaScript checks before the final make agent-report-progress.

Merge-main playbook

When explicitly asked to merge main:

1. Run make merge-main.
2. If conflicts exist in .go or .cjs, resolve and stage files.
3. Run:

   make build
   make recompile
   git commit
   make fmt
   

Capitalization Guidelines

The gh-aw CLI follows context-based capitalization to distinguish between the product name and generic workflow references.

Capitalization Rules

Context	Format	Example
Product name	Capitalized	"GitHub Agentic Workflows CLI from GitHub Next"
Generic workflows	Lowercase	"Enable agentic workflows"
Technical terms	Capitalized	"Compile Markdown workflows to GitHub Actions YAML"

This convention distinguishes between the product name (GitHub Agentic Workflows) and the concept (agentic workflows), following industry standards similar to "GitHub Actions" vs. "actions".

Implementation

The capitalization rules are enforced through automated tests in cmd/gh-aw/capitalization_test.go that run as part of the standard test suite.

Sub-Skills

The following sub-skills cover specific areas of the codebase. Load them lazily when the task requires the specific domain:

Sub-skill	When to use
.github/skills/developer-code-organization/SKILL.md	Creating new files, refactoring, WASM stubs, file size decisions
.github/skills/developer-security/SKILL.md	Implementing new features, reviewing for security, template injection concerns
.github/skills/developer-internals/SKILL.md	Working on compiler internals, validation, safe outputs, MCP server, schema changes
.github/skills/developer-release/SKILL.md	Creating a release, evaluating breaking changes, firewall log analysis