build: Add gh-aw-version single source of truth + justfile wrapper

.github/aw/gh-aw-version

@@ -0,0 +1 @@
+v0.81.6

.github/workflows/ci.yml

@@ -22,7 +22,7 @@ jobs:
           GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
         run: |
           set -euo pipefail
-          gh extension install github/gh-aw --pin v0.81.6
+          gh extension install github/gh-aw --pin "$(cat .github/aw/gh-aw-version)"
 
       - name: Compile workflows
         env:
@@ -35,6 +35,6 @@ jobs:
         run: |
           set -euo pipefail
           git diff --exit-code -- .github/workflows/ || {
-            echo "::error::Compiled .lock.yml files are out of sync with their .md sources — run 'gh aw compile drafter review fix --approve' locally and commit the result."
+            echo "::error::Compiled .lock.yml files are out of sync with their .md sources — run 'just setup && just compile' locally and commit the result."
             exit 1
           }

.github/workflows/drafter.md

@@ -153,7 +153,11 @@ implementation.
    the repo has no such tooling, validate by inspection and, where
    reasonable, a small ad hoc check (e.g. `python3 -c '...'`) instead of
    assuming a command that may not exist.
-5. Once validation passes, open a pull request via the `create-pull-request`
+5. If your change edits any `.github/workflows/*.md` file, recompile the
+   lockfiles before opening the pull request: run `just setup && just
+   compile` (this recompiles *all* workflows, not just the one you touched —
+   every `.lock.yml` must stay in sync with its `.md` source).
+6. Once validation passes, open a pull request via the `create-pull-request`
    safe-output. The PR description should summarize the change and state
    how it was validated.
 

.github/workflows/fix.md

@@ -216,7 +216,12 @@ cause a duplicate re-trigger.
 6. Validate your change using whatever the repo actually provides (tests,
    a lint command, or a small ad hoc check) — do not assume tooling that
    may not exist.
-7. Push your fix as a new commit on the same branch via the
+7. If your change edits any `.github/workflows/*.md` file, recompile the
+   lockfiles: run `just setup && just compile` (this recompiles *all*
+   workflows, not just the one you touched — every `.lock.yml` must stay in
+   sync with its `.md` source). Include the resulting `.lock.yml` changes in
+   your commit.
+8. Push your fix as a new commit on the same branch via the
    `push-to-pull-request-branch` safe-output. Do not open a new PR.
 
 ## Constraints

README.md

@@ -136,7 +136,8 @@ A few things here are non-obvious and were hard-won getting this to actually wor
   and an upgrade once shipped a compiler whose AI-credits pricing table had fallen out of
   sync with Anthropic's current model line — agents started failing with errors like
   `<model> has no AI credits pricing`. The fix: pin the extension to a known-good version
-  (`gh extension install github/gh-aw --pin v0.81.6`, as `ci.yml` does) and set
+  (the pinned version lives in `.github/aw/gh-aw-version`, used by both `ci.yml` and `just
+  setup` — run `just setup` locally to install it) and set
   `engine.model` explicitly in each `.md` file's frontmatter to an exact dated model ID
   (e.g. `claude-sonnet-4-5-20250929`) instead of a floating alias, then recompile. If
   workflows that were working suddenly start failing with a pricing-lookup error, this is
@@ -313,9 +314,9 @@ now at least readable by the agent, but it was never the intended recovery path.
 
    (The App used for this specific demo instance is `bootc-bot`; the steps above are
    written generically so you can register your own App if adapting this repo.)
-3. Make sure `gh aw compile` runs cleanly against the `.md` files (see below) — run `gh
-   aw compile drafter review fix --approve` after any workflow edit. Pin the gh-aw
-   extension version when you do (see "Design notes and gotchas" above).
+3. Make sure the workflows compile cleanly from the `.md` files (see below) — run `just
+   setup && just compile` after any workflow edit (see "Design notes and gotchas" above
+   for why the extension version must stay pinned).
 4. If validating your project needs network access beyond gh-aw's engine defaults —
    e.g. `cargo test`/`cargo check` reaching a crate registry, or any other compiled
    language's package manager — add a `network:` block to `drafter.md`'s and `fix.md`'s
@@ -414,9 +415,11 @@ the same names.
 After editing any `.md` file, recompile with:
 
 ```
-gh aw compile drafter review fix --approve
+just setup && just compile
 ```
 
+(see the `justfile` at the repo root).
+
 ## Files
 
 The pipeline lives entirely in

justfile

@@ -0,0 +1,27 @@
+# gh-agentic-workflows development helpers.
+# Run `just --list` to see available recipes.
+
+gh_aw_version := `cat .github/aw/gh-aw-version`
+
+# Install (or re-pin) the gh-aw CLI extension to the version this repo requires.
+setup:
+    #!/usr/bin/env bash
+    set -euo pipefail
+    wanted="{{ gh_aw_version }}"
+    if gh extension list 2>/dev/null | grep -q 'github/gh-aw'; then
+        installed=$(gh aw version 2>&1 | awk '{print $NF}')
+        if [ "$installed" = "$wanted" ]; then
+            echo "gh-aw $wanted already installed."
+            exit 0
+        fi
+        echo "gh-aw installed at ${installed:-unknown}, re-pinning to $wanted..."
+        gh extension remove gh-aw
+    fi
+    gh extension install github/gh-aw --pin "$wanted"
+
+# Compile all gh-aw workflow .md sources to .lock.yml (run `just setup` first).
+compile:
+    gh aw compile drafter review fix --approve
+
+# Setup + compile in one step.
+all: setup compile