migrate-workflow

Reading workflow files (TOC protocol)

When you Read any file under .claude/workflow/ or .claude/skills/, follow the protocol in conventions.md §1.8:

1. Read the TOC region: from <!--Document index start--> to <!--Document index end--> (read to the closing delimiter, not a fixed line count). If the file has no TOC region (a file whose only ## heading is this bootstrap block carries none, per §1.8(d)), read the file in full.
2. Match TOC rows where Roles contains any of your roles (or your role is any, or the row's Roles is any) AND Phases contains any of your phases (or your phase is any, or the row's Phases is any).
3. Use Read(offset, limit) to read only matched sections; if no row matches your role/phase, the file holds nothing for you — do not read further.

Your role: migrator. Your phase: any (migration sits outside the phase taxonomy).

Inline refs you find inside workflow files carry the same name:roles:phases suffix; apply file-level filtering before opening: a ref matches when any of your roles is in its roles and any of your phases is in its phases, your own any on either axis matches every ref on that axis, and a ref whose own roles or phases is any matches you. Backtick-wrapped refs carry no suffix; open or skip them at your discretion.

<!--Document index start-->

Section	Roles	Phases	Summary
§Inputs	migrator	any	The plan directory and worktree the migration operates on, resolved before any replay step runs.
§Step 0 — Create progress tracker	migrator	any	Create the TaskCreate progress tracker so a /clear mid-migration can resume from the last completed commit.
§Step 1 — Preflight	migrator	any	Resolve the plan directory and worktree, confirm the branch has migratable artifacts, and abort cleanly when none exist.
§Step 2.0 — Bootstrap unstamped artifacts	migrator	any	Stamp any artifact still missing a line-1 workflow-sha before the replay range is computed.
§Step 2 — Compute commit range	migrator	any	Derive the replay range from per-artifact stamps and HEAD, bounding retries on an unresolvable stamp.
§Step 3 — Load or initialize progress file	migrator	any	Load an existing .migration-progress file to resume, or initialize a fresh one when the migration starts clean.
§Step 4 — Per-commit migration loop	migrator	any	Replay each format-relevant commit: context check, read, classify, apply edits, advance stamps, record progress.
§4.1 Context check (mandatory before starting the commit)	migrator	any	Check context budget before each commit and checkpoint to a fresh session when it would not fit the whole commit.
§4.2 Read the commit	migrator	any	Read the commit's diff and message to determine what workflow-format change it introduced.
§4.3 Classify the commit	migrator	any	Classify the commit as format-relevant, no-op, or manual-review-needed to route how its edits are replayed.
§4.4 Apply the migration	migrator	any	Apply the commit's format edits to the matching artifacts in place, or route to manual review on a stamp-format halt.
§4.5 Advance stamps in lockstep	migrator	any	After the edits land, rewrite every artifact's line-1 stamp to this commit SHA; the order matters for crash resume.
§4.6 Update the progress file	migrator	any	Record the replayed commit and its classification in .migration-progress as the crash-resume marker.
§4.7 Mark the per-commit task completed	migrator	any	Mark the commit's TaskCreate entry complete so the progress tracker reflects the replayed commit.
§4.8 Final stamp-to-HEAD batch	migrator	any	After the loop, batch-rewrite every artifact's line-1 stamp to HEAD; already-at-HEAD artifacts are benign no-ops.
§Step 5 — Final summary	migrator	any	Report the replayed and manual-review commits and leave the dirty worktree for the user to review and commit.
§Step 6 — Self-improvement reflection	migrator	any	Run the shared reflection pass to capture migration-process friction as YouTrack proposals before ending the session.
§Notes	migrator	any	Standing caveats on in-place editing, the dirty-worktree contract, and the no-automatic-commits rule.

<!--Document index end-->

Auto-detection runs in /create-plan Step 1.5 and /execute-tracks startup via workflow-drift-check.md:orchestrator,planner:2,3A.

The skill runs inside the branch's own worktree. The branch is a self-contained capsule: workflow-format commits enter its view only when the user explicitly rebases or merges develop, so the migration's commit range is derived from per-artifact stamps and HEAD (see conventions.md §1.6), never from a develop-relative fork point. The skill applies each format-relevant commit's edits to the corresponding artifact files under the active plan's _workflow/.

The skill edits files in place and leaves the worktree dirty for the user to review and commit. No automatic commits.

Inputs

<!-- roles=migrator phases=any summary="The plan directory and worktree the migration operates on, resolved before any replay step runs." -->

$ARGUMENTS — optional. When supplied, it must equal the current branch name (git branch --show-current); the migration always runs in the current worktree on the current branch. Step 1 enforces the equality and rejects mismatches.

Step 0 — Create progress tracker

<!-- roles=migrator phases=any summary="Create the TaskCreate progress tracker so a /clear mid-migration can resume from the last completed commit." -->

Before any other tool call, create one task per step below using TaskCreate. Mark each in_progress when starting, completed when done. This list is the checklist; do not skip entries.

1. Preflight: verify clean tree under the active plan's _workflow/ and resolve the active plan dir
2. Bootstrap unstamped artifacts: prompt for a base SHA covering any unstamped _workflow/** artifact
3. Compute commit range + format-relevant commit list
4. Load or initialize progress file
5. Per-commit migration loop (one task per commit will be added at the start of Step 4, after Step 3 trims the resume queue)
6. Final stamp-to-HEAD batch
7. Final summary
8. Self-improvement reflection: invoke .claude/workflow/self-improvement-reflection.md with session-type=migrate-workflow

Step 1 — Preflight

<!-- roles=migrator phases=any summary="Resolve the plan directory and worktree, confirm the branch has migratable artifacts, and abort cleanly when none exist." -->

Run these checks in order. Halt on any failure.

Argument check. When $ARGUMENTS is non-empty, it must equal the current branch name. The single equality covers every legacy reject case — refs/heads/..., origin/..., a 7- to 40-character hex SHA, or a non-existent branch name all fail this check, since none of them can equal git branch --show-current's plain-branch-name output:

if [ -n "$ARGUMENTS" ] \
   && [ "$ARGUMENTS" != "$(git branch --show-current)" ]; then
  echo "ERROR: \$ARGUMENTS ($ARGUMENTS) does not match the current branch ($(git branch --show-current))"
  exit 1
fi

Active-plan-dir resolution. Enumerate docs/adr/*/_workflow/ directories in the current worktree:

ls -d docs/adr/*/_workflow/ 2>/dev/null

Apply this ladder and capture the result as $PLAN_DIR (the parent directory, without the trailing /_workflow/):

1. Zero matches — halt with "no _workflow/ directory on the current branch; nothing to migrate".
2. Exactly one match — use it. The parent directory name need not match the current branch; branch names and ADR directory names are not guaranteed to match.
3. More than one match — list them and ask the user which one to migrate. One plan at a time.

Subsequent steps reference $PLAN_DIR (e.g., $PLAN_DIR/_workflow/implementation-plan.md) instead of re-running the ladder.

Narrow-scope dirty check. Refuse to start when any tracked file under the active plan's §1.6(h) artifact paths has uncommitted changes (working tree or index), or when any untracked file lives there. The scope covers the implementation plan, the design files, and every track file under $PLAN_DIR/_workflow/plan/. The staged subtree at $PLAN_DIR/_workflow/staged-workflow/ is deliberately outside the check: on workflow-modifying branches, in-flight workflow-document changes accumulate under that subtree during execution (Phase 4 then promotes them to the live paths in one commit), and a whole-subtree check would refuse every such session with staged content present — the dogfood path this skill accepts.

DIRTY=$(git status --porcelain -- \
  "$PLAN_DIR/_workflow/implementation-plan.md" \
  "$PLAN_DIR/_workflow/design.md" \
  "$PLAN_DIR/_workflow/design-mechanics.md" \
  "$PLAN_DIR/_workflow/plan/" \
  | grep -v '^?? \.migration-progress$')

if [ -n "$DIRTY" ]; then
  echo "ERROR: uncommitted or untracked changes under the active plan's _workflow/ artifacts:"
  printf '%s\n' "$DIRTY"
  echo "Commit, stash, or remove these files before re-running /migrate-workflow."
  exit 1
fi

The .migration-progress sentinel (Step 3) is the only carve-out; it is allowed to be untracked or modified mid-session. Any tracked file under the narrow scope showing a non-? status (modified, added, deleted, renamed, etc.) or any untracked file showing ?? halts the session with the offending paths printed; the user must commit, stash, or remove them before re-invoking.

The check is deliberately narrow. The dropped develop-side whole-tree check incidentally guarded the live skill file (.claude/skills/migrate-workflow/SKILL.md); the staging convention for workflow-modifying branches (in-flight rewrites land under staged-workflow/ rather than the live paths) now keeps the live skill at develop's state throughout execution, so the migration always reads the develop-state skill regardless of st

---

Content truncated.