Parallel Add Skill
A user invocation (/parallel-add <issue|potential-entry>) forks the parallel-orchestrator
agent with this procedure in context. The issue reference or potential-entry path to admit is:
$ARGUMENTS
This skill implements the mutation-protocol add operation (spec FR1). It mutates a parallel run
that is already executing: the run's cohorts, its recolor_generation, and its mutations[]
audit log all belong to the parallel-orchestrator checkpoint, and the pinning invariant of the
## Mutation Protocol (F6) section of .claude/skills/parallel-orchestrate/SKILL.md governs what
this operation may and may not disturb. Read that section before applying anything here.
Prerequisites
Reject a pending or not-started run with guidance to consolidate the initial set through
/parallel-plan. Admit exactly one item only after execution has started in an open run; closed runs are not eligible.A parallel run is in progress and
artifacts/orchestration/parallel-orchestrator-state.jsontracks itsparallel_slug. This skill does not start a run; use/parallel-planand/parallel-runfor that.$ARGUMENTSnames exactly one item: a GitHub issue number or reference, or a path to an entry underdocs/features/potential/. An argument naming more than one item is rejected; admit one item per invocation so each admission decision and its mutation entry stay attributable.
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 computing any admission
decision, re-derive the run's true state and rewrite the checkpoint from it when they disagree:
git worktree list --porcelain— worktree existence and path per item.git branch— branch existence and name per item.gh pr view <pr> --json state,mergedAt,headRefOid— pull-request state and merge outcome per item.
The in-flight set this operation reads is derived from that re-verified state. Admitting against a stale in-flight set is the one way this operation can violate the pinning invariant, so the re-derivation is mandatory and is not an optimization to skip when the checkpoint "looks current".
Procedure
Enter
proposed. Add the item toitems[]in stateproposedwith itsissue_numas the primary key. Item keys are integers throughout this surface; there is no string key.Prepare the item. Run preparation through a preparation-mode child
Agent(orchestrator)run, reusing the existingroute_id: preparationcontract UNCHANGED: promotion, research,spec.md,user-story.md, the atomic plan, and preflight clearance. Do not fork a variant contract for parallel admission. Preparation yields the item's DECLARED blast radius, and only the planner-computed declared radius is authoritative for scheduling. The item's lifecycle advancesproposed->admitted->preparedduring this step, recorded as item-state updates initems[]with the checkpoint's lifecycle timestamps. After the admitted item's preflight clearance, perform theparallel-planskill's## Complexity Assessmentprocedure for it, and record the resultingcomplexity_bandon the admitted orchestrator-checkpoint item so step 3's edge derivation and the parent's model routing read the same band. The admitted item recordscomplexity_bandand nomodel_routing_receipt; the parent resolves the item's model from that band at spawn time perparallel-orchestrate## Model Selection. For an issue-number item, the preparation delegation prompt carries the issue-adoption line used by/parallel-plan## Preparation Fan-Out, quoted verbatim:Issue adoption: this item's GitHub issue already exists. Verify it read-only (gh issue view), do not call potential_to_issue or the promotion-entry tool, and record a top-level issue_adoption object in the checkpoint per .claude/rules/orchestrator-state.md with origin filed_before_orchestration (or transferred when the issue was transferred), waiving potential_to_issue and the promotion-entry tool for the checkpoint's promotion-type. When a lifecycle record for the item exists under docs/features/potential/promoted/, cite it as potential_record.The line is omitted for a potential-entry item, whose child promotes it.Compute conflict edges over ALL items, including in-flight ones. Invoke the scheduling entry point Get-BlastRadiusConflictEdge from the destination-runtime PowerShell port
.claude/lib/blast-radius/BlastRadius.psm1, which is published by push-down and needs no Python interpreter (the default PowerShell 5.1 execution policy blocksImport-Moduleof a.psm1file, sopwshis mandatory: run as$repoRoot = git rev-parse --show-toplevel; Import-Module (Join-Path $repoRoot '.claude/lib/blast-radius/BlastRadius.psm1') -Force -ErrorAction Stop). Call it once, asGet-BlastRadiusConflictEdge -Item <items> -Config <config> -Relation ${function:Test-BlastRadiusConflict}, where each item record carrieskey(theitems[].issue_numvalue),radius(the item's radius hashtable, not a string), and the optional complexityband, and-Configis the required parsedconfig/blast-radius.jsonmapping, which push-down publishes into the destination workspace. The -Relation argument is required and carries the facade's detection relation; an omitted relation fails fast. The entry point applies the contention relationTest-BlastRadiusConflictto every unordered pair and then the integration-cost edge rule of.claude/rules/parallel-orchestration.md(hard classes, integer cost, pairwise benefit, and the configuredconflict_tolerance); the relation still reads the mapping's optionalmergeable_pathslist and contributes nopath_overlapedge for a path matching it while the path stays in the declared radius.schedule_conflict_edges(items, config)andconflicts(a, b, config)inscripts/dev_tools/compute_blast_radius.py(defined inscripts/dev_tools/_blast_radius_scheduling.pyandscripts/dev_tools/_blast_radius_conflicts.py) remain the repository authority and the parity reference. The call returns a hashtable withedges(recordsa,b,reason,hard,cost,benefit, already normalized soa < b) andtolerated_overlaps(recordsa,b,reasons,cost,benefit). Take each returned edge as an(int, int)conflict edge ofitems[].issue_numvalues, and record the returned tolerated overlaps in the checkpoint's tolerated_overlaps list. WhenTest-BlastRadiusConflictis called directly for a single pair, read the verdict from$result['conflict']; do not test the returned hashtable itself, since it is always truthy under PowerShell boolean coercion, so a bareif ($result)check treats every pair as conflicting. Do not reimplement the relation or the edge rule, do not apply the relation to each pair by hand, and do not compute edges over the unstarted subset only: an in-flight conflict is precisely what the admission decision turns on. A tolerated overlap is not an edge: the two items run in the same or adjacent cohorts without a barrier, and the later-merging item mergesorigin/mainunder the existing per-item merge-conflict handling and re-passes CI before it merges.Decide admission. Call the bundled entry point, which needs no Python interpreter:
bash .claude/lib/bash/mutate-parallel-run.sh admit --candidate <key> --edges "<a>:<b> ..." --in-flight "<k> ..." --current-cohort-members "<k> ..."--edgescarries the step-3 conflict edges over ALL items,--in-flightthe in-flight (pinned) keys, and--current-cohort-membersthe full current-cohort membership. The command prints one JSON object whoseoutcomefield is one of:admit_current_cohort— the candidate shares no edge with any member of the current cohort, pinned or unstarted. Admit it into the current cohort. NO recompute occurs andrecolor_generationis unchanged — precisely because the candidate conflicts with no current-cohort member, so no cohort assignment needs to change.defer_and_recolor— the candidate shares an edge with at least one member of the current cohort, pinned or not-yet-launched. Defer it to a future cohort and recolor through the bundled entry point:bash .claude/lib/bash/mutate-parallel-run.sh recolor --unstarted "<k> ..." --edges "<a>:<b> ..." --pinned "<k> ..." --generation <g> --current-cohort <c> --highest-pinned-cohort <h>--highest-pinned-cohortis derived from re-verified durable state: the highest current-generation cohort index occupied by any in-flight item. The recolor is a recompute:recolor_generationincrements by exactly one, and it places every unstarted item at an index at or abovecurrent_cohort, strictly abovehighest_pinned_cohortwhen a pinned conflict exists.
Derive
current_cohort_membersfrom the re-verified durable state, not from the cached checkpoint: it is the full membership of the current-generation cohort atcurrent_cohort, INCLUDING its not-yet-launchedscheduledmembers. Derivecurrent_cohortfrom that same re-verified state; it is F3's top-levelcurrent_cohortfield, 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 derivehighest_pinned_cohortfrom the same re-verified state as well: the highest current-generation cohort index occupied by any in-flight item. Both matter becausemax_concurrencycaps simultaneously in-flight items independently of cohort size and refills each freed slot from the same current cohort — see## Cohort Barrier and Max-Concurrency Slot Fillingin.claude/skills/parallel-orchestrate/SKILL.md— so the current cohort durably holdsscheduledmembers that a candidate can contend with.A conflict with an unstarted member of the CURRENT cohort defers the candidate and recolors, because the next
max_concurrencybatch would otherwise launch the two concurrently. A conflict with an unstarted item OUTSIDE the current cohort does not defer: the cohort barrier keeps the two from running concurrently, so the coloring's existing separation already resolves it.Apply the recolor result. Write the recolor output field
cohort_assignmentsintocohorts[]and set the top-levelrecolor_generationto the output fieldgeneration. The result's key set equals the unstarted set exactly and contains no pinned key: no in-flight item changes cohort or state as a result of this admission. Verify that before writing, and stop rather than write a result that names a pinned key. The admit branch performs no recolor at all, precisely because the candidate conflicts with no current-cohort member.The returned
cohort_assignmentsvalues are ABSOLUTE cohort indices. Write them VERBATIM intocohorts[].index; never re-base them to zero. When the lowest returned index equalscurrent_cohort— the no-pinned-conflict case, where the offset is not applied — the returned keys at that index are MERGED into the single existing current-generation cohort entry atcurrent_cohortalongside its pinned members, and are never written as a second cohort entry carrying the sameindex, because F3 invariant 13 requires current-generationcohorts[].indexvalues to be unique (scripts/dev_tools/_parallel_state_structures.py:282-305— duplicate-index detection at 282-293, error emission at 301-305).Append exactly one
mutations[]entry, at admission-decision time, built by the bundled entry point. Run the first line on the admit branch (--deferred false) and the second on the defer branch (--deferred true):bash .claude/lib/bash/mutate-parallel-run.sh add-entry --item <key> --deferred false --generation <g> --at <timestamp> bash .claude/lib/bash/mutate-parallel-run.sh add-entry --item <key> --deferred true --generation <g> --at <timestamp>--generationis the run's generation before this admission, read before any step-5 recolor; the printed entry stamps it unchanged or plus one per the table below:Case opitem_keyprior_statenew_statedispositionrecolor_generationNo-conflict admit additem key null schedulednull g(unchanged)Deferred admit additem key null schedulednull g+ 1prior_stateis null on BOTH add rows. The accompanyingprepared->scheduledtransition is not lost and is not recorded in the mutation entry: it is recorded as an item-state update initems[], the same mechanism that recordsproposed->admitted->preparedin step 2. Theattimestamp is supplied through--at; when--atis omitted the entry point stamps the current UTC minute.Validate the checkpoint before treating the admission as applied. Run the
validate_orchestration_artifactsMCP tool withartifact_type: "parallel-orchestrator-state". A non-empty error list means the admission was applied incorrectly; correct the checkpoint rather than proceeding.
Constraints
- One admission per invocation, one
mutations[]entry per successful admission. A failed preparation appends no entry and leavesitems[]without the candidate. - No field and no enum member is added to
mutations[],items[], or any state or merge-status enum. Aconflict_edges[]entry may carry only the three tolerated extra fieldshard,cost, andbenefit(tolerated-not-validated, returned by the scheduling entry point), and no reason member is added: the fourconflict_edges[].reasonmembers are unchanged. The nine parallel enums are owned by.claude/rules/parallel-orchestration.mdand are consumed, never extended. Thecomplexity_bandrecorded in step 2 is not a new field: it is an existing scheduling field read by drift re-scheduling. - This operation never moves, restates, or re-derives an in-flight item's cohort or state.
- This operation performs no destructive side effect: it closes no pull request and removes no
worktree. Those belong to
/parallel-removewith--disposition abandon.
Completion Requirements
- Report the admitted item key, the admission outcome, the resulting
recolor_generation, and the single appendedmutations[]entry. - Report the cohort index the item landed in, and confirm explicitly that no in-flight item's cohort or state changed.
- Report the checkpoint validation result.