phase

Use to run a continuous review sweep over open contributor PRs in phase.rs. The skill is a thin orchestration layer over scripts/pr_review.py: discover candidates, detect stale reviews/follow-ups, dispatch review-impl for PRs that need judgment, and delegate authorized merge handling to pr-contribution-handler.

Use when doing any parser work — adding new Oracle text patterns, verb forms, phrase helpers, target patterns, subject handling, effect chain composition, fixing Unimplemented fallbacks, or understanding the parser architecture. This is the SINGLE SOURCE OF TRUTH for all oracle parser knowledge. Covers the nom combinator mandate, parsing priority system, AST type system, all helper modules, and contribution checklists.

Use when adding or modifying frontend UI components — interactive overlays for WaitingFor states, game board elements, card choice modals, animation effects, or any React component that interfaces with the engine via GameAction dispatch.

Use when adding or modifying replacement effects — ETB-tapped, shock lands, damage prevention, "as enters" choices, or any event-modifying ability. Covers ReplacementDefinition wiring, the pipeline flow, post-replacement effects, and interactive pre-zone-change choices.

Use when adding a new effect, mechanic, or parser capability to the engine. Covers the full lifecycle from types → parser → resolver → targeting → frontend → AI → tests.

Use when adding or modifying keyword abilities — evergreen keywords (flying, trample), parameterized keywords (ward {2}, kicker {R}), protection variants, or any keyword that needs runtime behavior wired into combat, targeting, damage, or triggers.

Use when adding or modifying static abilities, continuous effects, or layer system modifications — type-changing effects, power/toughness modification, keyword granting, color changes, CDAs, or any "as long as" / "enchanted creature" / "creatures you control" ability.

Use when adding or modifying triggered abilities — ETB, dies, attacks, damage dealt, spell cast, phase-based, or any "When/Whenever/At the beginning of" ability. Covers TriggerDefinition, TriggerMode, the matcher registry, APNAP ordering, targeting, intervening-if, constraints, and parser wiring.

Canonical recipe for writing engine cast-pipeline tests. Use GameScenario + GameRunner::cast(...).resolve() and assert via CastOutcome deltas. Covers the six test-harness foot-guns (hand-written TargetRef vectors, incomplete modal target submission, wrong-point hand baseline, inline-keyword cards, AST-internal flag assertions, vacuous negative assertions) and the right-way fix for each. Use whenever writing or porting a runtime test that casts a spell and checks its effect.

Use when modifying the casting flow, stack resolution, condition systems, WaitingFor/GameAction state machine, or adding optional costs, new casting steps, or conditional ability resolution.

Reference lookup for phase.rs — build/test/cargo/clippy commands, cargo aliases, WASM build, card-data pipeline and jq lookups, frontend (pnpm) commands, coverage report, crate/workspace architecture, engine internals, WASM bridge, AI engine, multiplayer server, frontend layers, environment variables, releasing (cargo-release), and CI. Use when you need to look up how to build, test, run, generate card data, release, or where a crate, module, command, or env var lives.

Use when asked to handle, harden, or shepherd one or more external contributor PRs. Checks out PRs in a worktree or main workspace, updates them against origin/main, resolves review comments, performs architecture-focused implementation review, decides whether fixes are inline or require engine-implementer review cycles, and usually closes explicitly deferred follow-up work while already in the PR.

Use when adding a new deck-aware AI feature (`DeckFeatures` axis) and its companion policies (`TacticalPolicy` + optional `MulliganPolicy`) to `phase-ai`. Codifies the structural-detection pattern, AST-type locations, parts-based predicate convention, registry wiring sites, and recurring review traps so a new feature ships in a single commit without re-research.

Review an implementation in scope, such as an uncommitted diff, a just-finished agent change, a commit, or named files, for missing or wrong behavior in phase.rs. Use when Codex needs a findings-only architecture and correctness review across engine, parser, frontend, multiplayer, AI, deck, build, or release changes.

Use when shipping local commits to main via the merge queue. Creates an isolated worktree based on origin/main, cherry-picks the named commits into a fresh branch, pushes with --no-verify, opens a PR with `gh pr create --fill`, and enqueues with `gh pr merge --squash --auto`. Outbound counterpart to `pr-contribution-handler`. Use when the user says "ship this", "push to main", "send through the queue", "PR this work", or has finished a chunk of work and wants it on main.

Produce an architecturally idiomatic implementation plan for a phase.rs parser or engine change. Design for the class of cards, not the single card. Use this when you need a plan that will survive `/review-engine-plan` without bandaids or workarounds.

Use when adding any effect or ability that requires player input mid-resolution — choices, selections, modal decisions, or any WaitingFor/GameAction round-trip. Covers the continuation pattern, engine handler wiring, AI legal actions, multiplayer routing, and frontend UI.

Use when triaging Phase Discord bug reports, syncing reports into triage artifacts, creating or updating GitHub issues, tracking bug clusters, or applying the repository's bug-fix review workflow.

Runnable checklist gate for any proposed engine enum variant addition. Routes the proposal through the parameterization filter, the categorical-boundary check, and the existence verification before extension is permitted. Invoke this skill BEFORE proposing or implementing any new variant on QuantityRef, QuantityExpr, FilterProp, TargetFilter, ReplacementCondition, AbilityCondition, TriggerCondition, StaticCondition, ChoiceType, DelayedTriggerCondition, Effect, Keyword, ContinuousModification, or any other engine enum.

End-to-end phase.rs implementation pipeline: plan, review-plan, implement, review-impl, commit — each step run in a fresh spawned agent.

Review phase.rs engine, parser, AI, frontend, or rules implementation plans before code is written. Use when Codex needs an architectural gate for plans involving parser changes, engine mechanics, MTG Comprehensive Rules behavior, new variants, targeting, replacement effects, stack/casting flow, AI policy, or frontend GameAction workflows.

Use when classifying a Phase bug report against a specific card's engine-authoritative parse_details. The primary job is validating that a card CLAIMS to support the misbehaving clause and then comparing the parsed AST against the Oracle text to confirm or refute that claim. Unsupported clauses are already known gaps and get deferred. Reads the same coverage data the Alt-hover overlay and card-bot render. Invoked by /bug-triage and /issue-clusterer.

Generate a Discord-ready "What's New" changelog for phase.rs from recent git history. Use when Codex is asked for a changelog, release notes, Discord update, recent shipped changes, or the next sequential changelog batch from a prior tip hash.

Use when implementing multiple unimplemented mechanics in batch. Creates an agent team that groups items by relevance, plans each group with review loops, then executes sequentially with post-implementation verification. Append the list of mechanics to address after invoking.

Use when modifying the card data pipeline — adding new fields to card exports, changing Oracle parser output shape, updating card database loading, modifying the coverage report, adding synthesis functions, or debugging why a card's data looks wrong at runtime.

Use when running AI-vs-AI duel simulations, validating AI matchup quality, checking combat or spellcasting regressions, tuning ai-duel CLI options, or interpreting batch simulation results.

Use when retraining AI evaluation weights from 17Lands replay data, adding new training datasets, updating learned weight values in phase-ai Rust code, or running CMA-ES optimization for AI profiles and evaluation parameters.

Fast-iteration loop for quick parser wins — surface near-miss cards via parser-gap-analyzer's typed category classifier, edit in batches, compile once per batch (not per card), defer the full gate (fmt/clippy/test-all/coverage/semantic-audit) to session end. Companion to `unlock-set`; use this when the fix is "add a `tag()` arm to an existing `alt()`" rather than cluster-level infrastructure. Trigger phrases: "quick parser wins", "scan near-misses", "velocity pass on <format>", "parser velocity sprint", "low-hanging parser fruit".

Unlock the majority of a Magic set's unsupported cards by clustering missing parser/engine primitives, briefing the engine-implementer skill tier-by-tier, and committing between clusters. Use when the user asks to "unlock the [SET] cards", "improve coverage for [SET]", or requests highest-ROI coverage work on a specific set (Standard, Commander precon, supplemental). If no set is named, default to the most recent Standard or Commander set by expected ROI (new-printing density).

Use when writing, modifying, or reviewing CR (Comprehensive Rules) annotations in engine code — any time a `// CR` or `/// CR` comment is added, changed, or audited. Ensures every CR number is verified against `docs/MagicCompRules.txt` before it enters the codebase.

Semantic audit of card-data.json — compare parsed JSON structures against Oracle text to find misparses in cards the coverage system marks as "supported." Supports --after for parallel agent runs and appends to a shared report.