agent-runtime-framework/task-templates/workflow/spec-review-loop@1.yaml

name: spec-review-loop
version: 1
description: >
  Opus + MiniMax review a spec draft, Sonnet revises, Haiku judges clean/rework.
  Additive alternative to review-spec-arch-opus@1 / review-spec-arch-airouter@1 —
  those single-pass templates remain the default for the spec-draft state; a
  project opts into this loop instead via its own triggers.yaml, it does not
  replace them.
runtime: code-sonnet-tdd-repo
input:
  state: spec-draft
  tags_forbidden: [security-sensitive]
  required_artifacts: [spec_file]
output:
  state: spec-reviewed-arch
scope_budget:
  wall_clock_seconds_max: 7200 # must be >= iterations_max * per_iteration_seconds_max
                                # (5 * 1200 = 6000) plus slack
  iterations_max: 5
  per_iteration_seconds_max: 1200
nodes:
  - id: review-opus
    kind: agent
    role: spec-review  # M36 v0.6 (bug 69370eda fix): per-node role replaces
                       # the ungrounded top-level `runtime: review-loop-repo`.
                       # Harness resolution: (role, model) → composite.
    model: claude-opus-5
    runtime_env:
      AGENT_REPO_URL: "git@gitea.oreillyit.nz-ai-enablement:skynet/agent-runtimes-agents.git"
      AGENT_UPSTREAM_REPO_URL: "git@gitea.oreillyit.nz-ai-enablement:skynet/agent-runtimes.git"
      AGENT_UPSTREAM_BRANCH: "main"
      AGENT_BRANCH: "spec/${item.uuid}"
    prompt: |
      The agent-runtimes project repo is cloned at /workspace/project.
      Change to that directory before doing any work.

      Review the spec draft for the following concept.

      **Title**: ${item.title}

      **Original concept**:
      ${item.body}

      Steps:
      1. cd /workspace/project
      2. Find the spec file: ls spec/ and look for a file matching the concept title slug
      3. Read the spec file completely
      4. Review it against architectural best practices:
         - Are requirements testable and unambiguous?
         - Are there security implications not addressed?
         - Are interfaces and data contracts clearly defined?
         - Are edge cases and failure modes covered?
      5. Write your findings to /workspace/.agent-output/review-opus.md
  - id: review-minimax
    kind: agent
    role: spec-review
    model: minimax-m2
    runtime_env:
      AGENT_REPO_URL: "git@gitea.oreillyit.nz-ai-enablement:skynet/agent-runtimes-agents.git"
      AGENT_BRANCH: "spec/${item.uuid}"
    prompt: |
      The agent-runtimes project repo is cloned at /workspace/project.
      Change to that directory before doing any work.

      Review the spec draft for the following concept.

      **Title**: ${item.title}

      **Original concept**:
      ${item.body}

      Steps:
      1. cd /workspace/project
      2. Find the spec file: ls spec/ and look for a file matching the concept title slug
      3. Read the spec file completely
      4. Review it against architectural best practices:
         - Are requirements testable and unambiguous?
         - Are there security implications not addressed?
         - Are interfaces and data contracts clearly defined?
         - Are edge cases and failure modes covered?
      5. Write your findings to /workspace/.agent-output/review-minimax.md
  - id: improve-sonnet
    kind: agent
    role: spec-review
    tier: coding
    depends_on: [review-opus, review-minimax]
    runtime_env:
      AGENT_REPO_URL: "git@gitea.oreillyit.nz-ai-enablement:skynet/agent-runtimes-agents.git"
      AGENT_BRANCH: "spec/${item.uuid}"
    prompt: |
      The agent-runtimes project repo is cloned at /workspace/project.
      Change to that directory before doing any work.

      Revise the spec file for the following concept to address both reviews
      left on this branch.

      **Title**: ${item.title}

      Steps:
      1. cd /workspace/project
      2. Find the spec file: ls spec/ and look for a file matching the concept title slug
      3. Read /workspace/.agent-output/review-opus.md and
         /workspace/.agent-output/review-minimax.md
      4. Revise the spec file in place to address every finding from both reviews
      5. Commit the revised spec on this branch
  - id: judge-haiku
    kind: agent
    role: spec-review
    model: claude-haiku-4-5
    depends_on: [improve-sonnet]
    runtime_env:
      AGENT_REPO_URL: "git@gitea.oreillyit.nz-ai-enablement:skynet/agent-runtimes-agents.git"
      AGENT_BRANCH: "spec/${item.uuid}"
    prompt: |
      The agent-runtimes project repo is cloned at /workspace/project.
      Change to that directory before doing any work.

      Judge the revised spec file for the following concept.

      **Title**: ${item.title}

      Steps:
      1. cd /workspace/project
      2. Find the spec file: ls spec/ and look for a file matching the concept title slug
      3. Check whether every finding from /workspace/.agent-output/review-opus.md
         and /workspace/.agent-output/review-minimax.md has been addressed
      4. Write exactly CLEAN or NEEDS_REWORK (nothing else, no trailing
         punctuation or explanation) to /workspace/.workflow/verdict
  - id: judge-gate
    kind: script
    cmd: scripts/workflow/verdict-gate
    depends_on: [judge-haiku]
loop:
  body: [review-opus, review-minimax, improve-sonnet, judge-haiku, judge-gate]
  condition_node: judge-gate
  on_max_reached: escalate
escalation:
  contract_ambiguous: review-spec-opus
  loop_max_reached: review-spec-opus