miadi-orchestration-kit

Use the Design Bundle Integration Kit

This skill is for Claude Code in the main session. It explains how to use the reusable Copilot plugin at /workspace/repos/jgwill/miadi-orchestration-kit/copilot/miadi-design-bundle-integration-kit to integrate any Claude Design bundle into any target codebase.

The plugin holds the generic toolkit (agents + skills). The PDE’s orchestration folder holds the instance-specific charters. Claude Code is the conductor.

When this skill applies

• A Claude Design bundle has been fetched and extracted (typically under <pde-folder>/bundle/<project>/).
• The bundle has a README.md, chats/, and project/ (with tokens.css, hub index.html, screens, and artifacts).
• A PDE folder already exists with a claude-design-handoff.md describing the bundle and the integration intent.
• The user is ready to begin (or resume) the integration waves.

If the bundle has not yet been fetched and extracted, that is a prior phase — handle it directly in the main session (the integration kit does not fetch bundles).

What Claude Code does (the main-session orchestrator role)

1. Read the PDE’s claude-design-handoff.md to confirm: bundle path, target codebase, milestone reference, key fidelity anchors.
2. Confirm the orchestration folder exists at <pde-folder>/orchestration/ with at minimum:
   • prompts/wave1-*.txt, prompts/wave2-*.txt, prompts/wave3-*.txt (session charters)
   • launch.sh (parameterized launcher)
   • audit.sh (cheap post-wave audit)
   • MAIN_SESSION_HANDOFF.md (instance-specific orchestration brief)
3. Read MAIN_SESSION_HANDOFF.md — this is where the previous Claude Code instance recorded everything you need to know about this specific Design→Codebase pair.
4. Run waves sequentially, one at a time:
   • ./launch.sh <N> — runs the wave via Copilot CLI with the kit plugged in
   • ./audit.sh <N> — runs the cheap post-wave audit using a free model (gpt-5-mini)
   • Read wave-<N>-report.md after each wave; verify the orchestration contract was followed
   • If audit shows the contract broke, tighten the prompt before launching the next wave
5. Stay out of implementation. The whole point of the kit is that Claude Code does not absorb implementation diffs. You are the conductor; Copilot + its subagents do the work; reports come back as compressed summaries.
6. The final wave (audit + close) stays in main session — you read all the reports, validate the integration, link rispecs, and close the milestone or issue.

The launch contract (what the orchestration folder’s launch.sh does)

copilot \
  --model gpt-5.4 \
  --reasoning-effort xhigh \
  --yolo \
  --no-ask-user \
  --plugin-dir /workspace/repos/jgwill/miadi-orchestration-kit/copilot/miadi-design-bundle-integration-kit \
  --add-dir <target-codebase> \
  --add-dir <pde-folder> \
  --add-dir /workspace/repos/jgwill/miadi-orchestration-kit \
  --add-dir /workspace/repos/miadisabelle/mia-awesome-copilot \
  --share <pde-folder>/orchestration/wave-<N>-session.md \
  --share-gist \
  --name "<wave-name>" \
  -p "$(cat <pde-folder>/orchestration/prompts/wave<N>-*.txt)"

--share-gist exports the full subagent dispatch ledger to a secret GitHub gist after the wave completes — Claude Code uses this to review and evolve the session.

The audit contract

After every wave:

copilot --resume --model gpt-5-mini --reasoning-effort high --yolo --no-ask-user \
  --add-dir <target-codebase> \
  --add-dir <pde-folder> \
  --share <pde-folder>/orchestration/wave-<N>-audit-session.md \
  --name "<wave-name>-audit" \
  -p "Read wave-<N>-report.md and the implementation files. Verify orchestration contract was followed: lane discipline, two-stage review, READ-ONLY bundle, context preservation, token fidelity. Report concretely with file:line. If broken, say where."

gpt-5-mini is free — the audit is cheap. Always run it.

Required reading before invoking

In order:

1. The PDE’s claude-design-handoff.md — the integration intent
2. The PDE’s orchestration/MAIN_SESSION_HANDOFF.md — instance-specific orchestration brief
3. /workspace/repos/jgwill/miadi-orchestration-kit/copilot/miadi-design-bundle-integration-kit/README.md — kit overview
4. /b/trading/skills/software-development/miadi-copilot-wave-launcher/SKILL.md — wave launcher conventions
5. /b/trading/skills/software-development/subagent-driven-development/SKILL.md — fresh-subagent-per-task pattern

Hard rules

• Don’t fork the plugin. If a new Design→Codebase pair needs integration, write new prompts in a new PDE’s orchestration folder and point at the same --plugin-dir.
• Don’t run waves out of order. Tokens before Hub before Screens before Audit.
• Don’t skip the cheap audit between waves.
• Don’t absorb implementation diffs into main-session context. Read wave reports; trust the orchestration contract; spot-check critical files only when an audit flags a gap.
• The Audit + Close wave stays in main session — synthesizing across all waves needs main-session context, not Copilot’s.

Where this fits in the suite

Kit	Use when
stckin-orchestration-kit	STCKin / structural-tension-aware deep-search
miadi-promotion-context-kit	Provenance → spec → wiki → retrieval promotion
miadi-adversarial-review-kit	Adversarial review of in-flight work
miadi-design-bundle-integration-kit	Design→Codebase integration (this skill drives it)

Compose by stacking --plugin-dir <kit> flags when a wave needs multiple kits.