From 18ef02a331ece9d5d31700d96a6b2fc1edaf4ed6 Mon Sep 17 00:00:00 2001 From: Steve Beaulac Date: Tue, 6 Oct 2026 12:45:12 -0400 Subject: [PATCH 1/3] feat: add orchestrate-herdr skill and dual-review; make to-spec/to-tickets agent-invocable Add an explicitly invoked Pi orchestration skill that drives a plan from the current conversation or an @file through a published spec, linked dependency-aware tickets, and one-at-a-time isolated implementation to a merged PR, using Herdr and Pi agents with no Bun CLI or orchestration runtime. - orchestrate-herdr (SKILL.md + dispatcher/run-loop/state references): worker-node selection and Herdr discovery/validation, plan-and-publish, one-at-a-time task loop (claim, isolate, implement, verify, four-axis review, scoped fix rounds max three, transient retries max two, reconcile uncertain side effects, escalate), PR/merge/close gates, authoritative worker-node state, cross-system recovery, and owned-only cleanup that preserves dirty worktrees and retained state. - dual-review: self-contained correctness/security + maintainability review axis (four-axis review with code-review). - to-spec and to-tickets: drop disable-model-invocation so the orchestration workflow can invoke them. - READMEs: list the two new skills. --- README.md | 2 + skills/engineering/README.md | 2 + skills/engineering/dual-review/SKILL.md | 49 +++++++++++ skills/engineering/orchestrate-herdr/SKILL.md | 87 +++++++++++++++++++ .../references/dispatcher.md | 45 ++++++++++ .../orchestrate-herdr/references/run-loop.md | 73 ++++++++++++++++ .../orchestrate-herdr/references/state.md | 48 ++++++++++ skills/engineering/to-spec/SKILL.md | 5 +- skills/engineering/to-tickets/SKILL.md | 3 +- 9 files changed, 309 insertions(+), 5 deletions(-) create mode 100644 skills/engineering/dual-review/SKILL.md create mode 100644 skills/engineering/orchestrate-herdr/SKILL.md create mode 100644 skills/engineering/orchestrate-herdr/references/dispatcher.md create mode 100644 skills/engineering/orchestrate-herdr/references/run-loop.md create mode 100644 skills/engineering/orchestrate-herdr/references/state.md diff --git a/README.md b/README.md index aeacfbb..6e7e304 100644 --- a/README.md +++ b/README.md @@ -14,6 +14,7 @@ Skills are grouped by invocation type. [User-invoked](docs/invocation.md) skills - [implement-isolation](skills/engineering/implement-isolation/SKILL.md) — Implement a piece of work from a spec or set of tickets in isolation. - [implement-isolation-tmux](skills/engineering/implement-isolation-tmux/SKILL.md) — Dispatch an isolated worktree agent to implement work from a PRD or issues. - [improve-codebase-architecture](skills/engineering/improve-codebase-architecture/SKILL.md) — Find and work through opportunities to deepen a codebase's architecture. +- [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. - [project-context-pack](skills/engineering/project-context-pack/SKILL.md) — Build a bounded project context pack for later agent work. - [recipe-diagrams](skills/engineering/recipe-diagrams/SKILL.md) — Convert recipes into high-resolution process-flow diagrams. - [setup-skills](skills/setup-skills/SKILL.md) — Configure engineering skills, issue tracking, triage labels, and domain docs. @@ -74,6 +75,7 @@ No user-invoked skills. - [code-review](skills/engineering/code-review/SKILL.md) — Review changes against repository standards and the originating specification. - [codebase-design](skills/engineering/codebase-design/SKILL.md) — Design and improve deep module interfaces and seams. +- [dual-review](skills/engineering/dual-review/SKILL.md) — Run parallel correctness/security and maintainability reviews of a branch diff, then synthesize findings. - [diagnosing-bugs](skills/engineering/diagnosing-bugs/SKILL.md) — Diagnose hard bugs and performance regressions. - [domain-modeling](skills/engineering/domain-modeling/SKILL.md) — Build and sharpen a project's domain model. - [lsp-code-analysis](skills/engineering/lsp-code-analysis/SKILL.md) — Navigate code and analyze it semantically with LSP. diff --git a/skills/engineering/README.md b/skills/engineering/README.md index f3fc0f3..a9b346d 100644 --- a/skills/engineering/README.md +++ b/skills/engineering/README.md @@ -10,6 +10,7 @@ Daily code work. - [implement-isolation](implement-isolation/SKILL.md) — Implement a piece of work from a spec or set of tickets in isolation. - [implement-isolation-tmux](implement-isolation-tmux/SKILL.md) — Dispatch an isolated worktree agent to implement work from a PRD or issues. - [improve-codebase-architecture](improve-codebase-architecture/SKILL.md) — Find and work through opportunities to deepen a codebase's architecture. +- [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. - [project-context-pack](project-context-pack/SKILL.md) — Build a bounded project context pack for later agent work. - [recipe-diagrams](recipe-diagrams/SKILL.md) — Convert recipes into high-resolution process-flow diagrams. - [setup-skills](../setup-skills/SKILL.md) — Configure engineering skills, issue tracking, triage labels, and domain docs. @@ -22,6 +23,7 @@ Daily code work. - [code-review](code-review/SKILL.md) — Review changes against repository standards and the originating specification. - [codebase-design](codebase-design/SKILL.md) — Design and improve deep module interfaces and seams. +- [dual-review](dual-review/SKILL.md) — Run parallel correctness/security and maintainability reviews of a branch diff, then synthesize findings. - [diagnosing-bugs](diagnosing-bugs/SKILL.md) — Diagnose hard bugs and performance regressions. - [domain-modeling](domain-modeling/SKILL.md) — Build and sharpen a project's domain model. - [lsp-code-analysis](lsp-code-analysis/SKILL.md) — Navigate code and analyze it semantically with LSP. diff --git a/skills/engineering/dual-review/SKILL.md b/skills/engineering/dual-review/SKILL.md new file mode 100644 index 0000000..70dc2df --- /dev/null +++ b/skills/engineering/dual-review/SKILL.md @@ -0,0 +1,49 @@ +--- +name: dual-review +description: "Run two independent, read-only reviews of a branch diff in parallel — correctness/security and maintainability — then synthesize prioritized findings. Use for a second review axis alongside code-review, a combined deep plus code-quality audit, or when the user asks for dual review. Runs both axes as parallel sub-agents so they do not pollute each other's context." +--- + +# Dual review + +Two independent, read-only reviews of the diff between `HEAD` and a fixed point, then a synthesis: + +- **Correctness/security** — bugs, breakages, security gaps, devex regressions, and feature-gate leaks in the changed code. +- **Maintainability** — structural quality, simplification, boundaries, and codebase health in the changed code. + +Together with `code-review` (spec, standards) these form the four review axes. Both axes run as **parallel sub-agents**, then this skill aggregates their findings. + +The issue tracker should have been provided to you. If `docs/agents/issue-tracker.md` is missing, tell the user to run `setup-skills`. + +## Process + +### 1. Pin the fixed point + +Whatever the user said is the fixed point (a commit SHA, branch name, tag, `main`, `HEAD~5`, etc.). If they did not specify one, ask for it. + +Capture the diff command once: `git diff ...HEAD` (three-dot, against the merge-base). Note the commit list via `git log ..HEAD --oneline`. + +Confirm the fixed point resolves (`git rev-parse `) and the diff is non-empty before spawning anything. A bad ref or empty diff fails here, not inside two sub-agents. + +### 2. Gather context + +Gather the diff and the contents of changed files, plus only the surrounding context needed to trace behavior. Read each changed file at its current version. Do not review files outside the diff scope. + +### 3. Spawn both sub-agents in parallel + +Both get the same scoped diff and changed-file context and a distinct task. + +**Correctness/security brief:** "Report, per file/hunk where relevant, every bug, breakage, security gap, devex regression, or feature-gate leak in the added or modified code. Cite the hunk and explain the concrete failure or exposure. Distinguish hard defects from judgement calls. Under 400 words." + +**Maintainability brief:** "Report, per file/hunk where relevant, structural quality problems in the added or modified code: duplication, large or over-generalized units, weak boundaries, primitive obsession, speculative generality, or other smells that will cost to maintain. Name the problem and quote the hunk; flag hard violations from judgement calls. Under 400 words." + +Ask each to report prioritized findings with file/line evidence and to **not** edit files. + +### 4. Synthesize + +Wait for both runs before synthesizing. Deduplicate overlapping findings, resolve disagreements using the evidence, and list the highest-priority findings first. Present them under `## Correctness/security` and `## Maintainability` headings. If there are no findings, say so and note the review scope and its limitations. Do not restate child summaries already visible to the user. + +## Review constraints + +- Report issues only in code added or modified within the review scope. +- Do not present uncertain or unfinished research as a finding. +- Do not fix reported issues unless the user asks. diff --git a/skills/engineering/orchestrate-herdr/SKILL.md b/skills/engineering/orchestrate-herdr/SKILL.md new file mode 100644 index 0000000..d15d4a1 --- /dev/null +++ b/skills/engineering/orchestrate-herdr/SKILL.md @@ -0,0 +1,87 @@ +--- +name: orchestrate-herdr +description: "Drive a plan from the current conversation or an @file through a published spec, linked dependency-aware tickets, and one-at-a-time isolated implementation to a merged PR, using Herdr and Pi agents with no Bun CLI or orchestration runtime. Use only when explicitly invoked, e.g. /orchestrate-herdr or /orchestrate-herdr @file. Composes to-spec, to-tickets, dual-review, code-review, worktrees, and forge-cli." +disable-model-invocation: true +--- + +# Orchestrate plans to merged PRs 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 is a **routing and safety contract**. Operational detail lives in `references/`: + +- `references/dispatcher.md` — select and validate the worker node, local or remote, and discover Herdr state before dispatch. +- `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/` state directory, recovery, cross-system sync, and cleanup. + +Read the reference for the phase you are in before acting in it. + +## 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. +- 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 + +Keep roles distinct. Never let one role do another's work. + +- **Orchestrator system** — the machine where this skill is invoked. Invokes and observes the workflow. +- **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/` 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. diff --git a/skills/engineering/orchestrate-herdr/references/dispatcher.md b/skills/engineering/orchestrate-herdr/references/dispatcher.md new file mode 100644 index 0000000..f5e1f00 --- /dev/null +++ b/skills/engineering/orchestrate-herdr/references/dispatcher.md @@ -0,0 +1,45 @@ +# Dispatcher: select and validate the worker node + +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. + +## Local vs remote + +- **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. +- **Remote worker node** — the user names another machine. Discover its Herdr session, workspace, and pane, confirm the repository/ref, then start the planner there. + +If the user did not select a node and the environment does not make it obvious, ask. Do not default to a guess. + +## Preconditions + +- Check Herdr access on the node: `HERDR_ENV=1`, `HERDR_WORKSPACE_ID`, and that the `herdr` CLI can reach the same named session. +- Resolve the explicit session from `HERDR_SESSION`; if unset, inspect `herdr session list` and ask if more than one plausible session exists. Pass `--session ` to every Herdr command; the environment variable alone can fall back to another server. +- 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. + +## Discover, do not guess + +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. + +```bash +herdr --session "$SESSION" session list +herdr --session "$SESSION" pane list --workspace "$HERDR_WORKSPACE_ID" +herdr --session "$SESSION" pane read --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 "/skill:orchestrate-herdr You are the root planner for: " +# After the text is present in the pane: +herdr --session "$SESSION" pane send-keys enter +herdr --session "$SESSION" agent wait --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. diff --git a/skills/engineering/orchestrate-herdr/references/run-loop.md b/skills/engineering/orchestrate-herdr/references/run-loop.md new file mode 100644 index 0000000..72a5a1a --- /dev/null +++ b/skills/engineering/orchestrate-herdr/references/run-loop.md @@ -0,0 +1,73 @@ +# Run loop: one ticket at a time + +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. + +## Scope control + +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. + +## 1. Select the frontier + +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. + +## 2. Isolate + +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--` on a clean base; never reuse a dirty worktree. Never parallel-write a shared checkout. + +## 3. Implement + +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. + +## 4. Verify + +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." + +## 5. Review — four axes + +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. + +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. + +## 6. Fix rounds + +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. + +## 7. Merge + +Merge only after every gate passes: + +- all four review axes pass and findings are resolved; +- required local checks pass; +- CI is green when available (the current Gitea host has no CI; this gate is silent when CI is absent); +- 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. diff --git a/skills/engineering/orchestrate-herdr/references/state.md b/skills/engineering/orchestrate-herdr/references/state.md new file mode 100644 index 0000000..33690a9 --- /dev/null +++ b/skills/engineering/orchestrate-herdr/references/state.md @@ -0,0 +1,48 @@ +# State, recovery, and cleanup + +Run state lives under a run-scoped `.orchestrate/` 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. + +## State directory + +Create `.orchestrate//` on the worker node: + +- `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). +- `state.json` — each task's status, attempt count, worktree path, branch, Herdr session/workspace/pane IDs, and handoff path. +- `handoffs/.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. + +## Persist immediately + +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. + +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. + +## Recovery + +On restart, in order: + +1. Read `plan.json`, `state.json`, and `handoffs/`. +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. + +## Handoffs + +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. + +- **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/` 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. diff --git a/skills/engineering/to-spec/SKILL.md b/skills/engineering/to-spec/SKILL.md index 100aab9..8997383 100644 --- a/skills/engineering/to-spec/SKILL.md +++ b/skills/engineering/to-spec/SKILL.md @@ -1,7 +1,6 @@ --- name: to-spec -description: "Turn the current conversation into a spec and publish it to the project issue tracker: no interview, just synthesis of what you've already discussed." -disable-model-invocation: true +description: "Turn the current conversation into a spec and publish it to the project issue tracker: no interview, just synthesis of what you've already discussed. Use when the user wants a spec from the current conversation, or when an orchestration workflow needs to publish a spec from context. --- This skill takes the current conversation context and codebase understanding and produces a spec. Do NOT interview the user; just synthesize what you already know. @@ -16,7 +15,7 @@ The issue tracker and triage label vocabulary should have been provided to you. Check with the user that these seams match their expectations. -3. Write the spec using the template below, then publish it to the project issue tracker. Apply the `ready-for-agent` triage label - no need for additional triage. +1. Write the spec using the template below, then publish it to the project issue tracker. Apply the `ready-for-agent` triage label - no need for additional triage. diff --git a/skills/engineering/to-tickets/SKILL.md b/skills/engineering/to-tickets/SKILL.md index 6291358..c4d5a45 100644 --- a/skills/engineering/to-tickets/SKILL.md +++ b/skills/engineering/to-tickets/SKILL.md @@ -1,7 +1,6 @@ --- name: to-tickets -description: Break a plan, spec, or the current conversation into a set of tracer-bullet tickets, each declaring its blocking edges, published to the configured tracker (edges as text in one file per ticket locally, or native blocking links on a real tracker). -disable-model-invocation: true +description: Break a plan, spec, or the current conversation into a set of tracer-bullet tickets, each declaring its blocking edges, published to the configured tracker (edges as text in one file per ticket locally, or native blocking links on a real tracker). Use when the user wants tickets from a plan or spec, or when an orchestration workflow needs to break a spec into agent-grabbable tickets." --- # To Tickets From eacd08426fde9ab4b12c9276ae0ed93056a430fd Mon Sep 17 00:00:00 2001 From: Steve Beaulac Date: Tue, 6 Oct 2026 12:49:03 -0400 Subject: [PATCH 2/3] fix: correct skill metadata descriptions --- skills/engineering/orchestrate-herdr/SKILL.md | 2 +- skills/engineering/to-spec/SKILL.md | 2 +- skills/engineering/to-tickets/SKILL.md | 2 +- 3 files changed, 3 insertions(+), 3 deletions(-) diff --git a/skills/engineering/orchestrate-herdr/SKILL.md b/skills/engineering/orchestrate-herdr/SKILL.md index d15d4a1..e4cc86a 100644 --- a/skills/engineering/orchestrate-herdr/SKILL.md +++ b/skills/engineering/orchestrate-herdr/SKILL.md @@ -1,6 +1,6 @@ --- name: orchestrate-herdr -description: "Drive a plan from the current conversation or an @file through a published spec, linked dependency-aware tickets, and one-at-a-time isolated implementation to a merged PR, using Herdr and Pi agents with no Bun CLI or orchestration runtime. Use only when explicitly invoked, e.g. /orchestrate-herdr or /orchestrate-herdr @file. Composes to-spec, to-tickets, dual-review, code-review, worktrees, and forge-cli." +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." disable-model-invocation: true --- diff --git a/skills/engineering/to-spec/SKILL.md b/skills/engineering/to-spec/SKILL.md index 8997383..14bde6b 100644 --- a/skills/engineering/to-spec/SKILL.md +++ b/skills/engineering/to-spec/SKILL.md @@ -1,6 +1,6 @@ --- name: to-spec -description: "Turn the current conversation into a spec and publish it to the project issue tracker: no interview, just synthesis of what you've already discussed. Use when the user wants a spec from the current conversation, or when an orchestration workflow needs to publish a spec from context. +description: "Turn the current conversation into a spec and publish it to the project issue tracker: no interview, just synthesis of what you've already discussed. Use when the user wants a spec from the current conversation or an orchestration workflow needs to publish one from context." --- This skill takes the current conversation context and codebase understanding and produces a spec. Do NOT interview the user; just synthesize what you already know. diff --git a/skills/engineering/to-tickets/SKILL.md b/skills/engineering/to-tickets/SKILL.md index c4d5a45..bb3acfd 100644 --- a/skills/engineering/to-tickets/SKILL.md +++ b/skills/engineering/to-tickets/SKILL.md @@ -1,6 +1,6 @@ --- name: to-tickets -description: Break a plan, spec, or the current conversation into a set of tracer-bullet tickets, each declaring its blocking edges, published to the configured tracker (edges as text in one file per ticket locally, or native blocking links on a real tracker). Use when the user wants tickets from a plan or spec, or when an orchestration workflow needs to break a spec into agent-grabbable tickets." +description: "Break a plan, spec, or the current conversation into tracer-bullet tickets with blocking edges, published to the configured tracker. Use when the user wants tickets from a plan or spec, or an orchestration workflow needs agent-grabbable tickets." --- # To Tickets From 781aa7dc94dcff14c005c5ff2717cfd179549863 Mon Sep 17 00:00:00 2001 From: Steve Beaulac Date: Tue, 6 Oct 2026 12:50:46 -0400 Subject: [PATCH 3/3] fix: ignore persisted orchestration state --- .gitignore | 1 + 1 file changed, 1 insertion(+) diff --git a/.gitignore b/.gitignore index c36d5b8..7e80138 100644 --- a/.gitignore +++ b/.gitignore @@ -1 +1,2 @@ docs/adr/ +.orchestrate/