Resolve every role through ../../../.codex/docs/plugin-agent-delegation.md; do not require a repository-local .codex/agents/ or .codex/agent-packs/ tree. Before default delegation, run python3 ../../../tools/codex_studio/agent_delegation.py resolve --project-root <project-root> --role <role> and use only its returned role contract.

Codex Interaction Contract

• Ask one decision question per turn and wait for the answer before asking another.
• Use request_user_input for structured choices when it is available; otherwise ask the same concise question directly.
• Use Codex custom agents by role and profile when delegation is useful.
• Treat any approved write as one complete proposed changeset. Do not add unlisted files or behavior; pause and request a new approval if scope expands.

Native readiness gate for $setup-engine

Before invoking or routing to $setup-engine, confirm that setup-engine is present in the current task's available skill catalog. If unavailable, report Staged dependency: $setup-engine is not available, defer the handoff, do not invoke $setup-engine, do not route to $setup-engine, and do not search for or copy a repository-local skill file.

Smoke Check

This skill is the gate between "implementation done" and "ready for QA hand-off". It runs the automated test suite, checks for test coverage gaps, batch-verifies critical paths with the developer, and produces a PASS/FAIL report.

The rule is simple: a build that fails smoke check does not go to QA. Handing a broken build to QA wastes their time and demoralises the team.

Output: production/qa/smoke-[date].md plus exact Config/Data evidence at production/qa/evidence/[story-id]-smoke-evidence.md

Parse Arguments

Arguments can be combined: $smoke-check sprint --platform console

Base mode (first argument, default: sprint):

• sprint — full smoke check against the current sprint's stories
• quick — skip coverage scan (Phase 3) and Batch 3; use for rapid re-checks

Platform flag (--platform, default: none):

• --platform pc — add PC-specific checks (keyboard, mouse, windowed mode)
• --platform console — add console-specific checks (gamepad, TV safe zones, platform certification requirements)
• --platform mobile — add mobile-specific checks (touch, portrait/landscape, battery/thermal behaviour)
• --platform all — add all platform variants; output per-platform verdict table

If --platform is provided, Phase 4 adds platform-specific batches and Phase 5 outputs a per-platform verdict table in addition to the overall verdict.

Phase 1: Detect Test Setup

Before running anything, understand the environment:

1. Test framework check: verify tests/ directory exists. If it does not: "No test directory found at tests/. Run $test-setup to scaffold the testing infrastructure, or create the directory manually if tests live elsewhere." Then stop.
2. CI check: check whether .github/workflows/ contains a workflow file referencing tests. Note in the report whether CI is configured.
3. Engine detection: read .codex/docs/technical-preferences.md and extract the Engine: value. Store this for test command selection in Phase 2.
4. Smoke test list: check whether production/qa/smoke-tests.md or tests/smoke/ exists. If a smoke test list is found, load it for use in Phase 4. If neither exists, smoke tests will be drawn from the current QA plan (Phase 4 fallback).
5. QA plan check: glob production/qa/qa-plan-*.md and take the most recently modified file. If found, note the path — it will be used in Phase 3 and Phase 4. If not found, note: "No QA plan found. Run $qa-plan sprint before smoke-checking for best results."

Report findings before proceeding: "Environment: [engine]. Test directory: [found / not found]. CI configured: [yes / no]. QA plan: [path / not found]."

Phase 2: Run Automated Tests

Attempt to run the test suite via the shell. Select the command based on the engine detected in Phase 1:

Godot 4:

godot --headless --script tests/gdunit4_runner.gd 2>&1

If the GDUnit4 runner script does not exist at that path, try:

godot --headless -s addons/gdunit4/GdUnitRunner.gd 2>&1

If neither path exists, note: "GDUnit4 runner not found — confirm the runner path for your test framework."

Unity: Unity tests require the editor and cannot be run headlessly via shell in most environments. Check for recent test result artifacts:

# List most recent test results (bash) — on Windows PowerShell use the fallback below
ls -t test-results/ 2>/dev/null | head -5 \
  || powershell -Command "Get-ChildItem test-results/ -ErrorAction SilentlyContinue | Sort-Object LastWriteTime -Descending | Select-Object -First 5 -ExpandProperty Name"

If test result files exist (XML or JSON), read the most recent one and parse PASS/FAIL counts. If no artifacts exist: "Unity tests must be run from the editor or CI pipeline. Please confirm test status manually before proceeding."

Unreal Engine:

# List most recent Unreal automation logs (bash) — on Windows PowerShell use the fallback below
ls -t Saved/Logs/ 2>/dev/null | grep -i "test\|automation" | head -5 \
  || powershell -Command "Get-ChildItem Saved/Logs/ -ErrorAction SilentlyContinue | Where-Object { $_.Name -match 'test|automation' } | Sort-Object LastWriteTime -Descending | Select-Object -First 5 -ExpandProperty Name"

If no matching log found: "UE automation tests must be run via the Session Frontend or CI pipeline. Please confirm test status manually."

Unknown engine / not configured: "Engine not configured in .codex/docs/technical-preferences.md. Run $setup-engine to specify the engine, then re-run $smoke-check."

If the test runner is not available in this environment (engine binary not on PATH, runner script not found, etc.), report clearly:

"Automated tests could not be executed — engine binary not found on PATH. Status will be recorded as NOT RUN. Confirm test results from your local IDE or CI pipeline. Unconfirmed NOT RUN is treated as PASS WITH WARNINGS, not FAIL — the developer must manually confirm results."

Do not treat NOT RUN as an automatic FAIL. Record it as a warning. The developer's manual confirmation in Phase 4 can resolve it.

Parse runner output and extract:

• Total tests run
• Passing count
• Failing count
• Names of any failing tests (up to 10; if more, note the count)
• Any crash or error output from the runner itself

Phase 3: Check Test Coverage

Draw the story list from, in priority order:

1. The QA plan found in Phase 1 (its Test Summary table lists expected test file paths per story)
2. The current sprint plan from production/sprints/ (most recently modified file)
3. If the quick argument was passed, skip this phase entirely and note: "Coverage scan skipped — run $smoke-check sprint for full coverage analysis."

For each story in scope:

1. Extract the system slug from the story's file path (e.g., production/epics/combat/story-001.md → combat)
2. file search tests/unit/[system]/ and tests/integration/[system]/ for files whose name contains the story slug or a closely related term
3. Check the story file itself for a Test file: header field or a "Test Evidence" section. Resolve all manual evidence only under the canonical production/qa/evidence/ root; do not search for manual evidence elsewhere.

Assign a coverage status to each story:

MISSING entries are advisory gaps. They do not cause a FAIL verdict but must appear prominently in the report and must be resolved before $story-done can fully close those stories.

Phase 4: Run Manual Smoke Checks

Draw the smoke test checklist from, in priority order:

1. The QA plan's "Smoke Test Scope" section (if QA plan was found in Phase 1)
2. production/qa/smoke-tests.md (if it exists)
3. tests/smoke/ directory contents (if it exists)
4. The standard fallback list below (used only when none of the above exist)

Tailor the sprint and regression checks to the actual systems identified from the sprint or QA plan. Replace every bracketed placeholder with a real mechanic.

Walk the checklist sequentially. Ask one decision question per turn for one check and wait for the answer before continuing. Each question offers Pass, Fail, and Not tested / N/A when N/A is valid. If the answer is Fail, ask for the failure description on the next turn before advancing. Record each answer verbatim.

Check groups:

1. Core stability: launch/main menu, new session, menu input, basic-navigation crash or hang.
2. Sprint changes and regression: each primary mechanic changed this sprint, each notable secondary change, and prior-feature regressions.
3. Data integrity and performance (unless quick): save/load integrity, frame-rate or hitching, and whether performance was measured.
4. PC when selected: keyboard, mouse/cursor, window mode, resolution changes.
5. Console when selected: gamepad, TV safe zones, device-appropriate prompts, cold start.
6. Mobile when selected: touch, orientation, background/foreground transitions, thermal performance.

Do not compress several checks into a multi-select or reproduce widget syntax. The report may group the recorded answers into batches, but the interaction remains sequential.

Phase 5: Generate Report

Assemble the full smoke check report:

## Smoke Check Report
**Date**: [date]
**Sprint**: [sprint name / number, or "Not identified"]
**Engine**: [engine]
**QA Plan**: [path, or "Not found — run $qa-plan first"]
**Argument**: [sprint | quick | blank]

---

### Automated Tests

**Status**: [PASS ([N] tests, [N] passing) | FAIL ([N] failures) |
NOT RUN ([reason])]

[If FAIL, list failing tests:]
- `[test name]` — [brief failure description from runner output]

[If NOT RUN:]
"Manual confirmation required: did tests pass in your local IDE or CI? This
will determine whether the automated test row contributes to a FAIL verdict."

---

### Test Coverage

| Story | Type | Test File | Coverage Status |
|-------|------|-----------|----------------|
| [title] | Logic | `tests/unit/[system]/[slug]_test.[ext]` | COVERED |
| [title] | Visual/Feel | `production/qa/evidence/[slug]-evidence.md` | MANUAL |
| [title] | Logic | — | MISSING ⚠ |
| [title] | Config/Data | — | EXPECTED |

**Summary**: [N] covered, [N] manual, [N] missing, [N] expected.

---

### Manual Smoke Checks

- [x] Game launches without crash — PASS
- [x] New game starts — PASS
- [x] [Core mechanic] — PASS
- [ ] [Other check] — FAIL: [user's description]
- [x] Save / load — PASS
- [-] Performance — not checked this session

---

### Missing Test Evidence

Stories that must have test evidence before they can be marked COMPLETE via
`$story-done`:

- **[story title]** (`[path]`) — Logic story has no test file.
  Expected location: `tests/unit/[system]/[story-slug]_test.[ext]`

[If none:] "All Logic and Integration stories have test coverage."

---

### Platform-Specific Results *(only if `--platform` was provided)*

| Platform | Checks Run | Passed | Failed | Platform Verdict |
|----------|-----------|--------|--------|-----------------|
| PC | [N] | [N] | [N] | PASS / FAIL |
| Console | [N] | [N] | [N] | PASS / FAIL |
| Mobile | [N] | [N] | [N] | PASS / FAIL |

**Platform notes**: [any platform-specific observations not captured in pass/fail]

Any platform with one or more FAIL checks contributes to the overall FAIL verdict.

---

### Verdict: [PASS | PASS WITH WARNINGS | FAIL]

[Verdict rules — first matching rule wins:]

**FAIL** if ANY of:
- Automated test suite ran and reported one or more test failures
- Any Batch 1 (core stability) check returned FAIL
- Any Batch 2 (primary sprint mechanic or regression check) returned FAIL

**PASS WITH WARNINGS** if ALL of:
- Automated tests PASS or NOT RUN (developer has not yet confirmed)
- All Batch 1 and Batch 2 smoke checks PASS
- One or more Logic/Integration stories have MISSING test evidence

**PASS** if ALL of:
- Automated tests PASS
- All smoke checks in all batches PASS or N/A
- No MISSING test evidence entries

Phase 6: Write and Gate

For every Config/Data story in scope, generate the exact path declared by the story:

production/qa/evidence/[story-id]-smoke-evidence.md

Each file uses this required schema:

# Config/Data Smoke Evidence
- Story ID: [stable story ID]
- Criterion IDs: [all verified criterion IDs]
- Build/engine: [build identifier and configured engine/version]
- Timestamp: [ISO-8601 date and time]
- Checks performed: [steps and inputs]
- Observed result: [actual values/behavior]
- Verdict: PASS / FAIL

Present the full summary and per-story evidence drafts. Then show one complete proposed changeset containing production/qa/smoke-[date].md and every per-story Config/Data evidence path. Ask:

"May I write this complete smoke summary and per-story evidence changeset?"

Write only after approval. Do not omit a declared Config/Data evidence file even when the summary passes; a FAIL run writes the exact file with Verdict: FAIL so $story-done can reject it deterministically.

After writing, deliver the gate verdict:

If verdict is FAIL:

"The smoke check failed. Do not hand off to QA until these failures are resolved:

[List each failing automated test or smoke check with a one-line description]

Fix the failures and run $smoke-check again to re-gate before QA hand-off."

If verdict is PASS WITH WARNINGS:

"Smoke check passed with warnings. The build is ready for manual QA.

Advisory items to resolve before running $story-done on affected stories: [list MISSING test evidence entries]

QA hand-off: share production/qa/qa-plan-[sprint].md with the qa-tester agent to begin manual verification."

If verdict is PASS:

"Smoke check passed cleanly. The build is ready for manual QA.

QA hand-off: share production/qa/qa-plan-[sprint].md with the qa-tester agent to begin manual verification."

Collaborative Protocol

• Never treat NOT RUN as automatic FAIL — record it as NOT RUN and let the developer confirm status manually. Unconfirmed NOT RUN contributes to PASS WITH WARNINGS, not FAIL.
• Never auto-fix failures — report them and state what must be resolved. Do not attempt to edit source code or test files.
• PASS WITH WARNINGS does not block QA hand-off — it records advisory gaps for $story-done to follow up on.
• quick argument skips Phase 3 (coverage scan) and Phase 4 Batch 3. Use it for rapid re-checks after fixing a specific failure.
• Use request_user_input for all manual smoke check verification.
• Never write the report without asking — Phase 6 requires explicit approval before any file is created.