diff --git a/.github/agents/adr-writer.agent.md b/.github/agents/adr-writer.agent.md index 53f2d316aee..b90f8fd0041 100644 --- a/.github/agents/adr-writer.agent.md +++ b/.github/agents/adr-writer.agent.md @@ -11,11 +11,10 @@ Expert Architecture Decision Record (ADR) writer. Follow the **Michael Nygard AD ADRs are permanent records of significant technical decisions: *"Why does the codebase look the way it does?"* -Key principles: -- **Immutable once accepted** — approved ADRs are never deleted; superseded ones are marked "Superseded by ADR-XXXX" -- **Decision-focused** — capture the *why*, not just the *what* -- **Honest about trade-offs** — include real negatives and costs, not just positives -- **Written for future readers** — someone unfamiliar with the context should understand the decision 12 months later +- **Immutable once accepted** — never deleted; superseded ones marked "Superseded by ADR-XXXX" +- **Decision-focused** — capture *why*, not just *what* +- **Honest about trade-offs** — include real negatives and costs +- **Written for future readers** — understandable 12 months later ## Storage Convention @@ -29,13 +28,13 @@ docs/adr/ ``` **Filename format**: `NNNN-kebab-case-title.md` -- `NNNN` zero-padded to 4 digits (e.g., `0001`, `0042`, `0100`) -- Title in lowercase kebab-case, derived from the ADR title -- No special characters other than hyphens +- `NNNN` zero-padded 4 digits (e.g., `0001`, `0042`) +- Lowercase kebab-case title +- Only hyphens as separators ## ADR Template -Two-part structure: a **human-friendly narrative** for developers/stakeholders, then a **normative specification** in RFC 2119 language for machine-checkable conformance. +Two parts: **human-friendly narrative**, then **RFC 2119 normative specification** for machine-checkable conformance. ```markdown # ADR-{NNNN}: {Concise Decision Title} @@ -125,7 +124,7 @@ An implementation is considered conformant with this ADR if it satisfies all **M #### Context (3–5 sentences) - *What problem? What constraints?* (technical, organizational, timeline) -- State of codebase at decision time +- Codebase state at decision time - Problem space, not implementation #### Decision (2–4 sentences) @@ -135,12 +134,12 @@ An implementation is considered conformant with this ADR if it satisfies all **M #### Alternatives Considered (2–4 sentences each) - **≥2 genuine alternatives** (no strawmen) -- For each: what it is, why considered, why rejected -- If a close call, say so +- For each: what, why considered, why rejected +- If close call, say so #### Consequences -- **Positive**: real benefits, not marketing -- **Negative**: real costs and trade-offs — be honest +- **Positive**: real benefits +- **Negative**: real costs and trade-offs - **Neutral**: side effects worth noting - ≥2 per category for non-trivial decisions @@ -243,7 +242,7 @@ For each: what problem? what alternatives? what consequences? 1. Read the ADR **Decision** — extract commitments 2. Check code for conformance/deviation 3. Note **divergences**: code contradicts decision -4. Note **scope creep**: significant decisions in code the ADR doesn't cover +4. Note **scope creep**: significant decisions in code not covered Return: - **Aligned**: code implements the ADR @@ -255,7 +254,7 @@ Return: Warrant an ADR: - Database, message queue, cache, or storage choice - Adopting/replacing a framework -- Auth/authorization approach change +- Auth/authz approach change - API convention (REST vs GraphQL vs gRPC) - Architectural patterns (microservices vs monolith, event-driven vs request-driven) - Significant infrastructure (Kubernetes, Terraform) @@ -266,5 +265,5 @@ Do **not** warrant an ADR: - Bug fixes without design trade-offs - Minor refactors within existing patterns - Documentation updates -- Dependency version bumps (unless major new dep) +- Dependency bumps (unless major new dep) - Code style/formatting changes diff --git a/.github/aw/visual-regression.md b/.github/aw/visual-regression.md index b4cfa5fca92..1a688ff8e58 100644 --- a/.github/aw/visual-regression.md +++ b/.github/aw/visual-regression.md @@ -51,15 +51,15 @@ Otherwise compare each screenshot to its baseline. Post a comment summarizing: p ## Key Design Decisions -- **`cache-memory` key per base branch** — scopes baselines to `main`, `develop`, etc. independently -- **`allowed_domains: [localhost, 127.0.0.1]`** — prevents SSRF; app must be served locally -- **`retention-days: 30`** — keeps baselines beyond the default 7-day cache expiry -- **Filesystem-safe timestamps** — `YYYY-MM-DD-HH-MM-SS` format; colons are invalid in artifact filenames -- **Minimal permissions** — all PR writes go through `safe-outputs`, not GitHub tools +- **`cache-memory` key per base branch** — scopes baselines to `main`, `develop`, etc. +- **`allowed_domains: [localhost, 127.0.0.1]`** — prevents SSRF; serve app locally +- **`retention-days: 30`** — beyond the default 7-day cache expiry +- **Filesystem-safe timestamps** — `YYYY-MM-DD-HH-MM-SS`; colons break artifact filenames +- **Minimal permissions** — all PR writes go through `safe-outputs` ## Network-Minimization Reminders -- Prefer local preview serving (`localhost`/`127.0.0.1`) over external preview environments when possible. -- If external previews are required, allowlist only exact preview domains needed for the check (avoid broad wildcards). -- Enable `network.node` only when the workflow actually installs/builds Node dependencies; scope domains to package registries and required preview hosts. -- Keep Playwright navigation limited to app-under-test URLs and avoid loading unrelated third-party domains. +- Prefer local preview (`localhost`/`127.0.0.1`) over external preview environments. +- If external previews are required, allowlist exact domains (no broad wildcards). +- Enable `network.node` only when installing/building Node deps; scope to registries and preview hosts. +- Keep Playwright navigation limited to app-under-test URLs. diff --git a/.github/aw/workflow-constraints.md b/.github/aw/workflow-constraints.md index 78e409c4220..452922f0015 100644 --- a/.github/aw/workflow-constraints.md +++ b/.github/aw/workflow-constraints.md @@ -8,7 +8,7 @@ description: Shared architectural and security constraints for designing or upda Agentic workflows run as a **single GitHub Actions job** with one agent execution. -## What They Can Do +## Can Do - read GitHub data, APIs, web pages, and local repository files - run tools inside the single job @@ -16,7 +16,7 @@ Agentic workflows run as a **single GitHub Actions job** with one agent executio - create GitHub resources through `safe-outputs:` - persist lightweight state with `cache-memory` or other approved mechanisms -## What They Cannot Do +## Cannot Do - pause and resume for external events - orchestrate multi-stage pipelines with job dependencies @@ -24,19 +24,17 @@ Agentic workflows run as a **single GitHub Actions job** with one agent executio - implement built-in rollback across external systems - wait for another workflow or deployment to finish inside the same agent run -## When to Recommend Traditional GitHub Actions Instead - -Use traditional Actions when the request needs: +## Recommend Traditional GitHub Actions When - multi-stage deployment pipelines -- fan-out or fan-in job orchestration +- fan-out/fan-in job orchestration - long waits for approvals or external systems - rollback logic across several steps or systems - cross-job state transfer -Suggested response pattern: +Suggested response: -> This requires capabilities that agentic workflows do not support in their single-job model. Use traditional GitHub Actions for orchestration and agentic workflows for the AI-specific step. +> This requires capabilities the single-job agentic model does not support. Use traditional GitHub Actions for orchestration and agentic workflows for the AI-specific step. ## Security Posture @@ -52,7 +50,7 @@ Suggested response pattern: When a requested feature increases risk: -1. explain the risk clearly +1. explain the risk 2. propose the safer pattern first 3. require explicit confirmation before relaxing safeguards @@ -81,4 +79,4 @@ For the full set of requirements (Docker socket, ARC / Docker-in-Docker, network ## Shared Reminder -Reference this file from creator, updater, and debugger prompts instead of repeating the same architectural explanation. +Reference this file from creator, updater, and debugger prompts instead of repeating the architectural explanation. diff --git a/.github/aw/workflow-editing.md b/.github/aw/workflow-editing.md index 41b6a8d4d51..ef093ba9166 100644 --- a/.github/aw/workflow-editing.md +++ b/.github/aw/workflow-editing.md @@ -8,12 +8,12 @@ Agentic workflows are single markdown files at `.github/workflows/. ## File Structure -1. **YAML frontmatter** between `---` markers configures triggers, permissions, tools, network, imports, and safe outputs. -2. **Markdown body** after the frontmatter is the agent prompt. +1. **YAML frontmatter** between `---` markers: triggers, permissions, tools, network, imports, safe outputs. +2. **Markdown body**: the agent prompt. -## When Recompilation Is Required +## Recompile When Changing Frontmatter Fields -Run `gh aw compile ` after changing frontmatter fields such as: +Run `gh aw compile ` after changing: - `on:` - `permissions:` @@ -24,9 +24,9 @@ Run `gh aw compile ` after changing frontmatter fields such as: - `mcp-servers:` - engine, timeout, concurrency, or other YAML configuration -## When Recompilation Is Not Required +## No Recompile Needed -Edit the markdown body directly when changing: +Edit the markdown body directly for: - agent instructions - task descriptions @@ -34,7 +34,7 @@ Edit the markdown body directly when changing: - formatting guidance - clarifications and guardrails -Markdown body changes take effect on the next run without recompiling. +Body changes take effect on the next run. ## Validation Commands @@ -48,15 +48,15 @@ Use `--strict` for production-quality validation. ## Editing Rules -- Make the smallest change that satisfies the request. -- Preserve existing structure unless reorganization is part of the task. -- Never leave a workflow in a broken state. -- If compilation fails, fix all errors before stopping. +- Smallest change that satisfies the request. +- Preserve structure unless reorganization is the task. +- Never leave a workflow broken. +- If compile fails, fix all errors before stopping. - After frontmatter changes, review the generated `.lock.yml`. ## Prompt-Authoring Rules -- Keep the prompt specific and imperative. -- Prefer short examples over long tutorials. -- Reference dedicated instruction files instead of duplicating long explanations. -- Tell agents to use `noop` when they complete successfully and no visible action is needed. +- Specific and imperative. +- Short examples over long tutorials. +- Reference dedicated instruction files instead of duplicating. +- Tell agents to use `noop` when no visible action is needed. diff --git a/.github/aw/workflow-patterns.md b/.github/aw/workflow-patterns.md index 14a6a63b453..2a13b59d9a3 100644 --- a/.github/aw/workflow-patterns.md +++ b/.github/aw/workflow-patterns.md @@ -30,61 +30,61 @@ See also: [triggers.md](triggers.md) ### Use `workflow_run` when - monitoring another GitHub Actions workflow in the **same repository** -- reacting to workflow completion or conclusion +- reacting to workflow completion/conclusion -Reusable incident-triage pattern: +Incident-triage pattern: -- trigger: `on.workflow_run` for the named deployment or CI workflow -- permissions: include `actions: read`; keep main job read-only -- reads: fetch failed job logs/artifacts via GitHub tools -- output: summarize impact/root cause in `create-issue`; use `noop` when no incident action is needed +- trigger: `on.workflow_run` for the named deployment/CI workflow +- permissions: include `actions: read`; main job read-only +- reads: failed job logs/artifacts via GitHub tools +- output: `create-issue` with impact/root cause; `noop` when no action needed ### Use `deployment_status` when -- monitoring an external deployment service that reports status back to GitHub +- monitoring an external deployment service reporting back to GitHub -Quick rule of thumb: +Rule of thumb: -- `workflow_run` → GitHub Actions workflow/job outcomes in this repository -- `deployment_status` → external platform deployment outcomes reported through the Deployments API +- `workflow_run` → GitHub Actions outcomes in this repo +- `deployment_status` → external platform outcomes via Deployments API -Single-job limits still apply in both patterns: +Single-job limits apply: -- keep triage, evidence collection, and summary generation in one agent job -- do not design multi-job fan-out/fan-in orchestration -- do not rely on cross-workflow waits or external workflow chaining +- triage, evidence collection, and summary in one agent job +- no multi-job fan-out/fan-in +- no cross-workflow waits or chaining See also: [deployment-status.md](deployment-status.md) ## High-Volume Triage and Escalation Pattern -For workflows that receive many similar events (issues, PR comments, CI failures, security alerts, dependency events): +For workflows receiving many similar events (issues, PR comments, CI failures, security alerts, dependency events): -- start with a narrow, cheap triage/classification pass -- detect known, duplicate, stale, or low-value cases first -- emit explicit `noop` or a safe output when triage is confident -- escalate to the main/frontier agent only when triage is uncertain or the case is genuinely new/high-value +- start with a cheap triage/classification pass +- detect known/duplicate/stale/low-value cases first +- emit `noop` or a safe output when triage is confident +- escalate to the main agent only when uncertain or genuinely new/high-value Decision flow: ```text -IF cheap triage is confident that the event is known, duplicate, stale, or low-value THEN - stop and emit the configured safe output or noop +IF cheap triage is confident (known/duplicate/stale/low-value) THEN + emit safe output or noop ELSE escalate to the main agent END IF ``` -Use this with pull-context workflows: fetch targeted evidence on demand instead of pushing large raw logs or payloads into the initial prompt. +Use with pull-context workflows: fetch targeted evidence on demand instead of pushing raw logs into the initial prompt. ## Large-Repository Improvement Pattern -For recurring maintenance in large repositories: +For recurring maintenance in large repos: - use `cache-memory` -- process one package, module, or directory per run -- store the last processed item and rotate in round-robin order -- prefer smaller focused PRs over wide repository sweeps +- process one package/module/directory per run +- store last-processed item; round-robin +- prefer small focused PRs over wide sweeps See also: [memory.md](memory.md) @@ -95,58 +95,58 @@ Use deterministic `steps:` when the workflow needs large external data before th Rules: - write prepared files to `/tmp/gh-aw/agent/` -- trim large outputs before handing them to the agent +- trim large outputs before handing to the agent - set `GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}` on every `gh` step -- add `permissions: actions: read` when downloading workflow logs or artifacts -- use `jq` to reduce JSON payload size before writing files +- add `permissions: actions: read` for downloading workflow logs/artifacts +- use `jq` to reduce JSON payload size ## PR Visual Regression Pattern -For pull-request UI validation and screenshot diffs: +For PR UI validation and screenshot diffs: - trigger: `pull_request` - tools: `playwright` plus `cache-memory` for baseline metadata -- permissions: read-only repo/PR access in agent job -- output: `add-comment` with pass/fail summary and links to captured artifacts -- fallback: use `noop` when no UI-relevant changes are detected +- permissions: read-only repo/PR access +- output: `add-comment` with pass/fail summary and artifact links +- fallback: `noop` when no UI changes detected ## QA Coverage Report Pattern -For pull-request QA coverage summaries (gaps, risks, and suggested test focus): +For PR QA coverage summaries (gaps, risks, suggested test focus): -- trigger: `pull_request` (optionally scoped with `paths:` for product areas under test) -- tools: `github` (`gh-proxy`) for changed files, PR metadata, labels, and linked checks -- permissions: `contents: read`, `pull-requests: read`; keep agent job read-only -- output: `add-comment` with a concise coverage matrix and explicit untested/high-risk areas -- fallback: use `noop` when the change is non-testable (for example docs-only PRs) +- trigger: `pull_request` (optionally scoped with `paths:`) +- tools: `github` (`gh-proxy`) for changed files, PR metadata, labels, checks +- permissions: `contents: read`, `pull-requests: read`; agent job read-only +- output: `add-comment` with coverage matrix and untested/high-risk areas +- fallback: `noop` for non-testable changes (e.g. docs-only) ## PM Stakeholder Digest Pattern -For recurring product/stakeholder digests (status, risks, and notable changes): +For recurring product/stakeholder digests: -- trigger: fuzzy `schedule` (for example `weekly on mondays`) +- trigger: fuzzy `schedule` (e.g. `weekly on mondays`) - tools: `github` (`gh-proxy`), optional `cache-memory` for period-over-period continuity -- permissions: read-only in the agent job -- output: `create-issue` by default; use `create-discussion` only when explicitly requested -- prompt: require audience-aware language (PM/stakeholder-friendly summary first, details second) +- permissions: read-only +- output: `create-issue` by default; `create-discussion` only when requested +- prompt: audience-aware language (summary first, details second) ## Database Migration Safety Pattern -For pull requests that add or modify database migration files: +For PRs adding/modifying migration files: -- trigger: `pull_request` with `paths:` scoped to migration directories (e.g. `db/migrate/**`, `migrations/**`, `*.sql`) -- permissions: `contents: read`, `pull-requests: read`; keep agent job read-only -- reads: changed migration file content via GitHub tools -- output: `add-comment` with a safety summary flagging risky operations; use `noop` when no concerns are detected -- prompt: suggest migration best practices in the agent prompt +- trigger: `pull_request` with `paths:` scoped to migration dirs (e.g. `db/migrate/**`, `migrations/**`, `*.sql`) +- permissions: `contents: read`, `pull-requests: read`; agent job read-only +- reads: changed migration content via GitHub tools +- output: `add-comment` flagging risky operations; `noop` when clean +- prompt: include migration best practices ## Cross-Repository Pattern -For cross-repository reads and writes: +For cross-repo reads and writes: -- enable the GitHub toolsets needed for external repos -- configure PAT or GitHub App auth in `safe-outputs:` when writing to another repo -- tell the agent to set `target-repo` explicitly for cross-repo outputs -- document the required token scopes in the workflow prompt or surrounding instructions +- enable GitHub toolsets needed for external repos +- configure PAT or GitHub App auth in `safe-outputs:` for cross-repo writes +- tell the agent to set `target-repo` explicitly +- document required token scopes in the prompt or instructions -Cross-repository workflows still inherit the single-job constraints in [workflow-constraints.md](workflow-constraints.md). +Cross-repo workflows inherit single-job constraints from [workflow-constraints.md](workflow-constraints.md).