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.

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/orchestrate-herdr/SKILL.md

@@ -1,14 +1,16 @@
 ---
 name: orchestrate-herdr
-description: "Start or monitor a Herdr/Pi planner for a published spec ticket. Invocation: /skill:orchestrate-herdr ISSUE [WORKER]; omitted worker uses the current local worker."
+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 a spec with Herdr
 
-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 monitors it. Otherwise it starts a planner. Re-run the same command after an orchestrator outage to reconnect monitoring.
+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.
 
-The **orchestrator** is the agent session invoking this skill. The **planner** is a fresh agent on the worker node that coordinates the spec workflow. Implementer, reviewer, and merger agents do scoped tasks. Never attach to or resume an existing agent; monitor it through Herdr's read-only agent commands.
+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.
+
+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`.
 
 Read these references before acting:
 
@@ -23,8 +25,5 @@ The selected worker must have Herdr, Git, the target repository and credentials,
 ## Workflow
 
 1. Validate the spec issue and worker, then follow `references/dispatcher.md` to find or start its planner.
-2. Monitor the planner and its scoped agents using Herdr's list/wait/get/read commands. Do not attach, prompt, resume, or otherwise control existing agents.
-3. Keep operational events in the worker's `.orchestrate/<slug>/`; use issue and PR comments for communication as defined in `references/run-loop.md`.
-4. Continue until the parent spec issue is closed or human action is required. The planner removes the `in-progress` label as it closes the spec. Retain run metadata and logs unless the user explicitly asks to delete them.
-
-There is no background service. After the orchestrator returns, invoke the same skill with the spec issue and worker node to resume monitoring.
+2. If a planner is already active for the spec, report that and exit. Do not attach, prompt, resume, or monitor it.
+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.

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

@@ -1,5 +1,5 @@
 interface:
-  display_name: "Start or monitor a spec with Herdr"
-  short_description: "Start or monitor its planner; completion is parent-ticket closure"
+  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

@@ -6,8 +6,8 @@ Invocation is `/skill:orchestrate-herdr <spec-ticket> [worker]` (for example, `/
 
 1. Confirm the issue exists, is the parent/spec ticket, and is open. If closed, report completion and do not launch anything.
 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.
-4. If a matching planner is active, monitor it; do not start another. If the matching run exists but the label is missing, verify the run identity, add `in-progress`, comment on the reconciliation, and monitor.
+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.
 
@@ -20,12 +20,8 @@ For an untracked agent, do not attach to it or assume it belongs to this spec. F
 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.
 
-## Monitor and recover
+## Start confirmation and failures
 
-Use Herdr's read-only commands (`agent list`, `agent wait`, `agent get`, and `agent read`) to observe agents. Do not use `agent attach`, send prompts/keys, or resume existing agents. Wait for Herdr state changes and periodically reconcile agent IDs, worker event logs, tracker comments, and Git state.
-
-The same skill invocation is the recovery entry point after an orchestrator outage. Workers continue their issue/PR comments and structured event logging while the orchestrator is unavailable. On re-invocation, inspect current state before doing anything. There is no startup daemon.
-
-If a 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. Continue monitoring other reachable work. If the run cannot be safely identified, comment with the blocker and stop; do not dispatch to a different worker.
+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.
 
 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.

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

@@ -13,19 +13,20 @@ All agent communication and handoffs go through tracker or PR comments; `.orches
 - 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.
-- The monitor posts only unreported actionable mismatches or blockers. It does not send agent prompts or take recovery actions.
 
 ## 1. Read and establish the integration branch
 
 - 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 an exploration agent and put concise findings in the relevant tracker comment for later agents to reference.
+- 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.
 
 ## 2. Implement the frontier
 
-For each open, unblocked ticket, start a **new implementer agent** in its own worktree and branch. Independent frontier tickets may run concurrently; never parallel-write a shared checkout. Start a fresh merger agent for each merge.
+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 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.
 
 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:
 
@@ -35,13 +36,15 @@ Start each implementer with its role, task-issue URL, worktree path, and startin
 - 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.
 
-When an implementer finishes, have a **new independent reviewer agent** 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 fix agent and rerun review until clear. Only then use a fresh merger agent to merge the task branch into the integration branch. Verify the merge and update tracker state before dispatching newly unblocked tickets. Reconcile uncertain Git or tracker outcomes before retrying.
+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.
+
+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
 
-After all tickets are implemented and merged, run `code-review` against the entire integration branch as a final integration review. Have a fresh implementer 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.
+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.
 
-If a draft PR exists, mark it ready for 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; retain unresolved work and the worker-side run log.
+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.
 
 ## Retry and escalation rules
 

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

@@ -4,8 +4,8 @@ The worker node is the source of truth. Keep state under `.orchestrate/<slug>/`
 
 ## Files
 
-- `run.json` — minimal recovery metadata: spec issue ID/URL, repository identity, worker label/ID, run status, and each tracked agent's role, issue ID, Herdr agent/pane/workspace IDs, 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.
+- `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.
 
 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`.
 
@@ -15,7 +15,7 @@ Before creating a planner, acquire a per-spec launch claim under `.orchestrate/`
 
 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.
 
-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, comment on the repair, and monitor.
+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.
 
 ## Persist and recover
 
@@ -25,9 +25,9 @@ On every invocation or restart:
 
 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.
+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.
 
-A matching live planner means monitor it through Herdr's read-only list/wait/get/read commands. Never attach to, prompt, or resume it. 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.
+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.
 
 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.

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.