Repo Sync

Repo Sync

Bidirectional sync between a plan document and GitHub issues. Creates, updates, closes, and enriches issues so GitHub mirrors the plan's structure and any fresh-context LLM picking up a step has enough context in the issue body to start work.

Principle: optimize for LLM effectiveness, not human-noise reduction

Issue bodies should be substantive. A fresh-context model reading gh issue view #N should understand:

• What to build (not just a name)
• Where in the codebase (specific files)
• How to know it's done (concrete acceptance)
• What it depends on (prior issues, blocked-by relationships)
• Build-phase flags (reviewers, isolation, --ui when frontend is touched)
• Where the canonical design lives (build doc + section anchor)
• Whether the step can run in parallel with neighbors (declared explicitly,

not left for the operator to infer)

Lean bodies (just "What to build" and a footer) tax every future session that picks up that issue. Treat enrichment as a first-class output, not optional polish. Issue count and inbox tidiness are human-experience costs the operator is fine paying — don't optimize for them at the expense of the LLM-context-effectiveness above.

Operator preference (HEAVY) — autonomous + bundled UI + parallel

This skill propagates the operator's strong workflow preference through every issue it writes. Three dials, applied to every step body:

1. Autonomous build readiness. Step bodies must contain enough acceptance

detail (Done when) for /build-step to verify PASS without asking the operator a follow-up. Bodies that force a human ping mid-build are a regression. When enriching, prioritize concrete acceptance over prose.

1. UI-bundle declaration. If a step's Files touch frontend/, change a

/api/... shape consumed by the dashboard, or modify WebSocket payloads, the issue body's Flags (recommended) line MUST include --ui and the Done when MUST reference UI evidence (Playwright screenshot, dashboard smoke, or any project-specific UI/dashboard smoke commands defined in the project's CLAUDE.md). Code-only acceptance on frontend-touching work is the gap repo-sync is here to close — flag any existing issue that violates this and propose enrichment.

1. Parallelism declared explicitly. If a step has no Depends on and

shares no Files with another open step in the same phase, the body MUST note **Parallel-safe with:** #M (and the reciprocal noted on #M too). Sequential is fine, but none — strictly sequential MUST carry a one-line justification (e.g. "Step N+1 imports this module"); a bare "strictly sequential" without a reason is a defect — the parallelism choice must be visible in the issue, not hidden in the operator's head.

These dials are applied during CREATE, ENRICH, and UPDATE — not just on first write. A pre-existing rich body that lacks the UI-bundle declaration on a frontend-touching step still counts as needing ENRICH.

When to use

• Plan steps were added, removed, or reworded after issues were created
• Existing issues have lean bodies that need richer context (--enrich)
• Cutting issues for a new phase from its build doc
• User says: "sync issues", "update GitHub issues", "enrich step issues",

"issues are out of date"

When NOT to use

• Closing a single issue after a step completes — just gh issue close N
• Bulk-closing issues from a deleted plan (use gh issue list ... | xargs gh issue close)

---

Prerequisites

Run the plan pipeline in order. /repo-sync is step 4 of 5:

1. /plan-init or /plan-feature — produce plan.md.
2. /plan-review — gap-check before sync.
3. /plan-wrap — clean-context check before sync.
4. /repo-sync — mint or update issues from the plan.
5. /build-phase — execute the steps.

Skipping /plan-review or /plan-wrap before sync is the N+1 rework trap: one plan edit becomes N+1 edits — the plan file plus every step issue body that needs the same fix. /repo-sync mints fresh-context-LLM-targeted issue bodies straight from the plan, so plan-only ambiguities (undefined IDs, unexplained acronyms, lingering TBDs) bake into every issue.

For an autonomous pre-flight that runs the chain unattended, use /plan-expedite --plan — it chains plan-review --autofix → plan-wrap --autofix → repo-sync → session-wrap in one shot.

Canonical workspace-level statement of the chain lives in dev/.claude/rules/plan-and-issue-flow.md § Order.

---

Arguments

| Arg | Required | Default | Description | |---|---|---|---| | --plan | yes | -- | Path to plan/build-doc (e.g. documentation/plans/phase-d-build-plan.md) | | --phase | no | inferred | Phase identifier (B, D, E, 6, 7, F, G, G.2, 9, etc.) — letters and numbers both supported. Inferred from filename if omitted. | | --scope | no | both | umbrella, steps, or both | | --enrich | no | false | Update existing-issue bodies if richer content is now in the plan | | --dry-run | no | false | Print issue-change preview and exit without applying — for validation before commit |

---

Phase identifier conventions

Phases can be:

• Numeric: Phase 0, Phase 1, ..., Phase 9 — common for substrate/operational tracks
• Letter: Phase A, Phase B, Phase D, ..., Phase G — common for capability tracks
• Sub-phase: Phase G.1, Phase G.2, Phase G.3 — for multi-step phases that fork

Numbering gaps are allowed and intentional (e.g. project skipped Phase C during a merge; project may skip Phase 8 to align with pre-existing issue titles). The skill honors the plan as-written — does NOT try to fill gaps.

Step numbering within a phase uses dot notation in the build doc (e.g. D.1, D.2, 7.1, G.2.1) but issue titles use the friendlier Phase X Step N: form.

Issue title patterns the skill recognizes:

• Umbrella: Phase X — (e.g. Phase D — Build-order z-statistic)
• Step: Phase X Step N: (e.g. Phase D Step 1: Audit reward_rules.json)
• Sub-phase umbrella: Phase X.M: (e.g. Phase G.2: Zerg bot)
• Sub-phase step: Phase X.M Step N:

Step-detection formats supported in plan docs

The skill scans the plan for any of:

• ### Step N: — heading style
• ### Phase X Step N: — explicit phase heading
• #### Step N: — sub-heading style
• - **Step N:** — list style
• | X.N | | — table row in a Scope / Build-steps section

For table-row format, the description is the step title; richer body content must be pulled from explicit per-step subsections OR the doc is flagged as lean (see "Doc richness check").

---

Flow

Step 0 — Pre-flight: resolve and verify target repo

gh resolves the target repo from cwd by walking up to the nearest .git/. The dev/ workspace root is itself a git repo with its own remote (/coding-root), so running gh from dev/ silently lands on /coding-root instead of the intended project subdirectory. Resolve and echo the repo before any mutating call:

cd 
REPO=$(gh repo view --json nameWithOwner -q .nameWithOwner)
echo "Target repo: $REPO"

Confirm the printed Target repo: matches the intended project. If it does not, stop — the cwd is wrong.

For every subsequent gh call in the run, pass -R / defensively so cwd-resolution cannot drift mid-run:

gh -R /Alpha4Gate issue create ...
gh -R /Alpha4Gate issue list ...

Equivalent fix: cd into the project subdirectory before invoking gh (e.g., cd Alpha4Gate && gh ...). The -R flag is preferred because it survives mid-run cwd changes.

Step 1 — Read the plan and infer phase

Read --plan. If --phase not specified, infer from filename (phase-d-build-plan.md → D; phase-9-build-plan.md → 9; improve-bot-evolve-plan.md → check # Phase X ... H1 in content).

Extract:

• Umbrella metadata: title (from # ), goal, prerequisites,

effort, kill criterion, validation

• Step list: every step matching one of the supported formats

For each step, capture from per-step subsections if present:

• Problem / What to build
• Files / Files to modify / Files touched
• Existing context
• Done when / Acceptance
• Flags (build-step flags like --reviewers code --isolation worktree)
• Depends on
• Produces

If steps are table-only (sparse), flag this and run the richness check (below).

Step 2 — Doc richness check (the LLM-effectiveness gate)

For each step, count populated rich-fields out of 6: {Files, Done when, Flags, Existing context, Produces, Depends on}.

• Rich step: ≥ 3 fields populated
• Lean step: ≤ 2 fields populated

If >50% of steps are lean:

WARNING:  has N of M lean steps (only title + description).

Issues created from lean steps will be lean too. Every fresh-context
LLM session that opens those issues will need to drill into the build
doc or source code for context the issue body should have.

Per the LLM-effectiveness principle (memory:
feedback_optimize_for_llm_over_human_noise.md), the recommendation is:

  1. Enrich the build doc first with per-step Files / Done when /
     Flags / Existing context sections.
  2. Then re-run this skill (or run with --enrich for an existing
     issue set).

Continuing — issue bodies will reflect the plan's current shape.
Operator can re-run /repo-sync after enriching the plan if higher-
fidelity issues are needed.

Surfacing this cost is mandatory; the warning is a printed observability note that proceeds automatically without prompting. The operator can re-run /repo-sync after enriching the plan when richer issues are needed — but no halt mid-sync.

Step 3 — Fetch existing GitHub issues

# jq requires POSIX classes — no \d / \w / \s / \. (see Common mistakes § Perl-style regex escapes)
gh issue list --state all --limit 200 --json number,title,body,state \
  --jq '.[] | select(.title | test("^Phase [A-Z0-9]+([.][0-9]+)?( Step [0-9]+)?:|^Phase [A-Z0-9]+([.][0-9]+)? — "))'

This regex matches both umbrella titles (Phase X — ...) and step titles (Phase X Step N: ...) across numeric, letter, and sub-phase numbering. Falls through to the legacy (Phase \d+ )?Step \d+: if the new pattern returns nothing (back-compat).

3.1 — Cross-plan collision check

When a repo holds issues from multiple plans, step keys (Phase X Step N) collide and a new plan's step may match a stale issue belonging to an unrelated, possibly closed prior plan.

The disambiguator is the body footer /repo-sync writes. There are TWO footer shapes — both encode the source-plan path and the parser must recognize both. In the rendered issue body the plan path is a markdown link (square-bracket label wrapping the path, parenthesis URL ../blob/master/ plus that same path) so the path is clickable from the GitHub issue — never a code-spanned path followed by a parenthetical "linked to" phrase.

• Create path (see Body template — step):

*Synced from by /repo-sync at * (with `` rendered as the markdown link described above).

• Enrich / update path (see Update / enrich):

*Enriched by /repo-sync from @ *

Long-lived issues that have been re-synced carry the second shape; the parser must match both or every previously enriched issue falls through as "footer missing" — exactly the issues most likely to be cross-plan-colliding.

Regex shapes the parser must match:

• Create: Synced from \[(.*?)\]
• Enrich: Enriched by /repo-sync from (.+?)( @ |$)

Algorithm: for each issue that matched a plan step in the Step 3 fetch above, parse the footer's plan path from the issue body — from EITHER Synced from [] OR Enriched by /repo-sync from . If that plan path differs from the current --plan argument's path, classify the match as a CROSS-PLAN COLLISION (the issue belongs to a different plan; the step key collision is incidental).

Action: emit a WARN: cross-plan collision line in the Step 5 preview output for each collision. No halt — autonomous default still executes; the operator sees the warning in the preview but the run proceeds without prompting. Collided issues are excluded from ENRICH / REOPEN candidate lists (treat as stale w.r.t. this plan).

Example warning line in the preview:

WARN: cross-plan collision — issue #123 "Phase D Step 3: foo"
  plan footer: documentation/old-plan.md
  --plan arg:  docs/archived-plans/repo-sync-improvements-plan.md
  classify as: stale (do not ENRICH, do not REOPEN)

Footer-absent issues (legacy or hand-authored) cannot be classified by this check; fall through to the existing title-prefix match behavior. Add (footer missing) to the preview note so the operator knows the check could not run on that issue.

Always-surface contract. The rendered Step 3.1 output MUST state the two recognized footer shapes explicitly — even when no existing issues were matched in Step 3. This makes the parser's footer-aware classification visible and auditable in every run, not only runs that exercise it.

Required Step 3.1 header line in the rendered output:

Footer shapes recognized:
  Create:  Synced from [](...)
  Enrich:  Enriched by /repo-sync from  @ 

When no issues were matched, follow with (no existing issues to classify). When issues exist, list each with its footer plan path or (footer missing) per the algorithm above. Either way, neither footer shape is omitted from the output, so enriched-path issues are never silently treated as footer missing.

Step 4 — Match and diff

Match plan entries to existing issues by title prefix:

• Umbrella: Phase X — matches plan's H1 phase
• Step: Phase X Step N: matches plan step X.N or Step N

within the phase

Classify into buckets:

| Bucket | Condition | Default action | |---|---|---| | CREATE umbrella | Plan has phase, no umbrella issue | Create with full body | | CREATE step | Plan step has no matching issue | Create with rich body | | ENRICH | Issue exists, body is lean (≤2 sections), plan now has richer content | Update body (auto if --enrich OR if plan has clear new fields) | | UPDATE | Issue exists but title or body changed substantively | Update | | CLOSE | Issue exists, plan step removed | Close with comment | | NO-OP | Issue exists, body is rich, no plan change | Skip |

Step 5 — Preview

Print all proposed changes grouped by phase:

repo-sync: documentation/plans/phase-d-build-plan.md (Phase D)

  Build doc richness: 3/8 steps rich, 5/8 lean

  CREATE umbrella  Phase D — Build-order z-statistic (reward refactor)
  CREATE step      Phase D Step 1: Audit reward_rules.json (rich body)
  CREATE step      Phase D Step 2: Define z schema (rich body)
  CREATE step      Phase D Step 3: build_order_reward.py (lean — Files missing)
  ENRICH           Phase D Step 5 (#168) — body lacks Done when + Files
  UPDATE           Phase D Step 7 (#170) — title changed
  CLOSE            (none)
  NO-OP            (none)

If --dry-run was specified, stop here and print:

Dry-run complete. No changes applied.

Otherwise, proceed directly to Step 6 — print Applying changes now... and execute. Do not prompt for confirmation. The preview is the operator's read-out, not a halt point; autonomous orchestration (/build-phase, /plan-expedite) depends on this.

--dry-run flag

When /repo-sync --dry-run is invoked, the preview above is printed but no changes are applied. The skill exits cleanly with the message Dry-run complete. No changes applied. Use this to validate plan→issue mapping before committing to a sync.

Step 6 — Execute (one tool call per gh action)

Process in this order:

1. Umbrella issues first (so step issues can reference them)
2. Step issue creates
3. Step issue enrichments + updates
4. Closes last

Each gh issue create/edit/close is its own Bash tool invocation, OR a loop in one Bash with explicit per-iteration error handling. Do NOT batch with && — one failure must not break the

…

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: aberson
• Source: aberson/claude-skills
• License: MIT

Install and usage instructions live in the source repository linked above.