feat: Phase 0 — install and initialize gh-aw in .github-private

.github/workflows/lint.yml

@@ -6,6 +6,7 @@ on:
       - 'scripts/**'
       - '.github/workflows/**'
       - 'tests/**'
+      - 'agents/**'
   workflow_dispatch:
 
 permissions:
@@ -34,3 +35,92 @@ jobs:
 
       - name: Run tests
         run: bats tests/fleet_report.bats
+
+  validate-agent-profiles:
+    runs-on: ubuntu-latest
+    timeout-minutes: 5
+    steps:
+      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd  # v6.0.2
+
+      - name: Install PyYAML
+        run: pip3 install --quiet pyyaml
+
+      - name: Validate agent profile frontmatter
+        run: |
+          set -euo pipefail
+          fail=0
+          for f in agents/*.md; do
+            [ -e "$f" ] || continue
+            name_from_file=$(basename "$f" .md)
+            if ! awk 'NR==1 && $0!="---"{exit 1} /^---/{n++; if(n==2) exit} END{exit (n<2)}' "$f"; then
+              echo "FAIL: $f — frontmatter missing or does not begin on line 1"
+              fail=1
+              continue
+            fi
+            frontmatter=$(awk 'BEGIN{found=0} /^---/{found++; if(found==2) exit; next} found==1{print}' "$f")
+            if ! printf '%s\n' "$frontmatter" | python3 -c "import sys, yaml; yaml.safe_load(sys.stdin)" 2>/dev/null; then
+              echo "FAIL: $f — invalid YAML in frontmatter"
+              fail=1
+              continue
+            fi
+            name_from_front=$(printf '%s\n' "$frontmatter" | grep '^name:' | sed 's/^name:[[:space:]]*//' | sed "s/^['\"]//;s/['\"]$//" | head -1)
+            if [ -z "$name_from_front" ]; then
+              echo "FAIL: $f — missing 'name' field in frontmatter"
+              fail=1
+            elif [ "$name_from_front" != "$name_from_file" ]; then
+              echo "FAIL: $f — name '$name_from_front' does not match filename '$name_from_file'"
+              fail=1
+            elif ! printf '%s\n' "$name_from_file" | grep -qE '^[a-z0-9]+(-[a-z0-9]+)*$'; then
+              echo "FAIL: $f — name '$name_from_file' is not kebab-case (only lowercase letters, digits, and hyphens)"
+              fail=1
+            fi
+            for field in description tools; do
+              if ! printf '%s\n' "$frontmatter" | grep -q "^${field}:"; then
+                echo "FAIL: $f — missing '${field}' field in frontmatter"
+                fail=1
+              fi
+            done
+            echo "OK: $f"
+          done
+          [ "$fail" -eq 0 ] || exit 1
+
+  gh-aw-compile:
+    runs-on: ubuntu-latest
+    timeout-minutes: 5
+    steps:
+      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd  # v6.0.2
+
+      - name: Check for agentic workflow files
+        id: check-aw-files
+        run: |
+          if find .github/workflows \( -name '*.md' -o -name '*.lock.yml' \) -print -quit 2>/dev/null | grep -q .; then
+            echo "found=true" >> "$GITHUB_OUTPUT"
+          else
+            echo "found=false" >> "$GITHUB_OUTPUT"
+            echo "No .github/workflows/*.md or *.lock.yml files found — skipping compile."
+          fi
+
+      - name: Install gh-aw
+        if: steps.check-aw-files.outputs.found == 'true'
+        env:
+          GH_TOKEN: ${{ github.token }}
+        run: gh extension install github/gh-aw --pin v0.74.4
+
+      - name: Compile agentic workflows
+        if: steps.check-aw-files.outputs.found == 'true'
+        env:
+          GH_TOKEN: ${{ github.token }}
+        run: gh aw compile --no-emit
+
+      - name: Detect orphaned lock files
+        if: steps.check-aw-files.outputs.found == 'true'
+        run: |
+          orphan=0
+          while IFS= read -r lock; do
+            md="${lock%.lock.yml}.md"
+            if [ ! -f "$md" ]; then
+              echo "FAIL: orphaned lock file $lock — no corresponding source $md"
+              orphan=1
+            fi
+          done < <(find .github/workflows -name '*.lock.yml')
+          [ "$orphan" -eq 0 ] || exit 1

AGENTS.md

@@ -26,6 +26,10 @@ This is the `.github-private` org infrastructure repo for `petry-projects`. It c
   To change behavior across all org repos (via the cross-repo reusable), edit `dev-lead-reusable.yml`.
 - All other workflow changes must use templates from
   [`standards/workflows/`](https://github.com/petry-projects/.github/tree/main/standards/workflows) verbatim.
+- **Exception:** The `gh-aw-compile` job in `lint.yml` is a documented repo-specific addition that gates
+  agentic workflow compilation. It is not covered by the org template and must not be removed by template
+  syncs. If the org template gains a `gh-aw-compile` equivalent, remove this exception and defer to the
+  template instead.
 
 ### Agent Profiles (`agents/*.md`)
 

agents/agentic-workflows.md

@@ -0,0 +1,44 @@
+---
+name: agentic-workflows
+description: >
+  Copilot custom agent for authoring, updating, debugging, and compiling
+  gh-aw agentic workflow markdown files in petry-projects/.github-private.
+model: claude
+tools: ["read", "search", "execute", "edit"]
+---
+
+You are the agentic workflow author for `petry-projects/.github-private`.
+
+## Engine
+
+This agent uses Claude via `ANTHROPIC_API_KEY` as the execution engine.
+
+## Responsibilities
+
+Use this agent to author, update, debug, and compile gh-aw agentic workflows:
+
+- Create new workflow markdown files in `.github/workflows/`
+- Update existing workflow definitions
+- Debug workflow compile or runtime errors
+- Run `gh aw compile --no-emit` to validate workflows without writing output
+- Write and update scenario specs in `tests/aw/<name>/README.md`
+
+## Available workflows
+
+- `issue-triage` — triages newly opened issues, applies labels, and routes to the right team
+- `ci-failure-analyst` — analyzes CI failures on PRs and posts a root-cause summary
+
+## Authoring rules
+
+1. New workflow files go in `.github/workflows/<name>.md`
+2. Write scenario specs in `tests/aw/<name>/README.md` before implementing
+3. Add at least one fixture payload under `tests/aw/<name>/fixtures/`
+4. After writing or editing, run `gh aw compile --no-emit` to validate
+5. Ensure the `gh-aw-compile` CI job passes before merging
+
+## Constraints
+
+- Never modify `.github/workflows/agent-shield.yml`
+- Follow org standards in `AGENTS.md` and `petry-projects/.github/AGENTS.md`
+- Use `GITHUB_TOKEN` for GitHub API calls; use `ANTHROPIC_API_KEY` for Claude invocations
+- Do not store or log secrets

tests/aw/README.md

@@ -0,0 +1,69 @@
+# Agentic Workflow Tests
+
+This directory contains scenario specs and smoke tests for `gh-aw` agentic workflows.
+
+## Test methodology
+
+Tests follow a three-level approach:
+
+1. **Compile validation (CI gate)** — `gh aw compile` runs on every PR that touches `.github/workflows/*.md`. A compile failure blocks merge. No runtime required.
+
+2. **Staged smoke tests (pre-merge)** — Run a workflow against a fixture payload without posting real GitHub API side-effects. Use `--dry-run` to validate the trigger request without dispatching a run:
+   ```
+   gh aw run <workflow-name> --dry-run -F payload=@tests/aw/<workflow-name>/fixtures/<fixture>.json
+   ```
+
+3. **Integration tests (manual / scheduled)** — Execute against a real GitHub event in a sandbox repo. Reserved for release-gate validation; not required on every PR.
+
+## Scenario spec format
+
+Write scenario specs **before** the workflow markdown. Each spec lives in `tests/aw/<workflow-name>/` as a plain markdown file:
+
+```
+tests/aw/<workflow-name>/
+  README.md          ← scenario specs (this pattern)
+  fixtures/          ← JSON payloads matching GitHub webhook schemas
+  smoke.sh           ← staged smoke test runner (optional)
+```
+
+A scenario spec block:
+
+```markdown
+### Scenario: <name>
+
+**Given** <precondition>
+**When** <event / trigger>
+**Then** <expected outcome>
+
+**Fixture:** `fixtures/<name>.json`
+```
+
+## Running compile validation locally
+
+```bash
+gh extension install github/gh-aw --pin v0.74.4
+gh aw compile
+```
+
+The compile step validates all `*.md` files in `.github/workflows/` against the gh-aw schema. It does not invoke Claude, but may query the GitHub API to resolve and pin action references; set `GH_TOKEN` before running if action resolution fails.
+
+## Running staged smoke tests
+
+```bash
+# Run a single workflow against a fixture payload (dry-run: no real GitHub API side-effects)
+gh aw run issue-triage --dry-run -F payload=@tests/aw/issue-triage/fixtures/new-bug.json
+
+# Run all smoke tests for a workflow
+bash tests/aw/issue-triage/smoke.sh
+```
+
+## Definition of Done checklist
+
+A workflow is ready to merge when:
+
+- [ ] Scenario specs written in `tests/aw/<name>/README.md` before implementation starts
+- [ ] `gh aw compile` passes with no errors
+- [ ] At least one fixture payload exists under `tests/aw/<name>/fixtures/`
+- [ ] Staged smoke test passes: `gh aw run <name>` exits 0
+- [ ] CI lint job (`gh-aw-compile`) is green on the PR
+- [ ] Workflow markdown reviewed by a second author or the pr-reviewer agent