Mine gh-aw for patterns; keep hand-rolled OpenCode workflows

Status: accepted

Our autonomous housekeeping loops (e.g. docs-drift-maintainer.yml) are hand-rolled GitHub Actions that install the OpenCode CLI and drive it against a prompt file (opencode run -- <prompt>). When planning the loop operating model (the loop-engineering operating model note) we considered adopting gh-aw (GitHub Agentic Workflows) as the authoring framework instead. We chose to borrow gh-aw's patterns — safe-outputs (PR-only, never direct push), least-privilege permissions: blocks, concurrency + timeout conventions — into the existing hand-rolled workflows, rather than adopt the framework itself.

Considered Options

• Adopt gh-aw as the standard. Workflows authored as markdown with frontmatter, compiled to *.lock.yml. Gains structure, MCP wiring, and GitHub-maintained guardrails. Rejected for now: it adds a gh extension dependency and a compile/lockfile step to bootstrap and doctor.sh, and would require rewriting working workflows — heavy for a template repo whose value is portability and low setup friction.
• Mine for patterns, keep hand-rolled (chosen). No new dependency, no compile step; the existing opencode run pattern stays, hardened with gh-aw's conventions.
• Defer entirely. Rejected — the safe-outputs and least-privilege patterns are worth applying now regardless of the framework question.

Consequences

• New loops follow the hand-rolled opencode run -- <prompt> shape, not gh-aw.
• We forgo gh-aw's built-in safe-outputs/MCP machinery and reimplement the parts we want by convention; if loop count grows and that reimplementation becomes a burden, revisit adopting the framework.
• A future reader will reasonably ask "why not the GitHub-maintained framework?" — this record is the answer.