How to Use the Prototype Workflow for Rapid Game Mechanic Validation

The prototype workflow is a lightweight, throw-away pipeline accessed via the /prototype command that lets game developers validate single mechanics in isolation without production-level overhead.

The Claude Code Game Studios repository provides a dedicated prototype workflow for rapid game mechanic validation that accelerates experimentation while keeping production code clean. This workflow, governed by the /prototype skill and defined in .claude/rules/prototype-code.md, creates isolated sandboxes where developers can test hypotheses using hard-coded values and relaxed coding standards. By design, no production code may import from the prototypes/ directory, ensuring complete isolation between experimental and shipping systems.

The Six-Phase Validation Lifecycle

The workflow follows a strict lifecycle defined in CCGS Skill Testing Framework/skills/utility/prototype.md. Each phase produces specific artifacts while maintaining velocity through intentionally relaxed architectural constraints.

Phase 1: Invocation and Permission

Developers initiate validation by running the /prototype <mechanic-name> command. According to the skill specification (lines 12-14), the system must request explicit permission before writing to the filesystem with the prompt: "May I write to prototypes/<mechanic-name>/?" This gate prevents accidental overwrites and ensures intentional prototype creation.

Phase 2: Scaffold Creation

Upon approval, the skill generates a minimal implementation in prototypes/<mechanic-name>/ following the subdirectory rules in .claude/rules/prototype-code.md (lines 22-24). The scaffold includes:

• A README.md with hypothesis and run instructions
• Starter scene/script files (Godot or Unity depending on project)
• Optional placeholder assets

Phase 3: Rapid Development

This phase permits hard-coded values, quick-and-dirty logic, and debug output without architectural review. The Prototype Code Standards (lines 11-19) explicitly allow practices forbidden in production:

• Inline comments instead of formal documentation
• print() statements for debugging
• No dependency injection or ADRs required

Phase 4: Findings Generation

When testing concludes, the skill generates findings.md summarizing the validation results. This document must contain:

• What Was Tested: Specific mechanics and input methods
• What Worked: Successful behaviors and performance metrics
• What Didn’t Work: Bugs, edge cases, or usability issues
• Recommendation: Verdict keyword and next steps

The required fields follow the specification (lines 53-58).

Phase 5: Verdict and Production Handoff

The workflow terminates with one of two verdicts emitted by the skill:

• PROTOTYPE COMPLETE: Mechanic validated, suggesting /design-system <mechanic> for full implementation
• PROTOTYPE ABANDONED: Mechanic deemed unviable

These verdicts appear in findings.md and trigger the protocol compliance checks defined in the skill specification (lines 59-66).

Phase 6: Collision Handling and Cleanup

If prototypes/<mechanic-name>/ already exists, the skill presents three options (lines 68-83):

1. Extend: Continue development in existing directory
2. Replace: Overwrite after confirmation ("May I replace prototypes/<mechanic-name>/?")
3. Archive: Move existing prototype to prototypes/archive/<mechanic-name>/ before creating fresh scaffold

The isolation rule (lines 28-30) mandates that production code never import from prototypes/, allowing safe deletion or archival after validation.

Required Prototype Documentation

Every prototype must contain two specific files to satisfy the validation protocol.

The README.md Structure

Generated automatically during scaffold creation, this file tracks the experiment's purpose and status:

# Grapple Hook Prototype

**Hypothesis:** A player-controlled grapple hook will enable fast traversal and add verticality.

**How to Run:** Open `grapple-hook.tscn` (Godot) or `GrappleHook.cs` (Unity) and press **G** in the demo scene.

**Status:** in-progress

**Findings:** *(filled after testing)*

This structure is enforced by the Prototype Code Standards (lines 23-27).

The findings.md Format

Upon completion, findings.md captures concrete learnings for stakeholders:

# Findings – Grapple Hook

## What Was Tested

- Player input `G` launches a hook toward mouse cursor.
- Hook pulls player to target point.

## What Worked

- Hook physics feel snappy.
- No crashes, collision detection works.

## What Didn’t Work

- Hook occasionally gets stuck on thin platforms.
- No visual feedback for hook trajectory.

## Recommendation

Mechanic validated – proceed to full design via `/design-system grapple-hook`.

**Verdict:** PROTOTYPE COMPLETE

The verdict keyword must match the skill specification exactly to trigger proper workflow state changes.

Practical Usage Examples

Creating a New Mechanic Prototype

To validate a wall-jump mechanic:

/prototype wall-jump

The system responds:

May I write to `prototypes/wall-jump/`?

After confirmation, the scaffold appears at prototypes/wall-jump/ with starter files and the required README.md.

Handling Existing Prototypes

When running /prototype grapple-hook on an existing directory:

Prototype already exists for grapple-hook.
Options: 1) Extend 2) Replace 3) Archive

Selecting Replace triggers permission confirmation:

May I replace `prototypes/grapple-hook/`?

Selecting Archive moves the current implementation to prototypes/archive/grapple-hook/ before generating fresh files, preserving historical iterations.

Key Configuration Files

The workflow behavior derives from two authority files:

• .claude/rules/prototype-code.md: Defines relaxed coding standards, directory isolation rules, and required README sections
• CCGS Skill Testing Framework/skills/utility/prototype.md: Contains the complete skill specification including command behaviors, static assertions, and verdict protocols

Together these files implement the rapid-iteration loop that distinguishes production code from experimental mechanics.

Summary

• The prototype workflow isolates experimental code in prototypes/<mechanic-name>/ directories with relaxed architectural standards
• Initiate validation using /prototype <mechanic-name>, which requires explicit permission before filesystem modifications
• Required artifacts include README.md (hypothesis and run instructions) and findings.md (test results and verdict)
• Verdicts are binary: PROTOTYPE COMPLETE (proceed to /design-system) or PROTOTYPE ABANDONED (discard)
• Existing prototypes support Extend, Replace, or Archive workflows to prevent accidental data loss
• Production code must never import from prototypes/ per the isolation rules in .claude/rules/prototype-code.md

Frequently Asked Questions

How do I start a prototype without affecting production code?

Run /prototype <mechanic-name> and confirm the permission prompt. The skill automatically creates an isolated directory under prototypes/ that is forbidden from being imported by production code according to the isolation rules in .claude/rules/prototype-code.md. This ensures your experimental changes remain sandboxed.

What happens if I need to iterate on an existing prototype?

If a prototype directory already exists, the skill detects this and offers three options: Extend to continue work, Replace to overwrite after confirmation, or Archive to move the existing version to prototypes/archive/ before starting fresh. This prevents accidental loss of previous iterations while supporting rapid pivots.

Can I use production coding standards in a prototype?

No, and you should not. The Prototype Code Standards explicitly relax requirements to maximize speed. You may use hard-coded values, skip dependency injection, and include debug print() statements. Architecture Decision Records (ADRs) and extensive documentation are not required during this phase.

How does the system decide if a mechanic moves to production?

After testing, you or the skill generates findings.md with a clear verdict. PROTOTYPE COMPLETE indicates the mechanic is validated and suggests the next step /design-system <mechanic>. PROTOTYPE ABANDONED marks the mechanic as unviable. The recommendation field documents specific technical or design reasons for the decision, creating an audit trail for stakeholders.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}