1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
|
# ============================================
# TIER 1: CRITICAL CONTEXT (Always Loaded)
# ============================================
@PROJECT_CONTEXT.md
@TODO.md
@README.md
# ============================================
# TIER 2: TECHNICAL REFERENCE (Always Loaded)
# ============================================
@doc/HOWTO.md
@doc/CONTRIBUTING.md
@doc/AI_RULES.md
@doc/EFFECT_WORKFLOW.md
# ============================================
# TIER 3: DESIGN DOCS (Load On-Demand)
# ============================================
# Load these only when working on specific subsystems:
#
# Audio & Tracker:
# doc/SPECTRAL_BRUSH_EDITOR.md - Spectral editor design
# doc/TRACKER.md - Audio tracker system
#
# 3D & Graphics:
# doc/3D.md - 3D rendering architecture
# doc/PROCEDURAL.md - Procedural generation
#
# Build & Assets:
# doc/ASSET_SYSTEM.md - Asset pipeline details
# doc/BUILD.md - Build system details
# doc/FETCH_DEPS.md - Dependency management
#
# Testing & Tools:
# doc/test_demo_README.md - test_demo tool documentation
#
# Architecture & Reference:
# doc/ARCHITECTURE.md - Detailed system architecture
# doc/CODING_STYLE.md - Code style examples
# doc/BACKLOG.md - Untriaged future goals
# doc/TOOLS_REFERENCE.md - Developer tools reference
# ============================================
# TIER 4: HISTORICAL ARCHIVE (Load Rarely)
# ============================================
# Load these only for historical context or debugging:
#
# Completion History:
# Use: "read @doc/COMPLETED.md" for detailed history
#
# Technical Investigations:
# doc/GPU_EFFECTS_TEST_ANALYSIS.md
# doc/PLATFORM_ANALYSIS.md
# doc/PLATFORM_SIDE_QUEST_SUMMARY.md
# doc/PEAK_FIX_SUMMARY.md
# doc/CNN_DEBUG.md - CNN post-processing binding bug resolution
#
# Agent Handoffs:
# doc/HANDOFF_CLAUDE.md
# doc/HANDOFF.md
# doc/HANDOFF_2026-02-04.md
#
# Task Tracking:
# doc/TASKS_SUMMARY.md
# ============================================
# PROJECT RULES (IMPORTANT)
# ============================================
IMPORTANT:
- Follow all rules in doc/AI_RULES.md
- This repository is shared with Claude-Code
- You are working in turns with another AI agent
- Work only on tasks explicitly requested by the user
- Do NOT modify files outside the current scope
- Do NOT perform refactors or cleanups unless explicitly asked
- Concise answers only
- No explanations unless asked
- Max 100 tokens per reply
# Context Maintenance:
- See @doc/CONTEXT_MAINTENANCE.md for keeping context clean
- Archive completed work to doc/COMPLETED.md regularly
- Keep PROJECT_CONTEXT.md focused on current status
- Keep TODO.md focused on active/next tasks only
# ============================================
# CURRENT STATE SNAPSHOT (Gemini-Specific)
# ============================================
<state_snapshot>
<overall_goal>
Produce a cross-platform (Windows, macOS, Linux) 64-kilobyte demoscene production. This is achieved through a C++ codebase utilizing WebGPU for graphics (with a hybrid SDF/rasterization pipeline) and a real-time procedural audio engine for sound, with a heavy focus on size-optimization at all stages.
</overall_goal>
<active_constraints>
- All tests passing (36/36 - 100%).
- Strict 64k final binary size target.
- Adherence to project coding style and contribution guidelines is mandatory.
</active_constraints>
<key_knowledge>
- **Workspace System:** The project is organized into self-contained workspaces (e.g., `workspaces/main`, `workspaces/test`) managed by a `workspace.cfg` file, separating demo-specific content from a `common/` directory that holds shared shaders and resources. Selection is done at build time with `-DDEMO_WORKSPACE=<name>`.
- **Build & Asset Pipeline:** A modular CMake system orchestrates the build. It uses host-native tools (`asset_packer`, `seq_compiler`, `tracker_compiler`) to parse manifest files (`assets.txt`, `timeline.seq`, `music.track`) and compile assets directly into the binary as C++ data, including procedural asset generation.
- **Audio Engine:** A real-time, sample-accurate audio engine with a tracker system for sequencing patterns from `.track` files. It features procedural synthesis from spectrograms (FFT-based IDCT), variable tempo that is decoupled from visual timing, and an abstracted backend for testing and offline rendering (`WavDumpBackend`).
- **Graphics & Rendering:** The renderer uses WebGPU (wgpu-native) and WGSL shaders. It employs a hybrid technique, rasterizing proxy geometry (cubes) and then performing SDF raymarching within the fragment shader. The 3D system supports BVH acceleration, and there's a pipeline for importing OBJ models.
- **Sequence & Timing:** Visuals are defined in `.seq` files using a beat-based timeline that is compiled into physical seconds. Shaders receive a `CommonPostProcessUniforms` buffer containing both physical time (`time`) for constant-speed animations and musical time (`beat_time`, `beat_phase`) for syncing with the audio playback clock.
- **CNN Post-Processing:** The project features a sophisticated CNN post-processing pipeline (CNNv2) for visual stylization. This includes a full Python/PyTorch training toolchain, a binary weight format, and a WebGPU-based validation tool. The network uses 7D parametric static features (RGBD, UV, sin, bias) for rich, position-aware effects.
- **Development Workflow:** There is a strong emphasis on tooling and process, including a visual timeline editor, audio analysis tools, a web-based CNN debugger, strict coding standards enforced by `clang-format`, and a comprehensive pre-commit script (`./scripts/check_all.sh`).
</key_knowledge>
<artifact_trail>
- `GEMINI.md`: This file, synchronized with CLAUDE.md structure
- `PROJECT_CONTEXT.md`: Current system status
- `TODO.md`: Active priorities (Task #5 in progress)
</artifact_trail>
<recent_actions>
- **File Hierarchy Cleanup:** Major reorganization of the project structure, establishing the `workspaces/` and `common/` directories and eliminating ~100 redundant files (especially shaders).
- **CNNv2 Training Pipeline:** Fixed critical checkpointing bugs and streamlined the output of the training scripts for faster iteration.
- **Effect Render API Refactor:** Simplified the `Effect::render` API and fixed uniform initialization bugs across 19 effects.
- **CNN Shader Testing Tool:** Implemented `tools/cnn_test` for offline GPU-accelerated validation of trained CNN models.
</recent_actions>
<task_state>
1. [IN PROGRESS] Task #5: Spectral Brush Editor (Priority 1)
2. [PENDING] Task #18: 3D System Enhancements (Priority 4)
3. [RECURRENT] Task #50: WGSL Modularization (Priority 4)
4. [PENDING] Tracker Humanization & Sample Offset (Priority 3)
</task_state>
</state_snapshot>
|
