docs: add release runbook to AGENTS.md

[itsmiso-ai]

Adds the full release cut process to AGENTS.md.

Covers:

• Tag and release creation workflow
• Release workflow via GitHub Actions (publishes Godot builds)
• Validation gates
• Version convention (plain semver, no v prefix)

[its-saffron]

AI Automated Review

Analysis engine: MiniMax@https://litellm.jory.dev/v1 (anthropic)

Recommendation: Approve (with one minor nit)

This is a clean, docs-only change that adds a Release Process runbook to AGENTS.md. It is internally consistent with the workflow files in .github/workflows/ and with the repository's tag history. The one nit worth flagging is the hard-coded --repo joryirving/windowstead flag in the gh release create example, which may be stale given the project now lives at misospace/windowstead.

Change-by-change findings

AGENTS.md (+48, -0)

New ### Release Process section — well-structured, covers tag creation, GitHub release via gh, and the workflow-dispatch alternative. Cross-references the actual release.yml workflow and its load-godot-toolchain composite action, which matches the repository's reality.

Version convention — "plain semver (e.g. 0.4.0, no v prefix)" is consistent with the historical tag list (0.0.14, 0.0.8 shown in git log).

Validation gates — references test.yml by name, which exists in .github/workflows/test.yml per the impact scan.

Minor redundancy — the line "Do not cut a release after every small change; discuss between releases when practical" now appears both in the "Current Collaboration Preferences" bullet above the new section and inside the new "Version convention" sub-section. This is acceptable reinforcement but could be deduplicated.

Nit: hard-coded upstream repo in gh example

The example command pins --repo joryirving/windowstead:

gh release create <version> \
  --repo joryirving/windowstead \
  --title "<version>" \
  --generate-notes

The PR is opened against misospace/windowstead, and recent merged PRs (e.g. #160, #157, #151, #150) all target misospace/* branches. Earlier history and tags (0.0.14, etc.) were under joryirving/windowstead, so this looks like a leftover from the original canonical instructions. Either drop the flag (when run from a checkout of the target repo) or update it to --repo misospace/windowstead. Not a blocker, but worth a one-line follow-up.

Sources

• PR diff: AGENTS.md lines 44–97 (post-change)
• .github/workflows/release.yml (confirmed exists, has description: Tag to build and publish assets for input — matches the workflow-dispatch step)
• .github/workflows/test.yml (confirmed exists, referenced in validation gates)
• .github/actions/load-godot-toolchain/action.yml (referenced indirectly by "Validates the Godot toolchain")
• Tag history: 0.0.14, 0.0.8 — confirms no-v-prefix convention
• Historical PR #12 fix: release workflow dispatch — confirms workflow-dispatch path is a supported entry point

Standards Compliance

The repository's AGENTS.md is the canonical home for project conventions; this PR extends it appropriately under "Current Collaboration Preferences". Content is consistent with the existing docs/toolchain-update.md description of release.yml and the composite action. No standards file is violated.

Linked Issue Fit

No linked issue is referenced. The PR is self-contained documentation work, so no acceptance criteria to verify against. Noted but not blocking.

Evidence Provider Findings

No evidence providers are configured. Nothing to evaluate.

Tool Harness Findings

Harness reported Planned requests: 0 and a planning-parse warning (Could not parse planning response as JSON). With zero planned requests, there is no actual harness content to weigh; the warning appears to be a parser hiccup, not a blocker on this docs-only change.

Unknowns or Needs Verification

• The intended canonical upstream (joryirving/windowstead vs misospace/windowstead) is not stated in the PR body. The example in the new doc still references the former, which is the only concrete inconsistency flagged above.
• Whether the project intends the workflow-dispatch path to be the primary release entry (vs. gh release create triggering on: release) is a stylistic choice; the runbook correctly documents both.

[its-saffron]

AI Automated Review

Analysis engine: MiniMax@https://litellm.jory.dev/v1 (anthropic)

Recommendation: Approve

This is a documentation-only PR that adds a useful Release Process runbook to AGENTS.md. The added content is internally consistent, references real workflow files that exist in the repo, and follows established tag conventions. No code, dependency, or runtime behavior is changed.

Change-by-change findings

AGENTS.md (+48 lines)

• Section placement: The new ### Release Process block is correctly placed inside the existing ## Current Collaboration Preferences section, sitting between the Avoid these regressions bullets and the existing bullet about detailed GitHub issues. Placement matches the intent of the section header.

• Workflow reference accuracy: The runbook references release.yml and test.yml. Both files exist in .github/workflows/ (confirmed via the repository impact scan for actions and from the repo history, e.g. 8764f3d refactor: extract toolchain config loading into composite action). The release workflow supports both release: types: [published] (implied by gh release create triggering it) and workflow_dispatch (confirmed by the description: Tag to build and publish assets for input on release.yml:10). Documenting both trigger paths is correct.

• Version convention (no v prefix): This matches the existing tag history. Confirmed tags in git log: 0.0.14, 0.0.8. The example 0.4.0 is consistent with this convention.

• Validation gates: References test.yml for the test suite and CI passing on main. Both checks are real and run in this repo (multiple test.yml references in the impact scan).

• Bash snippets: git pull --ff-only --tags, git tag, git push origin <version>, and gh release create ... --generate-notes are all standard, correct invocations. --generate-notes is a valid gh flag.

Minor observations (non-blocking)

• Slight redundancy: The sentence "Do not cut a release after every small change; discuss between releases when practical" already exists in the preceding Avoid these regressions list, and is repeated verbatim in the new Version convention subsection. The duplication is harmless and arguably intentional as a reminder within the runbook itself, but it could be tightened in a follow-up to keep the document DRY.
• Workflow dispatch step ordering: Step 4 ("Or use workflow dispatch") describes pushing the tag first and then running dispatch. That matches the workflow's Tag to build and publish assets for input, so this is accurate — but readers may want a one-line note that dispatch requires the tag to already exist. Not a blocker.

Sources

• PR diff and metadata (PR #165, chore/release-runbook → main)
• AGENTS.md (modified file)
• .github/workflows/release.yml (referenced by runbook; confirmed via repo impact scan)
• .github/workflows/test.yml (referenced by validation gates; confirmed via repo impact scan)
• Repository history confirming tag convention: 0.0.14, 0.0.8 (plain semver, no v prefix)

Standards Compliance

The standards file reflects the post-PR state of AGENTS.md and shows the new ### Release Process subsection aligned under Current Collaboration Preferences. The new content is consistent with:

• The existing Avoid these regressions list (the runbook formalizes the inverse: how to actually cut a release when appropriate).
• The existing ## Validation section, which already documents the test_runner.gd invocation; the new Validation gates subsection complements but does not duplicate that.
• Repository tag naming convention (plain semver, no prefix) as evidenced by existing tags.

No conventions in the standards file are violated. Markdown structure (heading levels, code fences, ordered lists, bold lead-ins) matches the surrounding document style.

Linked Issue Fit

No linked issue is referenced in the PR body, so there are no acceptance criteria or issue-intent checks to perform. The PR is a self-contained documentation improvement.

Evidence Provider Findings

No evidence providers were configured for this run. No blocker-level findings to evaluate.

Tool Harness Findings

The harness reported a planning parse warning ("Could not parse planning response as JSON") with 0 planned requests. This is a harness-internal warning, not a finding against the PR. For a documentation-only change with no executable steps, this is not material.

Unknowns or Needs Verification

• The exact on: triggers of release.yml were not fully shown in the impact scan snippet, but the presence of a description: field on an input strongly indicates workflow_dispatch is configured, and the runbook's claim that gh release create triggers the workflow is consistent with a standard on: release: types: [published] setup. If a stricter reviewer wants to be certain, opening release.yml and confirming both release: types: [published] and workflow_dispatch triggers exist would close the last gap. This is a low-priority verification, not a blocker.
• The example version 0.4.0 in the runbook is illustrative only; current tags in history are lower (0.0.14, 0.0.8). Not an error — examples in runbooks are conventionally forward-looking.