developer
Core developer rules and coding conventions for gh-aw changes.
Try your first task
A source-grounded starter task has not been verified for this skill yet.
SKILL.md
name: developerdescription: Core developer rules and coding conventions for gh-aw changes.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
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.
Sandbox-compatible commands
- Run commands from the active worktree, never the main checkout or a sibling
worktree. Each shell starts fresh; specify the working directory in each
command. From the repository root, use
npm --prefix docs run <script>for docs scripts, not barenpm run <script>. - Use literal
$TMPDIRpaths for scratch files and writable caches, not/tmp, resolved macOS temp paths, or system directories. When cache writes need isolation,makedefaults Go, golangci-lint, and npm caches under$TMPDIRwhen it is set, preserving explicit cache overrides. Before direct tool commands, includinggo envandgo version, export:
On macOS, canonicalize the existing temporary directory before path-sensitive tests so theexport GOCACHE="$TMPDIR/gh-aw-go-build" GOMODCACHE="$TMPDIR/gh-aw-go-mod" export GOLANGCI_LINT_CACHE="$TMPDIR/gh-aw-golangci-lint" export npm_config_cache="$TMPDIR/gh-aw-npm-cache"/varsymlink does not trigger symlink-rejection guards:
Restore local dependencies only after a manifest change or missing-tool failure; do not install tools globally.export TMPDIR="$(cd "$TMPDIR" && pwd -P)" - Prefer the smallest focused check. Docs title changes use
npm --prefix docs run test:titles. Full docs builds also require thegithubnext/agenticsworkflow sources: setAGENTICS_WORKFLOWS_DIRto an explicitly available dependency directory rather than relying on the default sibling path outside the worktree. Missing sources are a dependency blocker, not a sandbox denial; do not fabricate replacement workflows. - Attempt commands inside the sandbox. On a path denial, stop operations on that path, report the sandbox restriction, and request a policy update. Do not retry through another tool, change permissions, or rerun outside the sandbox. Missing approvals and ordinary build errors are not path denials.
Validation checkpoints
Run validation in tiers. Keep formatting and focused tests in the inner loop; defer package-wide Go linting and workflow drift to the final pass.
- After each significant code edit (format changed files, then run one focused check)
Replace the package and test pattern with the behavior being changed. This compiles the affected package too; do not add a CLI build unless the next command needsmake fmt go test ./pkg/cli -run '^TestRelevantBehavior' -count=1./gh-aw. First builds after Go edits can exceed the warm-cache budget because Go compiles the entire package, including its test files. - Before every intermediate
report_progresscall (fast, no test bodies)
This formats branch changes and compiles/vets changed Go packages. It does not link the CLI or run package-wide Go linters or workflow recompilation. Schema changes still rebuild the CLI; stale-lock and local-permission guards still run. JavaScript/action-shell checks remain change-scoped.make agent-report-progress-no-test - Before the FINAL
report_progresscall (build, lint, impacted tests, and workflow drift)
This is the full pre-PR gate. Run it once, not after every focused test.make agent-report-progressmake agent-finishis an explicit repository-wide maintenance sweep, not an inner-loop or routine handoff command.
Key rule: Run
test-unitonly before the finalreport_progresscall, not before intermediate saves. Intermediate saves defer full Go lint and workflow drift; they do not replace the final gate.
Timeout budget: Aim for warm-cache intermediate validation under 5 seconds. The 30-second
test-unitbudget covers selected test runtime, not compilation, linting, or full workflow drift; the final gate can take minutes. SetTEST_UNIT_RUN_FULL=1only when the full Go suite is required.
Change-type command matrix
- Formatting:
make fmtformats branch changes (including staged, unstaged, and untracked files). Go-only edits do not need npm. Usemake fmt-allonly for an explicit full-repository formatting sweep. - Workflow markdown changes:
make recompile - JavaScript (
*.cjs) changes:make fmt, then a focused runtime test. The intermediate gate runs changed-file JavaScript lint.
Common focused checks from recent repository work
pkg/workflow/edits: rungo test ./pkg/workflow -count=1during iteration; narrow with-runwhen only one workflow behavior is under active change.actions/setup/js/edits: aftermake fmt, run the targetedactions/setup/js/*.test.cjssuites for the files you touched. Gateway changes commonly validate withnpx 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 finalmake agent-report-progress.
Merge-main playbook
When explicitly asked to merge main:
- Run
make merge-main. - If conflicts exist in
.goor.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 |