@olegkoval/agent-skills 1.67.0 → 1.69.0

package/.github/copilot-instructions.md

@@ -43,6 +43,7 @@ Available reusable prompt files:
 - promptctl: .github/prompts/promptctl.prompt.md
 - veto-routing: .github/prompts/veto-routing.prompt.md
 - ai-tools-setup: .github/prompts/ai-tools-setup.prompt.md
+- agterm-team: .github/prompts/agterm-team.prompt.md
 - self-critique: .github/prompts/self-critique.prompt.md
 - review-past-performance: .github/prompts/review-past-performance.prompt.md
 - retro-analysis: .github/prompts/retro-analysis.prompt.md

package/.github/prompts/agterm-team.prompt.md

@@ -0,0 +1,55 @@
+<!-- Generated by scripts/build-adapters.sh. Do not edit directly. -->
+
+---
+description: "Coordinate Codex agents in project agterm workspaces with readable session names, acknowledged handoffs, failure recovery, and lead-owned acceptance."
+---
+
+Use the olko:agterm-team skill.
+
+# Agterm team
+
+The lead owns the outcome and all failures. Delegation transfers work, never accountability. A worker's done message requests verification; it never closes the task by itself.
+
+Read the installed agterm skill for current CLI syntax and input safeguards; if absent, use agtermctl help and do not guess commands. Read the target project's AGENTS.md and ledger.json when present. Locate and verify a checkout of oleg-koval/agents, then explicitly read roles/olko-team.md, roles/olko-engineer.md, roles/olko-qa.md and pipelines/delivery.md; read pipelines/review.md when reviewing code. Do not invent missing backbone content. Keep roles and pipelines in that repository and task automation in the skill catalog.
+
+## Plan and create sessions
+
+Write the problem, constraints, task ID, authority, acceptance checks, retry budget and terminal condition before assignment. Start with one developer; add workers only for independent work worth the coordination cost. Use isolated worktrees and explicit file ownership.
+
+Inspect fresh agtermctl tree --json output. Pass --socket with AGTERM_SOCKET when set. Identify the project's existing workspace from its session working directories and repository identity, not merely the active workspace. If multiple workspaces fit and context cannot disambiguate them, ask rather than launching into a guessed workspace. Do not move or rename unrelated sessions.
+
+Automatically create needed agent sessions in that project workspace once team orchestration is requested. Default names:
+
+- LEAD_ISSUE_123
+- SENIOR_DEV_ISSUE_123
+- QA_ISSUE_123
+- REVIEWER_PR_456
+
+For work without an issue use ROLE_TASK_SHORT_SLUG. For multiple workers on one issue append _A, _B. Keep agterm names concise and stable; Codex conversation titles may describe the task more verbosely where the installed client supports naming. Never pretend agterm naming also renames the Codex conversation.
+
+Before creating, check for a matching task session and task artifact. Reuse only a verified owned session; a matching name alone proves nothing. Record the task-to-session mapping to prevent duplicate launches after resume. Check installed session new help for workspace targeting flags. Launch Codex using session new --command with the owned worktree as cwd and the task brief as data, never by typing shell commands into another pane. Prefer no-select when supported. Do not alter sandbox, approval, model or access settings beyond the user's authority. Verify the created node belongs to the intended workspace, is realized, and has Codex as its foreground process. A returned session ID alone does not prove startup. Report startup failures without duplicate retries.
+
+## Handoff and return channel
+
+Prefer `codex queue --thread <codex-thread-uuid> --message <text>` when the installed client supports it. A Codex thread UUID is distinct from an agterm session UUID or paneID. Capture it from the running Codex session or supported app-server interface and verify the mapping; never guess it from terminal names. Queue success proves enqueueing, not execution: require a task-ID ACK and result. Check the local CLI help because this capability varies by version. Use terminal input only as the fallback below.
+
+
+Record each participant's fresh full session UUID and stable paneID from the live tree, including the lead return address. Validate hosting environment IDs against that tree; never reuse historical IDs or target active.
+
+Keep briefs and results in shared local task artifacts. The lead owns task-state writes; each developer owns a separate result artifact. Append timestamped evidence and messages. States: assigned, acknowledged, working, blocked, ready-for-review, accepted. Do not put transient coordination data in the shared knowledge ledger.
+
+Every message includes task ID, message ID, type, sender/recipient session and pane IDs, and artifact path. Types: ASSIGN, ACK, QUESTION, BLOCKED, READY_FOR_REVIEW, REWORK, ACCEPTED. Assignments state outcome, ownership, worktree, base SHA, acceptance commands and authority. Results state exact SHA, files, actual check outputs, failures, unavailable checks and remaining risks.
+
+For an existing Codex session, read its pane text and current tree first. Verify the intended process is ready for input without a user draft or approval prompt. Unknown readiness means stage a copyable relay and report blocked; never interrupt or restart another session to force delivery.
+
+Use agtermctl session type --stdin --target <session-uuid> --pane-id <pane-id>, with socket option when needed. This injects keystrokes into a shared buffer; it is not a message queue. Send a short single-line instruction to read the brief artifact. Verify installed submission behavior; avoid multiline injection and shell interpolation. Require readback and a task-ID ACK before calling the assignment received. CLI success proves only injection. Inspect uncertain delivery before retrying to avoid duplicate work. Workers return evidence to the verified lead address using the same readiness safeguards.
+
+## Verify and recover
+
+The lead inspects the actual diff and exact SHA and independently runs acceptance checks. Obtain independent diff review under project policy. Verify local proof, commit, remote SHA, complete check rollup, deployment and human/device acceptance as separate gates when in scope. Accept only proven criteria; return concrete failures and evidence as REWORK.
+
+The lead diagnoses, repairs or reassigns failures within authority and reverifies. After two identical failures stop retrying and diagnose. Exhausted budgets or missing authority end as blocked with receipts, never accepted. Delegated workers cannot expand publishing, spending or external communication authority. Further delegation preserves parent accountability.
+
+Agterm input does not guarantee waking an idle Codex session. This skill installs no daemon. Define bounded checkpoints or supported event-driven wakeups when available; do not promise unattended monitoring. If reliable wakeup is unavailable, leave a resume instruction and task artifact path and report that limitation.
+
+Final report says delivered, blocked or intentionally unchanged, with accepted tasks, separate evidence gates, unresolved failures and the next responsible action. Never blame a worker in place of resolving or reporting failure. Do not close agent sessions automatically; preserve their evidence for inspection.

package/.kiro/steering/agterm-team.md

@@ -0,0 +1,54 @@
+<!-- Generated by scripts/build-adapters.sh. Do not edit directly. -->
+
+---
+inclusion: manual
+description: "Coordinate Codex agents in project agterm workspaces with readable session names, acknowledged handoffs, failure recovery, and lead-owned acceptance."
+---
+
+# Agterm team
+
+The lead owns the outcome and all failures. Delegation transfers work, never accountability. A worker's done message requests verification; it never closes the task by itself.
+
+Read the installed agterm skill for current CLI syntax and input safeguards; if absent, use agtermctl help and do not guess commands. Read the target project's AGENTS.md and ledger.json when present. Locate and verify a checkout of oleg-koval/agents, then explicitly read roles/olko-team.md, roles/olko-engineer.md, roles/olko-qa.md and pipelines/delivery.md; read pipelines/review.md when reviewing code. Do not invent missing backbone content. Keep roles and pipelines in that repository and task automation in the skill catalog.
+
+## Plan and create sessions
+
+Write the problem, constraints, task ID, authority, acceptance checks, retry budget and terminal condition before assignment. Start with one developer; add workers only for independent work worth the coordination cost. Use isolated worktrees and explicit file ownership.
+
+Inspect fresh agtermctl tree --json output. Pass --socket with AGTERM_SOCKET when set. Identify the project's existing workspace from its session working directories and repository identity, not merely the active workspace. If multiple workspaces fit and context cannot disambiguate them, ask rather than launching into a guessed workspace. Do not move or rename unrelated sessions.
+
+Automatically create needed agent sessions in that project workspace once team orchestration is requested. Default names:
+
+- LEAD_ISSUE_123
+- SENIOR_DEV_ISSUE_123
+- QA_ISSUE_123
+- REVIEWER_PR_456
+
+For work without an issue use ROLE_TASK_SHORT_SLUG. For multiple workers on one issue append _A, _B. Keep agterm names concise and stable; Codex conversation titles may describe the task more verbosely where the installed client supports naming. Never pretend agterm naming also renames the Codex conversation.
+
+Before creating, check for a matching task session and task artifact. Reuse only a verified owned session; a matching name alone proves nothing. Record the task-to-session mapping to prevent duplicate launches after resume. Check installed session new help for workspace targeting flags. Launch Codex using session new --command with the owned worktree as cwd and the task brief as data, never by typing shell commands into another pane. Prefer no-select when supported. Do not alter sandbox, approval, model or access settings beyond the user's authority. Verify the created node belongs to the intended workspace, is realized, and has Codex as its foreground process. A returned session ID alone does not prove startup. Report startup failures without duplicate retries.
+
+## Handoff and return channel
+
+Prefer `codex queue --thread <codex-thread-uuid> --message <text>` when the installed client supports it. A Codex thread UUID is distinct from an agterm session UUID or paneID. Capture it from the running Codex session or supported app-server interface and verify the mapping; never guess it from terminal names. Queue success proves enqueueing, not execution: require a task-ID ACK and result. Check the local CLI help because this capability varies by version. Use terminal input only as the fallback below.
+
+
+Record each participant's fresh full session UUID and stable paneID from the live tree, including the lead return address. Validate hosting environment IDs against that tree; never reuse historical IDs or target active.
+
+Keep briefs and results in shared local task artifacts. The lead owns task-state writes; each developer owns a separate result artifact. Append timestamped evidence and messages. States: assigned, acknowledged, working, blocked, ready-for-review, accepted. Do not put transient coordination data in the shared knowledge ledger.
+
+Every message includes task ID, message ID, type, sender/recipient session and pane IDs, and artifact path. Types: ASSIGN, ACK, QUESTION, BLOCKED, READY_FOR_REVIEW, REWORK, ACCEPTED. Assignments state outcome, ownership, worktree, base SHA, acceptance commands and authority. Results state exact SHA, files, actual check outputs, failures, unavailable checks and remaining risks.
+
+For an existing Codex session, read its pane text and current tree first. Verify the intended process is ready for input without a user draft or approval prompt. Unknown readiness means stage a copyable relay and report blocked; never interrupt or restart another session to force delivery.
+
+Use agtermctl session type --stdin --target <session-uuid> --pane-id <pane-id>, with socket option when needed. This injects keystrokes into a shared buffer; it is not a message queue. Send a short single-line instruction to read the brief artifact. Verify installed submission behavior; avoid multiline injection and shell interpolation. Require readback and a task-ID ACK before calling the assignment received. CLI success proves only injection. Inspect uncertain delivery before retrying to avoid duplicate work. Workers return evidence to the verified lead address using the same readiness safeguards.
+
+## Verify and recover
+
+The lead inspects the actual diff and exact SHA and independently runs acceptance checks. Obtain independent diff review under project policy. Verify local proof, commit, remote SHA, complete check rollup, deployment and human/device acceptance as separate gates when in scope. Accept only proven criteria; return concrete failures and evidence as REWORK.
+
+The lead diagnoses, repairs or reassigns failures within authority and reverifies. After two identical failures stop retrying and diagnose. Exhausted budgets or missing authority end as blocked with receipts, never accepted. Delegated workers cannot expand publishing, spending or external communication authority. Further delegation preserves parent accountability.
+
+Agterm input does not guarantee waking an idle Codex session. This skill installs no daemon. Define bounded checkpoints or supported event-driven wakeups when available; do not promise unattended monitoring. If reliable wakeup is unavailable, leave a resume instruction and task artifact path and report that limitation.
+
+Final report says delivered, blocked or intentionally unchanged, with accepted tasks, separate evidence gates, unresolved failures and the next responsible action. Never blame a worker in place of resolving or reporting failure. Do not close agent sessions automatically; preserve their evidence for inspection.

package/.windsurf/rules/agterm-team.md

@@ -0,0 +1,53 @@
+<!-- Generated by scripts/build-adapters.sh. Do not edit directly. -->
+
+---
+description: "Coordinate Codex agents in project agterm workspaces with readable session names, acknowledged handoffs, failure recovery, and lead-owned acceptance."
+---
+
+# Agterm team
+
+The lead owns the outcome and all failures. Delegation transfers work, never accountability. A worker's done message requests verification; it never closes the task by itself.
+
+Read the installed agterm skill for current CLI syntax and input safeguards; if absent, use agtermctl help and do not guess commands. Read the target project's AGENTS.md and ledger.json when present. Locate and verify a checkout of oleg-koval/agents, then explicitly read roles/olko-team.md, roles/olko-engineer.md, roles/olko-qa.md and pipelines/delivery.md; read pipelines/review.md when reviewing code. Do not invent missing backbone content. Keep roles and pipelines in that repository and task automation in the skill catalog.
+
+## Plan and create sessions
+
+Write the problem, constraints, task ID, authority, acceptance checks, retry budget and terminal condition before assignment. Start with one developer; add workers only for independent work worth the coordination cost. Use isolated worktrees and explicit file ownership.
+
+Inspect fresh agtermctl tree --json output. Pass --socket with AGTERM_SOCKET when set. Identify the project's existing workspace from its session working directories and repository identity, not merely the active workspace. If multiple workspaces fit and context cannot disambiguate them, ask rather than launching into a guessed workspace. Do not move or rename unrelated sessions.
+
+Automatically create needed agent sessions in that project workspace once team orchestration is requested. Default names:
+
+- LEAD_ISSUE_123
+- SENIOR_DEV_ISSUE_123
+- QA_ISSUE_123
+- REVIEWER_PR_456
+
+For work without an issue use ROLE_TASK_SHORT_SLUG. For multiple workers on one issue append _A, _B. Keep agterm names concise and stable; Codex conversation titles may describe the task more verbosely where the installed client supports naming. Never pretend agterm naming also renames the Codex conversation.
+
+Before creating, check for a matching task session and task artifact. Reuse only a verified owned session; a matching name alone proves nothing. Record the task-to-session mapping to prevent duplicate launches after resume. Check installed session new help for workspace targeting flags. Launch Codex using session new --command with the owned worktree as cwd and the task brief as data, never by typing shell commands into another pane. Prefer no-select when supported. Do not alter sandbox, approval, model or access settings beyond the user's authority. Verify the created node belongs to the intended workspace, is realized, and has Codex as its foreground process. A returned session ID alone does not prove startup. Report startup failures without duplicate retries.
+
+## Handoff and return channel
+
+Prefer `codex queue --thread <codex-thread-uuid> --message <text>` when the installed client supports it. A Codex thread UUID is distinct from an agterm session UUID or paneID. Capture it from the running Codex session or supported app-server interface and verify the mapping; never guess it from terminal names. Queue success proves enqueueing, not execution: require a task-ID ACK and result. Check the local CLI help because this capability varies by version. Use terminal input only as the fallback below.
+
+
+Record each participant's fresh full session UUID and stable paneID from the live tree, including the lead return address. Validate hosting environment IDs against that tree; never reuse historical IDs or target active.
+
+Keep briefs and results in shared local task artifacts. The lead owns task-state writes; each developer owns a separate result artifact. Append timestamped evidence and messages. States: assigned, acknowledged, working, blocked, ready-for-review, accepted. Do not put transient coordination data in the shared knowledge ledger.
+
+Every message includes task ID, message ID, type, sender/recipient session and pane IDs, and artifact path. Types: ASSIGN, ACK, QUESTION, BLOCKED, READY_FOR_REVIEW, REWORK, ACCEPTED. Assignments state outcome, ownership, worktree, base SHA, acceptance commands and authority. Results state exact SHA, files, actual check outputs, failures, unavailable checks and remaining risks.
+
+For an existing Codex session, read its pane text and current tree first. Verify the intended process is ready for input without a user draft or approval prompt. Unknown readiness means stage a copyable relay and report blocked; never interrupt or restart another session to force delivery.
+
+Use agtermctl session type --stdin --target <session-uuid> --pane-id <pane-id>, with socket option when needed. This injects keystrokes into a shared buffer; it is not a message queue. Send a short single-line instruction to read the brief artifact. Verify installed submission behavior; avoid multiline injection and shell interpolation. Require readback and a task-ID ACK before calling the assignment received. CLI success proves only injection. Inspect uncertain delivery before retrying to avoid duplicate work. Workers return evidence to the verified lead address using the same readiness safeguards.
+
+## Verify and recover
+
+The lead inspects the actual diff and exact SHA and independently runs acceptance checks. Obtain independent diff review under project policy. Verify local proof, commit, remote SHA, complete check rollup, deployment and human/device acceptance as separate gates when in scope. Accept only proven criteria; return concrete failures and evidence as REWORK.
+
+The lead diagnoses, repairs or reassigns failures within authority and reverifies. After two identical failures stop retrying and diagnose. Exhausted budgets or missing authority end as blocked with receipts, never accepted. Delegated workers cannot expand publishing, spending or external communication authority. Further delegation preserves parent accountability.
+
+Agterm input does not guarantee waking an idle Codex session. This skill installs no daemon. Define bounded checkpoints or supported event-driven wakeups when available; do not promise unattended monitoring. If reliable wakeup is unavailable, leave a resume instruction and task artifact path and report that limitation.
+
+Final report says delivered, blocked or intentionally unchanged, with accepted tasks, separate evidence gates, unresolved failures and the next responsible action. Never blame a worker in place of resolving or reporting failure. Do not close agent sessions automatically; preserve their evidence for inspection.

package/README.md

@@ -3,7 +3,7 @@
   <p><strong>Agent-agnostic skill catalog for Codex, Claude, Cursor, Grok, Copilot, Windsurf, Kiro, Hermes Agent, and other skill-aware tools.</strong></p>
   <p>
     <img src="https://img.shields.io/badge/license-MIT-16a34a" alt="MIT license">
-    <img src="https://img.shields.io/badge/skills-59-2563eb" alt="59 skills">
+    <img src="https://img.shields.io/badge/skills-60-2563eb" alt="60 skills">
     <img src="https://img.shields.io/badge/platforms-Codex%20%7C%20Claude%20%7C%20Cursor%20%7C%20Grok%20%7C%20Copilot%20%7C%20Windsurf%20%7C%20Kiro%20%7C%20Hermes-111827" alt="Codex Claude Cursor Grok Copilot Windsurf Kiro Hermes">
     <img src="https://img.shields.io/badge/status-public%20catalog-16a34a" alt="Public catalog">
   </p>
@@ -279,12 +279,13 @@ Take a product idea to a shippable build: MVP passes, full-stack scaffolds, UX/U
 | [ingest-publication-slice](plugins/olko-product/skills/ingest-publication-slice/SKILL.md) | Builds a test-first ingest-to-publication path with atomic persistence, read fallback, and static artifact precedence | Publishing validated ingested data before a static artifact exists |
 | [viral-launch](plugins/olko-product/skills/viral-launch/SKILL.md) | Sets up a project repository and launch plan for shareable marketing, public launch readiness, and growth loops | Preparing a repo, product, or package for public launch ("prep for Product Hunt", "write the launch post", "make this shareable"); for building the thing itself use mvp-oneshot or product-builder |
 
-### olko-skill-meta (8)
+### olko-skill-meta (9)
 
 Author and maintain agent skills and the AI toolchain itself.
 
 | Skill | What it does | Use when |
 |-------|-------------|----------|
+| [agterm-team](plugins/olko-skill-meta/skills/agterm-team/SKILL.md) | Creates named Codex sessions in project agterm workspaces and coordinates acknowledged tasks with lead-owned verification | A lead delegates work across agterm sessions and remains accountable for failures |
 | [context-repo](plugins/olko-skill-meta/skills/context-repo/SKILL.md) | Resolves a single durable, private GitHub repository other skills use to persist context they produce, retro snapshots and shared-knowledge notes among them, searching the account for a store that already exists before ever asking to create one | A skill needs a durable, cross-machine store for content it generates, rather than a local scratch directory that does not survive across machines or repos |
 | [add-to-my-skills](plugins/olko-skill-meta/skills/add-to-my-skills/SKILL.md) | Copies a newly created skill from another repo into this catalog, refreshes the README and generated manifests, then commits and pushes | Adding a skill you wrote elsewhere into this catalog |
 | [skill-budget-audit](plugins/olko-skill-meta/skills/skill-budget-audit/SKILL.md) | Diagnoses and fixes Claude Code's skill context budget overflow, identifies heavy plugin bundles that exceed the 2% budget | Skills failing to load or Claude hitting context limits from plugin bundles |

package/adapters/claude/olko-github-pr/skills/lekker-review/SKILL.md

@@ -1139,8 +1139,17 @@ printf '%s\n' "$REVIEW_FILE" > ~/.cache/lekker-review/reviewed/<headSha>
 ```
 
 Write it against the sha that was actually reviewed. When fix mode later adds
-commits, write a marker for the NEW head sha too - a gate keys on the tip
-that is about to be pushed, and a marker for a superseded sha would be a lie.
+commits, write a marker for the new head only after fix verification and
+relevant tests pass. Any unrelated edits require a fresh review; never copy a
+marker to an unreviewed SHA.
+
+**PR label for branch reviews:** follow `references/reviewed-before-push.md`.
+After a complete, non-degraded local review and settling all Critical/Important
+findings, save the final-head receipt as `<scratchpad>/pre-push-review.json`
+BEFORE pushing. That reference defines the receipt schema and one-time cleanup
+workflow setup. The label is exactly `reviewed-before-push` (no AI prefix).
+A legacy SHA/path marker alone does not qualify. PR-mode reviews cannot earn
+this label.
 
 **Close the run log** right after the receipt, then print the review:
 
@@ -1314,33 +1323,42 @@ Ask once, via AskUserQuestion:
 
 Rules for each answer:
 
-- **Yes:** push with `git push -u origin "$local_branch"`, then create the PR
+- **Yes:** set `PREDICTED_AT=$(date -u +%Y-%m-%dT%H:%M:%SZ)` before pushing
+  or publishing, including when a PR already exists. Then push with
+  `git push -u origin "$local_branch"` and create or locate the PR. Create it
   with `gh pr create --repo "$repo_slug" --base "$base_ref" --head
   "$local_branch" --title "$pr_title" --body-file "$pr_body_file"`. Derive the title
   from the commit log (the recommended prefix plus a summary of the change) and
   the body from a short summary of what the branch does - do not leave either
-  as a placeholder. Report the PR url. Then record the prediction against the
-  new PR number - a branch-mode review is the ideal case for this, because the
-  prediction provably predates every bot comment. Record only the findings fix
+  as a placeholder. Report the PR url. If an eligible pre-push receipt was
+  saved, publish it using `scripts/review-label.mjs` as described in
+  `references/reviewed-before-push.md`. This posts the commit/engine/depth/result
+  evidence and applies `reviewed-before-push` only to the matching live head.
+  If cleanup is not installed, omit the label and report the setup requirement;
+  do not undo the successful PR creation. For an existing PR found after a
+  branch-mode push, use the same helper and head check. Then record the prediction
+  against the created or existing PR number using the saved `PREDICTED_AT`;
+  scoring uses it to include bot comments triggered by the push or PR creation,
+  even if they arrive before the record step. Record only the findings fix
   mode did NOT apply (every row of the fixes table that is not `✅ applied`):
   an applied fix is gone from the code the bots read, so they cannot raise it,
   and recording it would sink precision for doing exactly what branch mode is
   for. Build `<scratchpad>/unfixed.json` (a bare array is fine) from the merged
   `findings.json` minus the findings fix mode applied; when fix mode did not
-  run or applied nothing, it is the whole merged set. Take
-  `PREDICTED_AT=$(date -u +%Y-%m-%dT%H:%M:%SZ)` just BEFORE `gh pr create`, so
-  a bot comment that lands before the record step still counts:
+  run or applied nothing, it is the whole merged set. Keep the timestamp captured
+  before the push; do not replace it at the record step:
 
   ```bash
   node ${SKILL_ROOT}/scripts/bot-precision.mjs record \
-    --repo "$repo_slug" --pr <NEW_PR_NUMBER> --predicted <scratchpad>/unfixed.json \
+    --repo "$repo_slug" --pr <PR_NUMBER> --predicted <scratchpad>/unfixed.json \
     --at "$PREDICTED_AT"
   ```
 
   The review is already saved locally; offer `--post` on the new PR number only if the user asks - findings that fix
   mode already applied must never be posted as review comments.
 - **Push only:** `git push -u origin "$local_branch"` and stop. Say in one line
-  that no PR was created.
+  that no PR was created. Keep any eligible pre-push receipt for publication
+  when a matching PR is later created; no PR means no label yet.
 - **No:** stop. Print the branch name and the review file path.
 
 **Unattended runs never ask and never create a PR** (see the operating contract

package/adapters/claude/olko-github-pr/skills/lekker-review/references/reviewed-before-push.md

@@ -0,0 +1,94 @@
+# Reviewed before push
+
+`reviewed-before-push` records a completed local branch review of the current
+PR head. It is informational: it does not satisfy CI, required remote review,
+or the human-review marker for risky changes. The review comment records the
+full head/base SHAs, engine, depth, timestamp, and result. It is an attestation
+by the publishing user, not cryptographic proof that review preceded a push.
+
+## Install stale-label cleanup once per repository
+
+Copy `references/reviewed-before-push.yml` into the target repository as
+`.github/workflows/reviewed-before-push.yml` and land it on the default branch
+through that repository's normal review process. Do this before the local
+review whose receipt will be published. Do not add a workflow commit after
+review and then label that unreviewed commit.
+
+The workflow uses only GitHub API data, with no PR checkout. On new commits or
+receipt edits/deletion it removes the label unless a receipt from an owner,
+member, or collaborator matches the live head. Pagination includes all receipt
+comments. It does not add labels or replace merge gates. A newly reviewed head
+can be labeled again by the publisher. Cleanup is asynchronous; the label is
+not a merge-authorization signal. Workflows disabled by repository policy or
+Actions outages can delay removal.
+
+The helper refuses to publish if the cleanup workflow is absent. If setup is
+missing, keep the local review and PR creation successful, omit the label, and
+report the missing setup. Never silently install a write-capable workflow in
+another repository. A push-only run keeps the receipt locally until a PR exists.
+
+## Record before pushing
+
+Only in `MODE=branch`, after the review engine completed without degraded or
+missing required dimensions, settle every Critical/Important finding. Either
+fix it with verifier/test evidence or explicitly rebut it with a reason. Open
+observations may remain. A file containing only a review path or a SHA marker
+is not sufficient evidence.
+
+Save `<scratchpad>/pre-push-review.json` before the push:
+
+```json
+{
+  "version": 1,
+  "mode": "branch",
+  "result": "passed",
+  "headSha": "<full reviewed final local HEAD>",
+  "baseSha": "<full merge-base used by this review>",
+  "engine": "codex",
+  "depth": "medium",
+  "reviewedAt": "<UTC ISO timestamp when this review completed>",
+  "findings": [
+    {
+      "severity": "important",
+      "disposition": "fixed",
+      "evidence": "<actual fix verification and relevant test result>"
+    }
+  ]
+}
+```
+
+Use an empty `findings` array when the review found nothing. Otherwise include
+every finding in the merged review and lint set. Allowed dispositions are
+`fixed`, `rebutted`, and `open`; `open` is permitted only for observations and
+idiomatic suggestions. Rebuttals require specific evidence too. Set engine and
+depth to the values actually used. Keep the saved full review locally; finding
+text, evidence text, and local paths are not uploaded by the helper.
+
+`reviewedAt` must be a valid UTC ISO timestamp in `YYYY-MM-DDTHH:mm:ssZ`
+format, optionally with fractional seconds before `Z` (for example,
+`2026-10-29T09:00:00.123Z`). Date-only strings, timezone offsets, and invalid
+calendar dates are rejected by the publisher and cleanup workflow.
+
+After fixes, the receipt must describe the final SHA: fix verification and
+relevant tests must pass, and the only intervening edits must be those verified
+fixes. Any unrelated edit requires a fresh review. Never copy a receipt to a
+new SHA just to make the label apply.
+
+## Publish after pushing and creating or locating the PR
+
+Resolve the helper relative to the selected `SKILL.md` (same directory's
+`scripts/review-label.mjs`, including in Codex). Invoke with separate process
+arguments, or independently shell-quote each value:
+
+```bash
+node "<SKILL_ROOT>/scripts/review-label.mjs" \
+  --repo "<owner/repo>" --pr "<number>" \
+  --receipt "<scratchpad>/pre-push-review.json"
+```
+
+The helper checks the live open PR head, posts the receipt, creates the label
+if needed, and applies it. It checks the head before and after labeling, and
+removes the label if a concurrent push changed the head. Errors are failures
+to publish the label, not a failed local review. Do not claim the label was
+applied when the helper failed. Do not use this helper for a review performed
+in `MODE=pr` after pushing.

package/adapters/claude/olko-github-pr/skills/lekker-review/references/reviewed-before-push.yml

@@ -0,0 +1,57 @@
+# Install this file on the target repository's default branch as
+# .github/workflows/reviewed-before-push.yml before publishing review labels.
+name: Reviewed before push
+on:
+  pull_request_target:
+    types: [opened, reopened, synchronize, edited, labeled]
+  issue_comment:
+    types: [created, edited, deleted]
+permissions:
+  contents: read
+  issues: write
+  pull-requests: read
+concurrency:
+  group: reviewed-before-push-${{ github.event.pull_request.number || github.event.issue.number }}
+  cancel-in-progress: false
+jobs:
+  reconcile:
+    if: github.event.pull_request || github.event.issue.pull_request
+    runs-on: ubuntu-latest
+    steps:
+      # No checkout: never execute code from the PR with this write token.
+      - uses: actions/github-script@3a2844b7e9c422d3c10d287c895573f7108da1b3 # v9.0.0
+        with:
+          script: |
+            const label = 'reviewed-before-push';
+            function isUtcTimestamp(value) {
+              const match = typeof value === 'string' && value.match(/^(\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2})(?:\.(\d+))?Z$/);
+              if (!match || match[0] !== value) return false;
+              const time = Date.parse(value);
+              const canonical = `${match[1]}.${(match[2] || '').padEnd(3, '0').slice(0, 3)}Z`;
+              return Number.isFinite(time) && new Date(time).toISOString() === canonical;
+            }
+            const { owner, repo } = context.repo;
+            const issue_number = context.payload.pull_request?.number || context.payload.issue.number;
+            const { data: pr } = await github.rest.pulls.get({ owner, repo, pull_number: issue_number });
+            if (!pr.labels.some(item => item.name === label)) return;
+            const comments = await github.paginate(github.rest.issues.listComments, { owner, repo, issue_number, per_page: 100 });
+            const valid = comments.some(comment => {
+              if (!['OWNER', 'MEMBER', 'COLLABORATOR'].includes(comment.author_association)) return false;
+              const match = comment.body?.match(/<!-- lekker:reviewed-before-push (\{[^\n]*\}) -->/);
+              if (!match) return false;
+              try {
+                const r = JSON.parse(match[1]);
+                return r.version === 1 && r.mode === 'branch' && r.result === 'passed'
+                  && r.headSha === pr.head.sha && /^[a-f0-9]{40}$/.test(r.baseSha)
+                  && ['workflow', 'codex', 'revmux'].includes(r.engine)
+                  && ['scan', 'medium', 'deep', 'deps'].includes(r.depth)
+                  && isUtcTimestamp(r.reviewedAt);
+              } catch { return false; }
+            });
+            if (!valid) {
+              try {
+                await github.rest.issues.removeLabel({ owner, repo, issue_number, name: label });
+              } catch (error) {
+                if (error.status !== 404) throw error;
+              }
+            }

package/adapters/claude/olko-github-pr/skills/lekker-review/scripts/review-label.mjs

@@ -0,0 +1,90 @@
+#!/usr/bin/env node
+// Publish a local branch-review receipt using gh; PR-controlled values never enter shell source.
+import { execFileSync } from 'node:child_process';
+import { readFileSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+
+export const LABEL = 'reviewed-before-push';
+export const PREFIX = '<!-- lekker:reviewed-before-push ';
+const SHA = /^[a-f0-9]{40}$/;
+
+function isUtcTimestamp(value) {
+  const match = typeof value === 'string' && value.match(/^(\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2})(?:\.(\d+))?Z$/);
+  if (!match || match[0] !== value) return false;
+  const time = Date.parse(value);
+  const canonical = `${match[1]}.${(match[2] || '').padEnd(3, '0').slice(0, 3)}Z`;
+  return Number.isFinite(time) && new Date(time).toISOString() === canonical;
+}
+
+export function validateReceipt(receipt) {
+  if (receipt?.version !== 1 || receipt.mode !== 'branch' || receipt.result !== 'passed'
+      || !SHA.test(receipt.headSha) || !SHA.test(receipt.baseSha)
+      || !['workflow', 'codex', 'revmux'].includes(receipt.engine)
+      || !['scan', 'medium', 'deep', 'deps'].includes(receipt.depth)
+      || !isUtcTimestamp(receipt.reviewedAt)
+      || !Array.isArray(receipt.findings)) {
+    throw new Error('Invalid branch-review receipt');
+  }
+  for (const finding of receipt.findings) {
+    if (!['critical', 'important', 'observation', 'idiomatic'].includes(finding.severity)
+        || !['fixed', 'rebutted', 'open'].includes(finding.disposition)
+        || (['critical', 'important'].includes(finding.severity) && finding.disposition === 'open')
+        || (['fixed', 'rebutted'].includes(finding.disposition) && !finding.evidence?.trim())) {
+      throw new Error('Findings require dispositions and evidence; no open Critical/Important finding is allowed');
+    }
+  }
+  return receipt;
+}
+
+export function reviewComment(receipt) {
+  validateReceipt(receipt);
+  // Only publish the attestation, not local paths or potentially sensitive finding text.
+  const { version, mode, result, headSha, baseSha, engine, depth, reviewedAt } = receipt;
+  const attestation = { version, mode, result, headSha, baseSha, engine, depth, reviewedAt };
+  return `Reviewed before push\n\nCommit: \`${headSha}\`\nBase: \`${baseSha}\`\nEngine: ${engine}\nDepth: ${depth}\nReviewed at: ${reviewedAt}\nResult: passed; no unresolved Critical/Important findings.\n\nThis records a local review; required CI and remote review gates still apply.\n\n${PREFIX}${JSON.stringify(attestation)} -->`;
+}
+
+export function publishReview({ repo, pr, receipt }, run = execFileSync) {
+  if (!/^[\w.-]+\/[\w.-]+$/.test(repo) || !/^[1-9]\d*$/.test(String(pr))) {
+    throw new Error('Expected --repo owner/repo and a positive --pr number');
+  }
+  const body = reviewComment(receipt);
+  const gh = (args, input) => run('gh', args, { encoding: 'utf8', input });
+  const readHead = () => JSON.parse(gh(['pr', 'view', String(pr), '--repo', repo, '--json', 'headRefOid,state']));
+  const ensureCurrent = () => {
+    const current = readHead();
+    if (current.state !== 'OPEN' || current.headRefOid !== receipt.headSha) {
+      throw new Error('PR is closed or its head differs from the reviewed commit; label withheld');
+    }
+  };
+  ensureCurrent();
+  // The installation is explicit: do not silently add a privileged workflow to someone else's repo.
+  gh(['api', `repos/${repo}/contents/.github/workflows/reviewed-before-push.yml`]);
+  gh(['api', '--method', 'POST', `repos/${repo}/issues/${pr}/comments`, '--input', '-'], JSON.stringify({ body }));
+  gh(['label', 'create', LABEL, '--repo', repo, '--color', '0E8A16', '--description', 'Local review completed for the current PR head before push', '--force']);
+  ensureCurrent();
+  gh(['pr', 'edit', String(pr), '--repo', repo, '--add-label', LABEL]);
+  // Catch a concurrent push after adding the label. The workflow also reconciles later pushes.
+  try {
+    ensureCurrent();
+  } catch (error) {
+    gh(['pr', 'edit', String(pr), '--repo', repo, '--remove-label', LABEL]);
+    throw error;
+  }
+  return { label: LABEL, headSha: receipt.headSha };
+}
+
+function main(argv) {
+  const options = {};
+  for (let i = 0; i < argv.length; i += 2) {
+    if (!['--repo', '--pr', '--receipt'].includes(argv[i]) || !argv[i + 1] || options[argv[i]]) {
+      throw new Error('Usage: review-label.mjs --repo owner/repo --pr N --receipt receipt.json');
+    }
+    options[argv[i]] = argv[i + 1];
+  }
+  if (!options['--receipt']) throw new Error('--receipt is required');
+  const receipt = JSON.parse(readFileSync(options['--receipt'], 'utf8'));
+  console.log(JSON.stringify(publishReview({ repo: options['--repo'], pr: options['--pr'], receipt })));
+}
+
+if (process.argv[1] === fileURLToPath(import.meta.url)) main(process.argv.slice(2));

package/adapters/claude/olko-skill-meta/skills/agterm-team/SKILL.md

@@ -0,0 +1,53 @@
+---
+name: agterm-team
+description: Create and coordinate Codex agents in project agterm workspaces, with readable session names, task handoffs, failure recovery, and lead-owned acceptance.
+---
+<!-- Generated by scripts/build-adapters.sh. Do not edit directly. -->
+
+# Agterm team
+
+The lead owns the outcome and all failures. Delegation transfers work, never accountability. A worker's done message requests verification; it never closes the task by itself.
+
+Read the installed agterm skill for current CLI syntax and input safeguards; if absent, use agtermctl help and do not guess commands. Read the target project's AGENTS.md and ledger.json when present. Locate and verify a checkout of oleg-koval/agents, then explicitly read roles/olko-team.md, roles/olko-engineer.md, roles/olko-qa.md and pipelines/delivery.md; read pipelines/review.md when reviewing code. Do not invent missing backbone content. Keep roles and pipelines in that repository and task automation in the skill catalog.
+
+## Plan and create sessions
+
+Write the problem, constraints, task ID, authority, acceptance checks, retry budget and terminal condition before assignment. Start with one developer; add workers only for independent work worth the coordination cost. Use isolated worktrees and explicit file ownership.
+
+Inspect fresh agtermctl tree --json output. Pass --socket with AGTERM_SOCKET when set. Identify the project's existing workspace from its session working directories and repository identity, not merely the active workspace. If multiple workspaces fit and context cannot disambiguate them, ask rather than launching into a guessed workspace. Do not move or rename unrelated sessions.
+
+Automatically create needed agent sessions in that project workspace once team orchestration is requested. Default names:
+
+- LEAD_ISSUE_123
+- SENIOR_DEV_ISSUE_123
+- QA_ISSUE_123
+- REVIEWER_PR_456
+
+For work without an issue use ROLE_TASK_SHORT_SLUG. For multiple workers on one issue append _A, _B. Keep agterm names concise and stable; Codex conversation titles may describe the task more verbosely where the installed client supports naming. Never pretend agterm naming also renames the Codex conversation.
+
+Before creating, check for a matching task session and task artifact. Reuse only a verified owned session; a matching name alone proves nothing. Record the task-to-session mapping to prevent duplicate launches after resume. Check installed session new help for workspace targeting flags. Launch Codex using session new --command with the owned worktree as cwd and the task brief as data, never by typing shell commands into another pane. Prefer no-select when supported. Do not alter sandbox, approval, model or access settings beyond the user's authority. Verify the created node belongs to the intended workspace, is realized, and has Codex as its foreground process. A returned session ID alone does not prove startup. Report startup failures without duplicate retries.
+
+## Handoff and return channel
+
+Prefer `codex queue --thread <codex-thread-uuid> --message <text>` when the installed client supports it. A Codex thread UUID is distinct from an agterm session UUID or paneID. Capture it from the running Codex session or supported app-server interface and verify the mapping; never guess it from terminal names. Queue success proves enqueueing, not execution: require a task-ID ACK and result. Check the local CLI help because this capability varies by version. Use terminal input only as the fallback below.
+
+
+Record each participant's fresh full session UUID and stable paneID from the live tree, including the lead return address. Validate hosting environment IDs against that tree; never reuse historical IDs or target active.
+
+Keep briefs and results in shared local task artifacts. The lead owns task-state writes; each developer owns a separate result artifact. Append timestamped evidence and messages. States: assigned, acknowledged, working, blocked, ready-for-review, accepted. Do not put transient coordination data in the shared knowledge ledger.
+
+Every message includes task ID, message ID, type, sender/recipient session and pane IDs, and artifact path. Types: ASSIGN, ACK, QUESTION, BLOCKED, READY_FOR_REVIEW, REWORK, ACCEPTED. Assignments state outcome, ownership, worktree, base SHA, acceptance commands and authority. Results state exact SHA, files, actual check outputs, failures, unavailable checks and remaining risks.
+
+For an existing Codex session, read its pane text and current tree first. Verify the intended process is ready for input without a user draft or approval prompt. Unknown readiness means stage a copyable relay and report blocked; never interrupt or restart another session to force delivery.
+
+Use agtermctl session type --stdin --target <session-uuid> --pane-id <pane-id>, with socket option when needed. This injects keystrokes into a shared buffer; it is not a message queue. Send a short single-line instruction to read the brief artifact. Verify installed submission behavior; avoid multiline injection and shell interpolation. Require readback and a task-ID ACK before calling the assignment received. CLI success proves only injection. Inspect uncertain delivery before retrying to avoid duplicate work. Workers return evidence to the verified lead address using the same readiness safeguards.
+
+## Verify and recover
+
+The lead inspects the actual diff and exact SHA and independently runs acceptance checks. Obtain independent diff review under project policy. Verify local proof, commit, remote SHA, complete check rollup, deployment and human/device acceptance as separate gates when in scope. Accept only proven criteria; return concrete failures and evidence as REWORK.
+
+The lead diagnoses, repairs or reassigns failures within authority and reverifies. After two identical failures stop retrying and diagnose. Exhausted budgets or missing authority end as blocked with receipts, never accepted. Delegated workers cannot expand publishing, spending or external communication authority. Further delegation preserves parent accountability.
+
+Agterm input does not guarantee waking an idle Codex session. This skill installs no daemon. Define bounded checkpoints or supported event-driven wakeups when available; do not promise unattended monitoring. If reliable wakeup is unavailable, leave a resume instruction and task artifact path and report that limitation.
+
+Final report says delivered, blocked or intentionally unchanged, with accepted tasks, separate evidence gates, unresolved failures and the next responsible action. Never blame a worker in place of resolving or reporting failure. Do not close agent sessions automatically; preserve their evidence for inspection.

package/adapters/codex/olko-skill-meta/README.md

@@ -9,3 +9,4 @@ Use the canonical skills directly:
 - `plugins/olko-skill-meta/skills/promptctl/SKILL.md`
 - `plugins/olko-skill-meta/skills/veto-routing/SKILL.md`
 - `plugins/olko-skill-meta/skills/ai-tools-setup/SKILL.md`
+- `plugins/olko-skill-meta/skills/agterm-team/SKILL.md`