migration-dashboard

name	migration-dashboard
description	Codex-native migration analysis dashboard for Claude→Codex skills and agents. Reads `migration-state.json` to report progress, drift, velocity, nativeness-review state, validator results, and next-batch recommendations. Use for "migration status", "what should I migrate next", "migration progress", or "migration dashboard".

Migration Dashboard

Purpose: Answer "where are we, what drifted, what should be migrated next, and when should nativeness review take over?" from the tracker plus live repo state.

Conversation-First Entry

Bare dashboard requests should open with intent routing, not raw flags. Follow the shared contract at ../migrate-to-codex/references/conversational-migration-contract.md.

Default menu for underspecified requests:

1. Status
2. What should I migrate next?
3. Review nativeness backlog
4. Show unreviewed migrated artifacts
5. Show migrated agents needing nativeness review
6. Show migrated skills needing nativeness review
7. Validate migrated artifacts
8. Refresh tracker and show status

Routing rules:

• If the user already says what next, review nativeness, unreviewed migrated artifacts, agents needing nativeness review, skills needing nativeness review, validate migrations, or refresh, route directly.
• In Plan mode, use request_user_input only for the action choice.
• Outside Plan mode, render the same menu as numbered text.
• Require explicit confirmation before --refresh because it writes the tracker file.
• After any non-empty nativeness queue, stay inside that queue subtree and prompt for review next, review <number>, review <name>, or back.
• Bare numbers are reserved for the root dashboard menu; queue picks must use the review ... prefix.

Advanced CLI

• Canonical front door: python3 .codex/skills/migration-dashboard/scripts/analyze_migration.py
• python3 .codex/skills/migration-dashboard/scripts/analyze_migration.py
• python3 .codex/skills/migration-dashboard/scripts/analyze_migration.py --plan
• python3 .codex/skills/migration-dashboard/scripts/analyze_migration.py --review-backlog
• python3 .codex/skills/migration-dashboard/scripts/analyze_migration.py --unreviewed --json
• python3 .codex/skills/migration-dashboard/scripts/analyze_migration.py --agent-nativeness
• python3 .codex/skills/migration-dashboard/scripts/analyze_migration.py --skill-nativeness
• python3 .codex/skills/migration-dashboard/scripts/analyze_migration.py --validate --json
• python3 .codex/skills/migration-dashboard/scripts/analyze_migration.py --refresh --json
• Power-user raw analyzer: python3 .codex/skills/migration-dashboard/scripts/analyze_migration.py --json

Sandbox Policy

Recommended mode: workspace-write

Rationale: the dashboard reads repo state and tracker data, and --refresh updates migration-state.json through the repo tracker script.

Runtime Contract

1. Preserve direct script execution. This workflow is script-driven, not sub-agent-driven for status, planning, validation, and refresh modes.
2. The analyzer is the source of truth for status, planning, drift, velocity, and validator aggregation.
3. Shared tracker-state helpers live in tools/migration_support/; analyzer scripts bootstrap that package before importing tracker helpers.
4. Mode routing stays stable:
   • default / --status: structural progress, nativeness-review state, tier breakdown, drift, velocity
   • --plan: next batch recommendation with dependency ordering
   • --review-backlog: prioritized nativeness-review queue across skills and agents
   • --unreviewed: exhaustive pending nativeness-review queue across migrated skills and agents
   • --agent-nativeness: migrated agents currently parked in pending_native_review
   • --skill-nativeness: migrated skills currently parked in pending_native_review
   • --validate: validator pass/fail across migrated skills plus review-state context
   • --refresh: tools/migration_support/tracker.py --write, then status
5. Tracker data comes from migration-state.json. Missing or malformed tracker state is a first-class UX case: explain it briefly, offer the repair action, and do not collapse into an opaque stack trace.
6. Queue-selection state should come from the analyzer's JSON contract, not by reparsing rendered text. Cache the most recent displayed queue with session-scoped state such as session_state_store in the parent chat workflow so review next, review <number>, and review <name> resolve deterministically.
7. A queued nativeness review is bounded orchestration work. When the user says review next, review <number>, or review <name> for a displayed queue, this workflow is authorized to route into the sibling migration skill's read-only nativeness-review flow without asking for a second delegation confirmation.
8. File edits use apply_patch only when maintaining the skill package or the analyzer script itself.
9. Structured analyzer results may include an additive recommended_action field. Treat it as the top-level routing hint for chat-first UX, but do not break callers that only rely on items, blockers, next_actions, or selection.

Scripts

Script	Purpose
.codex/skills/migration-dashboard/scripts/analyze_migration.py	Tracker-driven migration dashboard with status, planning, drift, velocity, and validation modes
.codex/skills/migration-dashboard/scripts/analyze_migration.py	Stable repo-level entrypoint for the dashboard analyzer

Workflow

1. Resolve User Intent to Mode

Map the request to analyzer flags before running anything.

User says	Run
migration status, migration dashboard, no mode	(no flags)
what should I migrate next, plan batch	--plan
review nativeness, nativeness backlog, what should I review next	--review-backlog
show unreviewed migrated artifacts, what is still unreviewed	--unreviewed
show migrated agents needing nativeness review, agent nativeness queue	--agent-nativeness
show migrated skills needing nativeness review, skill nativeness queue	--skill-nativeness
validate migrations, check migration quality	--validate
refresh migration tracker, update tracker and show status	--refresh

Pass through supported options unchanged:

• --batch N
• --all
• --no-color

For bare requests, present the action menu from the shared conversational contract instead of defaulting straight to a status dump.

2. Run the Analyzer Directly

Execute the skill-owned script with python3:

python3 .codex/skills/migration-dashboard/scripts/analyze_migration.py [args]

Do not redesign this into a plan flow or a delegation workflow. The preserved behavior is a single analyzer command plus interpretation.

3. Interpret the Output

Read the analyzer output by mode:

• Status: structural progress, nativeness-review state, pending-tier breakdown, velocity, drift alerts, and ignored policy exclusions.
• Plan: ready skills ordered by unblock impact, blocked skills with the first missing dependency, and ignored skills listed separately.
• Review backlog: prioritized nativeness-review queue with agents first, then trust level, then skill tier.
• Unreviewed: all migrated skills and agents still waiting on nativeness review, grouped by artifact type.
• Agent nativeness: pending nativeness-review queue restricted to migrated agents.
• Skill nativeness: pending nativeness-review queue restricted to migrated skills.
• Validate: per-skill validator pass/fail for migrated Codex skills plus whether each artifact is pending review, reviewed native, or reviewed compatible-but-not-native.
• Refresh: tracker update first, then the same status interpretation as default.

Chat-first recommendation rules:

• If drift exists, drift repair is the primary recommendation.
• If actionable migration backlog is zero but nativeness-review backlog is non-zero, review nativeness backlog becomes the primary recommendation in status, plan, and validate modes.
• If ready migration backlog remains, planning or migration stays primary and nativeness review stays secondary.

Nativeness queue interaction rules:

• If the queue is non-empty, number the rows and recommend one next item.
• For queue modes, prefer python3 .codex/skills/migration-dashboard/scripts/analyze_migration.py --json so the workflow can store the structured selection payload directly.
• Cache the most recent displayed queue snapshot with:
  • scope.mode_name
  • displayed artifact_ids and display_index
  • selection.recommended_artifact_id
  • timestamp
• End the turn with:
  • review next
  • review <number>
  • review <name>
  • back
• review <number> resolves only against the most recent displayed queue.
• If no valid cached queue exists, fail closed and ask the user to reopen the queue instead of guessing.
• Treat the displayed queue as a finite session queue. After a review outcome is recorded, re-render the same queue minus the handled item; when it is exhausted, show a done state and require back before returning to the root menu.
• If the queue is truncated, say exact-name selection only works for items shown in the current session queue. Hidden items require backing out and reopening the queue.
• If tracker integrity is blocked, suppress queue selection and recommended_action payloads, tell the user to run python3 tools/migration_support/tracker.py --write, and do not route review next, review <number>, or review <name> until the tracker is repaired.

4. Offer the Next Action

After reporting the analyzer output:

• If drift is detected, suggest rerunning $migrate-to-codex for drifted skills.
• If --plan shows blockers, point out the single migration that unblocks the most downstream work.
• If --plan shows ignored items, treat them as backlog context only, not work to unblock.
• If --plan shows no actionable pending items but nativeness review backlog remains, recommend review nativeness backlog instead of leaving the user in a dead-end plan screen.
• If --review-backlog or --unreviewed returns pending items, point the user at the recommended artifact, then offer review next, review <number>, review <name>, or back.
• If --agent-nativeness returns no items, say the agent nativeness queue is clear rather than redirecting back to migration planning.
• If --skill-nativeness returns no items, say the skill nativeness queue is clear rather than redirecting back to migration planning.
• If --validate fails skills, suggest re-migrating or patching those skill packages before further rollout.
• If --validate passes and nativeness review backlog remains, recommend the backlog next and surface a short list of warning-heavy pending-review artifacts in text mode.
• If velocity is zero and tracker history looks sparse, note that a new tracker history can suppress velocity without implying a real stall.

If the user selects a single queued artifact:

• Route into a single-item nativeness review, not back to migration planning.
• Agent target -> hand off to migrate-agents-to-codex review flow.
• Skill target -> hand off to migrate-to-codex review flow.
• Start read-only: audit first, auto-record native by default when the final result is NO_FINDINGS, and only ask the user to choose when fixes remain, only MEDIUM findings remain, or the user explicitly requested audit-only behavior.
• Keep the dashboard as the router only. The sibling migration skill owns the spawned nativeness auditor, convergence loop, evidence handling, and tracker close-out guidance.
• The parent thread should return a compact summary only:
  • artifact id and verdict
  • top findings or NO_FINDINGS
  • recorded review outcome when auto-recorded
  • next action
  • evidence path when available
• Do not paste the full delegated review body back into the main thread unless the user explicitly asks for it.

5. Failure Handling

• Missing or malformed tracker file: explain the tracker state is unavailable, then offer python3 tools/migration_support/tracker.py --write.
• Ambiguous archived-review recovery: explain that nativeness queues are blocked until tracker state is repaired, then offer python3 tools/migration_support/tracker.py --write.
• Missing validator: report the missing repo script path directly.
• Timeout or subprocess errors in --validate: surface the failing skill and the truncated error output from the analyzer.

Notes

• Tier classification is heuristic. The dashboard is for prioritization, not for bypassing skill review.
• Status semantics:
  • blocked = unresolved dependency blockers inside the active migration backlog
  • ignored = intentionally excluded from migration policy and omitted from actionable backlog math
• Dependency extraction only trusts explicit skill-call syntax in source skills and agent skills: frontmatter, not prose references.
• Explicit legacy skill-call references are dependency signals for planning, not an automatic Tier 3 classifier by themselves.
• Runtime references to .claude/ remain intentional here because the dashboard audits migration from source .claude/ artifacts into .codex/ artifacts.