# AI Break Duel Card Addition

> Add or modify AI Break Duel cards end-to-end across the React/TypeScript game, headless simulation, decks, UI text, generated card art, documentation, tests, and commits. Use when the user asks to add a summon, command, relic, card effect, deck entry, card wording change, card image, or card-balance rule in the ai-break-duel repository.

- Skill: `tegnike/ai-break-duel-card-addition` (Agent Skill, multi-file: 3 files)
- Install (CLI): `npx skillmds@latest add tegnike/ai-break-duel-card-addition`
- Raw SKILL.md: https://api.skillmd.com/api/skills/tegnike/ai-break-duel-card-addition/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Web & Frontend
- Author: tegnike (https://skillmd.com/u/tegnike)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/tegnike/ai-break-duel-card-addition

---


# AI Break Duel Card Addition

## Workflow

1. Start from repository truth, not memory.
   - Read `docs/game-spec.md` for current rules and naming conventions.
   - Read `references/file-map.md` for the files that must stay synchronized.
   - Inspect current code around similar card effects before editing.

2. Model the card once in the single TypeScript implementation.
   - Add TypeScript effect unions, card pool entries, deck entries, rule helpers, action resolution, AI behavior, UI selection flow, and card text.
   - The browser game and the headless simulation CLI (`src/sim/`) share the same engine, so one change covers both.
   - **Register every new or changed card effect in `src/game/cardEffectCoverage.test.ts`.** The unit
     suite fails by design when an effect is unregistered, so skipping this breaks `npm run check`.
   - Respect the deck construction rules when touching deck entries: 25 cards per deck, at most 2
     copies per card name, and at most 5 summons of power 3 or higher.

3. Treat visible card text as player-facing rules text.
   - Do not include internal implementation caps such as "maximum 3" on the card unless the user explicitly wants it on-card.
   - Put internal details in `docs/game-spec.md` detailed rule sections when useful.
   - Write draw text as `山札からカードをN枚引く`.
   - Avoid `ただし`; split drawbacks into separate short sentences, e.g. `消耗で出る。手札防御に使えない。`
   - Opponent draw logs must not reveal opponent card names.

4. Add generated art for every new card unless the user explicitly opts out.
   - **Under Codex**: use the `imagegen` skill directly.
   - **Under Claude Code**: `imagegen` cannot be executed directly. Delegate the generation to
     Codex CLI via the `codex:rescue` skill (or the `codex:codex-rescue` subagent), passing a
     self-contained task such as:
     `imagegen スキルで「<カード名>」のカードアートを生成し、1600x900 (16:9) の WebP として
     src/assets/card-art/<card-id>.webp に保存して。アート方向性: <雰囲気・モチーフの指示>`
     After the run, verify the file exists and is 16:9 (e.g. `sips -g pixelWidth -g pixelHeight <file>`)
     before registering it.
   - Only if Codex is unavailable, procedural composition with PIL is an acceptable fallback
     (see `src/assets/card-art/cmd-purge.webp` for a precedent).
   - Default card art should be 16:9 landscape WebP under `src/assets/card-art/`.
   - Vary the art direction/style prompt for each card instead of reusing one
     fixed house style across a batch.
   - Import the asset in `src/components/cardPresentation.ts` and map it in `SUPPORT_CARD_ART` or `AI_CARD_ART`.

5. Update docs and tests.
   - Update `docs/game-spec.md` for authoritative current rules.
   - Update design/planning docs only when they would become misleading.
   - Add focused vitest cases in `src/game/*.test.ts` for rule behavior.
   - Add or adjust UI tests only if the project already has a relevant harness or the UI change is high risk.
   - **Check the tutorial is not broken.** `src/tutorial.ts` scripts a fixed playthrough that depends
     on specific card IDs, costs, effects, and draw order. Changing a card that appears in the
     tutorial decks can silently soft-lock the scripted flow. Run
     `npx vitest run src/game/tutorial.test.ts`, and for changes to tutorial-deck cards walk the
     scripted turns on paper (or in the browser) before calling the change done.

6. Verify before reporting or committing.
   - Run `npm run check` (typecheck + vitest + build). If `npm` is not on PATH
     (Codex runtime), use `PATH="/Users/user/.cache/codex-runtimes/codex-primary-runtime/dependencies/node/bin:$PATH" npm run check`.
   - If assets or text layout changed substantially, inspect the browser when practical.
   - Card additions and effect changes shift the balance. For anything beyond cosmetic changes,
     follow the verification pipeline in `.agents/skills/ai-break-duel-balance-tuning/SKILL.md`
     (league on 2+ seeds, excitement metrics, `docs/balance-history.md` entry).

7. Commit in useful units.
   - Separate mechanical wording/docs-only cleanup from new card implementation when both exist.
   - Include generated assets in the implementation commit.
   - Keep commit messages short and concrete.