diff --git a/agents-agentic-workflows.md b/agents-agentic-workflows.md new file mode 100644 index 000000000..6e4d27563 --- /dev/null +++ b/agents-agentic-workflows.md @@ -0,0 +1,27 @@ +# Squad agentic workflows bootstrap prompt + +```text +Bootstrap this repository with GitHub’s Squad agentic workflows from `github/squad`. Inspect the repo first, make only the necessary changes, validate them, and open a PR for human review if your tools permit it. Do not merge. + +Before editing: +- Check the default branch, working tree, authentication, and existing `.github/aw/`, `.github/workflows/`, and `.github/skills/` files. +- If an installation is already present, or files conflict and you can’t verify their ownership, stop and report the paths—don’t overwrite them. +- Verify `gh aw --version` is exactly `v0.91.5`. +- Obtain an approved, immutable 40-character lowercase `SQUAD_SHA` from published guidance or a maintainer. Never guess or use a moving branch. +- Check that Issues are enabled and Actions permissions match the documented Profile A (`default_workflow_permissions=read`, `can_approve_pull_request_reviews=false`). Don’t change settings without explicit authorization. + +Install on `chore/squad-gh-aw-bootstrap`, without overwriting existing work: +`gh aw add "github/squad/workflows@${SQUAD_SHA}"` + +Do not run generic `gh aw init` or create Squad files by hand. If the install generates `.github/skills/agentic-workflows/SKILL.md`, remove only that tool-generated file as the guide directs. Don’t create the optional secrets. If a first-install safe-update approval is required, approve only when its report contains exactly `SQUAD_GITHUB_APP_PRIVATE_KEY`, `SQUAD_GITHUB_TOKEN`, and `github/squad/.github/actions/squad-init`; otherwise stop. + +Run and require success: +1. `node .github/workflows/shared/squad-install-verifier.mjs --materialize-runtime` +2. `gh aw compile --strict` +3. `node .github/workflows/shared/squad-install-verifier.mjs --verify-install --source-revision "${SQUAD_SHA}" --strict-compile` +4. Stage only `.gitattributes`, `.github/aw/`, `.github/workflows/`, and `.github/skills/` (and only newly installed/materialized changed/owned paths within those surfaces; never stage whole directories containing unrelated files), review the staged diff, then run `node .github/workflows/shared/squad-install-verifier.mjs --verify-staged-install --stage-ownership --source-revision "${SQUAD_SHA}"`. + +Confirm eight workflows and their generated lockfiles are present, review the compiled artifacts, and allow only the two documented v0.91.5 warnings: `squad-review.md` (`pull_request_target`) and `squad.md` (combined `slash_command` and `bots` triggers). Stop on any other warning, error, unexpected deletion, or unrelated change. Stage only `.gitattributes`, `.github/aw/`, `.github/workflows/`, and `.github/skills/`; review the staged diff before committing. + +Open a PR against the default branch captured during inspection only after all checks pass. If you can’t verify a prerequisite, validate the install, push, or create the PR, report the exact blocker instead of claiming success. Report the PR URL and validation results if created; leave merge and post-merge activation to a human. +``` diff --git a/docs/src/content/docs/guide/gh-aw.md b/docs/src/content/docs/guide/gh-aw.md index b7b2443ae..ffc33c8de 100644 --- a/docs/src/content/docs/guide/gh-aw.md +++ b/docs/src/content/docs/guide/gh-aw.md @@ -111,13 +111,13 @@ SQUAD_SHA="<40-character-commit-sha>" exit 1 } -gh aw add "bradygaster/squad/workflows@${SQUAD_SHA}" +gh aw add "github/squad/workflows@${SQUAD_SHA}" rm -f .github/skills/agentic-workflows/SKILL.md # 5. On first install, review the safe-update report. Approve ONLY if it # contains exactly the two documented secrets (SQUAD_GITHUB_APP_PRIVATE_KEY, # SQUAD_GITHUB_TOKEN) and the one documented action -# (bradygaster/squad/.github/actions/squad-init) and nothing else. STOP and +# (github/squad/.github/actions/squad-init) and nothing else. STOP and # report any other entry instead of approving. gh aw compile --strict --approve # first install only, when the safe-update warning appears @@ -550,7 +550,7 @@ SQUAD_SHA="<40-character-commit-sha>" echo "STOP: SQUAD_SHA must be an explicit 40-character Squad commit SHA, not a branch name or shortened hash." >&2 exit 1 } -gh aw add "bradygaster/squad/workflows@${SQUAD_SHA}" +gh aw add "github/squad/workflows@${SQUAD_SHA}" rm -f .github/skills/agentic-workflows/SKILL.md ``` @@ -641,7 +641,7 @@ source/lock pairs, and one coherent 40-character revision. On a clean repository, `gh aw add` reports these expected safe-update changes: - Restricted secrets: `SQUAD_GITHUB_APP_PRIVATE_KEY` and `SQUAD_GITHUB_TOKEN` -- Action: `bradygaster/squad/.github/actions/squad-init` +- Action: `github/squad/.github/actions/squad-init` > **These are referenced names, not prerequisites.** `gh aw add` lists the secrets > the workflows *reference* so you can approve that surface — it is not asking you @@ -1614,7 +1614,7 @@ comment, ignore a missing proof, or dispatch partial bindings. #### Run the existing executable example The repository's -[activation finalization integration fixture](https://github.com/bradygaster/squad/blob/dev/test/gh-aw-activation-finalization.test.ts) +[activation finalization integration fixture](https://github.com/github/squad/blob/dev/test/gh-aw-activation-finalization.test.ts) is the executable producer/consumer example. In `continues after a later-phase pending-source recovery and validates the complete transitive reader chain`, it obtains proofs through the real workflow `verifyReconciliationRequest`, @@ -1623,7 +1623,7 @@ both the SDK selector and canonical checker. These helpers belong to `workflows/shared/squad-activation.mjs`; they are **not** public `/casting` verifier exports. The `trusted synchronous publication completion (source and strict-compiled jobs)` group also executes emitted job scripts and the pinned issue-creation API adapter. -The companion [selector contract tests](https://github.com/bradygaster/squad/blob/dev/test/agent-provenance.test.ts) +The companion [selector contract tests](https://github.com/github/squad/blob/dev/test/agent-provenance.test.ts) cover selection, no-record results and rejection cases; their hand-built evidence is test data, not production authorization. @@ -2507,7 +2507,7 @@ same native package as one unit: ```bash SQUAD_SHA="<40-character-commit-sha>" -gh aw add "bradygaster/squad/workflows@${SQUAD_SHA}" --force +gh aw add "github/squad/workflows@${SQUAD_SHA}" --force rm -f .github/skills/agentic-workflows/SKILL.md node .github/workflows/shared/squad-install-verifier.mjs --materialize-runtime gh aw compile --strict @@ -2526,8 +2526,8 @@ prints the exact safe recovery commands. The schema-v2 integrity manifest records two complete compiled lock digests per workflow: `lock_sha256` for a per-workflow source annotation and `package_lock_sha256` for a package-root annotation. gh-aw v0.91.5 emits -`bradygaster/squad/workflows@SHA` for direct package includes, but can emit -`bradygaster/squad/workflows/package/.md@SHA` when installing dispatched +`github/squad/workflows@SHA` for direct package includes, but can emit +`github/squad/workflows/package/.md@SHA` when installing dispatched dependencies. Fresh and forced installs can therefore contain different mixtures. The verifier selects one digest from the exact, ownership- and source-validated annotation; it never tries both until one passes. Compiled source comments, @@ -2610,7 +2610,7 @@ other refs. ## See also -- [Squad README](https://github.com/bradygaster/squad#readme) — project overview and local CLI usage -- [Workflow definition](https://github.com/bradygaster/squad/blob/dev/workflows/squad.md) — full slash command specification -- [Implementation worker](https://github.com/bradygaster/squad/blob/dev/workflows/squad-implement-worker.md) — isolated issue implementation workflow -- [Bootstrap component](https://github.com/bradygaster/squad/blob/dev/workflows/shared/squad.md) — activation and artifact lifecycle +- [Squad README](https://github.com/github/squad#readme) — project overview and local CLI usage +- [Workflow definition](https://github.com/github/squad/blob/dev/workflows/squad.md) — full slash command specification +- [Implementation worker](https://github.com/github/squad/blob/dev/workflows/squad-implement-worker.md) — isolated issue implementation workflow +- [Bootstrap component](https://github.com/github/squad/blob/dev/workflows/shared/squad.md) — activation and artifact lifecycle