Developer

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.

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

   make build && make fmt

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

   make agent-report-progress-no-test

• Before the FINAL report_progress call (slower, once per session — includes test-unit)

   make agent-report-progress

• 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. Each unnecessary invocation adds 120+ seconds to total validation time.

> Timeout budget: make test-unit is expected to take up to 120 seconds. If it exceeds that, use make test-impacted-go to run only tests for packages affected by the current branch's changes.

Change-type command matrix

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

Merge-main playbook

When explicitly asked to merge main:

• Run make merge-main.
• If conflicts exist in .go or .cjs, resolve and stage files.
• 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 |