refactor(orchestrate-herdr): scope skill to spec-ticket implementation on a named worker
Rewrite SKILL.md, dispatcher and run-loop references: the skill now takes <spec-ticket> [worker], always starts fresh agents, and follows the implement-spec flow (integration branch, frontier tickets, per-task review and merge) instead of the old plan-and-publish-to-merged-PR pipeline. Update the engineering README description to match.
This commit is contained in:
@@ -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) — Implement a published spec ticket using Herdr and Pi agents on a named worker node.
|
||||
- [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.
|
||||
|
||||
@@ -1,87 +1,35 @@
|
||||
---
|
||||
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: "Implement a published spec ticket using Herdr and Pi agents. Use with /skill:orchestrate-herdr <spec-ticket> [worker], such as /skill:orchestrate-herdr 32 obelix; 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.
|
||||
Invocation requires `<spec-ticket>` and optionally accepts `[worker]`. Example: `/skill:orchestrate-herdr 32 obelix`. If the worker is omitted or blank, use the current local worker; otherwise resolve it against `herdr machine list`. Always start a fresh agent for this invocation and for each dispatched task; never reuse or resume an existing agent. The selected worker owns execution and persisted run state.
|
||||
|
||||
This skill is a **routing and safety contract**. Operational detail lives in `references/`:
|
||||
**Start by reading the spec ticket and its linked tickets.** Follow the `implement-spec` flow: understand the task graph, create one integration branch, implement ready tickets in isolated worktrees, merge completed work onto the integration branch, and continue as the frontier advances. If there are no linked implementation tickets forming an actionable frontier, invoke `/to-tickets` and follow its approval and publishing process; otherwise, don't create or rewrite tickets.
|
||||
|
||||
- `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/<slug>` state directory, recovery, cross-system sync, and cleanup.
|
||||
This skill is a routing and safety contract. Read the relevant reference before acting:
|
||||
|
||||
Read the reference for the phase you are in before acting in it.
|
||||
- `references/dispatcher.md` — validate the named worker and discover the exact Herdr session and pane.
|
||||
- `references/run-loop.md` — spec-first, integration-branch implementation flow.
|
||||
- `references/state.md` — persisted state, recovery, cross-system sync, and cleanup.
|
||||
|
||||
## Prerequisites
|
||||
## Prerequisites and roles
|
||||
|
||||
- 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.
|
||||
The selected worker must have this skill, Herdr, Pi, Git, the target repository and credentials, and an authenticated forge CLI (`tea`, `gh`, or `glab`). Run the `forge-cli` preflight there. If anything is missing or ambiguous, stop with actionable guidance; do not guess or dispatch. Start a fresh agent in a newly created pane; do not route work to an existing agent.
|
||||
|
||||
## Roles
|
||||
- **Orchestrator** invokes and observes the workflow.
|
||||
- **Worker node** is the named machine and source of truth for run state.
|
||||
- **Planner** coordinates and verifies; it does not edit product code or merge.
|
||||
- **Implementer/merger agents** work only in assigned scopes; no worker merges unless assigned the merger task.
|
||||
|
||||
Keep roles distinct. Never let one role do another's work.
|
||||
## Run and finish
|
||||
|
||||
- **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.
|
||||
1. Validate the spec ticket and optional worker. Read the spec, all associated tickets, and relevant comments before creating agents or branches.
|
||||
2. Follow `references/run-loop.md`; keep all work within the spec and linked tickets. Preserve state and evidence on blockers, failures, or human decisions.
|
||||
3. On restart, follow `references/state.md` and reconcile worker-side state before resuming; never duplicate work because the planner restarted.
|
||||
4. At completion, clean only clean implementer worktrees and run-owned Herdr panes. Retain state unless the user explicitly asks to delete it.
|
||||
|
||||
## 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.
|
||||
Report the integration branch or PR, completed tickets, verification/review evidence, blockers, human handoffs, and remaining work. Say `done` only when all tickets are complete and the final review has passed.
|
||||
|
||||
@@ -1,45 +1,26 @@
|
||||
# Dispatcher: select and validate the worker node
|
||||
# Dispatcher: resolve the worker and start fresh
|
||||
|
||||
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 32 obelix`). The spec ticket is required; the worker is optional. If the worker is omitted or blank, use the current local worker and spawn the agent there. If a worker is named, resolve it from `herdr machine list`; if it is missing or ambiguous, stop and ask. Do not silently select a different worker.
|
||||
|
||||
## Local vs remote
|
||||
Always start a **new agent** for this orchestration and each dispatched task. Never reuse or resume an existing agent, even if one appears idle or already in the right repository.
|
||||
|
||||
- **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.
|
||||
## Validate the target
|
||||
|
||||
If the user did not select a node and the environment does not make it obvious, ask. Do not default to a guess.
|
||||
1. For a named worker, run `herdr machine list` and match it to an available saved machine. Use that exact label or ID with `herdr --machine <worker> ...`; do not treat arbitrary SSH hostnames as valid machine selectors. For the default local worker, stay on the current worker and spawn the agent locally.
|
||||
2. For a named worker, confirm the machine is reachable; for the default local worker, inspect the current local Herdr session. In either case, inspect workspaces, panes, and agents. Discover the target repository and ref; do not guess pane IDs, repo paths, or agent kinds.
|
||||
3. Confirm the spec ticket exists on the target repository's tracker and is the parent/spec ticket. The new planner must read the spec, linked tickets, and relevant comments before creating work.
|
||||
4. Confirm the target has this skill, Pi, Git, repository credentials, and an authenticated forge CLI (run the `forge-cli` preflight). Stop with actionable guidance if not.
|
||||
|
||||
## Preconditions
|
||||
Run `herdr --skill` to discover the installed Herdr skills and follow the relevant skill for CLI workflows; use CLI help for exact command syntax. Machine commands require a configured, enabled machine profile and a reachable, API-compatible Herdr server. A connection failure does not prove a mutation failed; inspect remote state before retrying.
|
||||
|
||||
- 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 <name>` 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.
|
||||
## Start a new planner
|
||||
|
||||
## Discover, do not guess
|
||||
Choose a pane in the target repository only as the source for creating a **new sibling pane**. Do not send work to any existing agent pane. Create the new pane with the confirmed repository working directory, read its returned pane ID, then start a fresh Pi agent there using the installed agent kind. If there is no suitable source pane or no available shell in the new pane, stop rather than commandeering an unrelated pane.
|
||||
|
||||
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.
|
||||
Submit the exact invocation to that new agent, using the spec ticket and resolved worker (omit the worker when using the current local worker):
|
||||
|
||||
```bash
|
||||
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
|
||||
```text
|
||||
/skill:orchestrate-herdr <spec-ticket> [worker]
|
||||
```
|
||||
|
||||
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.
|
||||
Confirm the fresh agent reaches `working` before reporting kickoff success. If startup or submission is uncertain, inspect that new pane/agent before retrying; do not create a duplicate agent blindly. Once the planner is working, report the worker, spec ticket, and new agent/pane, then stop monitoring the full workflow.
|
||||
|
||||
@@ -1,73 +1,45 @@
|
||||
# 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 its linked tickets define scope; the tracker is source of truth. Begin by reading the spec ticket, 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 existing tickets are blocked, don't invent additional work.
|
||||
|
||||
## Scope control
|
||||
The issue tracker should have been provided to you. 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 a single **integration branch**, with every ticket resolved the way the issue tracker closes work.
|
||||
|
||||
## 1. Select the frontier
|
||||
The tickets are not a list of steps. They are a **task graph** with blocking relationships between them. This means there is always a **frontier** of tickets which are ready to be grabbed.
|
||||
|
||||
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.
|
||||
Communication to and from subagents should be sparse. Communicate primarily through **context pointers**: to the spec, tickets, research notes, and previous commits. Don't duplicate information already available via pointers.
|
||||
|
||||
## 2. Isolate
|
||||
## 1. Read and establish the integration branch
|
||||
|
||||
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.
|
||||
- Confirm the supplied ticket is the spec/parent ticket and identify its linked implementation tickets.
|
||||
- Understand the ticket graph and its current frontier. Re-query tracker state as work advances.
|
||||
- When tickets require codebase or external-documentation exploration, dispatch an exploration subagent before implementation. Have it save concise Markdown notes outside the repo in a directory accessible to all future subagents; pass those notes as context pointers to implementers.
|
||||
- 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 inferring.
|
||||
|
||||
## 3. Implement
|
||||
## 2. Implement the frontier
|
||||
|
||||
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.
|
||||
For each open, unblocked ticket, start a **new implementer subagents** 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 as well.
|
||||
|
||||
## 4. Verify
|
||||
Each implementer gets the full ticket and acceptance criteria, relevant context pointers, scope boundaries, worktree path, and starting branch. Require the implementer to:
|
||||
|
||||
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."
|
||||
- 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;
|
||||
- report changed files, commit, checks, and any blockers; do not merge to the integration branch or open a PR.
|
||||
|
||||
## 5. Review — four axes
|
||||
When an implementer finishes, have a **new independent reviewer agent** run the `code-review` skill against that task branch, using the current integration branch as the base. Resolve all actionable findings in a fresh scoped fix agent and rerun the 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.
|
||||
|
||||
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.
|
||||
## 3. Final review and completion
|
||||
|
||||
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.
|
||||
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 all 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.
|
||||
|
||||
## 6. Fix rounds
|
||||
If a draft PR exists, mark it ready for review after final checks. Otherwise, resolve each ticket according to the tracker's close semantics and report the integration branch. Close the parent spec ticket only when all work is complete, verified, and merged. Clean up implementer worktrees only after confirming they are clean; retain unresolved work.
|
||||
|
||||
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.
|
||||
## Retry and escalation rules
|
||||
|
||||
## 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.
|
||||
- Retry transient infrastructure failures at most twice after the first attempt. Never blindly retry semantic failures, failed checks, or rejected reviews.
|
||||
- If an operation's outcome is uncertain, reconcile tracker, Git, worker, and Herdr state before repeating it.
|
||||
- Stop and preserve state/evidence for auth or permission failures, unresolved state mismatches, exhausted retries, ambiguity, or decisions requiring human judgment.
|
||||
|
||||
Reference in New Issue
Block a user