yusifeng / formax-repomix-handoff-workflow

formax-repomix-handoff-workflow

Goal

Create a clean handoff package for another AI with:

• the smallest correct repomix bundle
• a prompt that matches the target environment
• explicit acceptance criteria and non-goals
• predictable artifact naming + validation (so uploads stay consistent)

Where to change what

• All handoff artifacts live in one folder: repomix-output/
• Bundle output: repomix-output/repomix-<topic>-<tier>.txt
• Handoff prompt: repomix-output/<topic>-handoff-prompt.md
• File manifest notes: repomix-output/repomix-<topic>-files.md
• Template references: references/prompt-templates.md

Required hygiene: each new pack run must clear previous files in repomix-output/ first, so users can upload that folder as-is without manual file picking.

Pack tiers (default taxonomy)

Use exactly one tier label in bundle filename:

• minimal: changed runtime files + direct dependencies + adjacent tests.
• core: minimal + only critical contract/design docs needed for intent.
• full: broad context pack for deep investigations (cross-subsystem docs/tests).

Example names:

• repomix-topic-minimal.txt
• repomix-topic-core.txt
• repomix-topic-full.txt

Patterns

1. Classify target runtime first

• Static consumer (e.g., WebGPT): cannot run local commands or tests.
• Executable agent (repo access): can run local commands/tests.

1. Pick a pack tier first (minimal / core / full)

• Default to minimal.
• Upgrade to core only when architecture/contracts matter.
• Use full only when root cause plausibly spans multiple subsystems.

1. Build the include set for that tier

• Include changed runtime files + direct dependencies + adjacent tests.
• Include only docs needed for intent/constraints at the chosen tier.
• Avoid unrelated folders to keep context small.

1. Pack with deterministic command (single folder, auto-clean)

bunx repomix . \
  --style plain \
  --no-git-sort-by-changes \
  -o repomix-output/repomix-<topic>-<tier>.txt \
  --include "<comma-separated-file-list>"

Or use the helper script:

bash .codex/skills/formax-repomix-handoff-workflow/scripts/build-repomix.sh \
  repomix-<topic>-<tier>.txt \
  "<comma-separated-file-list>"

The helper script will:

• create repomix-output/ if missing
• delete previous files under repomix-output/ (except .gitkeep)
• write the new bundle into repomix-output/

1. Write prompt + file manifest with naming convention

• Prompt: repomix-output/<topic>-handoff-prompt.md
• Manifest: repomix-output/repomix-<topic>-files.md
• Always use repo-relative paths in prompt + manifest (no machine absolute paths).

1. Write prompt with explicit boundaries

• State known symptoms.
• State hard constraints (what must not change).
• Define deliverables (root cause model, options, recommended plan, test/validation matrix).
• Include acceptance criteria with observable assertions.

1. Run artifact validation (required)

bash .codex/skills/formax-repomix-handoff-workflow/scripts/check-handoff-artifacts.sh \
  repomix-<topic>-<tier>.txt \
  <topic>

This check enforces:

• Bundle/prompt/manifest files all exist.
• Prompt and manifest reference the current bundle name.
• Manifest references the prompt filename.
• Prompt + manifest do not contain local absolute paths.

1. Sanity-check before handoff

• repomix-output/ only contains current-round artifacts.
• Bundle exists and includes the expected files.
• Prompt has no impossible instructions for the target runtime.
• Prompt does not ask static consumers to run commands.
• Naming is topic-driven and consistent across all three artifacts.

See references/prompt-templates.md for copy-ready templates.

Tests to update

• No repository tests required for creating the handoff itself.
• If target is executable, include a suggested minimal test list in the handoff prompt.

Guardrails

• Never include bun run test:coverage in a static-consumer prompt.
• Never assume the other AI can read files outside the provided bundle unless explicitly attached.
• Keep asks decision-oriented first (root cause/options) before patch implementation.
• Prefer concrete acceptance checks over vague goals.
• Avoid mixing unrelated bugfixes into one handoff package.
• Never leak machine absolute paths (e.g., /Users/...) in prompt/manifest.