Apply Code Changes

Apply Code Changes

Orchestrate apply: execute tasks.md in order (Changelog group last), run the verify-aligned gate and verify-fix loop, then hand off per venue.

Core = steps 0–7. Change adapter = pre-flight path resolution — change-adapters.md.

Verification ref — branch where gate and verify-fix run: ORIGINAL_BRANCH (local/worktree); FEATURE_BRANCH (remote).

Never in apply: archive, spec sync, archive commit, /opsx:archive.

Invariant

ORIGINAL_BRANCH is the durable branch for local and worktree apply — no openspec/<name> feature branch on those venues. FEATURE_BRANCH exists only for remote (PR head). Worktree isolation uses ephemeral apply-<name> (APPLY_REF), squash-merged onto ORIGINAL_BRANCH at handoff then deleted.

Session variables

Venue matrix (single source of truth)

After bind, follow the row for venue × parallelism. Step 2 implements bind; step 5 implements handoff — do not contradict this table elsewhere.

Legacy Presets key workspace → treat as venue when venue is absent.

Inputs

After bind, paths are under ACTIVE_CHANGE_ROOT. Prefer OpenSpec artifactPaths / contextFiles when set.

Trusted hint: TRACKING_HINT loaded and its Change equals CHANGE_ROOT_REL (legacy: equals CHANGE_ROOT). Branch, Issue, PR, and Presets from an untrusted hint are ignored for merge overlay.

Steps

0. Pre-flight (adapter — planning reads only)

1. Run a change adapter per change-adapters.md; set CHANGE_ROOT, CHANGE_ROOT_REL, and NAME. Adapters never create on-disk tracking.md.
2. Read tasks.md, specs, design.md, proposal.md from CHANGE_ROOT for planning context.
3. Load tracking.md at CHANGE_ROOT into TRACKING_HINT when present; re-probe OpenSpec once when the hint selects a store. Do not treat it as final TRACKING.

1. Setup

Interactive host — structured-choices venue gate (one message; must run — a trusted Issue or filled Presets does not skip it):

1. Initialize TRACKING: copy non-empty TRACKING_HINT fields field-by-field, except Branch, Issue, PR, and Presets keys — copy those only on a trusted hint; set Change = CHANGE_ROOT_REL. Initialize empty PRESET_OVERRIDES. Do not write to disk.
2. Venue: local | worktree | remote → set TRACKING Presets → venue and PRESET_OVERRIDES → venue.
3. When the OpenSpec adapter set STORE, set Presets → store; add to PRESET_OVERRIDES only when STORE_SOURCE is explicit.
4. Parallelism (agent — not a user gate): choose single | subagent-per-group using the criteria below; set Presets → parallelism and PRESET_OVERRIDES → parallelism; note one-line rationale in session.
5. Snapshot TRACKING_SETUP = copy of TRACKING.

Done when: PRESET_OVERRIDES contains venue and parallelism; interactive hosts completed step 2 via structured-choices.

Non-interactive host (CI — no user present to answer; not merely a tool you cannot see): skip step 2 gate; set venue from merged Presets → venue (legacy workspace), else remote when shipping intent is clear, else local; choose parallelism per same criteria; lock both in PRESET_OVERRIDES; snapshot TRACKING_SETUP.

Parallelism criteria (all venues, including remote)

Choose subagent-per-group when every row holds; else single:

Sequential dispatch only — never concurrent subagents on shared git state.

Optional: invoke a git worktree skill when present for naming/cleanup conventions — never required.

2. Pre-bind merge, branch resolution, and bind

Pre-bind tracking merge — before branch resolution or bind:

1. Merge on-disk tracking.md at adapter CHANGE_ROOT when present (field-by-field; trusted-hint rules for Issue/PR/Branch).
2. When Presets → venue is remote: candidate FEATURE_BRANCH = TRACKING → Branch, else adapter default. When that branch exists locally or on origin, read CHANGE_ROOT_REL/tracking.md from it (prefer local, else origin/<branch>). When STORE_SOURCE is hint and path absent, search branch tree for .../NAME/tracking.md. Non-empty on-disk Branch ≠ candidate: STOP. Change mismatch: defer per store-adoption rules below.
3. Merge remote-branch tracking (Pre-bind tracking merge step 2 only): non-empty Issue, Branch, PR win; Presets keys merge individually. Overlay PRESET_OVERRIDES; set Change = CHANGE_ROOT_REL. Never replace Presets wholesale.
4. Store adoption (unchanged intent): when STORE_SOURCE is hint and Change mismatch deferred or branch Presets → store differs, adopt store, rerun adapter, restore TRACKING from TRACKING_SETUP, restart merge once.
5. Map legacy Presets → workspace to venue when venue empty.

Branch resolution — from merged TRACKING and Presets → venue:

1. ORIGINAL_BRANCH: TRACKING Presets → base-branch; else current branch; else repo default (main / origin/HEAD). Note assumption when inferred.
2. FEATURE_BRANCH — remote only: TRACKING → Branch, else adapter default. When exists on origin only, git checkout -b FEATURE_BRANCH origin/FEATURE_BRANCH — never recreate from ORIGINAL_BRANCH. When exists nowhere, git checkout -b FEATURE_BRANCH ORIGINAL_BRANCH.
3. APPLY_REF — worktree only: apply-<NAME>. Create from ORIGINAL_BRANCH if missing; never reuse a stale apply-<NAME> with unrelated commits — delete and recreate when Change differs.
4. Persist empty base-branch in TRACKING when inferred.

Bind — requires Presets → venue and parallelism. Set WORK_CHECKOUT, then ACTIVE_CHANGE_ROOT = WORK_CHECKOUT + "/" + CHANGE_ROOT_REL:

1. Persist tracking.md at ACTIVE_CHANGE_ROOT (reconcile; never wholesale Presets replace).
2. Re-read planning artifacts from ACTIVE_CHANGE_ROOT.

3. Execute tasks

Prerequisite: ACTIVE_CHANGE_ROOT bound. All artifact reads/writes use ACTIVE_CHANGE_ROOT only.

Work through tasks.md in order — numbered ## groups, then Verification, Documentation, Changelog last.

Per implementation task:

1. Map related #### Scenario: blocks; name tests after scenarios.
2. Invoke tdd when present (non-blocking if absent).
3. Implement; mark - [ ] → - [x] only when tests pass.
4. Invoke git-commit for logical units on the active work ref (ORIGINAL_BRANCH, APPLY_REF, or FEATURE_BRANCH per venue matrix). Commit this unit's in-scope paths; changelog-generator runs in the Changelog group.
5. After each ## group (or end when single), invoke code-review when present — fixed point = ORIGINAL_BRANCH.

Parallelism subagent-per-group:

• local: subagents read ACTIVE_CHANGE_ROOT; no git; orchestrator commits on ORIGINAL_BRANCH.
• worktree: optional group worktrees on apply-<name>-<slug>; orchestrator merges into APPLY_REF; merge gate (step 4) squash-merges to ORIGINAL_BRANCH before verify.
• remote: subagents on runner checkout; orchestrator commits on FEATURE_BRANCH.

Documentation group: update files from proposal Impact and tasks. Changelog group: invoke changelog-generator with ACTIVE_CHANGE_ROOT as the change root.

4. Merge gate (worktree only — blocking)

When venue is worktree, squash to ORIGINAL_BRANCH before step 5. Do not run verify-aligned or verify-fix on the worktree checkout.

1. Checkout main repo → ORIGINAL_BRANCH
2. Squash merge APPLY_REF → ORIGINAL_BRANCH (one commit preferred)
3. git branch --show-current equals ORIGINAL_BRANCH
4. git status --porcelain empty on main repo

Done when: implementation commits live on ORIGINAL_BRANCH and the session is on main repo — not the worktree path.

5. Completion gate — verify-aligned (blocking)

Re-run on the verification ref at ACTIVE_CHANGE_ROOT until every row passes:

1. All tasks.md checkboxes [x] (including Documentation and Changelog)
2. Canonical test command from tasks.md — exit 0; every #### Scenario: has a passing named automated test
3. Lint/format when tasks.md or repo docs name commands — zero new warnings from this change
4. Adapter validator — OpenSpec: openspec validate --all --json from PLANNING_HOME with --store when set; Direct: skip unless user requests
5. Material design.md decisions reflected in specs — material drift = FAIL
6. Documentation tasks reflect actual behavior
7. Changelog task complete
8. git status --porcelain empty on the verification ref. A dirty tree of this change's own work is resolved by committing it. Discarding the diff to turn the gate green is a defect, not a pass.

On FAIL: fix immediately; do not enter verify-fix or hand off.

6. Verify-fix loop (blocking)

Apply owns verification on the verification ref. Repeat until openspec-verify-change (or /opsx:verify) reports ✅ PASS with no unresolved warnings:

1. Invoke openspec-verify-change via Skill tool, or run /opsx:verify
2. On ❌ FAIL or new warnings: fix immediately; re-run step 5; return to (1)
3. Proceed to handoff only on ✅ PASS

Done when: a standalone /opsx:verify after this step would confirm PASS — not surface new FAILs or warnings. Interruption re-runs route failures back here.

Verify-fix checks implementation vs specs, design, and tasks — beyond structural openspec validate. Step 5 owns git housekeeping and lint; verify-fix does not re-check a dirty tree.

7. Handoff

Done when: verify-fix PASS and the venue handoff row below completes.

Delegation

Narrowing

• No archive or spec sync inside apply.
• No marking tasks [x] before tests pass.
• No PR before verify-fix PASS (remote).
• No handoff before verify-fix PASS.
• No verify-fix or verify-aligned gate on a worktree checkout — merge gate (step 4) first.
• No treating openspec validate alone as sufficient — verify-fix is mandatory for OpenSpec apply.
• No deferring verify FAILs or warnings to the user.
• No durable feature branch on local or worktree — only ORIGINAL_BRANCH (+ ephemeral apply-<name>).
• No skipping the interactive venue gate because Issue or Presets are prefilled.
• No FEATURE_BRANCH on local/worktree bind.
• No recreating FEATURE_BRANCH from ORIGINAL_BRANCH when it exists on origin.
• No skipping Changelog.
• No hardcoded openspec/changes/<name>/.
• No concurrent subagents on shared git state.
• No adapter creating on-disk tracking.md.
• No bind without Presets → venue and parallelism.
• No wholesale Presets replace during tracking merge.
• No inheritance of Change from a tracking file — always current adapter CHANGE_ROOT_REL.
• No post-bind artifact I/O via pre-bind CHANGE_ROOT.
• No gh pr create without --base ORIGINAL_BRANCH.
• No worktree handoff before merge gate (step 4) completes.
• No mixing superpowers-bridge apply with this skill on the same change.