@cxi-lmai/ci-agent-platform 3.0.0

package/payload/skills/fix-tests/SKILL.md

@@ -0,0 +1,70 @@
+---
+name: fix-tests
+description: Fix a failing test stage in a CI merge request or pull request. Handles three cases from one entry point, failing tests reported in the test artifacts, a compilation error that stopped the tests from running, and a coverage drop. Respects the fix-loop cap, verifies the fix, and commits without pushing. Use this when a CI test job failed and needs an automated fix attempt.
+---
+
+# fix-tests
+
+Generic replacement for `test-fix.sh`. The CI job runs `claude "/fix-tests"` after a failed test stage. This skill diagnoses which of the three cases it is, delegates to the right agent, verifies, and commits. The runner keeps checkout, rebase, push, and the label and comment API calls.
+
+## Step 1: read the project configuration
+
+Read `$PIPE_CONFIG_PATH` (default `.claude/pipeline-config.md`). You need the Build & Tests section (commands and report paths), the testing document from the Documentation Map, and the Domain Checks. If the file is missing, say so on the first line and continue generically.
+
+## Step 2: inputs
+
+- `$PIPE_TEST_REPORT_GLOB`: glob for the test report files (for example JUnit XML). Read these to find failing cases.
+- `$PIPE_COVERAGE_SIGNAL`: path to a coverage-drop signal file the coverage gate wrote, if any. Its content names the baseline and current coverage.
+- `$PIPE_VERIFY_CMD`: full verification command (compile plus unit tests) to run after a fix.
+- `$PIPE_COMPILE_CMD` (default: same as `$PIPE_VERIFY_CMD`): compile-only command, used to reproduce a compilation error and to check the coverage branch.
+- `$PIPE_FIX_LOOP_CAP` (default `2`): maximum consecutive bot fix commits before escalating.
+- `$PIPE_COMMIT_TESTFIX`: exact commit subject for a test fix. Its recurrence drives the cap count.
+- `$PIPE_COMMIT_COVERAGE`: exact commit subject for a coverage-tests commit. Separate cap counter.
+- `$PIPE_TARGET_BRANCH`: the branch the MR/PR targets, used as the base for the commit-history walk.
+- `$PIPE_CONTEXT_DIR` (default `build/pipeline`): where you write the result marker.
+
+## Step 3: pick the case
+
+In this order:
+
+1. **Failing tests.** Read the reports matched by `$PIPE_TEST_REPORT_GLOB`. If any report shows failures or errors, this is the test-fix case. Collect the failing class names, messages, and stack traces.
+2. **Coverage drop.** No failing tests, but `$PIPE_COVERAGE_SIGNAL` exists and is non-empty. This is the coverage case. Read the baseline and current values from it.
+3. **Compilation error.** No failing tests and no coverage signal, and no test reports were produced at all. The test stage crashed before tests ran, most likely a compilation error. Reproduce it by running `$PIPE_COMPILE_CMD` and capture the error output.
+4. **Nothing to do.** Tests produced results and all passed, no coverage signal. This was a false-alarm trigger. Write the marker with `FIX_BRANCH=none` and stop.
+
+## Step 4: cap check
+
+Count consecutive commits from the branch tip back toward `$PIPE_TARGET_BRANCH` whose subject matches the relevant commit subject (`$PIPE_COMMIT_TESTFIX` for the test-fix and compilation cases, `$PIPE_COMMIT_COVERAGE` for the coverage case). Use local git, no token:
+
+```
+git log "origin/$PIPE_TARGET_BRANCH"..HEAD --format="%s"
+```
+
+Stop counting at the first subject that does not match. If the count is at or above `$PIPE_FIX_LOOP_CAP`, do not attempt another fix. Escalate instead: follow the postmortem-mr flow (spawn the `postmortem` agent with the failure text, the fix-attempt git log, and the changed files, then read `failure_category` from its report). Write the marker with `FIX_ESCALATE=true` and the `FAILURE_CATEGORY`, and stop. The job applies the stuck label and posts the diagnostic.
+
+## Step 5: delegate
+
+- **Test-fix and compilation cases**: spawn the `test-fix` agent (Agent tool, `subagent_type: test-fix`). Pass the failure details (test failures or the compilation output) and the exact commit subject `$PIPE_COMMIT_TESTFIX`. The agent reads the config and the testing document itself, fixes the root cause in the implementation or the test, and commits.
+- **Coverage case**: spawn the `test-writer` agent (`subagent_type: test-writer`). Pass the baseline and current coverage, the diff of new code (`git diff "origin/$PIPE_TARGET_BRANCH"..HEAD` scoped to source files), and the exact commit subject `$PIPE_COMMIT_COVERAGE`.
+
+Tell the agent the commit subject must be exactly the value above, because the cap counter matches on it. Tell it not to run `git push`.
+
+## Step 6: verify
+
+- Test-fix case: run `$PIPE_VERIFY_CMD` (compile plus unit tests).
+- Coverage and compilation cases: run `$PIPE_COMPILE_CMD`. The pushed pipeline re-runs the full suite and re-measures coverage, so a compile check is enough here.
+
+If verification fails, the agent's self-correcting loop should have handled it. Do not push a state that does not compile.
+
+## Step 7: emit the result marker
+
+Write `$PIPE_CONTEXT_DIR/fix-tests.env` as dotenv:
+
+```
+FIX_BRANCH=tests|coverage|compile|none
+FIX_COMMIT_MADE=true|false
+FIX_ESCALATE=true|false
+FAILURE_CATEGORY=<category or empty>
+```
+
+Set `FIX_COMMIT_MADE=true` only when the consecutive-commit count grew during this run, meaning the agent actually committed. The job pushes when a commit was made, escalates the labels when `FIX_ESCALATE=true`, and skips silently when `FIX_BRANCH=none`.

package/payload/skills/implement-issue/SKILL.md

@@ -0,0 +1,62 @@
+---
+name: implement-issue
+description: Implement one issue in the autonomous issue-to-code loop. Delegates to the coder agent to write the code, tests, and a commit on the already-checked-out branch, confirms the coder did not push, and drafts the merge/pull request description from the diff. Writes a machine-readable result the CI runner acts on. Use this when a CI code job asks to implement an issue.
+---
+
+# implement-issue
+
+Generic replacement for the coder delegation in `code.sh`. The code job runs `claude "/implement-issue"` instead of building the delegation prompt in bash. This skill delegates to the coder and drafts the MR/PR body. The runner keeps only checkout, git identity, the push, and the MR/PR creation (all token or plumbing work).
+
+## Step 1: read the project configuration
+
+Read the config file at `$PIPE_CONFIG_PATH` (default `.claude/pipeline-config.md`). From it you need the Project stack, the Git & Platform section (commit convention, MR/PR description format), and the Documentation Map. If the file is missing, say so on the first line of your output and continue with generic behavior.
+
+## Step 2: inputs
+
+- `$PIPE_CONTEXT_DIR` (default `build/pipeline`): where the prepared context lives and where you write outputs.
+- `$PIPE_CONTEXT_DIR/coder-input.md`: the issue IID, title, and description. The job wrote this from the platform API.
+- `$PIPE_ISSUE_IID`: the issue number being implemented.
+- `$PIPE_TARGET_BRANCH`: the integration branch the MR/PR will target. The runner has already checked out the feature branch on top of it.
+
+The repository is already checked out on the feature branch. Git is local, no token needed.
+
+## Step 3: delegate to the coder
+
+Spawn the `coder` agent (Agent tool, `subagent_type: coder`) with the issue IID, title, and description from the context file, instructing it to implement the issue. The coder reads the config and the Documentation Map itself, explores existing patterns, implements, writes tests through the test-writer agent, runs the project verify command in a self-correcting loop, and commits. Do not restate its internal rules.
+
+The coder must NOT push. Pushing is the runner's job. After the coder returns, confirm no push happened: the coder has no push step, but if the working tree or branch state shows an attempted push, note it in your output. The commits stay local for the runner to push.
+
+## Step 4: check what the coder produced
+
+Run `git rev-list "origin/$PIPE_TARGET_BRANCH..HEAD" --count` to count the commits the coder made this run. Write it to the result marker. If it is zero, the coder made no changes (nothing to implement, or it got stuck). Do not draft an MR/PR body in that case; the runner handles the no-commits path.
+
+## Step 5: draft the MR/PR body
+
+Only when there is at least one commit, draft the description from the actual diff. Read it with `git diff "origin/$PIPE_TARGET_BRANCH..HEAD"` scoped to source paths. Do this in this session, do not spawn another claude process for it. Write `$PIPE_CONTEXT_DIR/mr-summary.md` using exactly this structure, no preamble, no extra headings:
+
+```
+## Summary
+- <what changed and why, 2-4 bullets>
+
+## Testing
+- <what was tested, 1-3 bullets>
+
+## Reviewer notes
+- <decisions or non-obvious choices a reviewer should validate, 1-3 bullets; omit this whole section if nothing to flag>
+```
+
+Bullet text only (no bold labels), one line per bullet. Omit a section that has nothing meaningful to say. Follow any MR/PR description convention the config's Git & Platform section defines.
+
+## Step 6: emit the result
+
+Write `$PIPE_CONTEXT_DIR/implement.env`:
+
+```
+IMPL_COMMITS=<integer count of commits this run>
+IMPL_PUSHED=false
+IMPL_SUMMARY_FILE=<path to mr-summary.md, or empty when no commits>
+```
+
+## What the CI job does after you
+
+The runner reads `implement.env`, recounts the commits itself as the authoritative gate, and acts: with zero commits it comments on the issue and applies the stuck label (no MR/PR); otherwise it pushes the branch and opens the MR/PR titled by the closing-commit convention, with the issue's labels inherited (ready swapped for wip) and the drafted summary as the body. None of that is your job.

package/payload/skills/init-pipeline-config/SKILL.md

@@ -0,0 +1,96 @@
+---
+name: init-pipeline-config
+description: Onboard a repository to the ci-agent-platform pipeline, end to end. Scans the project and generates a prefilled pipeline-config.md, walks the human through every open TODO interactively, wires the CI template into the repo itself, and hands over a guided checklist for secrets and the smoke test. Use this when setting up the pipeline in a new repo, or when someone asks to generate or refresh the pipeline config.
+---
+
+# init-pipeline-config
+
+Guided onboarding wizard for the whole pipeline setup. One invocation takes the repository from "no pipeline" to "ready for the smoke test". The human answers questions and approves commits; the wizard does the work.
+
+Ground rules for the whole run:
+
+- Runs interactively, not inside CI. It calls no agent and makes no paid pipeline run.
+- Never push. Commits happen only after the user approves them; pushing is offered, never done silently.
+- Never accept secret values (API keys, tokens) into the conversation. Name them, say where the human sets them, and verify presence, not values.
+- Do not overwrite an existing config or CI file without showing the diff and asking.
+- Leave `TODO` for anything you cannot detect or the user cannot answer now. Do not invent values.
+- Everything you write, in the config and on screen: plain factual sentences. No em dashes, no semicolons in prose, no filler. Any count you state (files, agents, skills, labels, and the like) comes from the output of a command you run in that same step (`ls <dir> | wc -l`, `git ...`, and so on), never from memory, a prior turn, or an estimate. When you cannot run the command, say the count is unknown rather than guess.
+- Maintain `.claude/onboarding-state.md` as you go: after every phase, and after every completed step of phase 4, rewrite it with the phase you are in, the decisions made so far, and the exact next action. It is gitignored (`INSTALL.md` step 1.4), never committed, and you delete it at the end of phase 5. A session resuming an interrupted onboarding reads it first and continues by this skill, never by improvisation.
+
+Source paths: `<root>` below means the first candidate that actually contains `templates/pipeline-config.template.md`, tested in this order: `.claude/` (a completed vendored install, see `INSTALL.md`), then `.ci-agent-platform-src/` (the folder the bootstrapper unpacked). Test for that file, never for the directory: do not choose `.claude/` merely because it exists. If neither candidate has it, search one level below the repository root for any directory containing `templates/pipeline-config.template.md` and use that. Matching on the file rather than on a directory name is deliberate, so a renamed or relocated source folder still resolves.
+
+## Phase 1: scan and draft
+
+1. Read the config template at `<root>/templates/pipeline-config.template.md`. It defines the required sections. The output keeps this structure.
+2. Scan the repository. Detect, without guessing where you can read the answer:
+   - **Language and build system.** The build manifest (Gradle or Maven build file, `package.json`, `pyproject.toml`, `go.mod`, `Cargo.toml`). Read the stack and versions from it. Derive the compile, test, and coverage commands from the same file and its scripts. The verify command must be runnable inside `PIPE_CI_IMAGE`: the default `node:22-bookworm` ships python3 but no pip and no ensurepip, so for a Python project on the default image compose `PIPE_VERIFY_CMD` with a pip bootstrap, `apt-get update -qq && apt-get install -y -qq python3-pip && python3 -m pip install --break-system-packages -q pytest && python3 -m pytest -q` (adapt the installed packages to the manifest), or record a `PIPE_CI_IMAGE` override instead.
+   - **Git platform and CLI.** Read the remote host without credentials: `git remote get-url origin | sed -E 's#//[^/@]+@#//#'`. Never print the raw remote URL, it may embed an access token. A GitLab host means the `glab` CLI, a GitHub host means `gh`. Record the platform; it drives phase 3.
+   - **Branch model.** Detect the default branch in this order: `git symbolic-ref refs/remotes/origin/HEAD` (the remote's default), else the current local branch. Record it as the proposed pipeline target branch; it is not a TODO. Also note a separate integration branch if one exists and the branch-naming convention if the docs state one. When local and remote disagree, or project files reference a branch that does not exist, keep your detected value as the proposal and mention the discrepancy in one sentence when confirming (phase 2), offering to fix it; do not present it as a blocker.
+   - **Documentation map.** Map the standard topics (testing, migrations, domain, integrations, security, performance, release, git workflow, e2e) to the files whose names or headings match.
+   - **Issue and PR templates.** The platform template directory (`.gitlab/issue_templates/`, `.github/`).
+   - **Test infrastructure.** Test report output path, coverage tool and its report path.
+   - **Labels.** Existing labels that can serve the six lifecycle roles (ready, wip, stuck, blocker, blocked, decomposed). When the project has none, propose the `pipe-*` defaults.
+3. Fill the template from what you detected. Prefer a link to an existing doc plus the key facts over copying content (anti-drift). Mark unused sections `not used`. Write the draft to `$PIPE_CONFIG_PATH` (default `.claude/pipeline-config.md`). Write plain factual sentences, in the config file and in everything you print to the user: no em dashes, no semicolons in prose, no filler.
+4. Show the user a short scan summary: what you detected, what is TODO and why.
+
+## Phase 2: human onboarding (interactive)
+
+Do not hand the user a homework list. Walk them through it:
+
+1. Start with one confirmation of the detected basics in a single question: "The pipeline will target branch `<detected>` on `<platform>`. Correct?" Detected values are proposals to confirm, never open questions.
+2. Split the remaining `TODO`s into two groups. **Defaultable:** the repo gives a defensible answer (coverage tooling absent means the policy is `not used`, Domain Check candidates read from the code, standard paths). Apply these without asking and keep them for the summary in step 4. **Genuinely open:** the repo gives no signal at all (a convention nobody wrote down, a check only a human knows about). Only these earn a question. Branch naming is not a question: with no repository convention use `<issue-iid>-<kebab-title>`, which is exactly what the runner accepts.
+3. Ask one scheduling question because frequency is a project policy, not a detectable technical fact: should the issue loop stay manual/disabled, run nightly on selected days, or use a custom cron? Recommend manual/disabled until both smoke tests pass. For a schedule, record days, local time, and time zone. Convert to UTC only for GitHub Actions; GitLab stores the chosen cron time zone. Then ask the other genuinely open items one concrete question at a time, in config order, each with a suggested default when possible. In a typical repo this is one to three questions total. Do not ask for the bot account username: the runner resolves it from the token at runtime (`platform_resolve_bot_user`); the account itself gets created with the token in phase 4. Apply each answer to the config immediately; the user never edits the file by hand during this phase.
+4. Close with one review summary of everything that was set: detected, defaulted, and answered, with the applied Domain Checks listed item by item. Invite the user to add, remove, or change anything; apply the edits. This summary is the safety net that lets steps 2-3 default aggressively.
+5. Then show the final config. As part of the `INSTALL.md` install, do not commit yet: one commit at the end of phase 3 covers the installed files, the config, and the wiring together. Only when the skill runs standalone (config refresh in an already-installed repo) offer the commit here, message `ci: pipeline config`.
+
+## Phase 3: wire the CI template
+
+Do this yourself; it is mechanical. The human only approves the diff. When the `INSTALL.md` step 1 already copied the template and scripts into place, skip the copies and only do the wiring edits.
+
+**GitLab** (detected in phase 1):
+
+1. Create `.claude-pipeline/` and copy `<root>/ci-templates/claude-pipeline.gitlab-ci.yml` and `<root>/ci-templates/scripts/` into it.
+2. Edit the project `.gitlab-ci.yml`: ensure the stages the template needs (`orchestrate, code, test, review`), add the `include:` of the vendored template, and add the non-secret `PIPE_*` values from the config that differ from the template defaults (typically `PIPE_VERIFY_CMD`, `PIPE_TEST_REPORT_GLOB`) as top-level `variables:`. Always write `PIPE_TARGET_BRANCH` with the branch detected in phase 1, as a literal: a nested `$CI_DEFAULT_BRANCH` is not expanded inside `rules:` comparisons and would silently disable every MR job (E2E finding N-3). You know the values since phase 1; wiring them now keeps phase 4 free of commits. Do not touch the project's own jobs without asking.
+3. Check the project's own test job: when neither its `rules:` nor a `workflow:` block makes it run in `merge_request_event` pipelines, the template's `test-fix` job can never fire (its `needs: test` finds no test job in the MR pipeline, E2E finding N-4). Tell the user and offer a concrete diff that adds the missing rule. Apply it only after they agree.
+4. Copy `<root>/templates/spec-issue.template.md` to `.gitlab/issue_templates/Spec.md` (or the path the user chose in phase 2). When that file already exists, show the diff and ask before replacing it. An issue template is project-owned content, and the ground rule above covers the config and the CI file by name, so this one has to be said explicitly.
+
+**GitHub:**
+
+1. Copy all three workflows from `<root>/ci-templates/github/` to `.github/workflows/`, and `<root>/ci-templates/scripts/` to `.claude-pipeline/scripts`. Ask before replacing any workflow file that already exists: `claude-pipeline.yml` is an ordinary enough name to collide with something the project wrote. The issue workflow always remains manually dispatchable. If phase 2 selected a schedule, enable its `schedule:` block with the converted UTC cron.
+2. Edit `claude-test-fix.yml`: set `workflows:` to the project's test workflow name. Check that the test workflow uploads its reports as the `test-reports` artifact and tell the user when it does not.
+3. Copy the spec template to `.github/ISSUE_TEMPLATE/spec.md`, asking first if it is already there.
+
+Then show one diff summary of everything so far (installed files, config, wiring) and offer the single install commit. Commit message: `ci: install ci-agent-platform pipeline`. In the standalone case (rewiring the template in an already-installed repo) commit just the wiring as `ci: claude pipeline template`.
+
+## Phase 4: secrets and platform setup (human does, wizard guides)
+
+Never take the values. And never dump the whole checklist at once: this phase is a guided walkthrough, one manual step at a time. For each step:
+
+- Announce where the user is: `Step 2/6: bot token`, plus one line on what it is for.
+- Give the shortest instruction that works: the exact UI path (Settings > CI/CD > ...), the exact name to type, the exact scopes to tick. No prose around it.
+- Wait for the user to say done before showing the next step.
+- When the platform CLI or API can see the result, verify it yourself before moving on (`glab variable list` / `gh variable list` and `gh secret list`, runner list, label list): presence, never values. A step that is already satisfied gets skipped with a one-line note.
+- Steps the wizard can do itself are offered as "I can run this, ok?" instead of an instruction to the user.
+- When the platform CLI (`glab`/`gh`) is not installed locally, offer once, at the start of the phase, to install it (it also serves the smoke test). If the user declines, do not derail: give the UI paths, skip the verifications, and trust the user's done.
+
+The steps, in this order (GitLab has 7, GitHub 6, number the counter accordingly):
+
+1. `ANTHROPIC_API_KEY`: where to create it, set as a masked CI variable (GitLab: Settings > CI/CD > Variables, not protected when MR pipelines run from unprotected branches; GitHub: repository secret).
+2. `PIPE_BOT_TOKEN`: GitLab project access token with `api` + `write_repository`, masked and hidden but not protected when ordinary unprotected feature branches need MR review/fix jobs; GitHub PAT with issues, contents, pull-requests and Actions write. Explain that protected GitLab variables work only when the project's protected-MR conditions are satisfied.
+3. GitLab only: `PIPE_TRIGGER_TOKEN` (Settings > CI/CD > Pipeline trigger tokens) for the orchestrate-to-code dispatch.
+4. The non-secret `PIPE_*` variables that differ from the defaults: these were already wired into the CI file in phase 3, so this step is normally a one-line "already wired, skipping". Only when something changed during phase 4 edit the CI file again (part of the walkthrough, no extra approval beyond showing the diff).
+5. A runner: check Settings > CI/CD > Runners shows one available for this project. Instances without shared runners (common on self-hosted GitLab) need a project runner registered, or an existing one enabled for this project. GitHub-hosted runners need nothing.
+6. The six lifecycle labels (ready, wip, stuck, blocker, blocked, decomposed). On GitLab this step is OPTIONAL and skipped by default: the orchestrator creates each label on first API use (`issue_ensure_label`), so nothing has to exist up front. Offer it only as a nicety, since pre-creating them makes the labels clickable in the board UI sooner. On GitHub the step is REQUIRED: a label must exist before the API can apply it. Offer to run the exact `glab`/`gh` commands yourself, or give the UI path.
+7. Scheduling (GitLab only): when phase 2 selected a schedule, offer to create it through the authenticated `glab api` session with `PIPE_ORCHESTRATE=1` and the chosen cron time zone. Otherwise leave it disabled and explain the manual run path. On GitHub this was already wired in phase 3, so report it as the sixth and final setup item instead of creating external state here.
+
+Close the phase with a one-line recap of what was created and verified.
+
+## Phase 5: smoke test (wizard drives) and final recap
+
+The smoke tests are the last step and the wizard drives them. The review smoke requires one approval for its push and MR/PR creation. The full issue-loop smoke has a separate approval because it creates another issue, branch, and MR/PR and incurs another paid run.
+
+1. Announce it in one line and prepare it: a branch named by the phase 2 convention, one small harmless change, an MR/PR against the target branch carrying the wip label. Then ask the one question of this phase: confirm the push plus MR/PR creation (ground rule: never push silently). One yes covers both. On GitLab without `glab`, create the MR with git push options (`git push -o merge_request.create -o merge_request.target=<target> -o merge_request.label=<wip label> origin <branch>`), no token or CLI needed. When no `merge_request_event` pipeline appears within about a minute of the MR existing, create it yourself with `POST /projects/:id/merge_requests/:iid/pipelines` (the bot token is set by phase 4). On GitHub without `gh`, push and print the compare URL for the user to open the PR.
+2. Check the run yourself with a single status query (`glab ci status` / `gh run list` for the run), or one short bounded wait, then report. Do not launch a blind polling loop that blocks for many minutes. If the jobs have not started or finished yet, say so and give the user the one command to re-check, rather than waiting them out. Scheduled pipelines and crons are best-effort and can lag by minutes, so an unstarted scheduled run is expected, not a failure. Expect, once it runs: the `review` job runs, a review comment from the bot account appears on the MR/PR, `review.env` and a metrics JSON land in `$PIPE_CONTEXT_DIR`. Report the result with a link to the MR/PR and the bot comment.
+3. On failure, read the job log yourself and say what is wrong and what to change. The common causes are a missing `ANTHROPIC_API_KEY`, a `PIPE_BOT_TOKEN` without comment/write scope, and an explicitly set `PIPE_BOT_USER` not matching the token's account (leave it unset; the runner resolves it from the token).
+4. After the review smoke test passes, offer a separate end-to-end issue-loop smoke test. This is the only test that proves issue -> triage -> code -> MR/PR rather than only the review half, so it is worth running. Run it only after explicit approval, then watch it through MR/PR creation. Steps: create one small issue whose full spec sits in the issue DESCRIPTION following `spec-issue.template.md` (a spec pasted into a comment does not count, the pipeline reads the spec from the description), apply the ready label, then start orchestrate IMMEDIATELY with a manual run rather than a schedule. On GitLab that is Run pipeline on the target branch with variable `PIPE_ORCHESTRATE=1` (pipeline source `web`, which the orchestrate rule already allows), on GitHub the `workflow_dispatch` of the issue pipeline. Do not set up a cron schedule for this test. A cron is only for ongoing autonomy later and adds minutes of best-effort delay, while the manual run starts within seconds. It spends another triage plus coder run, pushes a feature branch, and opens an MR/PR.
+5. Close with the final recap, one table: every setting that matters (target branch, branch convention, labels, verify command, report path, image, caps, models, schedule), its value, and its origin (detected / default / answered). Under the table, state what was committed and pushed, both smoke-test results (or `not run`), and whether the issue schedule is active or manual. End with a clear "done": the user must never have to ask what state the repo is in.

package/payload/skills/postmortem-mr/SKILL.md

@@ -0,0 +1,50 @@
+---
+name: postmortem-mr
+description: Produce a structured root-cause diagnostic for a stuck merge request or pull request when the automated fix loops are exhausted. Runs the postmortem agent, emits a failure_category and the recommended label changes in a machine-parsable form for CI. Use this when a fix job hit its cap and the MR/PR needs a human, or when another skill escalates.
+---
+
+# postmortem-mr
+
+Generic replacement for `diagnose.sh`. It is the shared escalation step. The `fix-tests` and `fix-review-findings` skills follow the same flow inline when they hit their cap. The CI job can also call `claude "/postmortem-mr"` directly, for example after a deploy fix exhausts its retries. The runner keeps the label and comment API calls.
+
+## Step 1: read the project configuration
+
+Read `$PIPE_CONFIG_PATH` (default `.claude/pipeline-config.md`) for the Labels section (the stuck and wip label names) and the Project stack. If the file is missing, say so on the first line and continue generically.
+
+## Step 2: inputs
+
+The calling job or skill provides the failure context. Read it from `$PIPE_CONTEXT_DIR/postmortem-input.md` (default `build/pipeline/postmortem-input.md`), or from these variables when the caller passed them directly:
+
+- MR/PR iid and title.
+- The original failure text (test failures, the review comment, or a deploy failure record).
+- The git log of the fix attempts (`git log "origin/$PIPE_TARGET_BRANCH"..HEAD --oneline`).
+- The context label naming which loop got stuck (for example a test-fix, a review-fix, or a deploy-fix).
+- `$PIPE_LABEL_STUCK` and `$PIPE_LABEL_WIP` from the config or CI variables.
+
+The changed-file list is available locally from `git diff --name-only "origin/$PIPE_TARGET_BRANCH"..HEAD`.
+
+## Step 3: run the postmortem agent
+
+Spawn the `postmortem` agent (Agent tool, `subagent_type: postmortem`). Pass the MR/PR meta, the changed files, the fix-attempt git log, the original failure text, and the context label. The agent reads the config itself and produces the structured report, which includes the mandatory line:
+
+```
+failure_category: <category>
+```
+
+The categories are defined by the postmortem agent. Do not invent your own.
+
+## Step 4: emit the outputs
+
+Write the diagnostic body to `$PIPE_CONTEXT_DIR/postmortem.md`. This is the text the job posts as the MR/PR comment, with the human-intervention note the job adds.
+
+Write `$PIPE_CONTEXT_DIR/postmortem.env` as dotenv:
+
+```
+FAILURE_CATEGORY=<category from the report, or "other" if none was emitted>
+ADD_LABELS=<value of $PIPE_LABEL_STUCK>
+REMOVE_LABELS=<value of $PIPE_LABEL_WIP>
+```
+
+## What the CI job does after you
+
+The job applies the label change through the platform API, posts `postmortem.md` as the comment, and emits the `dev_stuck` metrics event with the `FAILURE_CATEGORY`. Label and comment writes need the token and stay in the runner.

package/payload/skills/review-mr/SKILL.md

@@ -0,0 +1,82 @@
+---
+name: review-mr
+description: Run the automated code review of a merge request or pull request in CI. Builds the review context, runs the code-reviewer agent plus the security, performance, and migration reviewers when the diff calls for them, merges the findings into one comment body, and emits a machine-readable verdict for the pipeline to gate on. Use this when a CI job asks to review an MR/PR.
+---
+
+# review-mr
+
+Generic replacement for `review.sh`. The CI job runs `claude "/review-mr"` instead of assembling a long prompt in bash. This skill does the reasoning. The runner keeps only checkout, the API reads that fetch the context, posting the comment, and gating the pipeline.
+
+## Step 1: read the project configuration
+
+Read the config file at `$PIPE_CONFIG_PATH` (default `.claude/pipeline-config.md`). From it you need the Project stack, the Git & Platform section (target branch, bot account), the Documentation Map, the Domain Checks, and the Suppressions path. If the file is missing, say so on the first line of your output and continue with generic behavior.
+
+From the Documentation Map, read only the documents whose "when to read" matches the change in front of you. Do not preload every document. The reviewers you spawn read their own docs through the same map.
+
+## Step 2: inputs
+
+Everything comes from CI variables and a context file the job prepared with the platform token. Do not call the platform API yourself.
+
+- `$PIPE_CONTEXT_DIR` (default `build/pipeline`): directory holding the prepared context and where you write outputs.
+- `$PIPE_CONTEXT_DIR/mr-context.md`: MR/PR title, description, linked issue text, previous bot review comment, previous auto-fix activity. The job wrote this from the platform API. Read it for intent before judging the code.
+- `$PIPE_DIFF_BASE`: the SHA to diff against. For an incremental re-review it is the previous push head. For the first review or after a rebase it is the merge base. The job computes it.
+- `$PIPE_HEAD_SHA`: the current commit under review (the platform runtime SHA).
+- `$PIPE_IS_INCREMENTAL`: `true` when the diff base is a previous push head, otherwise `false`.
+- `$PIPE_TARGET_BRANCH`: the branch the MR/PR targets.
+- `$PIPE_RESULT_REVIEW` (default `$PIPE_CONTEXT_DIR/code-review-result.txt`): where the code-reviewer writes and where you write the merged body.
+
+## Step 3: build the diff
+
+Run `git diff "$PIPE_DIFF_BASE" "$PIPE_HEAD_SHA"` locally. Git is on the runner, no token needed. Scope the diff to reviewable source paths.
+
+When `$PIPE_IS_INCREMENTAL` is `true`, the diff is only what changed since the previous review. Tell each reviewer to focus on these new changes and not re-raise earlier findings unless this diff reintroduces or modifies the problematic code. When it is `false`, this is the initial review of the full diff.
+
+## Step 4: run the code-reviewer
+
+Spawn the `code-reviewer` agent (Agent tool, `subagent_type: code-reviewer`). Pass it:
+
+- the MR/PR intent (title, description, linked issues) from the context file,
+- the scope note (incremental or initial),
+- the diff,
+- the previous review comment and previous auto-fix activity, with the instruction to verify applied fixes are correct and not re-flag dismissed findings unless the diff reintroduces the problem.
+
+The code-reviewer reads the config, the Documentation Map, and the Suppressions file itself, applies its confidence threshold and mandatory verification, and writes its result to `$PIPE_RESULT_REVIEW`. Do not restate its internal rules in the prompt. Do not preload docs into the prompt, that is what the Documentation Map is for.
+
+## Step 5: run the specialist reviewers when the diff calls for them
+
+Inspect the diff paths and content, then spawn the specialists that apply. Each reads the config and its mapped documents itself. Decide from the Documentation Map and Domain Checks in the config, not from hardcoded paths:
+
+- **migration-reviewer** when the diff touches database migration or schema-change files (the "database migrations" row of the Documentation Map, or the migration paths named in Domain Checks).
+- **security-reviewer** when the diff touches authentication, authorization, request routing, secret handling, tenant or data isolation, or any area the Domain Checks security notes point at.
+- **performance-reviewer** when the diff touches data access, ORM mappings, repository or query code, or the performance-critical methods named in Domain Checks.
+
+If none apply, the code-reviewer result stands on its own. Run only the specialists that fit. Running all of them on every diff wastes tokens and invites noise.
+
+## Step 6: merge the findings
+
+Combine the code-reviewer result and any specialist findings into one comment body. Rules:
+
+- One status line first, exactly one of `**Status: blocking**`, `**Status: non-blocking**`, `**Status: clean**`. Blocking wins if any reviewer reports a blocking finding.
+- Then a flat bullet list, blocking items first, then non-blocking. Each bullet keeps the `` `path:line` `` prefix and a one-sentence description. Blocking items carry a fix suggestion.
+- Drop duplicates when two reviewers flag the same line. Keep the more specific finding.
+- No section headers, no summaries, no prose around the list.
+
+Write the merged body to `$PIPE_RESULT_REVIEW`.
+
+## Step 7: emit the verdict
+
+Write `$PIPE_CONTEXT_DIR/review.env` as dotenv for the pipeline to gate on:
+
+```
+REVIEW_STATUS=blocking|non-blocking|clean
+REVIEW_HAS_BUGS=true|false
+REVIEW_FINDINGS_TOTAL=<integer>
+```
+
+`REVIEW_HAS_BUGS=true` only when the merged status is blocking and at least one finding is a concrete runtime defect (null dereference, broken query, wrong logic) or a confirmed security or data-loss issue. Do not set it true for style, pattern, or convention findings, missing annotations with no runtime effect, or anything phrased as "potential", "consider", "could", or "may". This verdict decides whether the fix-review-findings job runs, so it replaces the separate classification pass the old script made.
+
+`REVIEW_FINDINGS_TOTAL` is the count of bullets in the merged body.
+
+## What the CI job does after you
+
+The job reads `$PIPE_RESULT_REVIEW` and posts it as the review comment, reads `review.env` to gate the downstream fix job, emits the metrics event, and exits non-zero when `REVIEW_HAS_BUGS=true` to block the pipeline. None of that is your job.

package/payload/skills/triage-issue/SKILL.md

@@ -0,0 +1,74 @@
+---
+name: triage-issue
+description: Triage one issue for the autonomous issue-to-code loop. Runs the orchestrator agent to classify the issue (implement, ask for clarification, or too large), and when too large runs the decomposer agent to split it into spec-compliant sub-issues. Writes a machine-readable decision the CI runner acts on. Use this when a CI orchestrate job asks to triage a ready issue.
+---
+
+# triage-issue
+
+Generic replacement for the awk prompt-extraction in `orchestrate.sh`. The orchestrate job runs `claude "/triage-issue"` once per ready issue instead of assembling agent prompts in bash. This skill does the reasoning. The runner keeps only the API reads that fetch the issue, and the API writes that create sub-issues, relabel, comment, and trigger the coder.
+
+## Step 1: read the project configuration
+
+Read the config file at `$PIPE_CONFIG_PATH` (default `.claude/pipeline-config.md`). From it you need the Project stack, the Git & Platform section (branch naming, label names), the Labels section, the Spec Template section, and the Capacities section (issue-size heuristic for the orchestrator and decomposer). If the file is missing, say so on the first line of your output and continue with generic behavior.
+
+## Step 2: inputs
+
+Everything comes from CI variables and a context file the job prepared with the platform token. Do not call the platform API yourself.
+
+- `$PIPE_CONTEXT_DIR` (default `build/pipeline`): where the prepared context lives and where you write outputs.
+- `$PIPE_CONTEXT_DIR/issue-context.md`: the issue IID, title, description, and non-system comments. The job wrote this from the platform API.
+- `$PIPE_ISSUE_IID`: the issue number under triage.
+- `$PIPE_SPEC_TEMPLATE_PATH`: path to the project's spec-issue template (the decomposer authors sub-issue bodies against it).
+
+## Step 3: run the orchestrator
+
+Spawn the `orchestrator` agent (Agent tool, `subagent_type: orchestrator`). Pass it the issue context (IID, title, description, comments) from the context file. The orchestrator reads the config, applies the spec-structure check and the capacity heuristic itself, and returns valid JSON, exactly one of:
+
+- `{"actionable":true,"branch":"IID-kebab-title"}`: right-sized, ready to implement.
+- `{"actionable":true,"scope":"too_large","decomposition":"short paragraph"}`: clear but too big.
+- `{"actionable":false,"question":"one clarifying question"}`: needs the author.
+
+Do not restate the orchestrator's internal rules in the prompt.
+
+## Step 4: decompose when too large
+
+Only when the orchestrator returned `scope:"too_large"`, spawn the `decomposer` agent (Agent tool, `subagent_type: decomposer`). Pass it the parent issue (IID, title, description, comments) and tell it the spec template path is `$PIPE_SPEC_TEMPLATE_PATH`. It reads the template and the config itself and returns JSON:
+
+```
+{"confidence":"high|low","reason":"...","sub_issues":[{"key":"a","title":"...","spec_markdown":"...","depends_on":[]}]}
+```
+
+Validate the decomposition before you emit it. It must satisfy the contract, otherwise treat it as failed:
+
+- 2 to 5 sub-issues.
+- `depends_on` references only keys present in the set, and the dependency graph is acyclic.
+- Every `spec_markdown` contains all eight section headers (`## 1. Outcome` through `## 8. Out of Scope`) and no unfilled placeholder text.
+
+The runner re-checks this deterministically as a gate, but you should not pass on a decomposition you already know is malformed. If it fails, emit the `decompose_failed` decision with a short human-readable suggestion (reuse the orchestrator's `decomposition` paragraph).
+
+## Step 5: emit the decision
+
+Write two files. The JSON carries the payload, the dotenv lets the runner branch quickly.
+
+`$PIPE_CONTEXT_DIR/triage.json`, exactly one of:
+
+```json
+{"decision":"implement","branch":"12-add-csv-export"}
+{"decision":"ask","question":"Sections 3 and 7 are empty; please complete them."}
+{"decision":"decompose","confidence":"high","reason":"clean data/service/API seams","sub_issues":[{"key":"a","title":"...","spec_markdown":"...","depends_on":[]}]}
+{"decision":"decompose_failed","suggestion":"Split into a data-model change, a service change, and an endpoint."}
+```
+
+`$PIPE_CONTEXT_DIR/triage.env`:
+
+```
+TRIAGE_DECISION=implement|ask|decompose|decompose_failed
+TRIAGE_BRANCH=<branch for implement, else empty>
+TRIAGE_CONFIDENCE=<high|low for decompose, else empty>
+```
+
+The `branch` follows the branch-naming convention from the config. The runner sanitizes it (lowercase, `[a-z0-9-]`, max 100) and falls back if it is empty, so a best-effort value is fine.
+
+## What the CI job does after you
+
+The runner reads `triage.env` and `triage.json` and does the platform work: for `implement` it queues the coder (respecting `PIPE_CODER_CAP`); for `ask` it posts the question and relabels the issue to the blocker label; for `decompose` it re-validates, creates the sub-issues with the right labels and blocking links, relabels the parent to the decomposed label, comments, and queues high-confidence unblocked children; for `decompose_failed` it posts the suggestion and relabels to blocker. It also emits the `orchestrator_decision` metric. None of that is your job.

package/payload/templates/pipeline-config.template.md

@@ -0,0 +1,98 @@
+# Pipeline config
+
+<!-- Generated by /init-pipeline-config. Review every section before committing.
+     Agents read this file at runtime (path in PIPE_CONFIG_PATH, default .claude/pipeline-config.md).
+     Prefer links to existing docs plus key facts over copying content (anti-drift).
+     Mark unused sections as "not used" instead of deleting them. -->
+
+## Project
+<!-- One sentence: what the app is + stack with versions. Agents quote this in their reasoning. -->
+TODO
+
+## Git & Platform
+- Platform: <!-- GitLab | GitHub --> TODO, CLI: <!-- glab | gh --> TODO
+- Default branch: TODO. Target branch for MRs/PRs: TODO
+- Branch naming: TODO
+- Commit convention for closing an issue: TODO
+- Bot account: autodetected from the token at runtime <!-- override with a username only when comments should be filtered by a different account -->. Commit identity: TODO <!-- defaults: Pipeline Bot / bot@pipeline.ci -->
+- Issue-loop schedule: <!-- manual/disabled | cron + time zone --> TODO
+
+## Labels
+| Label | Meaning |
+|---|---|
+| TODO | issue is ready for the autonomous pipeline (the single human action) |
+| TODO | pipeline is working on the issue |
+| TODO | automation exhausted, a human takes over |
+| TODO | waiting for clarification from the reporter |
+| TODO | waiting for a prerequisite issue |
+| TODO | decomposed into child issues |
+
+## Build & Tests
+- Compile: TODO
+- Unit tests: TODO, full tests: TODO
+- Test reports: TODO
+- Coverage policy: TODO
+
+## Documentation Map
+<!-- The core section. Topic -> file -> when an agent should read it. -->
+| Topic | Document | When to read |
+|---|---|---|
+| overall conventions | CLAUDE.md | always |
+| testing | TODO | writing or fixing tests |
+| database migrations | TODO | any schema change |
+| domain & entities | TODO | new entity, model changes |
+| security | TODO | security review |
+| performance | TODO | performance review |
+| release & deploy | TODO | release MR |
+| git workflow | TODO | branches, MRs, commits |
+
+## Spec Template
+- Path: TODO
+- Required sections: TODO
+
+## Capacities
+<!-- The issue-size heuristic the orchestrator uses to decide implement vs.
+     decompose, and the decomposer uses to size each sub-issue. Lives here, not
+     in the agents, so a project can tune it without editing them. -->
+- One coder session: ~15 files, ~600 changed lines. Larger issues must be decomposed.
+- Orchestrator: an issue that clearly exceeds this, or spans many unrelated
+  subsystems, is `too_large` and goes to the decomposer.
+- Decomposer: split into 2-5 sub-issues, each comfortably inside one session,
+  ordered along natural implementation seams (data before service before API/UI).
+
+## Domain Checks
+<!-- Project-specific review checks that generic reviewer catalogs cannot know:
+     - Security: security-sensitive classes/filters, sensitive fields, tenant-isolation mechanism.
+     - Performance: performance-critical repository/helper methods and user inputs to watch.
+     - Migrations: changeset author, changelog path, project SQL conventions.
+     - Code review anti-false-positives: intentional code-generation annotations
+       (for example Lombok @Getter/@Setter/@RequiredArgsConstructor) that reviewers must NOT
+       flag as missing boilerplate; deliberate overrides of generated code.
+     - Testing gotchas: base test classes to extend, helpers to reuse, patterns to avoid.
+     - CVE / dependency pinning convention (how transitive-CVE pins are recorded, e.g. an inline
+       comment citing the CVE next to a pinned version). -->
+TODO
+
+## Suppressions
+- Path: .claude/memory/review_suppressions.md (sections: Code / Security / Migration / Performance)
+
+## Release
+<!-- Used by the release agent. Mark "not used" if the project has no formal release flow. -->
+- Release title format: <!-- e.g. "Update to x.y.z" --> TODO
+- Release assignee: <!-- account to assign the release request to, or "none" --> TODO
+- Release notes: directory TODO, index file TODO
+- Deployment guide: TODO
+- Environment templates: TODO
+- Configuration files/dir: TODO
+- Infrastructure/compose files: TODO
+- Deploy version variable: <!-- the var in the deploy env file that pins the image tag --> TODO
+
+## E2E Tests
+<!-- Only for projects with a generated e2e suite. Otherwise: not used.
+     Framework, test dir, fixture import module, test-data prefix, cleanup rules, required tags.
+     Also (the e2e-test-writer relies on these):
+     - frontend source dirs + selector strategy (real element IDs vs test-id attributes),
+     - spec-file naming/extension convention (one scenario per file),
+     - entity-type -> cleanup-method mapping,
+     - which tag marks data-writing (mutating) tests vs the required regression/smoke tags. -->
+not used

package/payload/templates/review_suppressions.template.md

@@ -0,0 +1,25 @@
+# Review suppressions
+
+<!-- Dismissed review findings, permanent across MRs. Reviewers must skip matching
+     patterns even at confidence 100. Written by the coder agent when the author
+     dismisses a finding as a false positive, or by hand.
+     Entry format:
+     - **Pattern:** what the finding looks like
+       **Why:** why it is not a real problem in this project
+       **Where:** file/area it applies to (or "everywhere") -->
+
+## Code Review Suppressions
+
+(none yet)
+
+## Security Review Suppressions
+
+(none yet)
+
+## Migration Review Suppressions
+
+(none yet)
+
+## Performance Review Suppressions
+
+(none yet)