stack-standards

name	stack-standards
description	Hold the project-local standards for languages, frameworks, validation, and runtime assumptions. Use when planning or implementing work that should follow repo-specific engineering conventions.

Stack Standards

Before applying these rules, call skill_ping with skill_id: "stack-standards" and scope: "project".

Current scaffold mode: __STACK_LABEL__

Universal Engineering Standards

These rules apply to all work in this repository regardless of stack.

Code Quality

• Write code for readability first; optimise only when profiled evidence justifies it.
• Keep functions and methods focused on a single responsibility; extract helpers when a unit exceeds a single screen of logic.
• Every public or exported symbol must have a documentation comment that describes intent, not implementation.
• Delete dead code instead of commenting it out; use version control to recover removed code.

Quality Gate Commands

Use the smallest stack-appropriate command set that proves the code still builds, references resolve, and the test surface is callable.

• Python: ruff check ., mypy . when configured, pytest --collect-only
• Node.js: npm run lint, tsc --noEmit, npm test
• Rust: cargo clippy, cargo test
• Go: go vet ./..., golangci-lint run, go test ./...
• Godot: godot --headless --check-only when available, scene reference checks, autoload validation, and verbose project load/import verification such as godot --verbose --headless --path . --quit; any SCRIPT ERROR:, parse, load, icon, or malformed res://res:/ diagnostic is a blocker even when Godot exits 0
• Native Android fallback: when repo-root settings.gradle, build.gradle, and app/ exist beside a checked-in android/gradlew wrapper, run ./android/gradlew -p . assembleDebug --no-daemon from repo root and prove app/build/outputs/apk/debug/app-debug.apk; do not validate the native app with ./android/gradlew -p android ..., which targets the old Godot wrapper project
• C/C++: cmake --build ., compiler warning review, and the configured test target when present
• .NET: dotnet build, dotnet test
• Generic make-based repos: make check or make test

When the repo stack is finalized, rewrite this catalog so review and QA agents get the exact build, lint, reference-integrity, and test commands that belong to this project.

Validation

• All external inputs (API payloads, file reads, environment variables) must be validated at the boundary before use.
• Assertions and precondition checks belong at the call site, not buried in utility helpers.
• Write tests for correctness-critical paths; treat flaky tests as bugs to fix before merge.

Visual Quality For Reviewable Repos

• Treat visual review as a contract, not as optional taste commentary.
• Style choice is not a blocker by itself. Block only when layout, readability, hierarchy, finish, or feedback is broken.
• Use named failure categories such as screen-fit failure, menu hierarchy failure, readability failure, silhouette failure, material readability failure, and motion-feedback failure.
• Menus, title screens, HUDs, and modal overlays must fit common viewport shapes and keep the primary interaction surface readable.
• Prefer one clear focal surface plus compact supporting UI. Do not frame the whole screen with equal-weight chrome.
• For interactive work, put long notes, controls lists, or lore behind drawers, toggles, or pause states instead of leaving them permanently open.
• Prefer free/open tools by default when authoring or revising art direction inputs: Inkscape, Krita, GIMP, Blender, and similar FOSS tooling.

Visual Proof In QA

• When .opencode/meta/bootstrap-provenance.json says requires_visual_proof: true, VISUAL-001, FINISH-VALIDATE-001, finish-visual, finish-validation, and any ticket with explicit visual-proof acceptance criteria must include a structured visual-proof block before the ticket can enter smoke-test. Bootstrap, setup, and non-visual tickets still need real command evidence, but they do not have to fabricate screenshot proof before visual work exists.
• The QA artifact should record:
  • visual_proof_status: PASS|FAIL|BLOCKED|APPROVED|REJECT|DEFERRED
  • visual_proof_evidence: <comma-separated screenshot/render paths>
  • visual_proof_surfaces: <comma-separated reviewed surfaces>
  • visual_rubric_blockers: none|<comma-separated blocker categories>
  • visual_style_note: <why the style is intentional or why a deviation is acceptable>
  • visual_proof_screen_analysis: <what the screenshot/render actually shows and why it is not blank/system UI>
  • visual_proof_visible_content: <concrete readable labels, controls, game objects, or primary content visible in the evidence>
  • visual_proof_asset_content: <brief-specific product art/content visible in the evidence, such as cartoon pictures, sprites, characters, objects, environments, icons, textures, or authored scene assets>
  • visual_proof_post_overlay: true|none present for Android/emulator final proof after fullscreen overlays, permission dialogs, and launcher/system UI are dismissed
  • audio_runtime_proof: <current-build playback evidence> when the finish contract requires voice, music, sound, spoken prompts, or feedback audio
  • gameplay_proof: <current-build interaction evidence> when the finish contract requires a game, playable loop, learning round, progression path, reward, mission, wave, or other game state change
• DEFERRED is only for non-final visual tickets that have executable headless or build evidence while an open FINISH-VALIDATE-001 owns runtime screenshot/capture proof; the final validation ticket must still provide real screenshot, render, capture, or video file evidence.
• Final Android or emulator proof must be a fresh post-overlay capture of the app UI. Screenshots showing "Viewing full screen", "Got it", launcher/system UI, black frames, gray frames, uniform color, or near-blank output are blockers, not visual proof.
• Final proof cannot rely on generic screen-analysis prose. It must name the expected on-screen content from the brief or ticket, such as menu labels, readable controls, HUD text, or game objects, and those items must be visible and unclipped in the evidence.
• Final proof cannot pass with only labels on colored rectangles when the Product Finish Contract requires ship-ready visuals or authored content. It must identify the actual product art/content visible in the evidence and route back to visual/content implementation when the runtime surface is still placeholder-grade.
• Final audio proof cannot pass from file counts, non-empty WAV files, code references, or autoload/asset wiring alone. It must prove voice/music/sound playback was exercised in the current running app build through emulator/device capture, logcat playback evidence, or an equivalent runtime audio proof.
• Final gameplay proof cannot pass from source inspection or handler existence alone. It must exercise input and show visible feedback, progression, reward/end-state, or other brief-specific state change in the current running build.
• Backend-mediated implementation handoffs also require repo-local proof artifacts in addition to the QA markdown fields:
  • .opencode/state/qa/runtime-flow-proof.json when the completion prompt requires Runtime
  • .opencode/state/qa/gameplay-loop-proof.json when the completion prompt requires Gameplay
  • .opencode/state/qa/audio-runtime-proof.json when the completion prompt requires Audio
• These proof files must include status: "passed", the exact command or device/emulator action used, repo-relative evidence paths, and brief-specific observed results. Audio proof must name the exercised audio asset path or filename. Gameplay proof must name the input action and the visible progression/reward/fail/end-state reached.
• If the finish contract requires emulator proof, renderer limitations or "works on real hardware" claims are not completion evidence. Change renderer/export settings or the generated Android implementation stack until the app renders on the required emulator.
• A repo can be stylized and still pass. It cannot pass while the first screen is clipped, unreadable, corner-pinned, or obviously placeholder-grade.

Dependencies

• Add a dependency only when it solves a problem the project cannot reasonably solve itself.
• Pin dependency versions in lock files; never rely on floating ranges in production builds.
• Audit new dependencies for license compatibility before adding them.

Process

• Use ticket tools to track work; do not silently advance stages without updating ticket state.
• Artifacts produced by each stage must be registered via artifact_write / artifact_register.
• Smoke tests run on the real binary or export target, not on a mocked surrogate.
• When the project stack is confirmed, replace this file's Universal Standards section with stack-specific rules using the project-skill-bootstrap skill.