Create Architecture

Create Architecture

argument-hint: "[focus-area: full | layers | data-flow | api-boundaries | adr-audit] [--review full|lean|solo]"

Category: development Source: Donchitos/Claude-Code-Game-Studios

What Is This

The "Create Architecture" skill (create-architecture) is a guided authoring tool designed for game development teams using the Happycapy Skills platform. It generates a comprehensive, master architecture document at docs/architecture/architecture.md by synthesizing all available Game Design Documents (GDDs), system indexes, existing Architecture Decision Records (ADRs), and engine references. This document acts as the definitive technical blueprint for the game project, capturing the full system structure, data flows, module boundaries, and technology constraints before any implementation begins.

Unlike individual ADRs, which record discrete architectural decisions, the output from "Create Architecture" is a unified, top-down view of the entire system, providing essential context for decision-making and future development. The skill is engine-version-aware: it checks referenced features and architectural choices against the currently pinned engine version, highlighting knowledge gaps and validating the feasibility of key decisions.

Why Use It

A well-crafted architecture document is critical for successful game development projects. By leveraging the "Create Architecture" skill, teams can:

  • Align all developers and stakeholders with a single source of technical truth.
  • Identify and resolve design inconsistencies or gaps early in the process.
  • Ensure that all architectural decisions are informed by the latest GDDs and ADRs.
  • Validate technical feasibility against the project's chosen engine version.
  • Streamline sprint planning and task breakdown by providing clear module boundaries and data flows.

This skill reduces the risk of rework and miscommunication, supports onboarding, and creates a robust foundation for maintainable, scalable code.

How to Use It

The "Create Architecture" skill is invoked as a user-invocable command within the Happycapy platform. The invocation syntax supports focused authoring or review modes using argument hints:

create-architecture [focus-area: full | layers | data-flow | api-boundaries | adr-audit] [--review full|lean|solo]

Steps:

  1. Read Source Materials: The skill ingests all available GDDs, the systems index, existing ADRs, and the engine reference library.
  2. Section-by-Section Authoring: Guided prompts walk the user through composing each major section of the architecture document, such as:
    • System overview
    • Layered architecture diagram
    • Data flow diagrams
    • API boundaries and key interfaces
    • Mapping of ADRs to system components
    • Engine version constraints and validations
  3. Engine Version Validation: The skill cross-references the architecture with the capabilities of the pinned engine version, flagging any unsupported features or missing information.
  4. Argument Modes:
    • No argument or full: Generates the complete architecture document.
    • layers: Focuses solely on system layering and module relationships.
    • data-flow: Captures and diagrams how data moves through the system.
    • api-boundaries: Documents public interfaces and integration points.
    • adr-audit: Audits and maps all ADRs against system components.
  5. Review Mode: The review process can be customized using --review full, --review lean, or --review solo. The mode is resolved in this order:
    • If explicitly passed as an argument, that value is used.
    • Otherwise, read from production/review-mode.txt.
    • Defaults to lean if not specified.

Example Command

create-architecture layers --review full

This command generates only the layered architecture diagram section, using the "full" review process.

Example Output Snippet

## Layered Architecture

- **Presentation Layer**: Handles UI rendering and user input
- **Application Layer**: Orchestrates game states and system coordination
- **Domain Layer**: Encapsulates core game logic and rules
- **Infrastructure Layer**: Manages engine APIs, networking, and persistence

When to Use It

Invoke "Create Architecture" after GDDs and initial ADRs are approved, but before sprint planning or any code is written. This ensures that all technical risks are identified and resolved, and that the team has a clear implementation roadmap. Use focused argument modes (like data-flow or adr-audit) for targeted updates or architectural reviews as the project evolves.

Important Notes

  • The architecture document is distinct from ADRs. ADRs capture point decisions, while this skill produces a holistic system blueprint.
  • Engine-version awareness is built in. The skill will alert users to any incompatibilities or knowledge gaps related to the chosen engine version.
  • The review mode controls the depth and style of the review process. Store the chosen mode for consistent review handling across gates in a run.
  • Use the skill iteratively-update the architecture as new ADRs are added or GDDs change, but always ensure architectural coherence before coding starts.
  • Refer to .claude/docs/director-gates.md for the full review and check pattern.
  • This skill is essential for teams prioritizing maintainability, clarity, and technical rigor in game development.