docs(forge-cli): note tea verb fallback and label id vs name in tea.md

When the invoking session is the planner, skip the launch-claim and
monitor ceremony and run the loop in place. Reconcile stale pane IDs
instead of treating them as mismatches. Require clean/pushed task
worktrees before merge, review with one independent subagent, and assert
cross-ticket checks on the integration branch. Pair start/finish events
so silent phase gaps are detectable.

README.md

@@ -28,7 +28,7 @@ Many of these skills were created or originated by the following people and orga
 - [implement-spec](skills/engineering/implement-spec/SKILL.md) — Implement the result of /to-spec and /to-tickets in code.
 - [implementation-orchestrator](skills/engineering/implementation-orchestrator/SKILL.md) — Implements ready-for-agent tracker tickets through isolated worktrees, pull requests, review, conflict resolution, and merge. Use after wayfinder and planning have produced tickets, with or without a ticket ID/URL; no ticket ID/URL means process available tickets. Does not create planning tickets.
 - [improve-codebase-architecture](skills/engineering/improve-codebase-architecture/SKILL.md) — Scan a codebase for deepening opportunities, present them as a visual HTML report, then grill through whichever one you pick.
-- [orchestrate-herdr](skills/engineering/orchestrate-herdr/SKILL.md) — Drive a plan from context or @file through a published spec, linked tickets, and one-at-a-time isolated implementation to a merged PR using Herdr and Pi agents.
+- [orchestrate-herdr](skills/engineering/orchestrate-herdr/SKILL.md) — Start or monitor a Herdr/Pi planner for a published spec ticket; re-invoke after an orchestrator outage.
 - [project-context-pack](skills/engineering/project-context-pack/SKILL.md) — Use when the user wants a bounded repo context pack, project map, codebase index, or cached memory file so later work uses fd/rg/tree-sitter/LSP instead of repeated browsing.
 - [recipe-diagrams](skills/engineering/recipe-diagrams/SKILL.md) — Recipe diagrams: convert any recipe into a high-resolution Cooking for Engineers-style PNG process-flow table with aligned ingredient streams, preparation branches, joins, temperatures, timings, and finish steps. Use when the user asks for a recipe diagram.
 - [security-audit](skills/engineering/security-audit/SKILL.md) — Comprehensive security and correctness audit of a branch's changes. Use for deep review requests, or branch/PR diff audits focused on bugs, breaking changes, security issues, devex regressions, and feature-gate leaks.

skills/engineering/README.md

@@ -13,7 +13,7 @@ Daily code work.
 - [implement-spec](implement-spec/SKILL.md) — Implement the result of /to-spec and /to-tickets in code.
 - [implementation-orchestrator](implementation-orchestrator/SKILL.md) — Implements ready-for-agent tracker tickets through isolated worktrees, pull requests, review, conflict resolution, and merge. Use after wayfinder and planning have produced tickets, with or without a ticket ID/URL; no ticket ID/URL means process available tickets. Does not create planning tickets.
 - [improve-codebase-architecture](improve-codebase-architecture/SKILL.md) — Scan a codebase for deepening opportunities, present them as a visual HTML report, then grill through whichever one you pick.
-- [orchestrate-herdr](orchestrate-herdr/SKILL.md) — Drive a plan from context or @file through a published spec, linked tickets, and one-at-a-time isolated implementation to a merged PR using Herdr and Pi agents.
+- [orchestrate-herdr](orchestrate-herdr/SKILL.md) — Start or monitor a Herdr/Pi planner for a published spec ticket; re-invoke after an orchestrator outage.
 - [project-context-pack](project-context-pack/SKILL.md) — Use when the user wants a bounded repo context pack, project map, codebase index, or cached memory file so later work uses fd/rg/tree-sitter/LSP instead of repeated browsing.
 - [recipe-diagrams](recipe-diagrams/SKILL.md) — Recipe diagrams: convert any recipe into a high-resolution Cooking for Engineers-style PNG process-flow table with aligned ingredient streams, preparation branches, joins, temperatures, timings, and finish steps. Use when the user asks for a recipe diagram.
 - [security-audit](security-audit/SKILL.md) — Comprehensive security and correctness audit of a branch's changes. Use for deep review requests, or branch/PR diff audits focused on bugs, breaking changes, security issues, devex regressions, and feature-gate leaks.

skills/engineering/code-quality-review/SKILL.md

@@ -1,10 +1,10 @@
 ---
-name: thermo-nuclear-code-quality-review
+name: code-quality-review
-description: Run an extremely strict maintainability review for abstraction quality, giant files, and spaghetti-condition growth. Use for a thermo-nuclear code quality review, thermonuclear review, deep code quality audit, or especially harsh maintainability review.
+description: Run an extremely strict maintainability review for abstraction quality, giant files, and spaghetti-condition growth. Use for a code quality review, deep code quality audit, or especially harsh maintainability review.
 disable-model-invocation: true
 ---
 
-# Thermo-Nuclear Code Quality Review
+# Code Quality Review
 
 Use this skill for an unusually strict review focused on implementation quality, maintainability, abstraction quality, and codebase health.
 

skills/engineering/code-quality-review/agents/openai.yaml

@@ -0,0 +1,5 @@
+interface:
+  display_name: "Thermo-Nuclear Code Quality Review"
+  short_description: "Strict review of abstractions, large files, and condition complexity"
+policy:
+  allow_implicit_invocation: false

skills/engineering/dual-review/agents/openai.yaml

@@ -0,0 +1,5 @@
+interface:
+  display_name: "Dual Review"
+  short_description: "Parallel correctness, security, and maintainability review"
+policy:
+  allow_implicit_invocation: false

skills/engineering/feedback-bundle/agents/openai.yaml

@@ -0,0 +1,5 @@
+interface:
+  display_name: "Feedback Bundle"
+  short_description: "File Gitea issues with commit links and attached evidence"
+policy:
+  allow_implicit_invocation: false

skills/engineering/forge-cli/references/tea.md

@@ -21,6 +21,8 @@ tea comments add ID --description "$(cat BODY_FILE)"
 tea issues close ID
 ```
 
+Prefer these CLI verbs over hand-rolled REST. If `tea` lacks a verb (check `tea pulls --help` for the current close and merge verbs), and you fall back to the Gitea REST API, note that the issue create/update payload takes label **IDs**, while the `/issues/{id}/labels` sub-resource takes **names**. Keep `curl` output out of the transcript by writing it to a file (`curl -s ... -o FILE`).
+
 ## Pull request lifecycle
 
 ```bash

skills/engineering/implement-spec/SKILL.md

@@ -6,7 +6,7 @@ disable-model-invocation: true
 
 You have been provided a spec. This spec should have tickets associated with it, describing how to implement the spec.
 
-The issue tracker should have been provided to you. If not, tell the user to run `/setup-matt-pocock-skills`.
+The issue tracker should have been provided to you. If not, tell the user to run `/setup-skills`.
 
 The goal is the entire spec implemented on a single **integration branch**, with every ticket resolved the way the issue tracker closes work.
 

skills/engineering/implementation-orchestrator/SKILL.md

@@ -44,7 +44,7 @@ Comments are the message board. Record claims, status, evidence, questions, deci
 4. **Implement.** Launch one worker per ticket with `pi-subagents` in an isolated worktree, maximum three in flight by default. Pass the complete ticket, comments, acceptance criteria, non-goals, linked context, and validation contract. Each worker makes only ticket-scoped changes, commits them, and reports changed files and checks.
 5. **Escalate.** For missing requirements, unsafe ambiguity, credentials, unrelated scope, or a product/architecture decision, stop. For human review or judgment, assign the ticket to the configured human reviewer, apply `workflow:ready-for-human`, and comment the exact request. If no human identity is configured, ask before assigning and changing the state. Use `workflow:blocked` for non-human blockers. Preserve the worktree on failure.
 6. **PR.** Run documented local checks. Push the branch and create exactly one PR/MR for the ticket. Link the ticket's tracker ID and title in the PR/MR, set `workflow:pr-open`, and comment the PR/MR URL on the ticket. Keep the worktree.
-7. **Review.** Set `workflow:review`. Run a fresh-context `code-review` review with correctness/spec and standards axes separate. Post findings through the PR/MR comment/review function. For actionable findings, set `workflow:changes-requested`, send one fix worker, rerun checks, and repeat. Allow at most three rounds.
+7. **Review.** Set `workflow:review`. Run a fresh-context `code-review` review with correctness/spec and standards axes separate. Then run the `security-audit` and `code-quality-review` both in their own `reviewer` subagent. Post findings through the PR/MR comment/review function. For actionable findings, set `workflow:changes-requested`, send one fix worker, rerun checks, and repeat. Allow at most three rounds.
 8. **Conflict.** Set `workflow:conflict`, then follow `resolving-merge-conflicts`. Inspect both intents, preserve them where possible, never invent behavior, never abort, rerun local checks, and update the PR/MR. If judgment is needed, assign the PR/MR and ticket to the configured human reviewer, apply `workflow:ready-for-human`, and comment the request in both places. If no human identity is configured, ask before assigning.
 9. **Merge.** Merge only after independent review is clean, local checks pass, forge CI is green, the target is still the expected default branch, and no human decision or blocker remains. Comment the merge receipt and outcome, close the ticket, apply `workflow:merged` when supported, verify integration, then remove the worktree.
 10. **Finish.** Report merged tickets and PR/MR URLs, human handoffs, blocked tickets, failed checks, review rounds, and remaining eligible tickets. Report `done` only when no open implementation or human tickets remain in the selected scope. If only human tickets remain, report `waiting-on-human`.

skills/engineering/orchestrate-herdr/SKILL.md

@@ -1,87 +1,29 @@
 ---
 name: orchestrate-herdr
-description: "Drive a plan from context or @file through a published spec, linked tickets, and one-at-a-time isolated implementation to a merged PR using Herdr and Pi agents."
+description: "Start a Herdr/Pi planner for a published spec ticket. Invocation: /skill:orchestrate-herdr ISSUE [WORKER]; omitted worker uses the current local worker."
 disable-model-invocation: true
 ---
 
-# Orchestrate plans to merged PRs with Herdr
+# Orchestrate a spec with Herdr
 
-Turn a plan into a published spec and child tickets, then drive one tracker ticket at a time through isolated implementation, independent verification, four-axis review, and merge. The worker node is the source of truth for run state, so a later orchestrator system can reconnect and resume.
+This skill takes a tracker issue number and optional Herdr worker node. It checks whether a planner is already running for that spec; if so, it reports that and exits. Otherwise it starts a planner and exits after confirming startup. The planner runs independently; there is no need to monitor it.
 
-This skill is a **routing and safety contract**. Operational detail lives in `references/`:
+The **planner**  runs on the worker node and coordinates the spec workflow. It delegates implementation, review, and merge work to subagents—not separate CLI agents or Herdr-launched agents. Never attach to, prompt, or resume an existing agent.
 
-- `references/dispatcher.md` — select and validate the worker node, local or remote, and discover Herdr state before dispatch.
+When the invoking session is itself the planner — the local worker started the planner in this session, or no saved or matching machine and pane exists — the two identities collapse. Do not go looking for a planner to monitor: run the run-loop directly in this session, skip the launch-claim and monitor ceremony, and record the session as both orchestrator and planner in `run.json`.
-- `references/run-loop.md` — plan and publish, then the one-at-a-time task loop: claim, implement, verify, review, fix, merge, close.
-- `references/state.md` — the `.orchestrate/<slug>` state directory, recovery, cross-system sync, and cleanup.
 
-Read the reference for the phase you are in before acting in it.
+Read these references before acting:
+
+- `references/dispatcher.md` — discover an existing run or safely start a planner.
+- `references/run-loop.md` — implement and close the spec.
+- `references/state.md` — worker-side run metadata, event log, claims, and recovery.
 
 ## Prerequisites
 
-- Herdr, Pi, Git, and a forge CLI (`tea`, `gh`, or `glab`) reachable from the worker node. Run the `forge-cli` preflight in the target repo.
+The selected worker must have Herdr, Git, the target repository and credentials, this skill, and an authenticated forge CLI (`tea`, `gh`, or `glab`). Run the `forge-cli` preflight there. If a prerequisite, machine, or run identity is missing or ambiguous, stop with actionable guidance; do not guess or dispatch.
-- This skill discoverable in the worker node's Pi session. If the worker node is remote, confirm it before dispatching.
-- The target repository, Git, and credentials on the worker node.
-- If any prerequisite is missing on the selected node, stop with actionable setup guidance. Do not dispatch to an unprepared shell.
 
-## Roles
+## Workflow
 
-Keep roles distinct. Never let one role do another's work.
+1. Validate the spec issue and worker, then follow `references/dispatcher.md` to find or start its planner.
-
+2. If a planner is already active for the spec, report that and exit. Do not attach, prompt, resume, or monitor it.
-- **Orchestrator system** — the machine where this skill is invoked. Invokes and observes the workflow.
+3. If starting a planner, confirm it reaches `working`, then report the run identity and exit. The planner owns the workflow from there; retain run metadata and logs unless the user explicitly asks to delete them.
-- **Worker node** — the user-selected machine that runs the planner and worker agents and owns repository work. Local or remote, chosen at invocation. It is authoritative for run state.
-- **Worker agent** — a subagent (or remote Herdr pane running Pi) that implements or verifies a scoped task.
-- **Planner** — the agent that runs this loop. Coordinates and verifies state; does not edit product code or merge. Workers do not merge unless assigned an explicit merge task.
-
-## Phase 0 — Select and validate the worker node
-
-The worker node is authoritative for run state, so pick it before anything else.
-
-1. Select the worker node: the current machine for a local run, or a remote machine the user names. If the user did not select one and the environment is ambiguous, ask.
-2. If the node is remote, follow `references/dispatcher.md`: discover the Herdr session and pane, inspect the exact target and its repository/ref before dispatch, and confirm the node has this skill, Git, and a forge CLI. Never infer a pane ID, target a pane by display label alone, or touch unrelated panes.
-3. If the node, session, or repository is missing, ambiguous, or not ready, stop and say exactly what is missing. Do not guess.
-
-The worker node is ready when its checkout identifies the target repository, its forge CLI authenticates, and Herdr can reach the same named session.
-
-## Phase 1 — Plan and publish
-
-Work from the current conversation or an `@file` the user passes. If a reference is passed, fetch its full body and comments first.
-
-1. **Spec.** Run the `to-spec` skill to synthesize the current conversation into a spec and publish it to the current repository's tracker. Apply the `ready-for-agent` label. This is the durable record of the goal and acceptance criteria.
-2. **Tickets.** Run the `to-tickets` skill to break the spec into tracer-bullet tickets, each declaring its blocking edges, published to the same tracker in dependency order. Apply `ready-for-agent`. Each ticket is a complete, verifiable slice with acceptance criteria.
-
-Do not modify the spec after publishing except to record decisions. The spec and tickets are the scope; the loop below never widens it.
-
-## Phase 2 — Run one task at a time
-
-Process **one** in-scope, open, unblocked ticket at a time. See `references/run-loop.md` for the full loop. The loop, in order:
-
-1. **Select the frontier.** Only in-scope, open, unblocked tickets. Claim it before implementing; re-query tracker state as work advances.
-2. **Isolate.** Give the task one Git worktree and branch per `worktrees`. Never parallel-write a shared checkout.
-3. **Implement.** Dispatch a worker with the full ticket, acceptance criteria, scope boundaries, and any upstream handoffs. The worker works without access to another agent's conversation.
-4. **Verify.** For meaningful behavior changes, run an independent verifier that reports evidence; a worker's self-report is not enough.
-5. **Review.** Run all four axes — `dual-review` (correctness/security, maintainability) and `code-review` (spec, standards) — before merge.
-6. **Fix.** Send actionable findings to a scoped fix worker and recheck. Cap at **three** fix rounds; unresolved findings stop for human judgment.
-7. **Merge.** Only after all four axes pass, required local checks pass, CI is green when available, the target branch is still correct, and no human decision remains. Link the ticket in the PR.
-8. **Close.** Close the task ticket with a recorded outcome.
-
-Cross-cutting rules that apply through the loop (full detail in `references/run-loop.md`):
-
-- **Retries.** Retry transient infrastructure failures only, at most two after the first attempt (three total). Keep this budget separate from the three fix rounds. Never blindly retry semantic failures, failed checks, or rejected reviews — correct the cause first.
-- **Uncertain side effects.** Reconcile the tracker, Git, worker node, or Herdr state before repeating an operation. If the outcome stays uncertain, stop and escalate; do not blindly replay non-idempotent operations.
-- **Escalate** immediately for authentication/permission failures, unresolved state mismatches, exhausted retry or fix limits, unsafe ambiguity, or any decision requiring human judgment. Preserve state and evidence at every escalation.
-
-### Finish
-
-Close the parent spec ticket only when every in-scope task is complete, merged, verified, and run state is safely persisted. Leave it open when any work is blocked, failed, or unresolved.
-
-## Recovery
-
-On restart, follow `references/state.md`: inspect the persisted `.orchestrate/<slug>` state and native Herdr status before creating or restarting agents. A new orchestrator system syncs state from the worker node before resuming; a local copy is not authoritative. Never duplicate work solely because a planner session restarted.
-
-## Cleanup
-
-At completion, follow `references/state.md`: remove only clean task worktrees and close only run-owned Herdr panes. Preserve dirty or unresolved worktrees and the retained state. Retained state is deleted only by explicit user action.
-
-## Reporting
-
-Report merged work, PR links, verification evidence, human handoffs, blockers, and remaining work. Report `done` only when every in-scope task is merged, verified, and state is persisted.

skills/engineering/orchestrate-herdr/agents/openai.yaml

@@ -0,0 +1,5 @@
+interface:
+  display_name: "Start a spec with Herdr"
+  short_description: "Start its planner and exit after startup confirmation"
+policy:
+  allow_implicit_invocation: false

skills/engineering/orchestrate-herdr/references/dispatcher.md

@@ -1,45 +1,27 @@
-# Dispatcher: select and validate the worker node
+# Dispatcher: find or start the planner
 
-The dispatcher is one-shot. It selects the worker node, discovers and validates Herdr state, and kicks off the planner. It does not run the loop afterward.
+Invocation is `/skill:orchestrate-herdr <spec-ticket> [worker]` (for example, `/skill:orchestrate-herdr 34 obelix`). The spec issue is required. A named worker is the preferred node for a new planner; if omitted or blank, use the current local worker. Never silently select a different machine.
 
-## Local vs remote
+## Find an existing run first
 
-- **Local worker node** — the orchestrator system is the worker node. Use the current repository checkout. Skip the Herdr discovery below and run the planner in this session.
+1. Confirm the issue exists, is the parent/spec ticket, and is open. If closed, report completion and do not launch anything.
-- **Remote worker node** — the user names another machine. Discover its Herdr session, workspace, and pane, confirm the repository/ref, then start the planner there.
+2. Resolve the named worker with `herdr machine list`; it is the target for a new run. To find an existing run, inspect enabled saved machines using their exact labels/IDs and `herdr --machine <machine> agent list`.
+3. Read the issue's `in-progress` label and locate its `.orchestrate/<slug>/run.json` on candidate worker checkouts. Match exact recorded Herdr workspace/pane/agent IDs. Agent listings show runtime identity and status, not the spec issue; use a working directory only to locate a candidate checkout, never as proof of ownership. If the recorded pane no longer exists, match the live `herdr agent list` entry and rewrite `run.json` to it, logging the reconciliation; a stale ID is a reconciliation event, not a mismatch. `herdr machine list` reporting no saved machines means the local session is the worker.
+4. If a matching planner is active, monitor it; do not start another. If that planner is this session, the identities have collapsed: continue the run loop here instead of monitoring. If the matching run exists but the label is missing, verify the run identity, add `in-progress`, comment on the reconciliation, and monitor.
+5. If `in-progress` is set but no matching agent can be found, do not start a planner. Refresh Herdr and run state to account for propagation delay; if still unmatched, comment on the parent issue with the mismatch and evidence, then stop for human direction. Do not clear the label automatically.
+6. If there is no matching agent and no `in-progress` label, reconcile any existing run metadata, issue comments, and Git state. If there is no active or ambiguous work, proceed to start a planner. If anything is uncertain, stop rather than risk duplicate work.
 
-If the user did not select a node and the environment does not make it obvious, ask. Do not default to a guess.
+For an untracked agent, do not attach to it or assume it belongs to this spec. Flag it for human review if it appears relevant; otherwise leave it untouched.
 
-## Preconditions
+## Start a new planner
 
-- Check Herdr access on the node: `HERDR_ENV=1`, `HERDR_WORKSPACE_ID`, and that the `herdr` CLI can reach the same named session.
+1. On the selected worker, acquire a per-spec launch claim using an atomic exclusive create under `.orchestrate/`. If another invocation holds the claim, reconcile its owner and run state; never steal an uncertain claim.
-- Resolve the explicit session from `HERDR_SESSION`; if unset, inspect `herdr session list` and ask if more than one plausible session exists. Pass `--session <name>` to every Herdr command; the environment variable alone can fall back to another server.
+2. Create a new sibling pane in the confirmed repository checkout and start a fresh Pi planner agent there. Never use an existing agent pane as the planner. Give the planner the issue number, worker identity, repository path, and references to `run-loop.md` and `state.md`.
-- Confirm the node has this skill discoverable, plus Git and a working forge CLI (run the `forge-cli` preflight). If not, explain the setup needed; do not dispatch to an unprepared shell.
+3. The planner's first action is to set/verify the spec's `in-progress` label, before reading tickets or dispatching agents. It then records its Herdr IDs in `run.json` and begins the run loop.
+4. Confirm the planner reaches `working` and the label is set. Release the launch claim only after confirmed startup. If startup failure is confirmed, release the claim and report the failure. If the outcome is uncertain, retain the claim and stop; do not retry blindly.
 
-## Discover, do not guess
+## Start confirmation and failures
 
-Never infer a pane ID, an agent status, or a repository path. Discover and inspect them first. Do not close, rename, move, or reconfigure unrelated panes.
+After launching, confirm the planner reaches `working` and the `in-progress` label is set. Then report its run identity and exit; do not wait for later state changes or monitor its agents. If the machine is unreachable, check it with `herdr machine status`; when authentication is needed, run `herdr machine reconnect <label-or-id>` and verify connectivity. Retry transient connection failures at most twice after the first attempt. If the run cannot be safely identified, comment with the blocker and stop; do not dispatch to a different worker.
 
-```bash
+Herdr machine commands require an enabled saved machine and reachable, API-compatible Herdr server. A failed connection does not prove a mutation failed; reconcile remote state before retrying.
-herdr --session "$SESSION" session list
-herdr --session "$SESSION" pane list --workspace "$HERDR_WORKSPACE_ID"
-herdr --session "$SESSION" pane read <pane-id> --source recent-unwrapped --lines 200
-```
-
-Before dispatching, confirm the target pane is the intended remote Pi pane and that its repository/ref is correct. Inspect the exact target and repository/ref before dispatch — work starts in the intended environment, never a guessed one.
-
-## Kick off the planner
-
-Confirm the node has `orchestrate-herdr` available. If not, stop and explain that this skill must be installed or discoverable in the remote Pi session.
-
-Send the root kickoff as a separate text action followed by Enter; a TUI paste burst can swallow Enter. Use the exact pane ID returned by Herdr, never a guessed ID.
-
-```bash
-herdr --session "$SESSION" pane send-text <pane-id> "/skill:orchestrate-herdr You are the root planner for: <goal>"
-# After the text is present in the pane:
-herdr --session "$SESSION" pane send-keys <pane-id> enter
-herdr --session "$SESSION" agent wait <pane-id> --until working --timeout 120000
-```
-
-If the text was not submitted, inspect the pane and dismiss any slash-command popup with `escape`; do not blindly resend and create duplicate runs. Never claim kickoff succeeded on changed pane text alone: confirm native status became `working`.
-
-Wait for Herdr's native `working` status, then report the root pane/session and stop. Do not wait for the whole orchestration tree.

skills/engineering/orchestrate-herdr/references/run-loop.md

@@ -1,73 +1,53 @@
-# Run loop: one ticket at a time
+# Run loop: implement a spec ticket
 
-The loop drives one tracker ticket through implementation, verification, review, and merge, then moves to the next. The tracker is the source of truth; read the spec, the current ticket, and its comments before acting.
+The spec and linked tickets define scope; the tracker is the source of truth. The planner's first action is to set/verify the parent issue's `in-progress` label. Then read the spec, every associated ticket, blockers, and relevant comments. If the spec has no linked implementation tickets forming an actionable frontier, invoke `/to-tickets` and follow its approval and publishing process before implementation. If tickets are blocked, don't invent extra work.
 
-## Scope control
+The issue tracker should have been provided. If not, tell the user to run `/setup-skills`.
 
-The spec and tickets are the scope. Never widen it. For a supplied ticket, inspect only that ticket; do not process its siblings, parent, or descendants. Re-query tracker state as work advances; a ticket's status or blockers may have changed since it was selected.
+The goal is the entire spec implemented on one **integration branch**, with each ticket resolved according to tracker semantics. Treat tickets as a dependency graph; re-query the tracker as the ready frontier changes. If no ticket is actionable, report the blocker rather than guessing.
 
-## 1. Select the frontier
+## Communication
 
-Select only in-scope, open, unblocked tickets. Use native blocker/dependency relationships; otherwise require explicit blocker markers or linked URLs. Never infer order from titles. Claim the selected ticket before implementing.
+All agent communication and handoffs go through tracker or PR comments; `.orchestrate/<slug>/events.jsonl` is only the operational event log. Keep comments concise and link to context rather than copying ticket bodies or pane output.
 
-## 2. Isolate
+- Implementers post their completion handoff or blocker on the task issue, including branch/commit, changed files, acceptance evidence, checks, and concerns.
+- Reviewers put review discussion on the PR. Record the review outcome on the task issue.
+- The planner posts parent-spec comments at meaningful milestones: implementation ready, review outcome, merge, actionable blocker, and completion. Don't repeat comments already posted by a worker.
 
-Give the task one Git worktree and branch. Use the current checkout when the worker node is local; when remote, use the canonical `.bare` worktree layout and the agreed owner/repository worktree location. Create a branch such as `issue-<N>-<slug>` on a clean base; never reuse a dirty worktree. Never parallel-write a shared checkout.
+## 1. Read and establish the integration branch
 
-## 3. Implement
+- Confirm the supplied issue is the parent/spec ticket and identify linked implementation tickets.
+- Understand the task graph and current frontier. Re-query tracker state as work advances.
+- When tickets require codebase or external-documentation exploration, use a subagent and put concise findings in the relevant tracker comment for later subagents to reference.
+- Create one integration branch from the intended target branch. If a PR is required, open a draft after the first implementation merge and link it to close the spec and tickets.
+- If a ticket or its dependencies are ambiguous, stop and ask rather than infer.
 
-Dispatch one worker per task with a self-contained prompt: its role and one scoped outcome, the overall goal for context, allowed/forbidden paths and acceptance checks, its worktree path and starting branch, any upstream handoffs, and instructions to run focused checks, commit on the task branch, and not merge/rebase/open a PR unless the task explicitly requires it. The worker receives the full ticket, acceptance criteria, scope boundaries, and required upstream handoffs — no access to another agent's conversation.
+## 2. Implement the frontier
 
-## 4. Verify
+Use the `subagents` skill and native subagent workflow for every child role. Do not use Herdr agent commands or launch separate CLI processes for implementers, reviewers, fixers, or mergers.
 
-For meaningful behavior changes, run an independent verifier that runs the checks and reports evidence. The verifier must not modify the target source; its evidence overrides a worker's self-report. Name the target, branch, acceptance criteria, and an exact recipe — concrete commands or repro steps, not "test it."
+For each open, unblocked ticket, start a **worker subagent** from the planner using the native subagent workflow, with its own worktree and branch. Independent frontier tickets may run concurrently; never parallel-write a shared checkout. Do not launch implementers, reviewers, fixers, or mergers as separate CLI or Herdr agents; the planner is the only full CLI agent. Start a fresh worker subagent for each merge.
 
-## 5. Review — four axes
+Start each implementer with its role, task-issue URL, worktree path, and starting branch; the issue itself holds scope and acceptance criteria. Put any later clarification or handoff in tracker/PR comments, not agent-to-agent chat. Require the implementer to:
 
-Run all four axes before merge. `code-review` covers **spec** (does the code match the originating issue?) and **standards** (does it follow the repo's documented standards?). `dual-review` covers **correctness/security** and **maintainability**. All four must pass before merge.
+- confirm its worktree starts from the current integration branch (reset/rebase onto it if needed);
+- use the `tdd` skill and run focused checks;
+- commit its ticket work on its task branch;
+- merge the latest integration branch into its task branch before reporting done;
+- post its handoff on the task issue; do not merge to the integration branch or open a PR.
 
-Run the review against the base branch and the task's diff. Post findings through the tracker/PR comment or review function and link them from the ticket.
+When an implementer finishes, have a **new independent reviewer subagent** run the `code-review`, `security-audit`, and `code-quality-review` skills against that task branch, using the current integration branch as the base. Put review discussion on the PR and summarize its outcome on the task issue. Resolve actionable findings in a fresh scoped worker subagent and rerun review until clear. Only then use a fresh worker subagent to merge the task branch into the integration branch. Before dispatching the merger, confirm the task worktree is clean (`git status --porcelain` empty) and the task branch is fully pushed; recover unpushed or uncommitted work rather than merging around it. Verify the merge and update tracker state before dispatching newly unblocked tickets. Reconcile uncertain Git or tracker outcomes before retrying.
 
-## 6. Fix rounds
+When a check spans tickets — for example one coverage threshold covering several modules — an individual task branch can be red because it owns only part of the check, not because of a defect. Review still runs against the task branch, but assert the shared check after merge, on the integration branch; merge-then-fix is the allowed order in that case. Before deviating from green-before-merge, decide whether the check or the branch is mis-scoped, and record that decision.
+ 
+## 3. Final review and completion
 
-Send actionable findings to a scoped fix worker and recheck. Cap at **three** fix rounds; unresolved findings stop for human judgment rather than guessing. Keep this budget separate from the retry budget below.
+After all tickets are implemented and merged, have a **reviewer subagent** run `code-review` against the entire integration branch as a final integration review. Have a fresh worker subagent fix actionable findings in a scoped worktree; merge the fixes and rerun review until clear. Do not report completion until this review is clear and final checks pass; do not merge around unresolved findings or failed checks.
 
-## 7. Merge
+If a draft PR exists, mark it `needs-review` after final checks. Otherwise, resolve each ticket according to tracker close semantics and report the integration branch. Close the parent spec ticket only when all work is complete, verified, and merged. As part of closing it, remove the `in-progress` label. Clean only confirmed-clean implementer worktrees and issue branch that have been merged successfully in draft PR; retain unresolved work and the worker-side run log.
 
-Merge only after every gate passes:
+## Retry and escalation rules
 
-- all four review axes pass and findings are resolved;
+- Retry transient infrastructure failures at most twice after the first attempt. Never blindly retry semantic failures, failed checks, or rejected reviews.
-- required local checks pass;
+- If an operation's outcome is uncertain, reconcile tracker, Git, worker, and Herdr state before repeating it.
-- CI is green when available (the current Gitea host has no CI; this gate is silent when CI is absent);
+- Stop and preserve state/evidence for auth or permission failures, unresolved state mismatches, exhausted retries, ambiguity, or decisions requiring human judgment.
-- the target branch is still the expected default branch;
-- no human decision or blocker remains.
-
-Create exactly one PR per task and link the ticket's number and title in it. Do not use auto-merge, admin/bypass, or force. Merge after every gate passes; never merge around a failed check, unresolved finding, or missing decision.
-
-## 8. Close
-
-Close the task ticket with a recorded outcome once its PR is merged and completion is verified. Leave it open when any in-scope work is blocked, failed, or unresolved.
-
-## Retries
-
-Retry transient infrastructure failures only, at most two retries after the first attempt (three total). Keep this budget separate from the three fix rounds. Never blindly retry semantic failures, failed checks, or rejected reviews — correct the cause first. Cap retries; do not respawn indefinitely.
-
-## Uncertain side effects
-
-For an uncertain side effect, reconcile the tracker, Git, worker node, or Herdr state before repeating the operation. If the outcome stays uncertain, stop and escalate; do not blindly replay non-idempotent operations. Reconciliation prevents duplicate agents, worktrees, comments, PRs, merges, or state transitions.
-
-## Escalation
-
-Escalate immediately, preserving state and evidence:
-
-- authentication or permission failures;
-- unresolved state mismatches;
-- exhausted retry or fix limits;
-- unsafe ambiguity;
-- any decision requiring human judgment.
-
-For a human decision or judgment call, assign the ticket to the configured human reviewer, mark it for human review, and comment the exact request. If no human identity is configured, ask before assigning; never invent one.
-
-## Finish
-
-When every in-scope task is complete, merged, and verified, close the parent spec ticket and record that run state is safely persisted. Report merged work, PR links, verification evidence, human handoffs, blockers, and remaining work. Report `done` only when no in-scope work remains.

skills/engineering/orchestrate-herdr/references/state.md

@@ -1,48 +1,33 @@
-# State, recovery, and cleanup
+# Worker-side run state and recovery
 
-Run state lives under a run-scoped `.orchestrate/<slug>` directory in the worker node's repository checkout. The worker node is the source of truth. Keep this state out of product commits and PRs.
+The worker node is the source of truth. Keep state under `.orchestrate/<slug>/` in the target repository checkout, outside product commits and PRs. Use a stable issue-derived slug such as `spec-34`; do not mirror state on the orchestrator node.
 
-## State directory
+## Files
 
-Create `.orchestrate/<slug>/` on the worker node:
+- `run.json` — minimal recovery metadata: spec issue ID/URL, repository identity, worker label/ID, planner's Herdr agent/pane/workspace IDs, and each tracked child subagent's role, issue ID, subagent run ID, branch, and worktree.
+- `events.jsonl` — append-only structured operational events: timestamp, actor/task, action, outcome, and relevant Herdr/Git/tracker IDs. No pane transcripts, copied ticket bodies, plans, or handoff prose. Record a start and finish event for every phase (worktree created, implementer handoff, review dispatched, review completed, merge completed); a phase with only one of the pair is a detectable gap, whereas a silent absence is not.
 
-- `plan.json` — the original goal, repo path/URL, base ref, acceptance criteria, and task definitions (name, type, scoped goal, dependencies, path boundaries, acceptance, verification recipe, retry cap).
+The issue tracker is canonical for ticket status, acceptance criteria, decisions, and communication. Keep agent handoffs and blockers in comments on the relevant task issue; use PR comments for review discussion; use parent-spec comments for milestone rollups. Do not create local handoff files or duplicate tracker content in `run.json`.
-- `state.json` — each task's status, attempt count, worktree path, branch, Herdr session/workspace/pane IDs, and handoff path.
-- `handoffs/<task>.md` — each agent's final response, saved verbatim with task, branch, and execution metadata.
-- `recovery.log` — spawns, recovery, reconciliation, and operator decisions.
 
-Use kebab-case task names. Validate that dependencies and verifier targets exist and that the dependency graph has no cycles before starting work.
+## Claim and label
 
-## Persist immediately
+Before creating a planner, acquire a per-spec launch claim under `.orchestrate/` with an atomic exclusive create. The claim only serializes startup; it is not a second progress record. Record its owner and issue ID. Never steal an uncertain claim.
 
-Persist state immediately after every side effect and record enough Herdr, branch, worktree, and task identity to reconcile execution after interruption. On restart, inspect persisted state and native Herdr status before creating or restarting agents. Never duplicate work solely because a planner session restarted.
+The new planner's first action is to set/verify the parent's `in-progress` label, before reading tickets or dispatching work. After confirmed startup and recording the planner's Herdr IDs, release the launch claim. Release a claim after startup failure only when failure and absence of a running planner are confirmed. Keep it and escalate when the result is uncertain.
 
-A new orchestrator system reconnects to the worker node and syncs from it before resuming; a local copy is not authoritative. Do not create a separate Git branch solely to transfer this state.
+If the parent has `in-progress` but no matching agent is found, do not start a replacement or clear the label. Comment with the mismatch and wait for the user's explicit retry decision. If a matching agent exists but the label is missing, verify the run record, add the label, and comment on the repair.
 
-## Recovery
+## Persist and recover
 
-On restart, in order:
+Append a structured event after each consequential side effect and enough identity data to match the run to Herdr. The worker log records activity while the orchestrator is unavailable; agents continue posting comments to the tracker.
 
-1. Read `plan.json`, `state.json`, and `handoffs/`.
+On every invocation or restart:
-2. Discover native Herdr state and reconcile stored IDs with what Herdr actually reports.
-3. Reconcile tracker and Git state.
-4. Reattach to running agents; never duplicate a task just because the session restarted.
 
-If reconciliation cannot resolve a state mismatch, stop and escalate rather than guessing.
+1. Read the parent issue, labels, and relevant comments.
+2. Inspect the worker's `run.json` and event log.
+3. Query Herdr agent state and match exact recorded IDs; do not infer ownership from a matching working directory. If the recorded pane was recreated or removed between sessions, match the live entry, rewrite `run.json` to it, and log the reconciliation.
+4. Reconcile tracker and Git state before deciding to start a planner. If the worker is unreachable or identities/state disagree, report the blocker and stop rather than guessing.
 
-## Handoffs
+If a matching live planner exists, report that it is already running and exit; do not attach to, prompt, or resume it. The planner manages its own subagents. If there is no matching agent and no `in-progress` label, reconcile any stale run record; start a fresh planner only when no active or ambiguous work remains and a new atomic claim is acquired.
 
-Handoffs are the only information channel between workers and planners. Save each final response verbatim; add a short metadata comment above it with task, branch, worktree, and Herdr identifiers. Do not paraphrase the evidence.
+Retain `run.json` and `events.jsonl` after completion. The planner removes `in-progress` while closing the parent spec only after all tickets are complete, verified, and merged. Delete retained run state only at the user's explicit request.
-
-- **Worker** — status (`success`/`partial`/`blocked`), actual branch, what it did, acceptance with evidence, verification tier, commands run, concerns, suggested follow-ups. A worker commits to its task branch and does not merge/rebase/open a PR unless the task requires it. Do not accept `success` if stated acceptance is unmet or evidence is absent.
-- **Verifier** — verification tier, target, execution, findings per criterion (met/not met/n/a) with severity, and environment limits. `verifier-blocked` means the environment prevented a meaningful check; `verifier-failed` means the check ran and the target did not pass. Do not downgrade a failure to a blocked verdict.
-- **Planner** — an aggregated handoff to the parent: status, actual deliverable branch, one bullet per meaningful slice, strongest evidence actually produced, risks, and parent-scope follow-ups.
-
-## Cleanup
-
-At completion, remove only what this run owns and leave everything else untouched.
-
-- **Remove** clean task worktrees (via `git worktree remove`, after accounting for every staged, unstaged, and untracked change) and close only Herdr panes created by this run.
-- **Preserve** dirty or unresolved worktrees — cleanup cannot destroy unfinished work or recovery evidence.
-- **Retain** the worker node's canonical checkout, `.orchestrate/<slug>` state, handoffs, and logs. Never delete retained state automatically. Cleanup of retained state requires an explicit user action.
-- Leave unrelated Herdr panes, tickets, repositories, branches, and PRs untouched.

skills/engineering/recipe-diagrams/agents/openai.yaml

@@ -0,0 +1,5 @@
+interface:
+  display_name: "Recipe Diagrams"
+  short_description: "Turn recipes into process-flow diagrams"
+policy:
+  allow_implicit_invocation: false

skills/engineering/security-audit/SKILL.md

@@ -1,7 +1,6 @@
 ---
 name: security-audit
 description: Comprehensive security and correctness audit of a branch's changes. Use for deep review requests, or branch/PR diff audits focused on bugs, breaking changes, security issues, devex regressions, and feature-gate leaks.
-disable-model-invocation: true
 ---
 
 # Security Audit Skill

skills/engineering/security-audit/agents/openai.yaml

@@ -0,0 +1,5 @@
+interface:
+  display_name: "Security Audit Skill"
+  short_description: "Audit diffs for security and correctness risks"
+policy:
+  allow_implicit_invocation: false

skills/engineering/worktrees/agents/openai.yaml

@@ -0,0 +1,5 @@
+interface:
+  display_name: "Git Worktrees"
+  short_description: "Manage worktrees under a canonical repository root"
+policy:
+  allow_implicit_invocation: false

skills/engineering/write-discoverable-code/agents/openai.yaml

@@ -0,0 +1,5 @@
+interface:
+  display_name: "Write Discoverable Code"
+  short_description: "Write searchable identifiers, comments, and file names"
+policy:
+  allow_implicit_invocation: false

skills/misc/bro/agents/openai.yaml

@@ -0,0 +1,5 @@
+interface:
+  display_name: "Bro"
+  short_description: "Restate messages in plain language"
+policy:
+  allow_implicit_invocation: false

skills/misc/show-me/agents/openai.yaml

@@ -0,0 +1,5 @@
+interface:
+  display_name: "Show Me"
+  short_description: "Explain topics with diagrams and concise artifacts"
+policy:
+  allow_implicit_invocation: false

skills/misc/visual-verification/agents/openai.yaml

@@ -0,0 +1,5 @@
+interface:
+  display_name: "Visual Verification"
+  short_description: "Verify desktop UI changes with screenshots and recordings"
+policy:
+  allow_implicit_invocation: false

skills/personal/arch-maintenance/agents/openai.yaml

@@ -0,0 +1,5 @@
+interface:
+  display_name: "Arch Maintenance"
+  short_description: "Keep Arch and CachyOS systems updated and healthy"
+policy:
+  allow_implicit_invocation: false

skills/personal/arch-troubleshooting/agents/openai.yaml

@@ -0,0 +1,5 @@
+interface:
+  display_name: "Arch Troubleshooting"
+  short_description: "Diagnose and repair Arch and CachyOS problems"
+policy:
+  allow_implicit_invocation: false

skills/pstack/bugfix-regression-test/agents/openai.yaml

@@ -0,0 +1,5 @@
+interface:
+  display_name: "Bug-Fix Regression Test"
+  short_description: "Fix bugs test-first with focused regression tests"
+policy:
+  allow_implicit_invocation: false

skills/pstack/fix-merge-conflicts/agents/openai.yaml

@@ -0,0 +1,5 @@
+interface:
+  display_name: "Fix Merge Conflicts"
+  short_description: "Resolve merges and validate the resulting code"
+policy:
+  allow_implicit_invocation: false

skills/pstack/how/agents/openai.yaml

@@ -0,0 +1,5 @@
+interface:
+  display_name: "How"
+  short_description: "Explain code behavior, flow, and architectural ownership"
+policy:
+  allow_implicit_invocation: false

skills/pstack/interrogate/agents/openai.yaml

@@ -0,0 +1,5 @@
+interface:
+  display_name: "Interrogate"
+  short_description: "Challenge code and plans with independent reviews"
+policy:
+  allow_implicit_invocation: false

skills/pstack/reflect/SKILL.md

@@ -42,6 +42,7 @@ Show the complete Accepted / Rejected / Backlog output and wait for explicit use
 
 For each approved item, follow its Routing field:
 
+- Package-installed skill (for example under `node_modules` or a marketplace directory): do not edit it — the change is lost on update. Route the lesson to project-level config or a project skill, or report it as a backlog item instead.
 - Trivial edit to an existing skill: edit it directly.
 - Substantive edit to an existing skill: use the harness's established skill-authoring workflow, if available; otherwise draft and validate the smallest clear change.
 - Description needs tuning: improve the target skill's routing description using its supported metadata format.

skills/pstack/reflect/agents/openai.yaml

@@ -0,0 +1,5 @@
+interface:
+  display_name: "Reflect"
+  short_description: "Turn durable learnings into targeted skill improvements"
+policy:
+  allow_implicit_invocation: false

skills/pstack/unslop/agents/openai.yaml

@@ -0,0 +1,5 @@
+interface:
+  display_name: "Unslop"
+  short_description: "Edit prose to remove AI patterns while preserving meaning"
+policy:
+  allow_implicit_invocation: false

skills/pstack/why/agents/openai.yaml

@@ -0,0 +1,5 @@
+interface:
+  display_name: "Why"
+  short_description: "Investigate code rationale using historical evidence"
+policy:
+  allow_implicit_invocation: false

skills/skill-authoring/effective-agent-skills/agents/openai.yaml

@@ -0,0 +1,5 @@
+interface:
+  display_name: "Agent Skills: A Complete Guide"
+  short_description: "Write and improve effective agent skills"
+policy:
+  allow_implicit_invocation: false

skills/thinking-and-docs/brain-to-docs/agents/openai.yaml

@@ -0,0 +1,5 @@
+interface:
+  display_name: "Brain to Docs"
+  short_description: "Extract project vision and decisions into README and ADRs"
+policy:
+  allow_implicit_invocation: false

skills/thinking-and-docs/next-decision/agents/openai.yaml

@@ -0,0 +1,5 @@
+interface:
+  display_name: "Next Decision"
+  short_description: "Drill the next open decision with choices and a recommendation"
+policy:
+  allow_implicit_invocation: false

skills/thinking-and-docs/prompt-me/agents/openai.yaml

@@ -0,0 +1,5 @@
+interface:
+  display_name: "Prompt Me"
+  short_description: "Ask pointed questions to surface project priorities"
+policy:
+  allow_implicit_invocation: false

skills/thinking-and-docs/save-idea/agents/openai.yaml

@@ -0,0 +1,5 @@
+interface:
+  display_name: "Save Idea"
+  short_description: "Capture video and podcast ideas in the content backlog"
+policy:
+  allow_implicit_invocation: false