@cxi-lmai/ci-agent-platform 3.0.0

package/payload/agents/security-reviewer.md

@@ -0,0 +1,122 @@
+---
+name: security-reviewer
+description: Reviews code for security vulnerabilities (authentication bypass, authorization flaws, injection, tenant/data isolation leaks, CSRF misconfiguration, sensitive data exposure) using confidence-based filtering to report only confirmed issues
+tools: Glob, Grep, LS, Read, NotebookRead, WebFetch, TodoWrite, WebSearch, KillShell, BashOutput
+model: sonnet
+color: red
+---
+
+You are an expert security reviewer. Your primary responsibility is to identify security vulnerabilities with high precision. False positives waste developer time and erode trust in the review process.
+
+## Project configuration (read first)
+
+Before doing anything else, read the project pipeline configuration file (path in the `PIPE_CONFIG_PATH` environment variable, default `.claude/pipeline-config.md`). It defines the project stack, git and platform conventions, label names, build and test commands, capacity limits, domain-specific checks, and a documentation map (topic -> file). Resolve every project-specific reference in this prompt through that file and the documents it links. If the config file does not exist, state that explicitly at the top of your output and continue with conservative, generic behavior.
+
+## Architecture Context
+
+Before reviewing, read the security documents listed in the Documentation Map of the pipeline config (the security topic), plus the security entries in the Domain Checks section. These describe the project's authentication layers, role hierarchy, permission levels, tenant isolation mechanism, security-sensitive classes, and sensitive fields. Use these docs as the authoritative reference, do not rely on training data about the stack.
+
+## Review Scope
+
+By default, review unstaged changes from `git diff`. The user or CI may specify different files, an MR/PR diff, or a scope to review. When a title, description, and linked issues are provided, use them to understand the **intent** of the change before judging the implementation.
+
+## Mandatory Security Checks
+
+Apply the generic categories below. For each one, resolve the project-specific classes, filters, endpoints, and fields through the Domain Checks section and the security documents named in the pipeline config.
+
+### 1. Authentication bypass
+- Overly broad public/permit-all rules on sensitive paths in the security configuration
+- New endpoints not covered by the security filter chain
+- The set of endpoints exempted from authentication must match the set the project intends to protect by API key or equivalent
+
+### 2. Authorization flaws
+- Every handler that modifies data must be behind an authorization check or a role-gated path
+- Verify role checks use the correct hierarchy level for the project
+- Read the actual handler source, do not infer authorization from layer or naming
+
+### 3. CSRF misconfiguration
+- When the project documents matching production and test policies, compare the actual exemption sets rather than assuming they match
+- Only endpoints authenticated by a non-cookie mechanism (for example an API key) should be CSRF-exempt
+- New form-submission endpoints must NOT be added to the exemption list
+
+### 4. Injection
+- Direct string concatenation into SQL, JPQL, or other query languages
+- User input used as query property names or identifiers
+- Native or raw queries with interpolated parameters are critical
+- Prefer parameterized queries and query-builder APIs
+
+### 5. Sensitive data in logs
+- Passwords, tokens, API keys, secrets, session IDs, and any sensitive field named in the Domain Checks section
+- Flag logging that emits a sensitive value without sanitization
+- Correct pattern: log a context message plus the exception object, never the sensitive value itself
+
+### 6. Credential and hash handling
+- Never re-encode a value already stored in the project's detected hash format; verify the format from configuration or library usage rather than assuming one algorithm
+- Review encoding logic changes in the services named in the Domain Checks section
+- Constant-time comparison for secrets, with null checks before the comparison call
+
+### 7. API key / token auth
+- Where both a key and a secret are required, both must be validated, not just one
+- New endpoints that should require API-key auth must be added to the protected set
+
+### 8. Tenant / data isolation leaks
+- All queries for tenant-scoped or ownership-scoped entities must filter at the database query level
+- Cross-tenant or cross-owner access via direct ID lookup that bypasses the permission filter is critical
+
+## Suppression Check (read before reporting anything)
+
+Before reporting any issue, read the suppressions file (path in the Suppressions section of the pipeline config, default `.claude/memory/review_suppressions.md`). If the pattern you are about to flag matches an entry under "Security Review Suppressions", skip it. It is a documented intentional decision. Do not report suppressed patterns even if your confidence is 100.
+
+## Mandatory Verification Before Reporting
+
+Before reporting any issue, you MUST verify the claim using your tools. Never report based on assumption or partial reading:
+
+- **Endpoint protection claims**: Read the security configuration and confirm the endpoint's actual security chain before claiming it is unprotected.
+- **Missing authorization claims**: Read the handler class and confirm the authorization check is actually absent, not just on a different line.
+- **Injection claims**: Read the query code and confirm it uses string concatenation, not parameterization.
+- **Config mismatch claims**: Read both the production and test security configuration and compare the actual exemption lists.
+- **Test profile assumptions**: Do not assume test-profile configuration applies to production, verify the profile annotation or condition.
+
+### CI and automation scripts
+
+For CI files, establish the trust boundary before judging a value. Issue and
+MR/PR titles, bodies, comments, branch names, changed repository files, and code
+checked out from a contributor branch are untrusted. Runner-generated numeric
+IDs and fixed project paths may be trusted only when the platform documentation
+guarantees their shape.
+
+Read sibling scripts and the mapped CI documentation for context, but repeated
+use is not evidence that a pattern is safe. Report a repeated pattern when there
+is still a concrete injection, secret-exposure, permission, or persistence path.
+Account for ephemeral containers when assessing persistence and cleanup impact,
+without treating ephemerality as protection for credentials available during
+the job.
+
+If a source file is not available to read, explicitly state that and lower your confidence accordingly.
+
+## Confidence Scoring
+
+Rate each potential issue on a scale from 0-100:
+
+- **0**: Not confident at all, likely a false positive or pre-existing issue
+- **25**: Somewhat confident, might be real but could be intentional design
+- **50**: Moderately confident, real issue but low impact or unlikely to be exploited in practice
+- **75**: Highly confident, verified this is a real vulnerability that could be exploited
+- **100**: Absolutely certain, confirmed exploitable vulnerability with a clear attack path
+
+**Only report issues with confidence >= 80.** Quality over quantity, one confirmed critical vulnerability is worth more than ten speculative warnings.
+
+## Output Guidance
+
+Start by clearly stating what you are reviewing and the security context.
+
+For each high-confidence issue, provide:
+- Severity: **CRITICAL** (exploitable now) or **IMPORTANT** (defense-in-depth concern)
+- Confidence score
+- File path and line number
+- Description of the vulnerability and attack scenario
+- Concrete fix suggestion
+
+Group issues by severity. If no high-confidence issues exist, confirm the code meets security standards with a brief summary of what was checked.
+
+End with a **Security Posture Summary**, one paragraph assessing the overall security impact of the reviewed changes.

package/payload/agents/test-fix.md

@@ -0,0 +1,33 @@
+---
+name: test-fix
+description: Fixes failing tests in pipeline merge requests. Reads failing test files and their production source classes, determines root cause, fixes implementation or test as needed, verifies compilation, and commits. Never pushes.
+tools: Agent, Bash, Edit, Glob, Grep, LS, MultiEdit, NotebookRead, Read, Skill, TodoWrite, Write
+model: sonnet
+---
+
+You are the test-fix agent. Your job is to fix failing tests in a merge request, not to rewrite features.
+
+## Project configuration (read first)
+
+Before doing anything else, read the project pipeline configuration file (path in the `PIPE_CONFIG_PATH` environment variable, default `.claude/pipeline-config.md`). It defines the project stack, git and platform conventions, label names, build and test commands, capacity limits, domain-specific checks, and a documentation map (topic -> file). Resolve every project-specific reference in this prompt through that file and the documents it links. If the config file does not exist, state that explicitly at the top of your output and continue with conservative, generic behavior.
+
+## Workflow
+
+1. **Read conventions**: Read `CLAUDE.md` and the testing document from the Documentation Map for project and testing conventions.
+2. **Understand failures**: The task prompt contains test failure details (class names, error messages, stack traces from the test reports).
+3. **Read the tests**: Open each failing test file and read it completely.
+4. **Read the source**: Read the production class(es) the test exercises. Confirm constructors, method signatures, and return types match what the test calls.
+5. **Fix the root cause**: If the superpowers plugin is available, use the `superpowers:systematic-debugging` skill to diagnose root cause before touching any code. Fix either the implementation or the test, whichever is wrong:
+   - If the test calls a method/constructor that no longer matches the production class → update the test
+   - If the implementation doesn't satisfy a valid test expectation → fix the implementation
+   - If it's a missing dependency or import → add it
+6. **Verify**: If the superpowers plugin is available, use the `superpowers:verification-before-completion` skill before claiming the fix is done. Run the compile commands from Build & Tests to confirm the fix compiles.
+7. **Commit**: `git add -A && git commit -m "Fix test errors"`. If the CI job provides an exact commit subject, use that instead (it drives fix-loop caps).
+8. **Stop**: Do NOT run `git push`. The CI script handles pushing.
+
+## Constraints
+
+- Fix only what is causing failures. Do not refactor or improve unrelated code.
+- Do not rewrite the whole feature.
+- If a test is testing something that was intentionally removed, it is acceptable to remove or update the test. Explain why in the commit message.
+- Read the testing document from the Documentation Map for project-specific test infrastructure rules and pitfalls before changing test code. It covers language-level traps (what counts as a valid argument versus a missing overload), mocking pitfalls (checked exceptions, proxy wrapping and its effect on exception handlers), and the exact limits of transactional rollback for test isolation (when data written by the code under test survives the rollback and needs manual cleanup). Follow the testing doc on these points, do not reason them out from first principles.

package/payload/agents/test-writer.md

@@ -0,0 +1,40 @@
+---
+name: test-writer
+description: Generates integration and unit tests that increase coverage for new or changed code, following the project's documented testing patterns, with a self-correcting compilation loop
+tools: Agent, Bash, Edit, Glob, Grep, LS, MultiEdit, NotebookRead, Read, Skill, TodoWrite, Write
+model: sonnet
+color: green
+---
+
+You are the test-writer agent. Your job is to write tests that increase coverage for new or changed code.
+
+## Project configuration (read first)
+
+Before doing anything else, read the project pipeline configuration file (path in the `PIPE_CONFIG_PATH` environment variable, default `.claude/pipeline-config.md`). It defines the project stack, git and platform conventions, label names, build and test commands, capacity limits, domain-specific checks, and a documentation map (topic -> file). Resolve every project-specific reference in this prompt through that file and the documents it links. If the config file does not exist, state that explicitly at the top of your output and continue with conservative, generic behavior.
+
+## Workflow
+
+1. **Read conventions**: Read `CLAUDE.md` and the testing document from the Documentation Map completely before writing any test. The testing document contains the full test patterns, naming rules, test base class details, and common gotchas. If the superpowers plugin is available, use the `superpowers:test-driven-development` skill to guide the overall test-writing loop.
+2. **Read the source**: Open the production class(es) to test. Understand constructors, method signatures, dependencies, and return types completely before writing any test code.
+3. **Read existing tests**: Find and read tests in the same package or for similar classes. Reuse existing helpers and fixture utilities rather than inventing new setup patterns.
+4. **Choose test type**:
+   - **Unit test**: no framework context, dependencies mocked. Use for pure service/component logic with mockable dependencies.
+   - **Integration test**: extends the project's shared test base class, boots the framework context. Use for repository, service, or controller behavior that needs a real database.
+
+   Take the exact naming conventions and base class details from the testing document and the Build & Tests section of the config.
+5. **Write tests** following the project's documented patterns.
+6. **Verify**: Run the compile commands from Build & Tests. If compilation fails, read the error, fix the root cause, and retry. Allow up to 3 fix attempts.
+7. **Commit**: `git add -A && git commit -m "Add coverage tests"`. If the CI job provides an exact commit subject, use that instead (it drives fix-loop caps).
+8. **Stop**: Do NOT run `git push`. The CI script handles pushing.
+
+## Critical Rules (Non-Negotiable)
+
+Read the testing document from the Documentation Map for project-specific test infrastructure rules and pitfalls. Treat its constraints as non-negotiable. In particular, resolve these questions from that document before writing tests:
+
+- Which annotations or setup patterns are forbidden because they break test-context caching or restart shared containers per class.
+- When to use transactional rollback for test isolation and when it provides no benefit or does not apply at all: follow the testing doc, do not guess.
+- Which fixture helpers to use for creating test entities instead of raw repository calls.
+- Which external components must be mocked in integration tests.
+- What mutating HTTP requests need in tests (security tokens, headers).
+- Which cleanup steps are required when data is written outside a rolled-back transaction.
+- Pitfalls when mocking methods that throw checked exceptions.

package/payload/ci-templates/claude-pipeline.gitlab-ci.yml

@@ -0,0 +1,233 @@
+# =============================================================================
+# Claude ci-agent-platform: GitLab CI template (tier 1)
+# =============================================================================
+# Include this file from your project's .gitlab-ci.yml:
+#
+#   include:
+#     - local: .claude-pipeline/claude-pipeline.gitlab-ci.yml   # vendored copy
+#
+# Your project's `stages:` must include `test` and `review` for the review loop:
+#   stages: [build, test, review, deploy]
+# The issue -> code loop needs `orchestrate` and `code` as well (see the note
+# further down); wiring all four up front costs nothing, since a stage with no
+# job is skipped:
+#   stages: [orchestrate, code, build, test, review, deploy]
+# The `test` job that produces JUnit/coverage artifacts stays in YOUR project.
+# This template only reads its results (see the test-fix job's `needs:`).
+#
+# Override any PIPE_ variable in your own variables: block. Secrets
+# (ANTHROPIC_API_KEY, PIPE_BOT_TOKEN) are set as masked CI variables, never
+# here. Do NOT re-declare a secret in a job's variables: block as a same-name
+# self-reference (FOO: "$FOO"): on GitLab it resolves to an empty string and
+# shadows the real project variable (pilot 2 finding, P6). Project variables
+# reach every job automatically. The GitHub workflows are different: there the
+# explicit env: mapping from secrets is required.
+# The jobs call the runner scripts, which call `claude "/<skill>"`.
+# All reasoning lives in the skills, this file is triggers plus plumbing.
+# =============================================================================
+
+variables:
+  # --- Where the runner scripts live (vendored copy path) --------------------
+  PIPE_SCRIPTS_DIR: ".claude-pipeline/scripts"
+
+  # --- CI image (see ci-templates decision note) -----------------------------
+  # Must provide: node + npm, git, curl. jq and claude-code are installed in
+  # before_script when missing. The runner scripts talk to the GitLab API with
+  # curl and jq directly, so no glab is needed in the image; glab is only used
+  # interactively, by the install wizard.
+  # Python caveat (E2E finding N-7): node:22-bookworm ships python3 but NOT
+  # pip and NOT ensurepip ("python3 -m venv" fails). A Python project's
+  # PIPE_VERIFY_CMD must bootstrap pip first, e.g.
+  # "apt-get update -qq && apt-get install -y -qq python3-pip && ...",
+  # or the project overrides PIPE_CI_IMAGE with a stack image. The onboarding
+  # wizard composes the verify command accordingly. Override the image only
+  # when the fix/coder jobs need a toolchain the image lacks (JDK, Go, ...).
+  PIPE_CI_IMAGE: "node:22-bookworm"
+
+  # --- Platform + config -----------------------------------------------------
+  # PIPE_PLATFORM is autodetected from GITLAB_CI now, so setting it is optional.
+  # It is kept here as an explicit, harmless override.
+  PIPE_PLATFORM: "gitlab"
+  PIPE_CONFIG_PATH: ".claude/pipeline-config.md"
+  PIPE_CONTEXT_DIR: "build/pipeline"
+
+  # --- Git model -------------------------------------------------------------
+  # Integration branch MRs target. Must be a LITERAL branch name: a nested
+  # variable like "$CI_DEFAULT_BRANCH" is NOT expanded inside rules:
+  # comparisons, so review/review-fix/test-fix would never be added to the
+  # pipeline (E2E finding N-3). The onboarding wizard writes the detected
+  # branch into the project's variables: block; override there, never here.
+  PIPE_TARGET_BRANCH: "main"
+  PIPE_BOT_USER: ""                     # leave empty: resolved from the token at runtime; set only to filter comments by a different account
+  PIPE_GIT_NAME: "Pipeline Bot"         # coder commit identity (name)
+  PIPE_GIT_EMAIL: "bot@pipeline.ci"     # coder commit identity (email)
+
+  # --- Lifecycle labels ------------------------------------------------------
+  # Neutral defaults. Override with your project's own label names in your
+  # variables: block (roles: ready / wip / stuck / blocker / blocked / decomposed).
+  PIPE_LABEL_READY: "pipe-ready"
+  PIPE_LABEL_WIP: "pipe-wip"
+  PIPE_LABEL_STUCK: "pipe-stuck"
+  PIPE_LABEL_BLOCKER: "pipe-blocker"
+  PIPE_LABEL_BLOCKED: "pipe-blocked"            # issue waiting on a prerequisite
+  PIPE_LABEL_DECOMPOSED: "pipe-decomposed"      # parent split into sub-issues
+
+  # --- Issue -> code loop ----------------------------------------------------
+  PIPE_CODER_CAP: "3"                            # max coder pipelines per orchestrate run
+  PIPE_ORCHESTRATE: "0"                          # set to "1" in the schedule to run orchestrate
+  PIPE_SPEC_TEMPLATE_PATH: ".gitlab/issue_templates/Spec.md"
+
+  # --- Build / verify --------------------------------------------------------
+  PIPE_VERIFY_CMD: ""                   # compile + unit tests, run after a fix
+  PIPE_COMPILE_CMD: ""                  # compile only (defaults to PIPE_VERIFY_CMD)
+  PIPE_TEST_REPORT_GLOB: ""             # e.g. build/test-results/**/TEST-*.xml
+  PIPE_COVERAGE_SIGNAL: ""              # path to a coverage-drop signal file
+
+  # --- Commit subjects (drive the fix-loop cap counters) ---------------------
+  PIPE_COMMIT_TESTFIX: "Fix test errors"
+  PIPE_COMMIT_REVIEWFIX: "Fix review findings"
+  PIPE_COMMIT_COVERAGE: "Add coverage tests"
+
+  # --- Caps + models ---------------------------------------------------------
+  PIPE_FIX_LOOP_CAP: "2"
+  # Main-loop model per job group, passed as `claude --model` by the runner.
+  # Aliases track the current model, same convention as the agent frontmatter.
+  # Subagents keep the models from their own frontmatter.
+  PIPE_MODEL_TRIAGE: "haiku"
+  PIPE_MODEL_CODE: "sonnet"
+  PIPE_MODEL_REVIEW: "sonnet"
+  PIPE_AGENT_ENV_ALLOWLIST: ""          # credential-like env names the agent-run build must receive (comma-separated; prefer empty)
+
+  # --- Result files (defaults live under PIPE_CONTEXT_DIR) --------------------
+  PIPE_RESULT_REVIEW: "$PIPE_CONTEXT_DIR/code-review-result.txt"
+  PIPE_RESULT_REVIEWFIX: "$PIPE_CONTEXT_DIR/review-fix-result.json"
+
+# --- Hidden base job: shared config + runtime variable mapping ---------------
+# Maps GitLab's CI_ runtime variables onto the PIPE_ names the scripts read, and
+# installs claude-code if the image does not ship it.
+.claude-base:
+  image: $PIPE_CI_IMAGE
+  variables:
+    GIT_DEPTH: "0"                      # full history for diff base + cap counting
+    PIPE_API_URL: "$CI_API_V4_URL"
+    PIPE_PROJECT_ID: "$CI_PROJECT_ID"
+    PIPE_PROJECT_PATH: "$CI_PROJECT_PATH"
+    PIPE_SERVER_HOST: "$CI_SERVER_HOST"
+    PIPE_MR_IID: "$CI_MERGE_REQUEST_IID"
+    PIPE_SOURCE_BRANCH: "$CI_MERGE_REQUEST_SOURCE_BRANCH_NAME"
+    PIPE_HEAD_SHA: "$CI_COMMIT_SHA"
+    PIPE_TOKEN: "$PIPE_BOT_TOKEN"
+    PIPE_JOB_NAME: "$CI_JOB_NAME"
+    PIPE_JOB_ID: "$CI_JOB_ID"
+    PIPE_PIPELINE_ID: "$CI_PIPELINE_ID"
+  before_script:
+    # jq is a hard dependency of every runner script. GitHub-hosted runners
+    # ship it, plain docker images (node:22-bookworm) do not, so install it
+    # here (finding from the GitLab pilot: silent HTTP 400s + exit 127).
+    - command -v jq >/dev/null 2>&1 || (apt-get update -qq && apt-get install -y -qq jq)
+    - command -v claude >/dev/null 2>&1 || npm install -g @anthropic-ai/claude-code
+  artifacts:
+    paths:
+      - $PIPE_CONTEXT_DIR/metrics/
+    when: always
+    expire_in: 60 days
+
+# =============================================================================
+# review: run the automated review on a non-draft MR that changes code.
+# =============================================================================
+review:
+  extends: .claude-base
+  stage: review
+  timeout: 20m
+  script:
+    - bash "$PIPE_SCRIPTS_DIR/review.sh"
+  artifacts:
+    paths:
+      - $PIPE_CONTEXT_DIR/metrics/
+    reports:
+      dotenv: $PIPE_CONTEXT_DIR/review.env
+    when: always
+    expire_in: 60 days
+  rules:
+    - if: '$CI_PIPELINE_SOURCE == "merge_request_event" && $CI_MERGE_REQUEST_TARGET_BRANCH_NAME == $PIPE_TARGET_BRANCH && $CI_MERGE_REQUEST_TITLE !~ /^Draft:/'
+      when: on_success
+
+# =============================================================================
+# review-fix: on review failure (REVIEW_HAS_BUGS), fix the confirmed bugs.
+# Gated to wip MRs. Reads REVIEW_HAS_BUGS from the review job's dotenv artifact.
+# =============================================================================
+review-fix:
+  extends: .claude-base
+  stage: review
+  timeout: 60m
+  needs:
+    - job: review
+      artifacts: true
+      optional: true
+  variables:
+    GIT_STRATEGY: clone
+  script:
+    - bash "$PIPE_SCRIPTS_DIR/review-fix.sh"
+  allow_failure: true
+  rules:
+    - if: '$CI_PIPELINE_SOURCE == "merge_request_event" && $CI_MERGE_REQUEST_TARGET_BRANCH_NAME == $PIPE_TARGET_BRANCH && $CI_MERGE_REQUEST_LABELS =~ $PIPE_LABEL_WIP'
+      when: on_failure
+
+# =============================================================================
+# orchestrate: triage ready issues and fire the coder (issue -> code loop).
+# Runs on a scheduled pipeline that sets PIPE_ORCHESTRATE=1 (kept off by default
+# so a schedule turns it on deliberately, for spend control). Needs a pipeline
+# trigger token in PIPE_TRIGGER_TOKEN (set as a protected/masked CI variable) to
+# start the child `code` pipeline.
+#
+# To enable the issue loop, add `orchestrate` and `code` to your `stages:`.
+# =============================================================================
+orchestrate:
+  extends: .claude-base
+  stage: orchestrate
+  timeout: 30m
+  variables:
+    GIT_STRATEGY: clone
+  script:
+    - bash "$PIPE_SCRIPTS_DIR/orchestrate.sh"
+  rules:
+    - if: '$CI_PIPELINE_SOURCE == "schedule" && $PIPE_ORCHESTRATE == "1"'
+    - if: '$CI_PIPELINE_SOURCE == "web" && $PIPE_ORCHESTRATE == "1"'
+
+# =============================================================================
+# code: implement one issue and open the MR (issue -> code loop).
+# Triggered by orchestrate via the Pipeline Trigger API with CODER_ISSUE and
+# CODER_BRANCH set. The coder agent runs with --dangerously-skip-permissions on
+# this isolated runner (and non-root where the image allows); see code.sh.
+# =============================================================================
+code:
+  extends: .claude-base
+  stage: code
+  timeout: 45m
+  variables:
+    GIT_STRATEGY: clone
+  script:
+    - bash "$PIPE_SCRIPTS_DIR/code.sh"
+  rules:
+    - if: '$CODER_ISSUE && $CODER_BRANCH'
+
+# =============================================================================
+# test-fix: on failure of YOUR project's `test` job, on a wip MR, fix tests /
+# compilation / coverage. Consumes the test job's artifacts via needs.
+# =============================================================================
+test-fix:
+  extends: .claude-base
+  stage: test
+  timeout: 60m
+  needs:
+    - job: test
+      artifacts: true
+      optional: true
+  variables:
+    GIT_STRATEGY: clone
+  script:
+    - bash "$PIPE_SCRIPTS_DIR/test-fix.sh"
+  allow_failure: true
+  rules:
+    - if: '$CI_PIPELINE_SOURCE == "merge_request_event" && $CI_MERGE_REQUEST_TARGET_BRANCH_NAME == $PIPE_TARGET_BRANCH && $CI_MERGE_REQUEST_LABELS =~ $PIPE_LABEL_WIP'
+      when: on_failure

package/payload/ci-templates/github/README.md

@@ -0,0 +1,76 @@
+# GitHub Actions variant: concept mapping
+
+The skills and agents are identical across platforms. Only the CI wiring and a
+few names differ. The runner scripts in `../scripts/` are shared: they read
+`$PIPE_PLATFORM` and branch on it (see `scripts/lib/platform.sh`).
+
+| Concept | GitLab | GitHub Actions |
+|---|---|---|
+| Change unit | Merge Request (MR) | Pull Request (PR) |
+| CLI used by the runner | `glab` / GitLab REST via `curl` | `gh api` |
+| Config values | CI/CD variables | repository/org **Variables** (`vars.*`) |
+| Secrets | protected/masked CI variables | **Secrets** (`secrets.*`) |
+| Run after a job fails | `when: on_failure` | `needs:` + `if: ${{ failure() }}` (same workflow) |
+| Cross-workflow trigger | pipeline artifact + `needs` | `on: workflow_run` (`claude-test-fix.yml`) |
+| Gate a downstream job on a runtime value | `dotenv` artifact (`review.env`) | job `outputs` (`needs.review.outputs.has_bugs`) |
+| Block the merge | job exits non-zero | required status check fails |
+| Incremental diff base | MR versions API | `github.event.before` on `synchronize` |
+| Bot identity for push | project/personal access token | bot **PAT** (`PIPE_BOT_TOKEN`) |
+
+## Gaps where the platforms do not map one to one
+
+- **Push must re-trigger the pipeline.** GitHub's default `GITHUB_TOKEN` does not
+  trigger workflows on its own push (loop protection). The fix loop therefore
+  needs a bot PAT in `PIPE_BOT_TOKEN` so a fix commit re-runs review/tests.
+  GitLab has no such restriction, but a bot token is still cleaner than the
+  pipeline's own `CI_JOB_TOKEN`.
+- **test-fix hangs off your test workflow.** GitLab evaluates `on_failure`
+  within one pipeline. GitHub keeps your test workflow separate, so `test-fix`
+  runs via `workflow_run`. It downloads the failed run's `test-reports`
+  artifact, so your test workflow must upload the reports under that name (or
+  set `PIPE_TEST_ARTIFACT`). If you prefer one workflow, drop this job into your
+  test workflow instead:
+
+  ```yaml
+  claude-test-fix:
+    needs: [test]
+    if: ${{ failure() && contains(github.event.pull_request.labels.*.name, vars.PIPE_LABEL_WIP) }}
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with: { ref: ${{ github.event.pull_request.head.ref }}, fetch-depth: 0, token: ${{ secrets.PIPE_BOT_TOKEN }} }
+      - run: command -v claude >/dev/null 2>&1 || npm install -g @anthropic-ai/claude-code
+      - env: { ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}, GH_TOKEN: ${{ secrets.PIPE_BOT_TOKEN }} }
+        run: bash "$PIPE_SCRIPTS_DIR/test-fix.sh"
+  ```
+- **Fork PRs.** `workflow_run.pull_requests` is empty for PRs from forks (a
+  GitHub security boundary), so `claude-test-fix.yml` skips them. review and
+  review-fix in `claude-pipeline.yml` still run, but secrets are not exposed to
+  fork PRs by default, so the paid steps are effectively same-repo only.
+- **Draft filtering.** GitLab reads `$CI_MERGE_REQUEST_TITLE !~ /^Draft:/`.
+  GitHub has a first-class `draft` flag, used in the review job `if:`.
+
+## Issue-to-code loop (claude-issue-pipeline.yml)
+
+| Concept | GitLab | GitHub Actions |
+|---|---|---|
+| Orchestrate trigger | scheduled pipeline (`PIPE_ORCHESTRATE=1`) | `workflow_dispatch`, manual during the pilot (decision D2); cron is provided commented out |
+| Orchestrate -> code | Pipeline Trigger API (`PIPE_TRIGGER_TOKEN`) | `workflow_dispatch` of the same workflow with `inputs.coder_issue` + `inputs.coder_branch` (bot PAT) |
+| Labels | project-level (`/projects/:id/labels`) | repo-level (`/repos/:repo/labels`) |
+| Blocking links | native `is_blocked_by` links | text convention `Blocked by #N` in the body (decision D1) |
+| Decomposed-parent children | native `blocks` links | machine marker `<!-- pipe-children: #a #b -->` in the parent comment |
+| MR/PR labels | set at creation | set after creation via the issues API |
+| Delete source branch | `remove_source_branch: true` | repo setting "Automatically delete head branches" |
+
+Both platforms share `orchestrate.sh`, `code.sh`, and `lib/issue-loop.sh`. The
+platform is autodetected from `GITHUB_ACTIONS` / `GITLAB_CI`, so `PIPE_PLATFORM`
+does not need setting.
+
+### Gaps in the GitHub issue loop
+
+- **Decomposed-parent auto-close is best-effort.** With no native child links,
+  the release poll parses the `<!-- pipe-children: ... -->` marker the
+  decomposition comment embeds. If a human edits that comment away, the parent
+  will not auto-close. Native sub-issues (REST/GraphQL) are the future upgrade.
+- **Milestone inheritance is not carried** onto the PR (kept simple for the
+  pilot); labels are inherited.

package/payload/ci-templates/github/claude-issue-pipeline.yml

@@ -0,0 +1,141 @@
+# =============================================================================
+# Claude ci-agent-platform: GitHub Actions workflow (issue -> code loop)
+# =============================================================================
+# Copy this to .github/workflows/claude-issue-pipeline.yml. It mirrors the
+# GitLab `orchestrate` and `code` jobs in a single workflow, both driven by
+# workflow_dispatch:
+#
+#   - No inputs (or coder_issue empty)  -> the `orchestrate` job runs: it triages
+#     ready issues and dispatches this same workflow with coder inputs.
+#   - coder_issue + coder_branch set    -> the `code` job runs: it implements the
+#     issue and opens a PR.
+#
+# Decision D2: orchestrate is manual only (workflow_dispatch), no cron, so paid
+# runs stay under human control during the pilot. A cron schedule is provided
+# commented out below for when you are ready.
+#
+# Decision D1: GitHub has no native "is blocked by" issue links, so this loop
+# expresses dependencies with the text convention "Blocked by #N" in the issue
+# body. The release poll reads it back. Native sub-issues are a future upgrade.
+#
+# Configuration:
+#   - Repository/org VARIABLES: PIPE_TARGET_BRANCH, PIPE_LABEL_* , PIPE_CODER_CAP,
+#     PIPE_SPEC_TEMPLATE_PATH, PIPE_GIT_NAME, PIPE_GIT_EMAIL, etc.
+#   - SECRETS: ANTHROPIC_API_KEY, PIPE_BOT_TOKEN (a bot PAT with issues +
+#     contents + pull-requests + actions write). The bot PAT is required so the
+#     coder's push and the orchestrate -> code dispatch re-trigger workflows;
+#     the default GITHUB_TOKEN cannot.
+#   - Vendor the ci-agent-platform repository's ci-templates/scripts/ into your
+#     repo (PIPE_SCRIPTS_DIR).
+# =============================================================================
+
+name: claude-issue-pipeline
+
+on:
+  workflow_dispatch:
+    inputs:
+      coder_issue:
+        description: "Issue number to implement. Leave empty to run orchestrate (triage)."
+        required: false
+        default: ""
+      coder_branch:
+        description: "Branch for the coder (required together with coder_issue)."
+        required: false
+        default: ""
+  # Enable scheduled orchestrate when the pilot is over (spend control). The
+  # orchestrate job's `if:` also requires coder_issue to be empty, which a
+  # schedule event satisfies.
+  # schedule:
+  #   - cron: "30 23 * * 1-5"   # 23:30 UTC on weekdays
+
+permissions:
+  contents: write
+  issues: write
+  pull-requests: write
+
+env:
+  PIPE_SCRIPTS_DIR: ".claude-pipeline/scripts"
+  # PIPE_PLATFORM is autodetected from GITHUB_ACTIONS; no need to set it.
+  PIPE_CONFIG_PATH: ".claude/pipeline-config.md"
+  PIPE_CONTEXT_DIR: "build/pipeline"
+  # On `schedule` events the payload has no repository object, so the middle
+  # term is empty there; set vars.PIPE_TARGET_BRANCH when the default branch
+  # is not main and the cron trigger is used.
+  PIPE_TARGET_BRANCH: ${{ vars.PIPE_TARGET_BRANCH || github.event.repository.default_branch || 'main' }}
+  PIPE_LABEL_READY: ${{ vars.PIPE_LABEL_READY || 'pipe-ready' }}
+  PIPE_LABEL_WIP: ${{ vars.PIPE_LABEL_WIP || 'pipe-wip' }}
+  PIPE_LABEL_STUCK: ${{ vars.PIPE_LABEL_STUCK || 'pipe-stuck' }}
+  PIPE_LABEL_BLOCKER: ${{ vars.PIPE_LABEL_BLOCKER || 'pipe-blocker' }}
+  PIPE_LABEL_BLOCKED: ${{ vars.PIPE_LABEL_BLOCKED || 'pipe-blocked' }}
+  PIPE_LABEL_DECOMPOSED: ${{ vars.PIPE_LABEL_DECOMPOSED || 'pipe-decomposed' }}
+  PIPE_CODER_CAP: ${{ vars.PIPE_CODER_CAP || '3' }}
+  PIPE_ISSUE_SCAN: ${{ vars.PIPE_ISSUE_SCAN || '20' }}
+  PIPE_SPEC_TEMPLATE_PATH: ${{ vars.PIPE_SPEC_TEMPLATE_PATH || '.github/ISSUE_TEMPLATE/spec.md' }}
+  PIPE_GIT_NAME: ${{ vars.PIPE_GIT_NAME || 'Pipeline Bot' }}
+  PIPE_GIT_EMAIL: ${{ vars.PIPE_GIT_EMAIL || 'bot@pipeline.ci' }}
+  PIPE_MODEL_TRIAGE: ${{ vars.PIPE_MODEL_TRIAGE || 'haiku' }}
+  PIPE_MODEL_CODE: ${{ vars.PIPE_MODEL_CODE || 'sonnet' }}
+  PIPE_AGENT_ENV_ALLOWLIST: ${{ vars.PIPE_AGENT_ENV_ALLOWLIST || '' }}
+  # Runtime mapping onto the PIPE_ names the scripts read.
+  PIPE_REPO: ${{ github.repository }}
+  PIPE_PROJECT_PATH: ${{ github.repository }}
+  PIPE_SERVER_HOST: "github.com"
+  PIPE_CODE_WORKFLOW: "claude-issue-pipeline.yml"
+
+jobs:
+  # ---------------------------------------------------------------------------
+  # orchestrate: triage ready issues, dispatch the code job for actionable ones.
+  # ---------------------------------------------------------------------------
+  orchestrate:
+    if: ${{ github.event.inputs.coder_issue == '' }}
+    runs-on: ubuntu-latest
+    timeout-minutes: 30
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+          token: ${{ secrets.PIPE_BOT_TOKEN }}
+      - name: Install claude-code
+        run: command -v claude >/dev/null 2>&1 || npm install -g @anthropic-ai/claude-code
+      - name: Run orchestrate
+        env:
+          ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
+          GH_TOKEN: ${{ secrets.PIPE_BOT_TOKEN }}
+        run: bash "$PIPE_SCRIPTS_DIR/orchestrate.sh"
+      - name: Upload metrics
+        if: always()
+        uses: actions/upload-artifact@v4
+        with:
+          name: orchestrate-metrics
+          path: ${{ env.PIPE_CONTEXT_DIR }}/metrics/
+          if-no-files-found: ignore
+
+  # ---------------------------------------------------------------------------
+  # code: implement one issue and open a PR.
+  # ---------------------------------------------------------------------------
+  code:
+    if: ${{ github.event.inputs.coder_issue != '' }}
+    runs-on: ubuntu-latest
+    timeout-minutes: 45
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          ref: ${{ env.PIPE_TARGET_BRANCH }}
+          fetch-depth: 0
+          token: ${{ secrets.PIPE_BOT_TOKEN }}
+      - name: Install claude-code
+        run: command -v claude >/dev/null 2>&1 || npm install -g @anthropic-ai/claude-code
+      - name: Run code
+        env:
+          ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
+          GH_TOKEN: ${{ secrets.PIPE_BOT_TOKEN }}
+          CODER_ISSUE: ${{ github.event.inputs.coder_issue }}
+          CODER_BRANCH: ${{ github.event.inputs.coder_branch }}
+        run: bash "$PIPE_SCRIPTS_DIR/code.sh"
+      - name: Upload metrics
+        if: always()
+        uses: actions/upload-artifact@v4
+        with:
+          name: code-metrics
+          path: ${{ env.PIPE_CONTEXT_DIR }}/metrics/
+          if-no-files-found: ignore