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](#operational-command-playbook) - [Capitalization Guidelines](#capitalization-guidelines) - [Sub-Skills](#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) ```bash make build && make fmt ``` 2. **Before every intermediate `report_progress` call** (fast, <30s — no tests) ```bash make agent-report-progress-no-test ``` 3. **Before the FINAL `report_progress` call** (change-scoped, includes impacted Go tests) ```bash make agent-report-progress ``` 4. **Before final handoff when time allows** ```bash 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: ```bash 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 |