Parallel Remove Skill
A user invocation (/parallel-remove <item> [--disposition detach|abandon]) forks the
parallel-orchestrator agent with this procedure in context. The item key and optional disposition
are:
$ARGUMENTS
This skill implements the mutation-protocol remove operation (spec FR2). It mutates a parallel run
that is already executing, so the pinning invariant and the recompute boundary in the
## Mutation Protocol (F6) section of .claude/skills/parallel-orchestrate/SKILL.md govern what
this operation may disturb. Read that section before applying anything here.
Prerequisites
- A parallel run is in progress and
artifacts/orchestration/parallel-orchestrator-state.json
tracks its parallel_slug.
$ARGUMENTS names exactly one item key — an integer items[].issue_num. Item keys are integers
throughout this surface; there is no string key.
Re-Derive Durable State Before Applying Anything
The checkpoint is a CACHE of durable state, not the source of truth
(.claude/rules/parallel-orchestration.md, Cache Doctrine). Before deciding a removal, re-derive
the target item's true state and rewrite the checkpoint from it when they disagree:
git worktree list --porcelain — worktree existence and path.
git branch — branch existence and name.
gh pr view <pr> --json state,mergedAt,headRefOid — pull-request state and merge outcome.
The removal branch is selected by the item's state, so a stale state selects the wrong branch. An
item the checkpoint calls scheduled but which is really in_flight would be silently withdrawn
and recolored, moving work that is already running. The re-derivation is therefore mandatory.
State-Dependent Behavior Table (Normative)
Implement this table exactly, one branch per row:
| Item state |
Behavior |
proposed, admitted, prepared, scheduled |
Mark withdrawn, drop the vertex, recolor the unstarted subgraph (recompute). |
in_flight |
Reject unless --disposition is supplied. A default disposition is never inferred. |
in_flight with --disposition detach |
Let the item finish and merge on its own; the run stops tracking it. No recompute. |
in_flight with --disposition abandon |
Close the PR, remove the worktree, mark withdrawn. Destructive; hook-gated. No recompute. |
merged |
Reject; the change is already in main. |
An item already withdrawn or blocked is not a live removal target and is rejected as an unknown
item.
No Default Disposition
Removing an item that is in_flight without an explicit --disposition is REJECTED. No default is
inferred, in either direction. The choice between letting running work finish and destroying it
changes what happens to a pull request and a worktree, so it belongs to the caller and never to
this procedure. Do not guess, do not prompt-and-assume, and do not pick detach because it is the
non-destructive option.
Rejected Removals Change Nothing
A rejected removal — in_flight without a disposition, merged, or an unknown or already-withdrawn
item — fails fast with a specific error, appends NO mutations[] entry, and makes NO state change.
Do not record a partial removal, and do not record the rejection itself in mutations[].
Procedure
Re-derive durable state as above and resolve the item key against items[].
Decide the removal through the bundled entry point:
bash .claude/lib/bash/remove-parallel-item.sh decide --item <key> --state <state> --removal-disposition <detach|abandon>
--state is the state re-derived in step 1; omit it when the key resolves to no items[]
entry. Pass the caller's disposition as --removal-disposition, and omit the option when none
was supplied. Exit 0 prints the decision object (item_key, prior_state, new_state,
disposition, triggers_recompute) as one JSON line on stdout. Exit 1 is a rejected row:
surface its single stderr line and stop. Exit 2 is a usage error in the invocation itself.
Unstarted removal (recompute). Set the item's state to withdrawn, drop its vertex, and
recolor through the bundled entry point:
bash .claude/lib/bash/remove-parallel-item.sh recolor --unstarted "<k> ..." --edges "<a>:<b> ..." --pinned "<k> ..." --generation <g> --current-cohort <c> --highest-pinned-cohort <h>
Write the output field cohort_assignments into cohorts[] and set the top-level
recolor_generation to the output field generation; the generation increments by exactly
one. The result names no pinned key, so no in-flight item moves.
current_cohort is F3's top-level field, read from the re-verified durable state: the lowest
current-generation cohort index still holding a non-terminal item. Under the per-edge barrier an
in-flight item is not confined to that index, so highest_pinned_cohort — the highest
current-generation cohort index occupied by any in-flight item — is read from the same
re-verified state. The returned indices are ABSOLUTE and are written VERBATIM into
cohorts[].index, never re-based to zero. Returned keys whose index equals current_cohort are
MERGED into the single existing current-generation cohort entry at that index alongside its
pinned members, never written as a second entry carrying the same index, which F3 invariant 13
rejects.
detach (no recompute). Set the item's state to withdrawn and record
disposition: "detach" in the mutation entry. recolor_generation is UNCHANGED: the detached
item was pinned and was never a vertex of the unstarted subgraph, so its departure cannot change
the induced subgraph. Perform no side effect — the item's own pull request continues to its own
merge outcome and the run simply stops tracking it. The closed-mode completion predicate
excludes withdrawn items, so the run does not wait for a detached item.
abandon (no recompute, destructive, CLI-only). Set the item's state to withdrawn and
record disposition: "abandon" in the mutation entry. recolor_generation is UNCHANGED, for the
same reason as detach. Execute the destructive side effects — closing the pull request and
removing the worktree — through the single deterministic CLI invocation below and through nothing
else:
bash .claude/lib/bash/abandon-parallel-item.sh --item <key> --disposition abandon --confirm-abandon --pr <pr-number> --worktree <worktree-path>
Executing the abandon disposition through ad hoc gh pr close or git worktree remove commands
is PROHIBITED. The prohibition is not stylistic: the abandon gate matches on the tokens of the
invocation above, so an ad hoc command is not matchable and would bypass the confirmation
contract entirely. One invocation, one item, both side effects.
Append exactly one mutations[] entry for a successful removal, built through the
bundled entry point:
bash .claude/lib/bash/remove-parallel-item.sh entry --item <key> --prior-state <state> --removal-disposition <detach|abandon> --recompute <true|false> --generation <g> --at <timestamp>
--recompute equals the decision's triggers_recompute. --generation is the generation
before the removal. Omit --removal-disposition for an unstarted item. --at is the mutation
timestamp in yyyy-MM-ddTHH-mm form; when it is omitted the entry point uses the current UTC
minute. Exit 0 prints the entry as one JSON line on stdout; exit 1 is a contract rejection whose
single stderr line is surfaced before stopping; exit 2 is a usage error.
| Case |
op |
item_key |
prior_state |
new_state |
disposition |
recolor_generation |
| Remove, unstarted |
remove |
item key |
prior state (proposed/admitted/prepared/scheduled) |
withdrawn |
null |
g + 1 |
Remove, detach |
remove |
item key |
in_flight |
withdrawn |
detach |
g (unchanged) |
Remove, abandon |
remove |
item key |
in_flight |
withdrawn |
abandon |
g (unchanged) |
disposition is non-null only on an in-flight removal and is null on the unstarted row. The at
timestamp comes from the --at value, or from the current UTC minute when --at is omitted.
The repository-local module scripts/dev_tools/parallel_mutation_protocol.py is retained as the
parity reference for this entry point and is not invoked on this path.
Validate the checkpoint before treating the removal as applied. Run the
validate_orchestration_artifacts MCP tool with artifact_type: "parallel-orchestrator-state". A non-empty error list means the removal was applied incorrectly;
correct the checkpoint rather than proceeding.
Abandon Confirmation-Marker Contract
The abandon path is guarded by the PreToolUse hook
.claude/hooks/enforce-parallel-abandon-gate.ps1 on the Bash matcher. The contract is:
- A Bash command carrying the disposition token for abandon MUST also carry the explicit
confirmation marker
--confirm-abandon in the SAME command.
- A command carrying the abandon disposition token WITHOUT the confirmation marker is DENIED. The
deny reason is prefixed
PARALLEL_ABANDON_BLOCKED.
- A command carrying both tokens is allowed.
- A command carrying neither is out of scope and is allowed unchanged.
The two token values are declared once each in .claude/lib/bash/abandon-parallel-item.sh (the
pushed-down producer), once each in scripts/dev_tools/parallel_mutation_abandon_cli.py (the retained
Python parity reference), and once each in the hook (the consumer). The seam test
tests/scripts/dev_tools/test_parallel_abandon_token_seam.py parses all four artifacts — the bundled
entry point, the Python reference, the hook, and the invocation line in step 5 above — at run time
to prove they still agree. Renaming a token in one artifact without the identical rename in the
others fails that test. The invocation in step 5 is the file's only executable abandon command
line, and the seam test parses that one line; do not add a second one.
When the gate denies a command, the correct response is to add the confirmation marker
deliberately, not to reformulate the command to evade the match. Reformulating to evade the gate
defeats the only mechanism protecting a destructive operation.
Constraints
- One removal per invocation; at most one
mutations[] entry per invocation.
- No field and no enum member is added to
mutations[], items[], or any state or merge-status
enum. The nine parallel enums are owned by .claude/rules/parallel-orchestration.md and are
consumed, never extended.
- Neither
detach nor abandon recomputes. An unstarted item previously deferred because of a
conflict with the removed item keeps its cohort assignment: the assignment stays valid and is at
most conservative, and no opportunistic recompute is performed.
- No in-flight item other than the removal target changes cohort or state.
Completion Requirements
- Report the item key, the branch of the behavior table taken, the disposition recorded, the
resulting
recolor_generation, and the single appended mutations[] entry — or, for a rejected
removal, the rejection and the explicit confirmation that nothing was appended and no state
changed.
- For an abandon, report the CLI's exit code and both side-effect outcomes.
- Report the checkpoint validation result.
1---2name: parallel-remove3description: Remove one item from a running parallel run per the state-dependent removal behavior table — withdraw and recolor for an unstarted item, detach or abandon for an in-flight item, reject for a merged item. No default disposition is ever inferred. The abandon path runs through one deterministic CLI invocation and is hook-gated.4argument-hint: "[item] [--disposition detach|abandon]"5context: fork6agent: parallel-orchestrator7metadata:8 source: https://skillmd.com/skills/drmoisan/parallel-remove9---1011# Parallel Remove Skill1213A user invocation (`/parallel-remove <item> [--disposition detach|abandon]`) forks the14`parallel-orchestrator` agent with this procedure in context. The item key and optional disposition15are:1617$ARGUMENTS1819This skill implements the mutation-protocol remove operation (spec FR2). It mutates a parallel run20that is already executing, so the pinning invariant and the recompute boundary in the21`## Mutation Protocol (F6)` section of `.claude/skills/parallel-orchestrate/SKILL.md` govern what22this operation may disturb. Read that section before applying anything here.2324## Prerequisites2526- A parallel run is in progress and `artifacts/orchestration/parallel-orchestrator-state.json`27 tracks its `parallel_slug`.28- `$ARGUMENTS` names exactly one item key — an integer `items[].issue_num`. Item keys are integers29 throughout this surface; there is no string key.3031## Re-Derive Durable State Before Applying Anything3233The checkpoint is a CACHE of durable state, not the source of truth34(`.claude/rules/parallel-orchestration.md`, Cache Doctrine). Before deciding a removal, re-derive35the target item's true state and rewrite the checkpoint from it when they disagree:3637- `git worktree list --porcelain` — worktree existence and path.38- `git branch` — branch existence and name.39- `gh pr view <pr> --json state,mergedAt,headRefOid` — pull-request state and merge outcome.4041The removal branch is selected by the item's state, so a stale state selects the wrong branch. An42item the checkpoint calls `scheduled` but which is really `in_flight` would be silently withdrawn43and recolored, moving work that is already running. The re-derivation is therefore mandatory.4445## State-Dependent Behavior Table (Normative)4647Implement this table exactly, one branch per row:4849| Item state | Behavior |50| --- | --- |51| `proposed`, `admitted`, `prepared`, `scheduled` | Mark `withdrawn`, drop the vertex, recolor the unstarted subgraph (recompute). |52| `in_flight` | **Reject** unless `--disposition` is supplied. A default disposition is never inferred. |53| `in_flight` with `--disposition detach` | Let the item finish and merge on its own; the run stops tracking it. No recompute. |54| `in_flight` with `--disposition abandon` | Close the PR, remove the worktree, mark `withdrawn`. Destructive; hook-gated. No recompute. |55| `merged` | Reject; the change is already in `main`. |5657An item already `withdrawn` or `blocked` is not a live removal target and is rejected as an unknown58item.5960## No Default Disposition6162Removing an item that is `in_flight` without an explicit `--disposition` is REJECTED. No default is63inferred, in either direction. The choice between letting running work finish and destroying it64changes what happens to a pull request and a worktree, so it belongs to the caller and never to65this procedure. Do not guess, do not prompt-and-assume, and do not pick `detach` because it is the66non-destructive option.6768## Rejected Removals Change Nothing6970A rejected removal — `in_flight` without a disposition, `merged`, or an unknown or already-withdrawn71item — fails fast with a specific error, appends NO `mutations[]` entry, and makes NO state change.72Do not record a partial removal, and do not record the rejection itself in `mutations[]`.7374## Procedure75761. Re-derive durable state as above and resolve the item key against `items[]`.77782. Decide the removal through the bundled entry point:7980 ```shell81 bash .claude/lib/bash/remove-parallel-item.sh decide --item <key> --state <state> --removal-disposition <detach|abandon>82 ```8384 `--state` is the state re-derived in step 1; omit it when the key resolves to no `items[]`85 entry. Pass the caller's disposition as `--removal-disposition`, and omit the option when none86 was supplied. Exit 0 prints the decision object (`item_key`, `prior_state`, `new_state`,87 `disposition`, `triggers_recompute`) as one JSON line on stdout. Exit 1 is a rejected row:88 surface its single stderr line and stop. Exit 2 is a usage error in the invocation itself.89903. **Unstarted removal (recompute).** Set the item's state to `withdrawn`, drop its vertex, and91 recolor through the bundled entry point:9293 ```shell94 bash .claude/lib/bash/remove-parallel-item.sh recolor --unstarted "<k> ..." --edges "<a>:<b> ..." --pinned "<k> ..." --generation <g> --current-cohort <c> --highest-pinned-cohort <h>95 ```9697 Write the output field `cohort_assignments` into `cohorts[]` and set the top-level98 `recolor_generation` to the output field `generation`; the generation increments by exactly99 one. The result names no pinned key, so no in-flight item moves.100101 `current_cohort` is F3's top-level field, read from the re-verified durable state: the lowest102 current-generation cohort index still holding a non-terminal item. Under the per-edge barrier an103 in-flight item is not confined to that index, so `highest_pinned_cohort` — the highest104 current-generation cohort index occupied by any in-flight item — is read from the same105 re-verified state. The returned indices are ABSOLUTE and are written VERBATIM into106 `cohorts[].index`, never re-based to zero. Returned keys whose index equals `current_cohort` are107 MERGED into the single existing current-generation cohort entry at that index alongside its108 pinned members, never written as a second entry carrying the same `index`, which F3 invariant 13109 rejects.1101114. **`detach` (no recompute).** Set the item's state to `withdrawn` and record112 `disposition: "detach"` in the mutation entry. `recolor_generation` is UNCHANGED: the detached113 item was pinned and was never a vertex of the unstarted subgraph, so its departure cannot change114 the induced subgraph. Perform no side effect — the item's own pull request continues to its own115 merge outcome and the run simply stops tracking it. The `closed`-mode completion predicate116 excludes withdrawn items, so the run does not wait for a detached item.1171185. **`abandon` (no recompute, destructive, CLI-only).** Set the item's state to `withdrawn` and119 record `disposition: "abandon"` in the mutation entry. `recolor_generation` is UNCHANGED, for the120 same reason as `detach`. Execute the destructive side effects — closing the pull request and121 removing the worktree — through the single deterministic CLI invocation below and through nothing122 else:123124 ```shell125 bash .claude/lib/bash/abandon-parallel-item.sh --item <key> --disposition abandon --confirm-abandon --pr <pr-number> --worktree <worktree-path>126 ```127128 Executing the abandon disposition through ad hoc `gh pr close` or `git worktree remove` commands129 is PROHIBITED. The prohibition is not stylistic: the abandon gate matches on the tokens of the130 invocation above, so an ad hoc command is not matchable and would bypass the confirmation131 contract entirely. One invocation, one item, both side effects.1321336. **Append exactly one `mutations[]` entry** for a successful removal, built through the134 bundled entry point:135136 ```shell137 bash .claude/lib/bash/remove-parallel-item.sh entry --item <key> --prior-state <state> --removal-disposition <detach|abandon> --recompute <true|false> --generation <g> --at <timestamp>138 ```139140 `--recompute` equals the decision's `triggers_recompute`. `--generation` is the generation141 before the removal. Omit `--removal-disposition` for an unstarted item. `--at` is the mutation142 timestamp in `yyyy-MM-ddTHH-mm` form; when it is omitted the entry point uses the current UTC143 minute. Exit 0 prints the entry as one JSON line on stdout; exit 1 is a contract rejection whose144 single stderr line is surfaced before stopping; exit 2 is a usage error.145146 | Case | `op` | `item_key` | `prior_state` | `new_state` | `disposition` | `recolor_generation` |147 | --- | --- | --- | --- | --- | --- | --- |148 | Remove, unstarted | `remove` | item key | prior state (`proposed`/`admitted`/`prepared`/`scheduled`) | `withdrawn` | null | `g` + 1 |149 | Remove, `detach` | `remove` | item key | `in_flight` | `withdrawn` | `detach` | `g` (unchanged) |150 | Remove, `abandon` | `remove` | item key | `in_flight` | `withdrawn` | `abandon` | `g` (unchanged) |151152 `disposition` is non-null only on an in-flight removal and is null on the unstarted row. The `at`153 timestamp comes from the `--at` value, or from the current UTC minute when `--at` is omitted.154 The repository-local module `scripts/dev_tools/parallel_mutation_protocol.py` is retained as the155 parity reference for this entry point and is not invoked on this path.1561577. **Validate the checkpoint** before treating the removal as applied. Run the158 `validate_orchestration_artifacts` MCP tool with `artifact_type:159 "parallel-orchestrator-state"`. A non-empty error list means the removal was applied incorrectly;160 correct the checkpoint rather than proceeding.161162## Abandon Confirmation-Marker Contract163164The abandon path is guarded by the PreToolUse hook165`.claude/hooks/enforce-parallel-abandon-gate.ps1` on the `Bash` matcher. The contract is:166167- A Bash command carrying the disposition token for abandon MUST also carry the explicit168 confirmation marker `--confirm-abandon` in the SAME command.169- A command carrying the abandon disposition token WITHOUT the confirmation marker is DENIED. The170 deny reason is prefixed `PARALLEL_ABANDON_BLOCKED`.171- A command carrying both tokens is allowed.172- A command carrying neither is out of scope and is allowed unchanged.173174The two token values are declared once each in `.claude/lib/bash/abandon-parallel-item.sh` (the175pushed-down producer), once each in `scripts/dev_tools/parallel_mutation_abandon_cli.py` (the retained176Python parity reference), and once each in the hook (the consumer). The seam test177`tests/scripts/dev_tools/test_parallel_abandon_token_seam.py` parses all four artifacts — the bundled178entry point, the Python reference, the hook, and the invocation line in step 5 above — at run time179to prove they still agree. Renaming a token in one artifact without the identical rename in the180others fails that test. The invocation in step 5 is the file's only executable abandon command181line, and the seam test parses that one line; do not add a second one.182183When the gate denies a command, the correct response is to add the confirmation marker184deliberately, not to reformulate the command to evade the match. Reformulating to evade the gate185defeats the only mechanism protecting a destructive operation.186187## Constraints188189- One removal per invocation; at most one `mutations[]` entry per invocation.190- No field and no enum member is added to `mutations[]`, `items[]`, or any state or merge-status191 enum. The nine parallel enums are owned by `.claude/rules/parallel-orchestration.md` and are192 consumed, never extended.193- Neither `detach` nor `abandon` recomputes. An unstarted item previously deferred because of a194 conflict with the removed item keeps its cohort assignment: the assignment stays valid and is at195 most conservative, and no opportunistic recompute is performed.196- No in-flight item other than the removal target changes cohort or state.197198## Completion Requirements199200- Report the item key, the branch of the behavior table taken, the disposition recorded, the201 resulting `recolor_generation`, and the single appended `mutations[]` entry — or, for a rejected202 removal, the rejection and the explicit confirmation that nothing was appended and no state203 changed.204- For an abandon, report the CLI's exit code and both side-effect outcomes.205- Report the checkpoint validation result.