Add a spec-aware GitHub issue fix template

[jormundur00]

What changed

This adds a project-local github-issue-fix template that turns one GitHub issue into a spec-aware, reviewable Rhei workspace. The workflow creates an isolated issue worktree, captures the issue and repository rules, evaluates whether the issue is sufficiently specified and compatible with the project, implements and validates an accepted fix, runs focused review cycles, and optionally publishes a pull request.

The change includes:

• the typed template manifest and directory-workspace skeleton under .agents/rhei/templates/github-issue-fix/;
• a custom, documented 17-state machine with artifact contracts, a human gate, deterministic dispatch programs, bounded review/fix loops, and local-only blocked paths;
• a two-hour agent timeout setting for long implementation and review work;
• a pre-rendered publication_mode=no-pr smoke example under examples/github-issue-fix-example/;
• supporting agent-profile parsing changes so explicit codex[yolo] targets resolve correctly, plus updated workflow examples and changelog/spec documentation.

Why

A GitHub issue is not automatically safe to implement. It may be vague, conflict with repository goals, require a product decision, omit a validation path, or need project-specific grounding and citation rules. This template makes those checks explicit before code is changed and preserves durable artifacts for every decision.

It also separates implementation from review and publication. Requirements, specification/grund fit, implementation quality, and validation readiness are reviewed independently; their results are aggregated into a deterministic publication decision. Unsafe or underspecified work stays local instead of generating speculative code, issue comments, pushes, or PRs.

Template parts

Part	Purpose
template.yaml	Declares the template metadata and typed, validated input surface.
index.rhei.md	Renders the workspace overview, source coordinates, publication policy, and validation configuration.
tasks/01-issue-intake.md	Seeds the initial intake task. Intake later creates exactly one top-level follow-up task so its dependency on Task issue-intake remains valid.
states.yaml	Defines the complete custom workflow, transitions, artifact inputs/outputs, visit budgets, dispatch programs, agent targets, and state diagram.
settings.json	Gives agent work a default two-hour timeout.
README.md	Documents the inputs, paths, workflow, safety behavior, and canonical commands.
examples/github-issue-fix-example/	Provides a rendered, local-only workspace that can be validated and dry-run without publishing anything.

Workflow

1. Intake creates or reuses rhei/issue-<slug> in an isolated worktree, fetches the issue, discovers applicable AGENTS.md and grund configuration, and writes durable issue, repository-rule, worktree, spec-fit, and routing artifacts.
2. Adequacy/spec-fit analysis classifies the issue as compatible, compatible with required human review, underspecified, conflicting, missing information, or requiring an external owner.
3. Intake writes exactly one follow-up task starting in implementation, the human gate, or local GitHub handoff.
4. Accepted work is implemented in the issue worktree. A machine-readable status marker deterministically routes ready work to validation and blocked work to handoff.
5. Validation runs focused behavior checks and cheap targeted repository checks by default, always runs explicitly configured commands, and records broad skipped checks as disclosed gaps rather than silently ignoring them.
6. Four focused reviews assess requirements, spec/grund compliance, implementation quality, and validation readiness. Aggregate review converts them into one publication-readiness verdict.
7. Ready work must complete the configured number of clean review passes. Fixable blockers enter a bounded repair/revalidation loop; external blockers hand off; exhausted attempts produce a local blocked-publication record.
8. Publication honors no-pr, draft, or ready, uses a configured or inferred fork remote, applies only labels that already exist, and creates a user-facing PR body with exact validation evidence and the appropriate issue-closing reference.

States

State	How it works and what it does
issue-intake	Initial agent state. Creates/reuses the issue branch and worktree, snapshots the GitHub issue, discovers repository instructions and validation rules, evaluates adequacy and spec fit, writes five durable artifacts, and creates exactly one routed follow-up task. The intake task then completes.
human-review	Gating state. Autonomous execution stops while a human reads the spec-fit and routing artifacts, then explicitly chooses implement-fix, github-handoff, or cancelled.
github-handoff	Operations state for unclear, incompatible, externally blocked, or implementation-blocked issues. Writes a local handoff and optional suggested comment, but never posts comments, pushes, or opens/updates a PR.
implement-fix	Implementation agent works only in the isolated issue worktree, follows applicable repository and grund rules, keeps scope minimal, updates specs/docs/tests when required, and writes an exact Implementation status: ready or blocked marker with evidence.
implementation-dispatch	Deterministic program state. Parses the implementation marker: exit 0 routes ready work to validate-fix; exit 2 routes blocked work to github-handoff; malformed/missing status fails loudly.
validate-fix	Runs focused checks for changed behavior, targeted hygiene and grounding checks, and every configured validation command. It records exact commands, directories, results, output summaries, and gaps in both latest and per-cycle artifacts. Its visit budget is review_passes + review_fix_attempts.
requirements-review	Focused review of whether the diff actually solves the reported issue, acceptance criteria, expected outcome, and affected behavior without substituting a different or speculative problem. Produces a ready yes/no marker.
spec-review	Focused review of AGENTS.md, goals, non-goals, decisions, spec fit, grund declarations/citations, behavioral-test references, required docs/spec changes, and accidental internal citations in public docs. Produces a ready yes/no marker.
implementation-review	Focused engineering review of local patterns, API boundaries, scope, maintainability, error handling, edge cases, compatibility, test behavior, annotation placement, and unrelated cleanup. Produces a ready yes/no marker.
validation-review	Focused review of command selection, focused failures, skipped broad checks, likely CI risk, affected-area compile/test evidence, and whether the PR can honestly report validation. Distinguishes blocking failures from disclosure-only gaps.
aggregate-review	Combines the four focused reviews without inventing new review themes. Records blockers by category, disclosure gaps, fixability, external blockers, and Ready to publish: yes/no under policy that varies appropriately for draft versus ready PRs.
review-dispatch	Deterministic program state that parses aggregate markers. Ready work publishes once review_passes is met or loops to validation for another clean pass; fixable blockers route to address-review; external blockers route to handoff; exhausted attempts route to blocked publication.
address-review	Implementation agent fixes only the blocking findings from the latest focused cycle, preserves issue scope, and writes latest plus per-cycle repair artifacts before returning to validation. Its visit budget is review_fix_attempts.
publish-pr	Operations state. In no-pr, records local branch/commit status only. In draft or ready, resolves a writable fork, pushes, opens or updates the PR, applies only existing configured labels, includes a closing/reference keyword, and records the publication result. It refuses to override a not-ready aggregate verdict.
record-blocked-publication	Terminal-path operations state used after the repair budget is exhausted. Performs no GitHub writes and records the remaining blockers, validation evidence, branch/SHA, and required human action locally.
completed	Final success state for intake, handoff, publication, and blocked-publication tasks after their required artifacts are recorded.
cancelled	Final cancellation state reachable from any non-final state. Stops work while deliberately leaving branches, worktrees, and runtime artifacts available for inspection.

Configurability

Inputs	Controls
issue, repo, repo_checkout	Required issue identity, target repository, and local checkout used to create the worktree. issue is also positional.
work_subdir, worktree_root, base_branch, branch_prefix	Where implementation runs, where isolated worktrees live, and how the base/issue branches are selected.
require_human_spec_review	Whether otherwise compatible issues stop at the human gate before implementation. Defaults to true.
publication_mode	no-pr, draft, or ready; validated at instantiation. no-pr prohibits all external GitHub writes.
pr_push_remote, pr_head_owner, pr_labels	Explicit fork publication coordinates and labels. Empty remote/owner values are inferred; missing labels are skipped and never created.
validation_commands	Additional commands that must run. With no override, the workflow chooses focused issue-specific and cheap targeted repository checks.
implementation_target, operations_target, review_target, aggregate_review_target	Independently select the agents/models used for deep implementation, procedural operations, focused reviews, and aggregation. Defaults route stronger reasoning to implementation/aggregation, a review-oriented target to focused reviews, and a lighter target to operations.
review_passes, review_fix_attempts	Positive-integer budgets for required clean review cycles and additional blocker repair cycles.
plan_title, extra_context	Customize the rendered workspace title and append project-specific guidance.

Examples

Start with a completely local run:

rhei instantiate github-issue-fix 1234 \
  --set repo=owner/repo \
  --set repo_checkout=/path/to/repo \
  --set publication_mode=no-pr \
  --output .agents/scratchpad/issue-1234-local

rhei validate .agents/scratchpad/issue-1234-local
rhei run .agents/scratchpad/issue-1234-local --dry-run
rhei run .agents/scratchpad/issue-1234-local

Open a draft PR after one clean focused review cycle:

rhei instantiate github-issue-fix 1234 \
  --set repo=owner/repo \
  --set repo_checkout=/path/to/repo \
  --set base_branch=main \
  --set publication_mode=draft \
  --set pr_push_remote=my-fork \
  --set pr_head_owner=my-login \
  --output .agents/scratchpad/issue-1234

rhei run .agents/scratchpad/issue-1234

Require two clean review cycles and allow three repair cycles:

rhei instantiate github-issue-fix 1234 \
  --set repo=owner/repo \
  --set repo_checkout=/path/to/repo \
  --set publication_mode=ready \
  --set review_passes=2 \
  --set review_fix_attempts=3 \
  --output .agents/scratchpad/issue-1234-ready

Structured label and validation-command inputs can be supplied through a YAML values file:

pr_labels:
  - rhei
  - bug
validation_commands:
  - cargo test -p affected-crate focused_test
  - cargo clippy -p affected-crate -- -D warnings

rhei instantiate github-issue-fix 1234 \
  --values issue-fix-values.yaml \
  --set repo=owner/repo \
  --set repo_checkout=/path/to/repo \
  --output .agents/scratchpad/issue-1234

Validation

• grund check
• target/debug/rhei validate examples/github-issue-fix-example
• target/debug/rhei run examples/github-issue-fix-example --dry-run
• two additional rhei instantiate github-issue-fix ... --dry-run variants covering local/no-human-gate and ready-publication configuration
• cargo fmt --all -- --check
• cargo clippy --workspace --all-targets -- -D warnings -W clippy::all
• cargo build --workspace --all-targets
• cargo test --workspace --all-targets --no-fail-fast

[jormundur00]

Closing in favor of graalvm/native-build-tools#1006