xiaohongshu
xiaohongshu
Execute approved sprint plans for Stapledons Voyage using AILANG. ALL game logic must be AILANG - engine is rendering only. Use when user says "execute sprint", "start implementation", or wants to begin an approved sprint plan.
Full skill instructions
Execute an approved sprint plan with AILANG as the primary implementation language. All game logic, state machines, and gameplay code goes in sim/*.ail - the Go engine only renders DrawCmd output.
Every sprint MUST have a tracking JSON file:
# Location: sprints/sprint_<sprint-id>.json
# Example: sprints/sprint_view-system-v1.json
Two formats supported:
{
"sprint_id": "<sprint-id>",
"created": "YYYY-MM-DDTHH:MM:SSZ",
"status": "in_progress",
"design_doc": "design_docs/planned/next/<feature>.md",
"features": [
{
"id": "feature-id",
"description": "What this feature does",
"estimated_loc": 300,
"actual_loc": null,
"dependencies": [],
"acceptance_criteria": ["Criterion 1", "Criterion 2"],
"passes": null,
"started": null,
"completed": null,
"notes": null
}
],
"velocity": { "target_loc_per_day": 275, "actual_loc_per_day": 0 },
"ailang_issues": [],
"dx_issues_discovered": [],
"lessons_learned": [],
"last_updated": "YYYY-MM-DDTHH:MM:SSZ"
}
{
"sprint_id": "<sprint-id>",
"name": "Sprint Name",
"status": "in_progress",
"type": "ailang",
"started": "YYYY-MM-DD",
"design_doc": "design_docs/planned/next/<feature>.md",
"phases": [
{
"id": "phase1",
"name": "Phase Name",
"status": "in_progress",
"tasks": [
{"id": "1.1", "name": "Task Name", "status": "pending", "notes": ""}
]
}
],
"ailang_issues": [],
"dx_issues_discovered": [],
"lessons_learned": [],
"notes": []
}
AILANG sprints MUST include these sections (added to standard format):
ailang_issues - Bugs/features reported to AILANG teamdx_issues_discovered - DX friction discovered during sprintlessons_learned - What to do differently next timeUpdate this JSON:
completed immediately after finishingBefore writing any code, verify these items:
game_views/ insteadgo run ./cmd/game -screenshot N -output /tmp/test.pngfile command - Catch HTML error pages masquerading as imagesdisplay.InternalWidth and display.InternalHeightscreenW * 0.5 for center, not fixed 320make build - Detects sim_gen errors and enforces correct bug reportingmake game for executable - Builds bin/gamego run for quick testing - Compiles fresh each timego build ./... - Won't detect AILANG codegen bugsvoyage manifest - Validate all assets exist before startingThis project is ALL-IN on AILANG. The architecture is:
| Layer | Language | Responsibility | Edit? |
|---|---|---|---|
sim/*.ail | AILANG | ALL game logic | ✅ Primary work |
sim_gen/*.go | Generated | AILANG → Go output (OK to have game types) | ❌ Never edit |
game_views/*.go | Go | Game-specific rendering helpers | ✅ For Stapledon-specific visuals |
engine/*.go | Go | Generic rendering (reusable for ANY game) | ⚠️ Must be game-agnostic |
If you're writing game logic in Go, STOP. Write it in AILANG.
Mock-only mode was for early prototyping. We are past that phase.
The engine should work unchanged for a completely different AILANG game.
Before writing Go code, ask: Could a different game use this unchanged?
| Answer | Where to Put It |
|---|---|
| YES - generic rendering | engine/*.go |
| NO - game-specific visual | game_views/*.go |
| NO - game logic/data | sim/*.ail (AILANG) |
sim_gen/ is fine - It's generated from AILANG. Game-specific types (World, DeckType, Planet) belong there because they come from AILANG.
engine/ must be generic:
game_views/ for game-specific rendering:
Example Violation (DO NOT DO):
// ❌ WRONG - in engine/render/draw.go
func getBridgeSpriteColor(id int64) color.RGBA {
case id == 1200: return ... // pilot
case id == 1201: return ... // comms <- GAME CONCEPTS IN ENGINE!
}
// ✅ RIGHT - move to game_views/sprite_colors.go
// Or better: define colors in AILANG and pass via DrawCmd
Most common usage:
# User says: "Execute the arrival sequence sprint"
# This skill will:
# 1. Check AILANG modules compile
# 2. Write new AILANG types and functions
# 3. Run ailang check after every change
# 4. Report AILANG issues immediately
# 5. Compile to Go and test in engine
Invoke this skill when:
Do NOT use this skill for:
sim/*.ail - no exceptionsailang check after every changeAlways update the sprint JSON file as you work. This enables session continuity.
Sprint JSON files can use either features-based (preferred for new sprints) or phases/tasks-based (legacy) structure.
# Location: sprints/sprint_<sprint-id>.json
# For feature-based sprints (preferred):
.claude/skills/sprint-executor/scripts/update_progress.sh \
sprints/sprint_<sprint-id>.json feature <feature_id> in_progress
.claude/skills/sprint-executor/scripts/update_progress.sh \
sprints/sprint_<sprint-id>.json feature <feature_id> completed [actual_loc]
# For phase/task-based sprints (legacy):
.claude/skills/sprint-executor/scripts/update_progress.sh \
sprints/<sprint-id>.json task <task_id> completed
.claude/skills/sprint-executor/scripts/update_progress.sh \
sprints/<sprint-id>.json phase <phase_id> completed
# Update overall sprint status (both formats):
.claude/skills/sprint-executor/scripts/update_progress.sh \
<sprint-file>.json sprint in_progress
# Show current progress (auto-detects format):
.claude/skills/sprint-executor/scripts/update_progress.sh \
<sprint-file>.json show
| Command | Effect |
|---|---|
feature <id> in_progress | Sets started timestamp |
feature <id> completed | Sets completed timestamp, passes: true |
feature <id> completed <loc> | Also sets actual_loc |
feature <id> blocked | Sets passes: false |
feature <id> pending | Resets to initial state |
Status values: pending | in_progress | completed | blocked
in_progress when startingin_progress before starting workcompleted immediately after finishingcompleted at the endMost work should be AILANG. Engine changes are only needed for:
STOP - Is this game-specific?
game_views/*.goengine/*.goFor engine-only work:
make engine # Build engine only (skips sim_gen check)
make run # Test rendering
Remember: Engine code should be "dumb" - it only renders what AILANG tells it via DrawCmd. It should work unchanged for ANY AILANG game.
For rendering helpers that reference game concepts:
# game_views imports both engine/ and sim_gen/
# engine/ should NOT import game_views/
Check Status
# For AILANG sprints:
for f in sim/*.ail; do ailang check "$f"; done
ailang messages list --unread
# For mock-only sprints:
go test ./...
make game-mock
Initialize JSON Progress
.claude/skills/sprint-executor/scripts/update_progress.sh \
sprints/<sprint-id>.json sprint in_progress
Create Todo List
For each milestone:
Pre-Implementation
ailang prompt for syntax referenceImplement AILANG Code
# After each file edit:
ailang check sim/<file>.ail
# If errors, fix immediately
# If stuck, report to AILANG team
Test with ailang run
# Test entry function
ailang run --entry <function> sim/step.ail
Report Issues Encountered
# For bugs
~/.claude/skills/ailang-feedback/scripts/send_feedback.sh bug \
"Issue title" "Description" --from stapledons_voyage
# For missing features
~/.claude/skills/ailang-feedback/scripts/send_feedback.sh feature \
"Feature needed" "Why it would help" --from stapledons_voyage
Update Progress (IMPORTANT)
# After each task
.claude/skills/sprint-executor/scripts/update_progress.sh \
sprints/<sprint-id>.json task <task_id> completed
# After completing all tasks in a phase
.claude/skills/sprint-executor/scripts/update_progress.sh \
sprints/<sprint-id>.json phase <phase_id> completed
Pause for Review
.../update_progress.sh sprints/<id>.json showCompile AILANG to Go
make sim # Generates sim_gen/*.go
Check Codegen Quality (MANDATORY)
# Run quality check on generated Go code
.claude/skills/sprint-executor/scripts/check_codegen_quality.sh
What it checks:
If issues found:
ailang messages send user "..." --type bug --githubTest Game
make run # Run with Ebiten
Fix Integration Issues
Final Testing
# All AILANG modules
for f in sim/*.ail; do ailang check "$f"; done
# Game build
make game
AILANG Feedback Summary
Developer Experience (DX) Report (AILANG sprints only)
Skip this for mock-only sprints - the ailang-feedback skill is for AILANG language feedback, not general sprint completion.
For sprints that involve AILANG code, send a DX feedback message reflecting on the overall experience:
~/.claude/skills/ailang-feedback/scripts/send_feedback.sh dx \
"Sprint DX: <sprint-name>" \
"<honest reflection on working with AILANG this sprint>" \
--from stapledons_voyage
Include in your reflection:
ailang prompt have what you needed?Be honest - negative feedback is valuable. Examples:
Sprint Report
make build - It Enforces Correct BehaviorAlways use make build instead of go build!
make build automatically:
sim_gen/ (AILANG codegen bug)# CORRECT - use this
make build
# WRONG - don't use direct go build
go build ./... # Won't detect codegen bugs
If make build shows "ERROR IN sim_gen/":
If make build shows a normal error (not in sim_gen/):
ailang prompt for correct syntaxailang check passesQuick reference for known issues and their solutions:
| Problem | Error Message | Workaround |
|---|---|---|
| Nested field access | "cannot unify open record with TVar2" | Break a.b.c into let b = a.b; b.c |
| Record update with derived value | "cannot unify open record" on {b | pos: newPos} | Use explicit construction: { field1: b.field1, pos: newPos } |
Module-level let in function | "undefined variable" | Inline constant or pass as parameter (intentional design) |
| Tuple destructuring | Parse error on let (x, y) = pair | Use match pair { (x, y) => ... } |
| ADT in inline tests | Test harness crashes | Only use primitive types in test inputs |
| DrawCmd uses color index not RGBA | N/A (works but limited) | Use direct Ebiten drawing in engine/ for custom colors. Feature requested from AILANG. |
| Go codegen wrong return types | Exported func returns struct{} but impl returns typed value | DO NOT create wrapper files - report bug via ailang-feedback and wait for fix |
| Go codegen unexported converters | convertToDrawCmdSlice is lowercase | DO NOT create wrapper files - report bug via ailang-feedback and wait for fix |
| Editing sim_gen/.go* | Changes overwritten | NEVER edit sim_gen files. Request features via ailang-feedback. |
This project's purpose is to surface and fix AILANG issues. Keep this workarounds table current:
Scripts for tracking workarounds:
# Check inbox and verify workarounds still needed
.claude/skills/sprint-executor/scripts/check_workarounds.sh
# Add a new workaround (updates both SKILL.md and CLAUDE.md)
.claude/skills/sprint-executor/scripts/add_workaround.sh \
"Problem name" "Error message" "Workaround description"
# Mark an issue as fixed (moves to Fixed section)
.claude/skills/sprint-executor/scripts/mark_fixed.sh \
"problem keyword" "v0.5.0"
When you discover a new issue:
add_workaround.sh with problem, error, and workaroundailang-feedback with detailed repro stepsWhen AILANG fixes an issue:
ailang messages list --unreadailang check sim/*.ailmark_fixed.sh "<keyword>" "<version>"ailang messages ack <msg-id>At sprint start:
# Full status check
.claude/skills/sprint-executor/scripts/check_workarounds.sh
When updating nested records, this pattern works:
-- WORKS: newPos comes from parameter or fresh construction
pure func moveBox(b: Box, newPos: Point) -> Box {
{b | pos: newPos}
}
-- FAILS: newPos derived from b.pos
pure func moveBoxBad(b: Box) -> Box {
let oldPos = b.pos;
let newPos = { x: oldPos.x + 1, y: oldPos.y };
{b | pos: newPos} -- ERROR!
}
-- WORKAROUND: explicit construction
pure func moveBoxFixed(b: Box) -> Box {
let oldPos = b.pos;
let newPos = { x: oldPos.x + 1, y: oldPos.y };
{ pos: newPos, size: b.size } -- Explicit fields
}
After each milestone:
# 1. All AILANG modules compile
for f in sim/*.ail; do ailang check "$f"; done
# 2. Entry functions run
ailang run --entry init_world sim/step.ail
# 3. Game builds (if engine changes)
make game
For any milestone involving visual output, YOU MUST take and verify screenshots.
NEVER use macOS screencapture command - it captures the entire desktop at native resolution (5K+ on Retina), producing huge files that crash Claude.
ALWAYS use the in-game screenshot functionality - it captures the game's internal render buffer at 1280x960, producing consistent, small PNG files.
Use the dedicated screenshot helper for easy, reliable screenshots:
# Basic game screenshot at frame 30
.claude/skills/sprint-executor/scripts/take_screenshot.sh
# Bridge demo at frame 60
.claude/skills/sprint-executor/scripts/take_screenshot.sh -c demo-game-bridge -f 60
# Game with effects
.claude/skills/sprint-executor/scripts/take_screenshot.sh --effects bloom,sr_warp --velocity 0.5
# Arrival sequence at frame 120
.claude/skills/sprint-executor/scripts/take_screenshot.sh --arrival -f 120
# Custom output path
.claude/skills/sprint-executor/scripts/take_screenshot.sh -o out/screenshots/my-test.png
You can also use the screenshot flags directly on any game command:
# Main game
go run ./cmd/game --screenshot 30 --output out/screenshots/game.png
# Demo commands
go run ./cmd/demo-game-bridge --screenshot 30 --output out/screenshots/bridge.png
go run ./cmd/demo-saturn --screenshot 60 --output out/screenshots/saturn.png
# With effects
go run ./cmd/game --screenshot 60 --output out/test.png --effects bloom,sr_warp --velocity 0.5
# Arrival sequence
go run ./cmd/game --screenshot 120 --output out/arrival.png --arrival
| Method | Resolution | File Size | Works? |
|---|---|---|---|
--screenshot flag | 1280x960 | ~50-200KB | YES |
macOS screencapture | 5120x2880+ | 5-20MB | NO (crashes) |
Take Screenshots at Key States
# Initial state
.claude/skills/sprint-executor/scripts/take_screenshot.sh -f 30 -o out/screenshots/initial.png
# Mid-animation (if applicable)
.claude/skills/sprint-executor/scripts/take_screenshot.sh -f 60 -o out/screenshots/mid.png
# Final state
.claude/skills/sprint-executor/scripts/take_screenshot.sh -f 90 -o out/screenshots/final.png
View Screenshots Using Read Tool
# Claude Code can view PNG images directly
# Use Read tool on screenshot path to verify visuals
Document What to Look For
For each visual feature:
| Command | Description |
|---|---|
game | Main game (bridge view, NPC, etc.) |
demo-game-bridge | Bridge interior only |
demo-saturn | Saturn with rings |
demo-arrival | Black hole arrival sequence |
demo-sr-flyby | SR effects flyby demo |
demo-view | View system demo |
All generated output MUST go in the correct out/ subdirectory. See out/README.md for full details.
out/
├── eval/ # Benchmarks, evaluation reports
├── generated/ # Final GIFs, videos, animations
├── scenarios/ # Scenario runner temp output
├── screenshots/ # Demo screenshots from sprints ← USE THIS
└── test/ # Visual test golden files
| Output Type | Location | Example |
|---|---|---|
| Demo screenshots | out/screenshots/ | out/screenshots/bridge-initial.png |
| Sprint verification | out/screenshots/<sprint>/ | out/screenshots/arrival-v1/mid-transition.png |
| Evaluation output | out/eval/ | out/eval/report.json |
| Generated videos/GIFs | out/generated/ | out/generated/flyby-demo.gif |
| Test scenario output | out/test/<scenario>/ | out/test/camera-pan/after-right.png |
out/ root - always use a subdirectorybridge-initial.png not test1.pngout/screenshots/<sprint-name>/# Single screenshot
./bin/demo --screenshot 30 --output out/screenshots/initial.png
# Sprint with multiple screenshots
mkdir -p out/screenshots/arrival-v1
./bin/demo --screenshot 30 --output out/screenshots/arrival-v1/initial.png
./bin/demo --screenshot 60 --output out/screenshots/arrival-v1/mid.png
./bin/demo --screenshot 90 --output out/screenshots/arrival-v1/final.png
# Generate frames to temp directory
mkdir -p /tmp/frames
./bin/demo --capture-frames /tmp/frames/
# Create final video
ffmpeg -i /tmp/frames/frame_%05d.png out/generated/demo.mp4
# Clean up intermediate frames
rm -rf /tmp/frames
Do NOT leave frame directories in out/ - they can grow to hundreds of MB.
If out/ gets cluttered during development:
make clean # Removes bin/, out/* but preserves structure
IMPORTANT: Before implementing features, review these reference documents:
| Document | Contents | When to Use |
|---|---|---|
| engine-capabilities.md | All DrawCmd types, effect handlers, assets, shaders, physics | Any sprint involving rendering or engine features |
| game-capabilities.md | AILANG game features (celestial, starmap, bridge, viewport) | Any sprint involving game logic in sim/*.ail |
| ai-capabilities.md | AI text/image/TTS, 30 voices, SSML, style control | NPC dialogue, voice generation, AI-driven content |
| demos.md | Demo index (demo-engine-, demo-game-) | Creating or running feature demos |
| gr-effects.md | GR physics formulas, shader uniforms, danger levels | Black hole/neutron star features |
| ai-handler-system.md | AI effect, multimodal APIs, provider config | NPC dialogue, AI-driven decisions |
Key Engine Capabilities:
| Category | What's Available |
|---|---|
| DrawCmd | Sprite, Rect, Text, IsoTile, IsoEntity, GalaxyBg, Star, Ui, Line, Circle, TextWrapped |
| Effects | Debug, Rand, Clock, AI (with Claude/Gemini/stub backends) |
| Assets | Sprites (animated), Audio (OGG/WAV), Fonts (TTF with scaling) |
| Shaders | SR warp (Doppler, aberration), GR warp (lensing, redshift), bloom, vignette, CRT |
| Physics | Lorentz factor, time dilation, gravitational redshift, Schwarzschild radius |
make sim - Compile AILANG to Gomake game - Build game executablemake run - Run gamemake install - Install voyage CLI globallyThe voyage CLI provides development tools. Install with make install.
# API documentation (always up-to-date via AST parsing)
voyage api # List all engine packages
voyage api tetra # List types in package
voyage api tetra.Scene # Show type details
voyage api tetra.Scene --methods # Show with method signatures
voyage api --search camera # Search across all packages
# Demo runner (use instead of manual go run)
voyage demo # Interactive selection menu
voyage demo bridge # Run demo-game-bridge directly
voyage demo orbital # Partial name matching works
# File watcher (auto-rebuild on changes)
voyage watch # Watch sim/*.ail, run make sim on changes
voyage watch --test # Also run ailang test after rebuild
voyage watch --run bridge # Rebuild and restart demo automatically
# Screenshot capture (use for visual verification)
voyage screenshot # Capture main game (frame 60)
voyage screenshot bridge # Capture specific demo
voyage screenshot --all # Capture all demos to out/screenshots/
voyage screenshot bridge -f 120 -o out/ # Custom frames/output
# Asset validation (run before sprints)
voyage manifest # Validate all asset manifests exist
voyage manifest -v # Verbose (show all files)
voyage manifest sprites # Check specific manifest
# Other inspection tools
voyage world # Inspect world state
voyage bench # Run benchmarks
voyage ai # Test AI handlers
Use voyage commands for:
ailang check <file> - Type-checkailang run --entry <func> <file> - Run with entry pointailang prompt - Syntax referenceailang messages list --unread - Check unread messagesailang messages ack <msg-id> - Acknowledge messageailang messages send <inbox> <msg> - Send message~/.claude/skills/ailang-feedback/scripts/send_feedback.sh - Report issues## Milestone: [Name]
### Implementation
- [ ] AILANG types defined
- [ ] AILANG functions implemented
- [ ] `ailang check` passes
- [ ] `ailang run` works
### Testing
- [ ] Edge cases handled
- [ ] Error conditions covered
### Visual Verification (if visual feature)
- [ ] Screenshot captured at initial state
- [ ] Screenshot captured during animations/transitions
- [ ] Screenshot captured at final state
- [ ] Screenshots viewed and verified correct
- [ ] Visual issues fixed
### Feedback
- [ ] Issues reported: [list]
- [ ] Workarounds documented: [list]
### Status
- [ ] Complete and ready for next milestone
ailang check failure is a learning opportunityxiaohongshu
technical spec
product ux expert
database patterns
Conduct multi-agent task orchestration and workflow coordination.
Initialize project with Conductor artifacts (product definition,
Expert in web animations, transitions, and motion design using Framer Motion and CSS
Creates Mermaid and ASCII diagrams for flowcharts, architecture, ERDs, state machines, mindmaps, and more. Use when user mentions diagram, flowchart, mermaid, ASCII diagram, text diagram, terminal diagram, visualize, C4, mindmap, architecture diagram, sequence diagram, ERD, or needs visual docume...
PostgreSQL bindings for H3 hexagonal grid system. Use when working with H3 cells in Postgres, including spatial indexing, geometry/geography integration, and raster analysis.
Context-Driven Development skill for projects using Conductor. Use this skill when you detect a `conductor/` directory in the project, when working on tasks defined in a `plan.md` file, or when the user asks about tracks, specs, or plans. Automatically applies TDD workflow, tracks task completion...
Display project status, active tracks, and next actions
Official Stakpak application containerization standard operating procedure, a step-by-step guidline to properly dockerize applications. This is a rule book curated by the Stakpak Team.
Generate, edit, and beat-sync AI video with leading models in one workspace.
The world's fastest calendar for remote work
Transform Your Design with AI Designer by ImgCreator.ai
Revolutionizing Video Production with AI-Powered Creativity
Extend an image past the frame and let AI fill the new aspect ratio.
Discover your celebrity doppelgänger with StarByFace!
ChainClarity explains 700+ crypto whitepapers in plain English, with layered summaries, comparisons, research tools, alerts, and a $4.99 Pro plan.
Opus.ai: Revolutionize Your Web Experience