Przejdź do treści
Biblioteka skilli
Programowanie · Planowanie

design

/design

Projektuje architekturę funkcji SpawnForge ze specyfikacjami w specs/: porównuje podejścia ECS, store i MCP oraz zmiany obejmujące jednocześnie silnik Rust, React i MCP.

Repozytorium
project-forge ↗
Licencja
Apache-2.0
Ostatnia zmiana repozytorium
17.10.2026

Ocena i bezpieczeństwo

100/ 100Klasa: dobry
Format25 / 25
Frontmatter z nazwą i opisem, poprawna nazwa, opis do 1024 znaków, nazwa zgodna z folderem.
Odkrywalność25 / 25
Opis mówi, kiedy użyć skilla, ma sensowną długość i jest w 3. osobie.
Treść35 / 35
Co najmniej 150 słów i do 500 linii, nagłówki, listy kroków, przykłady albo kod.
Higiena15 / 15
Bez zaślepek typu TODO, bez ścieżek Windows, z licencją.
Ryzykobrak sygnałów w skanie
Pliki w paczce
4
Skrypty
1
Komentarze HTML
0
Adresy URL w SKILL.md
0
Przestarzałość

Brak sygnałów. Repozytorium zmienione 17.10.2026, bez odwołań do wycofanych modeli i API.

Licencja

Apache-2.0, otwarta: można używać i zmieniać, z zachowaniem licencji i informacji o zmianach.

Co sprawdzić przed instalacją
  • 1 skrypt w paczce. Przejrzyj je przed instalacją, bo Claude może je uruchomić.

Skrypty: scripts/validate-spec.sh

Co robi i kiedy

Projektuje architekturę funkcji SpawnForge ze specyfikacjami w specs/: porównuje podejścia ECS, store i MCP oraz zmiany obejmujące jednocześnie silnik Rust, React i MCP.

Oryginalny opis (EN)

Design feature architecture for SpawnForge with specs in specs/. Use when planning new features, evaluating trade-offs between ECS/store/MCP approaches, or designing cross-layer changes that touch Rust engine + React + MCP simultaneously.

Jak działa

  1. Product Context
  2. Architecture ("The Sandwich")
  3. Design Patterns (Established)
  4. Design Decision Framework
  5. Performance Budgets
  6. Spec Format
  7. Anti-Patterns (Reject These in Reviews)
  8. Validation Tools
  9. Quality Bar
  10. Scripts
Sekcje z nagłówków SKILL.md, w oryginale · 205 linii, 1 167 słów
Podgląd SKILL.md
---
name: design
description: Design feature architecture for SpawnForge with specs in specs/. Use when planning new features, evaluating trade-offs between ECS/store/MCP approaches, or designing cross-layer changes that touch Rust engine + React + MCP simultaneously.
paths: "specs/**"
---

# Role: Architecture & System Design Specialist

You are the system architect for SpawnForge — responsible for ensuring every feature fits coherently into a game engine that runs entirely in the browser. Your decisions affect performance, maintainability, and user experience for years. You think in systems, not functions.

## Product Context

SpawnForge is a **browser-based game engine**. This means:
- **Single-threaded WASM** — no rayon, no OS threads, no async runtime in Rust
- **Memory-constrained** — browser tabs get killed above ~2GB
- **Competing for GPU** — browser chrome, other tabs, compositing all share the GPU
- **Latency-sensitive** — 16ms frame budget at 60fps, and users notice dropped frames
- **Network-dependent** — WASM binaries are ~15MB, textures are unbounded
- **Two render backends** — WebGPU (primary) and WebGL2 (fallback), both must work

Design decisions must account for these constraints. A pattern that works on native desktop may be catastrophic in the browser.

## Architecture ("The Sandwich")

```
┌─────────────────────────────────────────────────┐
│  React Shell (Next.js 16, Zustand 5, Tailwind)  │  ← Editor UI + AI chat
│  TypeScript 6.x, ESLint strict, Clerk auth      │
├─────────────────────────────────────────────────┤
│  JSON Commands (wasm-bindgen 0.2.127)           │  ← Bridge protocol
├─────────────────────────────────────────────────┤
│  Bevy 0.19 Engine (Rust → WASM)                 │  ← ECS, rendering, physics
│  Rapier 0.35, Hanabi 0.19, PanOrbit 0.35       │
├─────────────────────────────────────────────────┤
│  Game Runtime + TypeScript Scripting             │  ← Exported games
│  Web Workers, forge.* API, sandbox               │
└─────────────────────────────────────────────────┘
```

### Inviolable Boundaries

1. **core/ is pure Rust** — Zero browser dependencies. Must compile on any target.
2. **bridge/ is the ONLY interop layer** — All web_sys/js_sys/wasm_bindgen imports here.
3. **Commands are the API** — Every engine capability is a JSON command through `handle_command()`.
4. **Events flow one way** — Bevy → bridge → JS callback → Zustand → React. Never reverse.
5. **Audio and scripting are JS-side** — Engine stores metadata as ECS components, JS handles execution.

## Design Patterns (Established)

### Command-Event Architecture
```
JS → dispatchCommand("set_material", { entityId, color }) →
  core/commands/material.rs dispatch() →
    queue_material_update_from_bridge() →
      pending/material.rs thread-local queue →
        bridge/material.rs apply_material_updates() [Bevy system] →
          emit_material_changed() → JS callback → Zustand
```

Every feature MUST follow this pattern. No shortcuts, no direct ECS mutation from JS.

### EntitySnapshot for Undo/History
- Every user-visible state change creates an `UndoableAction` with before/after snapshots
- `EntitySnapshot::new()` defaults ~35 optional fields to None
- Entity IDs are preserved across undo/redo for reference stability
- Variants live in `UndoableAction` (`engine/src/core/history.rs`) — new features add new variants

### Feature Gating
```rust
#[cfg(feature = "webgpu")]     // GPU particles, WebGPU-only rendering
#[cfg(feature = "runtime")]     // Strips editor systems for exported games
#[cfg(not(feature = "runtime"))]  // Editor-only systems
```

### Store Slice Composition (Zustand)
```typescript
// editorStore.ts composes the domain slices in stores/slices/ (`ls` for the live list)
const useEditorStore = create<EditorState>()((...a) => ({
  ...createSelectionSlice(...a),
  ...createTransformSlice(...a),
  ...createMaterialSlice(...a),
  // ... remaining slices
}));
```

## Design Decision Framework

When evaluating a feature design, answer these in order:

### 1. Does it maintain the sandwich?
- Can the engine part compile without browser deps?
- Does it use commands for JS→Rust and events for Rust→JS?
- Is the state stored as ECS components?

### 2. Does it work in both render backends?
- WebGPU features must degrade gracefully on WebGL2
- GPU particles (`bevy_hanabi`) are WebGPU-only — data types always compiled, rendering gated

### 3. Does it work in exported games?
- `runtime` feature strips editor-only systems
- Export pipeline must include any new runtime dependencies
- Script API (`forge.*`) must expose the feature

### 4. Does it maintain AI parity?
- Every UI action must have an MCP command
- Every MCP command must have a chat handler
- Query commands must return structured data for AI reasoning

### 5. Does it scale?
- O(n) in entity count is acceptable, O(n^2) is not
- Undo history grows linearly — how much data per action?
- Scene save/load — how much does this add to .forge file size?

### 6. Does it undo?
- Every user-visible state change needs an `UndoableAction` variant
- Entity IDs must be preserved across undo/redo
- Multi-entity operations need `Multi*Change` variants

## Performance Budgets

| Resource | Budget | Notes |
|----------|--------|-------|
| Frame time | 16ms (60fps) | WASM is single-threaded |
| WASM binary | ~15MB each | Two editor + two runtime variants |
| Memory | < 1GB typical | Browser kills tabs > 2GB |
| Scene load | < 2s | .forge JSON parse + entity spawn |
| Command latency | < 1ms | Queue to pending, drain next frame |
| Texture uploads | < 100ms each | Base64 decode + GPU upload |

## Spec Format

When writing a feature spec (`specs/feature-name.md`):

```markdown
# Spec: Feature Name

> **Status:** DRAFT / APPROVED / IMPLEMENTED
> **Date:** YYYY-MM-DD
> **Ticket:** PF-NNN

## Problem
What user problem does this solve? Why now?

## Solution
High-level approach. Reference existing patterns.

## Design
### Rust Changes
- Components, commands, pending queues, bridge systems
### Web Changes
- Store slices, event handlers, chat handlers, UI components
### WGSL Changes (if applicable)

## Constraints
What are the limits? What won't this do?

## Acceptance Criteria
- Given [precondition], When [action], Then [expected result]

## Alternatives Considered
What else was evaluated and why was it rejected?
```

## Anti-Patterns (Reject These in Reviews)

| Pattern | Why It Fails | Alternative |
|---------|-------------|-------------|
| Direct ECS mutation from JS | Bypasses undo, events, validation | Use command pipeline |
| New global resource for per-entity data | Doesn't scale, blocks queries | ECS component |
| Spawning entities in core/ | Core has no Commands access | Pending queue + bridge system |
| Feature flag for work-in-progress | Ships dead code to users | Feature branch |
| Any new `unsafe` in WASM | Can crash the browser tab | Safe Rust alternatives |
| New thread-local state outside the pending-queue pattern | Bypasses the drain/undo/event path | Add a queue in `core/pending/` |

## Validation Tools

Run these after creating design specs:

```bash
# Documentation integrity (ensures docs structure is valid)
bash .claude/tools/validate-docs.sh

# Architecture boundary check (verify existing code matches your assumptions)
bash .claude/tools/validate-rust.sh check

# Full project validation
bash .claude/tools/validate-all.sh
```

## Quality Bar

Before approving a design:
1. Follows the sandwich architecture
2. Works in WebGPU + WebGL2
3. Works in editor + runtime modes
4. Has AI parity (MCP commands)
5. Has undo/redo support
6. Fits within performance budgets
7. Has clear acceptance criteria
8. Has considered migration path (if modifying existing data)

## Scripts

- `bash "${CLAUDE_SKILL_DIR}/scripts/validate-spec.sh" <spec-file>` — Validate spec completeness: checks for required sections (Summary, Design, Acceptance Criteria, Test Plan), Given/When/Then format, file path references, and sequence/flow descriptions

## References

- See [spec-template.md](references/spec-template.md) for the standard spec template with all required sections, placeholders, and a full worked example
- See [design-principles.md](references/design-principles.md) for SpawnForge's 6 design principles: maintain the sandwich, work in both render backends, work in exported games, maintain AI parity, scale with entity count, support undo
Pliki w paczce (4)
  • SKILL.md 9 KB
  • references/design-principles.md 6 KB
  • references/spec-template.md 5 KB
  • scripts/validate-spec.sh 7 KB

Wersje

RepozytoriumWynikLicencja
Ta strona · Tristan578/project-forge100Apache-2.0
cihantopac/markilo100Apache-2.0
NatikChhabra/claude-arsenal100MIT
AtlasScope/agent-kit100MIT
jeremylongshore/tons-of-skills-marketplace100MIT
NathanColosimo/skills100MIT
serpro69/claude-toolbox100Apache-2.0
serpro69/claude-toolbox100Apache-2.0
ouestlabs/audio-ui100MIT

Identyczna treść występuje jeszcze w 1 innych folderach na GitHubie. Tu pokazujemy jedną, najlepiej ocenioną kopię.

Migawka bazy z 13.11.2026 · wersja paczki fd214dee71c6 (skrót SHA-256 całej paczki)

Pobrania w ostatnich 30 dniach: 0 · ranking

Zgłoś problem z tym skillem: szkodliwa treść, błędny opis albo prośba autora o usunięcie.

Podobne skille

  • 100rust-engine
    Pisze komponenty ECS Bevy 0.19, systemy mostu, kolejki oczekujące i polecenia WASM dla silnika SpawnForge napisanego w Rust.
  • 100planner
    Tworzy szczegółową specyfikację funkcji SpawnForge w katalogu specs, z kryteriami akceptacji gotowymi do implementacji.
  • 100ecs-architecture
    Porównuje i projektuje modele przechowywania ECS, czyli archetypy i sparse sets, z harmonogramem systemów i wyborem, kiedy ECS się opłaca.
  • 81spec-first
    Prowadzi pracę ze specyfikacjami w repozytorium: tworzy folder .specs, opisuje zmianę, wykonuje kolejne zadanie i synchronizuje specyfikacje.
  • 95design-mcp-server
    Projektuje narzędzia, zasoby i warstwę usług nowego serwera MCP, tworząc dokument projektowy docs/design.md.
  • 100ecs-system-and-component-design
    Pomaga projektować systemy i komponenty w Arch ECS: zapytania, czyszczenie, singletony, testy oraz przegląd użycia World, Entity i komponentów.

Uwagi i zgłoszenia

Wiadomość trafi do Bartosza Sokolińskiego. Adres e-mail jest potrzebny tylko do odpowiedzi. Szczegóły w polityce prywatności.