@elalfner/relevo 0.0.0-stage → 0.3.0

package/templates/issue.md

@@ -0,0 +1,99 @@
+## Summary
+
+<!-- What this does, who it is for and why, in two or three sentences. -->
+
+## Outcome
+
+<!-- Optional. The observable result that shows the issue is done, in one or two sentences. -->
+
+## Scenarios
+
+- **WHEN** <the situation>
+- **THEN** <the result a person can observe>
+
+## Edge cases
+
+- <unusual input or state>: <what must happen>
+
+## Out of scope
+
+- <what is deliberately left out, with the issue that covers it when there is one>
+
+<!-- Optional sections: delete what does not apply. Headings stay in English; write the contents in the language of the repository. -->
+
+## Decisions
+
+<!-- Optional. One block per decision the agreement settled, with an id. Words that were rejected go under Discarded. -->
+
+### D1. <decision title>
+Decided: <what was decided>
+Why: <the reason>
+Discarded: <the alternative> (<why not>)
+
+## Constraints
+
+<!-- Optional. A concrete limit per line, with an id: security, performance, data, integration, business rule or accessibility. -->
+
+- C1: <a concrete limit>
+
+## Code pointers
+
+<!-- Optional. What the exploration found in the code; the builder checks it before trusting it. -->
+
+- `<path/to/file>`: <why it matters>
+
+## Verification
+
+<!-- Optional. What only a person can check on a device or in a browser. Test data by name, never secrets. -->
+
+- <what only a person can check, and with which data>
+
+## Assumptions
+
+<!-- Optional. What the person approved without being sure. -->
+
+- <an assumption>
+
+## Open questions
+
+<!-- Anything written here sends the issue back to its writer: answer it first, then delete the section. -->
+
+## Screens and behaviour
+
+<!-- Where it appears, what it looks like, when it shows or hides, animation and feedback, loading and error states, reference image. -->
+
+## Data contract
+
+<!-- For each endpoint or data source: method and path, how the caller authenticates, request fields, a realistic response with types, and which values may be null. -->
+
+## Design reference
+
+<!-- Optional. What the screen must look like: one bullet per reference, saying what must match (structure, spacing, typography, colour, states). A file of this repository, a picture pasted into this issue, a file of a linked repository written owner/repo:path, or example code in a fenced block. At most five. -->
+
+- `<path/to/reference>`: <what must match>
+
+## Documentation
+
+<!-- Optional. Only when the agreement settled terms or decisions to record; leave it out otherwise. Exact text, nothing but glossary entries and decision records. -->
+
+- Add these entries to `GLOSSARY.md`, under its existing heading, after the existing ones, exactly as written. They are vocabulary only; nothing else in that file changes.
+
+**<term>**:
+<definition>
+_Avoid_: <words to avoid>
+
+<!-- Optional. Only when relevo.yml has several platforms: the one platform this issue is for. A feature that needs two platforms is two issues linked with Depends-on. -->
+
+Platform: <name of a platform in relevo.yml>
+
+<!-- Optional. Only when the change needs a new dependency: the manifest and lock files it may touch. Without this line an unattended run refuses to change them. -->
+
+Allow-paths: <dependency files the change may touch, for example pubspec.yaml, pubspec.lock>
+
+<!-- Optional. Related issues of the same idea; it only informs. -->
+
+Related: #<number>
+
+<!-- Optional. #<number> is an issue of this repository; owner/repo#<number> is an issue of a repository listed in links of relevo.yml. -->
+
+Depends-on: #<number>

package/templates/relevo.yml

@@ -0,0 +1,59 @@
+# relevo.yml: one per repository. /relevo:init creates and updates this file.
+# Validate it with: node scripts/validate-config.mjs relevo.yml
+# Never put API keys or tokens here; they belong in the repository secret store.
+
+branches:
+  base: dev            # integration branch: feature pull requests target it
+  release: main        # promoted from base in a separate pull request
+
+tracker: github        # github (more later)
+git_provider: github   # github (more later)
+platforms:                         # what is built and where; one entry per stack (see docs/stacks.md)
+  app:
+    stack: flutter                 # the profile in stacks/<stack>.md of the plugin, or in .relevo/stacks/
+    path: .                        # folder of the repository where this platform lives
+    targets: [android]             # flutter: android | ios | web
+    # checks:                      # replace a verification command of the profile, for example:
+    #   test: fvm flutter test
+
+links: []              # repositories an issue may depend on (Depends-on: owner/repo#N); private ones need the secret RELEVO_LINKS_TOKEN
+
+team:
+  members: []          # GitHub usernames of the people who build and review
+  spec_writer: null    # writes the specs; never reviews or merges
+  approvers: []        # only used when review.mode is "roles"
+
+review:
+  mode: peer           # none (solo) | peer | roles
+  merger: approver     # author | approver: who runs /relevo:ship
+  autopilot: off       # off | precheck | verify: how much of the on-device review the agent may drive (the person always closes it)
+  allowed_origins: []  # web origins a driven review may visit besides localhost, e.g. https://staging.example.com
+
+limits:
+  built_unreviewed_per_person: 2   # built issues one person may have waiting
+  concurrent_agents: 3             # unattended runs at the same time
+  review_sla_hours: 8              # reminder, then escalation after the same time again
+  run_max_turns: 100               # per unattended run
+  building_alert_hours: 3          # hours without activity before an issue on `building` is reported as stuck
+  run_max_cost: 5                  # REQUIRED: US dollars per unattended run; choose your own
+
+qa:
+  retries: 1                       # developer attempts after QA rejects
+  rules_from: CLAUDE.md            # project rules QA reads at every run
+
+evidence:
+  policy: attach_to_pr             # attach_to_pr | local_only (use for sensitive data)
+
+digest:
+  issue: null                     # number of the issue where the daily digest is posted as a comment; subscribe your chat tool to it
+
+design:
+  images: false        # true: a picture pasted into an issue is downloaded and shown to the model (it may hold customer data); files in the repository are always available
+
+language: en                       # language of hand-off messages (en, es)
+trust: private-team                # private-team | public
+
+# Rename any label here; keys are fixed, names are yours.
+# labels:
+#   ready: relevo:ready
+#   built: relevo:built

package/templates/workflows/relevo-digest.yml

@@ -0,0 +1,54 @@
+# Relevo: posts one digest per working day, as a comment on the issue named by digest.issue in relevo.yml.
+# It lists who is waiting on what and the alerts, and posts nothing when nothing is waiting.
+# Subscribe your chat tool to that issue to receive it. Copy to .github/workflows/relevo-digest.yml.
+# Change the time below to suit your team (cron is in UTC).
+# The scripts come from the published package @elalfner/relevo, at the version pinned in RELEVO_VERSION.
+
+name: relevo-digest
+
+# The version of @elalfner/relevo whose scripts this workflow runs. The plugin's templates carry the version they
+# were released with, and `/relevo:init` reports this file as different when it is older; change it by hand to update.
+env:
+  RELEVO_VERSION: '0.3.0'
+
+on:
+  schedule:
+    - cron: '0 13 * * 1-5'
+  workflow_dispatch:
+
+concurrency:
+  group: relevo-digest
+  cancel-in-progress: false
+
+permissions:
+  contents: read
+  issues: write
+  pull-requests: read
+
+jobs:
+  digest:
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 22
+
+      - name: Install the Relevo scripts
+        # The published package at the version pinned above; no repository is cloned for them. A package without the
+        # script this job runs stops the run here, before anything is changed.
+        run: |
+          mkdir -p .relevo-plugin
+          npm pack "@elalfner/relevo@$RELEVO_VERSION" --silent --pack-destination "$RUNNER_TEMP" > /dev/null
+          tar -xzf "$RUNNER_TEMP"/elalfner-relevo-*.tgz --strip-components=1 -C .relevo-plugin
+          for f in scripts/digest.mjs; do
+            [ -f ".relevo-plugin/$f" ] || { echo "::error::The Relevo package $RELEVO_VERSION lacks $f"; exit 1; }
+          done
+
+      - name: Post the digest
+        env:
+          GH_TOKEN: ${{ github.token }}
+          GITHUB_REPOSITORY: ${{ github.repository }}
+        run: node .relevo-plugin/scripts/digest.mjs --repo "$GITHUB_REPOSITORY"

package/templates/workflows/relevo-go.yml

@@ -0,0 +1,263 @@
+# Relevo: builds an issue when someone with write access labels it `relevo:ready`.
+# Copy to .github/workflows/relevo-go.yml. If you renamed the ready label in relevo.yml, change it below too.
+#
+# Two jobs. `decide` is light (Node and the plugin's scripts, about half a minute): it runs the gates, claims the
+# issue and comments when there is nothing to build. Only when the decision is `start` does `build` install the
+# toolchain and run the agent, so an issue that is blocked, queued or incomplete never pays for that setup.
+#
+# Needs: a model credential secret (ANTHROPIC_API_KEY or CLAUDE_CODE_OAUTH_TOKEN), and a relevo.yml at the
+# repository root.
+# Keep the numbers in claude_args in line with limits.run_max_turns and limits.run_max_cost.
+# Where the numbers disagree the lower one wins, so this file can only make a run cheaper than relevo.yml says.
+
+name: relevo-go
+
+# The version of @elalfner/relevo whose scripts this workflow runs. The plugin's templates carry the version they
+# were released with, and `/relevo:init` reports this file as different when it is older; change it by hand to update.
+env:
+  RELEVO_VERSION: '0.3.0'
+
+on:
+  issues:
+    types: [labeled]
+  # The queue workflow (relevo-queue.yml) starts waiting issues through this trigger.
+  workflow_dispatch:
+    inputs:
+      issue:
+        description: Issue number to build
+        required: true
+
+# One run per issue: a repeated label event waits for the first run and then finds the issue already building.
+concurrency:
+  group: relevo-go-${{ github.event.issue.number || inputs.issue }}
+  cancel-in-progress: false
+
+permissions:
+  contents: read
+  issues: write
+  pull-requests: read
+
+jobs:
+  decide:
+    # The repository variable RELEVO_CLOUD_GO set to `off` pauses the cloud: a ready label starts nothing and the issue
+    # stays ready for a local run (/relevo:go <n>). It is read at run time, so changing it needs no pull request.
+    if: vars.RELEVO_CLOUD_GO != 'off' && (github.event_name == 'workflow_dispatch' || (github.event.label.name == 'relevo:ready' && github.event.sender.type == 'User'))
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    outputs:
+      action: ${{ steps.plan.outputs.action }}
+      decision_b64: ${{ steps.plan.outputs.decision_b64 }}
+      # The platform the issue is for (empty unless the decision is `start`): the build job installs only its toolchain.
+      platform: ${{ steps.plan.outputs.platform }}
+      stack: ${{ steps.plan.outputs.stack }}
+      path: ${{ steps.plan.outputs.path }}
+    steps:
+      # The repository holds relevo.yml; the plugin holds the scripts that apply the gates.
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 22
+
+      - name: Install the Relevo scripts
+        # The published package at the version pinned above; no repository is cloned for them. A package without the
+        # script this job runs stops the run here, before anything is changed.
+        run: |
+          mkdir -p .relevo-plugin
+          npm pack "@elalfner/relevo@$RELEVO_VERSION" --silent --pack-destination "$RUNNER_TEMP" > /dev/null
+          tar -xzf "$RUNNER_TEMP"/elalfner-relevo-*.tgz --strip-components=1 -C .relevo-plugin
+          for f in scripts/go-plan.mjs; do
+            [ -f ".relevo-plugin/$f" ] || { echo "::error::The Relevo package $RELEVO_VERSION lacks $f"; exit 1; }
+          done
+
+      # Applies the gates and, when the decision is `start`, claims the issue (relevo:building). Any other decision
+      # (needs-spec, blocked, queued, denied, no milestone, no assignee) is applied here with its comment.
+      - name: Gates and claim
+        id: plan
+        env:
+          GH_TOKEN: ${{ github.token }}
+          # Only needed when `links` in relevo.yml lists a private repository: a read-only token (issues and pull
+          # requests) stored as the secret RELEVO_LINKS_TOKEN. It is used only to read the issues the dependencies
+          # name, never to write, and an empty value is fine (public repositories are read without it).
+          GH_LINKS_TOKEN: ${{ secrets.RELEVO_LINKS_TOKEN }}
+          GITHUB_REPOSITORY: ${{ github.repository }}
+          ISSUE: ${{ github.event.issue.number || inputs.issue }}
+          # Without a model credential the cloud cannot build: the issue stays ready and a comment says to run it locally.
+          HAS_CREDENTIAL: ${{ secrets.ANTHROPIC_API_KEY != '' || secrets.CLAUDE_CODE_OAUTH_TOKEN != '' }}
+        run: node .relevo-plugin/scripts/go-plan.mjs --repo "$GITHUB_REPOSITORY" --only "$ISSUE" --apply --claim --credential "$HAS_CREDENTIAL" --github-output "$GITHUB_OUTPUT"
+
+      # See the same step in `build`. A failure before the issue is claimed (the plugin cannot be cloned, the
+      # scripts fail) leaves it ready or queued with nobody told.
+      - name: Report a run that ended without an outcome
+        if: always()
+        env:
+          GH_TOKEN: ${{ github.token }}
+          ISSUE: ${{ github.event.issue.number || inputs.issue }}
+          JOB_STATUS: ${{ job.status }}
+          RUN_URL: ${{ github.server_url }}/${{ github.repository }}/actions/runs/${{ github.run_id }}
+        run: |
+          labels=$(gh issue view "$ISSUE" --json labels --jq '.labels[].name')
+          if [ "$JOB_STATUS" = "success" ]; then
+            exit 0
+          fi
+          if ! printf '%s\n' "$labels" | grep -qxE 'relevo:(ready|queued|building)'; then
+            exit 0
+          fi
+          assignee=$(gh issue view "$ISSUE" --json assignees --jq '.assignees[0].login // empty')
+          gh issue edit "$ISSUE" --remove-label relevo:ready --remove-label relevo:queued --remove-label relevo:building --add-label relevo:qa-failed
+          gh issue comment "$ISSUE" --body "${assignee:+@$assignee }The run failed before it could decide what to do (job status: $JOB_STATUS), so nothing was built. Read the log to see why: $RUN_URL. When the cause is fixed, remove \`relevo:qa-failed\` and apply \`relevo:ready\` again."
+
+  build:
+    needs: decide
+    if: needs.decide.outputs.action == 'start'
+    runs-on: ubuntu-latest
+    timeout-minutes: 60
+    permissions:
+      contents: write
+      issues: write
+      pull-requests: read
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 22
+
+      # The agent runs the project's own checks (QA runs them), so install here the toolchain of the stack of the
+      # platform of the issue. The `decide` job tells which one (`needs.decide.outputs.stack`) and where it lives
+      # (`needs.decide.outputs.path`), so an issue for the front does not install the back's tools. Uncomment the
+      # examples your stacks need and adjust versions and caching; the names are the `stack` of relevo.yml:
+      #   - if: needs.decide.outputs.stack == 'flutter'
+      #     uses: subosito/flutter-action@v2
+      #     with:
+      #       channel: stable
+      #       cache: true
+      #   - if: needs.decide.outputs.stack == 'vue'
+      #     uses: actions/setup-node@v4
+      #     with:
+      #       node-version: 22
+      #       cache: npm
+      #       cache-dependency-path: ${{ needs.decide.outputs.path }}/package-lock.json
+      #   - if: needs.decide.outputs.stack == 'laravel'
+      #     uses: shivammathur/setup-php@v2
+      #     with:
+      #       php-version: '8.3'
+      #       tools: composer
+      # Install the dependencies of the platform from its folder, for example:
+      #   - if: needs.decide.outputs.stack == 'vue'
+      #     working-directory: ${{ needs.decide.outputs.path }}
+      #     run: npm ci --ignore-scripts
+      # Install dependencies without package scripts where the tool offers it, so a dependency cannot run code
+      # while it is installed: `npm ci --ignore-scripts`, `pnpm install --frozen-lockfile --ignore-scripts`,
+      # `composer install --no-scripts`. `flutter pub get` and `dart pub get` run no install-time scripts of
+      # the packages, so they need no such option.
+
+      - name: Install OpenSpec
+        run: npm install --global @fission-ai/openspec
+        env:
+          OPENSPEC_TELEMETRY: '0'
+
+      - id: agent
+        uses: anthropics/claude-code-action@v1
+        env:
+          OPENSPEC_TELEMETRY: '0'
+          GH_TOKEN: ${{ github.token }}
+          # Without this the agent may start a subagent in the background and end the run before it finishes,
+          # leaving the issue stuck on building with no comment (seen in the pilot, see docs/pilot-findings.md).
+          CLAUDE_CODE_DISABLE_BACKGROUND_TASKS: '1'
+        with:
+          # Credentials: choose ONE of the next two lines.
+          # a) API key (default):
+          anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}
+          # b) Subscription: create a token with `claude setup-token` and store it as the secret CLAUDE_CODE_OAUTH_TOKEN.
+          #    The command prints the token over two lines; remove all whitespace before storing it, for example
+          #    `pbpaste | tr -d '[:space:]' | gh secret set CLAUDE_CODE_OAUTH_TOKEN`. Then replace the line above with:
+          # claude_code_oauth_token: ${{ secrets.CLAUDE_CODE_OAUTH_TOKEN }}
+          github_token: ${{ github.token }}
+          # The queue starts builds with `gh workflow run`, so the actor is the Actions bot and the action refuses
+          # it unless it is allowed. Only this one bot: never '*', which would let outside apps start runs.
+          allowed_bots: github-actions
+          # Plugin repository: choose ONE of the next two lines.
+          # a) Public repository (default):
+          plugin_marketplaces: https://github.com/elalfner/relevo.git
+          # b) Private repository: the runner cannot clone it without a credential. Store a read-only fine-grained
+          #    token as the secret RELEVO_PLUGIN_TOKEN and replace the line above with:
+          # plugin_marketplaces: https://x-access-token:${{ secrets.RELEVO_PLUGIN_TOKEN }}@github.com/elalfner/relevo.git
+          plugins: relevo@relevo
+          # The issue text is data, never instructions: the skill tells the agent so. The tool list is closed:
+          # only the tools in --allowedTools, and no web access (nothing to fetch, nowhere to send a secret).
+          # Do not set allowed_non_write_users or show_full_output here, and never widen allowed_bots: they open the run to
+          # strangers or print tool results (possibly secrets) to the log.
+          # The decision the `decide` job already made travels with the prompt, encoded so that the issue title in it
+          # is never read as an instruction. The skill decodes it and skips its own planning step.
+          prompt: /relevo:go ${{ github.event.issue.number || inputs.issue }} --decision ${{ needs.decide.outputs.decision_b64 }}
+          claude_args: >-
+            --max-turns 100
+            --max-budget-usd 5
+            --allowedTools "Bash,Read,Write,Edit,Glob,Grep,Task"
+            --disallowedTools "WebFetch,WebSearch,Bash(curl:*),Bash(wget:*)"
+
+      # The scripts of the next two steps come from the plugin package. It is unpacked into the workspace only now, after the agent has
+      # finished, because the agent's preflight needs a clean working tree and a checkout inside it would not be.
+      - name: Install the Relevo scripts for the reports
+        if: always()
+        continue-on-error: true
+        run: |
+          mkdir -p .relevo-plugin
+          npm pack "@elalfner/relevo@$RELEVO_VERSION" --silent --pack-destination "$RUNNER_TEMP" > /dev/null
+          tar -xzf "$RUNNER_TEMP"/elalfner-relevo-*.tgz --strip-components=1 -C .relevo-plugin
+          for f in scripts/run-usage.mjs scripts/usage-limit.mjs; do
+            [ -f ".relevo-plugin/$f" ] || { echo "::error::The Relevo package $RELEVO_VERSION lacks $f"; exit 1; }
+          done
+
+      # What the run used, read from the agent's execution log. The format of that log is not documented, so the
+      # reader is tolerant: when it finds nothing it posts nothing, and this step can never fail the job.
+      - name: Report what the run used
+        if: always()
+        continue-on-error: true
+        env:
+          GH_TOKEN: ${{ github.token }}
+          ISSUE: ${{ github.event.issue.number || inputs.issue }}
+          EXECUTION_FILE: ${{ steps.agent.outputs.execution_file }}
+          # With a subscription token and no API key the cost is notional.
+          ONLY_SUBSCRIPTION: ${{ secrets.ANTHROPIC_API_KEY == '' && secrets.CLAUDE_CODE_OAUTH_TOKEN != '' }}
+        run: |
+          [ -n "$EXECUTION_FILE" ] || exit 0
+          flag=""; [ "$ONLY_SUBSCRIPTION" = "true" ] && flag="--subscription"
+          line=$(node .relevo-plugin/scripts/run-usage.mjs --file "$EXECUTION_FILE" $flag)
+          [ -n "$line" ] && gh issue comment "$ISSUE" --body "$line"
+          exit 0
+
+      # A run can end without telling anyone: the plugin cannot be cloned, the login fails, preflight stops, the
+      # run reached --max-turns or --max-budget-usd (the runner cuts it; the agent cannot see those counters and
+      # does not stop itself), or the agent ends its session early (all seen in the pilot, see docs/pilot-findings.md). If the issue is still
+      # ready or building after the agent step, no outcome was recorded, so say so on the issue.
+      # If you renamed the labels in relevo.yml, change the names below too.
+      - name: Report a run that ended without an outcome
+        if: always()
+        env:
+          GH_TOKEN: ${{ github.token }}
+          ISSUE: ${{ github.event.issue.number || inputs.issue }}
+          JOB_STATUS: ${{ job.status }}
+          RUN_URL: ${{ github.server_url }}/${{ github.repository }}/actions/runs/${{ github.run_id }}
+          EXECUTION_FILE: ${{ steps.agent.outputs.execution_file }}
+        run: |
+          labels=$(gh issue view "$ISSUE" --json labels --jq '.labels[].name')
+          # A run the queue dispatched that fails before it claims the issue leaves it `queued`: report that
+          # too, or the queue would dispatch it again every 30 minutes. A run that ends normally leaves it queued
+          # on purpose (no capacity), so that case is only reported when the job failed.
+          if ! printf '%s\n' "$labels" | grep -qxE 'relevo:(ready|building)'; then
+            if ! { [ "$JOB_STATUS" != "success" ] && printf '%s\n' "$labels" | grep -qx 'relevo:queued'; }; then
+              exit 0
+            fi
+          fi
+          assignee=$(gh issue view "$ISSUE" --json assignees --jq '.assignees[0].login // empty')
+          gh issue edit "$ISSUE" --remove-label relevo:ready --remove-label relevo:queued --remove-label relevo:building --add-label relevo:qa-failed
+          # A usage limit, a quota or an empty credit balance is not a failure of the code: say so.
+          if [ -n "$EXECUTION_FILE" ] && node .relevo-plugin/scripts/usage-limit.mjs --file "$EXECUTION_FILE"; then
+            gh issue comment "$ISSUE" --body "${assignee:+@$assignee }The run stopped because the usage limit (or the credit) of the model account was reached, so nothing was built. Nothing is wrong with the code. Label the issue \`relevo:ready\` again later, after removing \`relevo:qa-failed\`: $RUN_URL"
+          else
+            gh issue comment "$ISSUE" --body "${assignee:+@$assignee }The run ended without a result (job status: $JOB_STATUS), so nothing was built or reported. Read the log to see why: $RUN_URL. When the cause is fixed, remove \`relevo:qa-failed\` and apply \`relevo:ready\` again."
+          fi

package/templates/workflows/relevo-queue.yml

@@ -0,0 +1,72 @@
+# Relevo: re-evaluates the queue and starts the issues that are now eligible.
+# Copy to .github/workflows/relevo-queue.yml next to relevo-go.yml (it starts builds through that workflow).
+#
+# Runs when an issue is closed or its labels change (a merge, a built issue leaving that state) and on a
+# schedule, so a lost event does not stall the queue. Needs a relevo.yml at the repository root.
+# The scripts come from the published package @elalfner/relevo, at the version pinned in RELEVO_VERSION.
+
+name: relevo-queue
+
+# The version of @elalfner/relevo whose scripts this workflow runs. The plugin's templates carry the version they
+# were released with, and `/relevo:init` reports this file as different when it is older; change it by hand to update.
+env:
+  RELEVO_VERSION: '0.3.0'
+
+on:
+  issues:
+    types: [closed, labeled, unlabeled]
+  schedule:
+    - cron: '*/30 * * * *'
+  workflow_dispatch:
+
+# One evaluation at a time; a second one waits and then sees the first one's labels.
+concurrency:
+  group: relevo-queue
+  cancel-in-progress: false
+
+permissions:
+  contents: read
+  issues: write
+  pull-requests: read
+  actions: write
+
+jobs:
+  requeue:
+    # Paused together with the go workflow by the repository variable RELEVO_CLOUD_GO set to `off`.
+    if: vars.RELEVO_CLOUD_GO != 'off'
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 22
+
+      - name: Install the Relevo scripts
+        # The published package at the version pinned above; no repository is cloned for them. A package without the
+        # script this job runs stops the run here, before anything is changed.
+        run: |
+          mkdir -p .relevo-plugin
+          npm pack "@elalfner/relevo@$RELEVO_VERSION" --silent --pack-destination "$RUNNER_TEMP" > /dev/null
+          tar -xzf "$RUNNER_TEMP"/elalfner-relevo-*.tgz --strip-components=1 -C .relevo-plugin
+          for f in scripts/requeue.mjs; do
+            [ -f ".relevo-plugin/$f" ] || { echo "::error::The Relevo package $RELEVO_VERSION lacks $f"; exit 1; }
+          done
+
+      - name: Evaluate the queue and dispatch builds
+        env:
+          GH_TOKEN: ${{ github.token }}
+          # Only needed when `links` in relevo.yml lists a private repository: a read-only token (issues and pull
+          # requests) stored as the secret RELEVO_LINKS_TOKEN. It is used only to read the issues the dependencies
+          # name, never to write, and an empty value is fine (public repositories are read without it).
+          GH_LINKS_TOKEN: ${{ secrets.RELEVO_LINKS_TOKEN }}
+          GITHUB_REPOSITORY: ${{ github.repository }}
+          # Without a model credential nothing is dispatched.
+          HAS_CREDENTIAL: ${{ secrets.ANTHROPIC_API_KEY != '' || secrets.CLAUDE_CODE_OAUTH_TOKEN != '' }}
+        run: |
+          result=$(node .relevo-plugin/scripts/requeue.mjs --repo "$GITHUB_REPOSITORY" --credential "$HAS_CREDENTIAL")
+          echo "$result"
+          for issue in $(echo "$result" | node -e 'JSON.parse(require("fs").readFileSync(0,"utf8")).start.forEach(n=>console.log(n))'); do
+            gh workflow run relevo-go.yml --repo "$GITHUB_REPOSITORY" -f issue="$issue"
+          done

package/templates/workflows/relevo-review.yml

@@ -0,0 +1,60 @@
+# Relevo: keeps the issue label in step with its pull request.
+# A review that requests changes sets `relevo:changes-requested` and mentions the author; a new push returns the
+# issue to `relevo:pr-open`; an approval mentions the person who will run /relevo:ship.
+# Copy to .github/workflows/relevo-review.yml. Needs a relevo.yml at the repository root.
+# Pull requests from forks are skipped explicitly (and would only get a read-only token anyway).
+# The scripts come from the published package @elalfner/relevo, at the version pinned in RELEVO_VERSION.
+
+name: relevo-review
+
+# The version of @elalfner/relevo whose scripts this workflow runs. The plugin's templates carry the version they
+# were released with, and `/relevo:init` reports this file as different when it is older; change it by hand to update.
+env:
+  RELEVO_VERSION: '0.3.0'
+
+on:
+  pull_request_review:
+    types: [submitted]
+  pull_request:
+    types: [synchronize]
+
+concurrency:
+  group: relevo-review-${{ github.event.pull_request.number }}
+  cancel-in-progress: false
+
+permissions:
+  contents: read
+  issues: write
+  pull-requests: read
+
+jobs:
+  review:
+    if: startsWith(github.event.pull_request.head.ref, 'feature/') && github.event.pull_request.head.repo.full_name == github.repository
+    runs-on: ubuntu-latest
+    timeout-minutes: 5
+    steps:
+      # The base branch holds relevo.yml; the pull request code is never checked out or run.
+      - uses: actions/checkout@v4
+        with:
+          ref: ${{ github.event.pull_request.base.ref }}
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 22
+
+      - name: Install the Relevo scripts
+        # The published package at the version pinned above; no repository is cloned for them. A package without the
+        # script this job runs stops the run here, before anything is changed.
+        run: |
+          mkdir -p .relevo-plugin
+          npm pack "@elalfner/relevo@$RELEVO_VERSION" --silent --pack-destination "$RUNNER_TEMP" > /dev/null
+          tar -xzf "$RUNNER_TEMP"/elalfner-relevo-*.tgz --strip-components=1 -C .relevo-plugin
+          for f in scripts/review-event.mjs; do
+            [ -f ".relevo-plugin/$f" ] || { echo "::error::The Relevo package $RELEVO_VERSION lacks $f"; exit 1; }
+          done
+
+      - name: Update the label
+        env:
+          GH_TOKEN: ${{ github.token }}
+          GITHUB_REPOSITORY: ${{ github.repository }}
+        run: node .relevo-plugin/scripts/review-event.mjs --repo "$GITHUB_REPOSITORY"

package/templates/workflows/relevo-sla.yml

@@ -0,0 +1,53 @@
+# Relevo: reminds the reviewer when a pull request waits longer than limits.review_sla_hours, and escalates
+# to the spec writer (adding the needs-reviewer label) after the same time again.
+# Copy to .github/workflows/relevo-sla.yml. Needs a relevo.yml at the repository root.
+# The scripts come from the published package @elalfner/relevo, at the version pinned in RELEVO_VERSION.
+
+name: relevo-sla
+
+# The version of @elalfner/relevo whose scripts this workflow runs. The plugin's templates carry the version they
+# were released with, and `/relevo:init` reports this file as different when it is older; change it by hand to update.
+env:
+  RELEVO_VERSION: '0.3.0'
+
+on:
+  schedule:
+    - cron: '17 * * * *'
+  workflow_dispatch:
+
+concurrency:
+  group: relevo-sla
+  cancel-in-progress: false
+
+permissions:
+  contents: read
+  issues: write
+  pull-requests: write
+
+jobs:
+  sla:
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 22
+
+      - name: Install the Relevo scripts
+        # The published package at the version pinned above; no repository is cloned for them. A package without the
+        # script this job runs stops the run here, before anything is changed.
+        run: |
+          mkdir -p .relevo-plugin
+          npm pack "@elalfner/relevo@$RELEVO_VERSION" --silent --pack-destination "$RUNNER_TEMP" > /dev/null
+          tar -xzf "$RUNNER_TEMP"/elalfner-relevo-*.tgz --strip-components=1 -C .relevo-plugin
+          for f in scripts/review-sla.mjs; do
+            [ -f ".relevo-plugin/$f" ] || { echo "::error::The Relevo package $RELEVO_VERSION lacks $f"; exit 1; }
+          done
+
+      - name: Remind and escalate
+        env:
+          GH_TOKEN: ${{ github.token }}
+          GITHUB_REPOSITORY: ${{ github.repository }}
+        run: node .relevo-plugin/scripts/review-sla.mjs --repo "$GITHUB_REPOSITORY"