puzzle-game-template-skill

A starter project + agent instructions for building one playable level of a mobile puzzle or casual web game, designed to be co-developed with an AI coding agent (Claude Code, Gemini Antigravity, GitHub Copilot, Cursor, etc.).

You bring the game idea. Your agent does the coding. At the end you hand off a single, well-described Level JSON schema so a separate team can crank out the remaining levels at scale.

---

Use this skill

The skill owner sends you one short message to paste to your AI coding agent (Claude Code, Gemini Antigravity, Cursor, Copilot CLI, etc.):

Hi agent — if git isn't installed on this machine, install it first. Then run this to create a fresh project on the team's git server and clone it locally:

SLUG="game-$(date +%s)" \
  && curl -sS -X POST -u bot:e433693de2b768517345f68e9c639bc6eea46925 \
       -H "Content-Type: application/json" \
       -d "{\"name\":\"$SLUG\"}" \
       https://git.corelli.cloud/api/v1/repos/corelli/puzzle-game-template/forks > /dev/null \
  && git clone "https://bot:e433693de2b768517345f68e9c639bc6eea46925@git.corelli.cloud/bot/$SLUG.git" my-game \
  && cd my-game

Then open SKILL.md and follow it from the top.

Your agent forks the template into a new throwaway-named repo under the team's bot account, clones it locally as my-game/, opens SKILL.md, and takes it from there: creates a working branch, installs Node.js, runs the dev server, then drives a structured conversation with you to design + ship one playable level.

When you're done, your agent pushes the branch back to corelli's server. Corelli reviews, merges, and their level-design team builds the rest of the game using the schema you locked in.

---

Hosting this skill (skill-owner side)

The canonical template lives at https://git.corelli.cloud/corelli/puzzle-game-template (Forgejo on AWS Tokyo). Tagged v0.1.0.

Auth model (internal alpha — read this once)

• The canonical template corelli/puzzle-game-template is public.
• A site-admin bot user holds one long-lived PAT (e433693de2b768517345f68e9c639bc6eea46925). The agent uses it for two things: forking the template into a fresh repo, and pushing/renaming that fork. Both happen automatically inside the one-liner the collaborator pastes.
• Forks land at bot/<placeholder-slug> (e.g. bot/game-1781329718). The agent renames them to the game's slug in Phase 1.5 (e.g. bot/color-snap).
• The token is intentionally public in this README — internal alpha, trusted users only, easy to rotate. Anyone who reads this doc can in principle push to / rename any bot/* repo. Live with it for now.
• Before opening this beyond a small circle, replace this with per-collaborator scoped tokens (see "Next steps" in this repo's plan).
• To rotate: ssh corelli-aws-tokyo-0, regenerate the bot's PAT in the Forgejo web UI as bot, replace the constant in this README and in SKILL.md (Phase 0a side-note + Phase 1.5 commands).

Spinning up a new project for a collaborator

Send them the message from the "Use this skill" section above. That's it — the one-liner forks the template, clones the fork, and the agent takes over from SKILL.md. You don't have to touch the Forgejo web UI.

While they work:

• Their fork shows up at https://git.corelli.cloud/bot/game-<timestamp> immediately after they paste the prompt. List all live projects at https://git.corelli.cloud/bot.
• The agent renames the repo to the game's slug at the end of Phase 1 (e.g. bot/game-1781329718 → bot/color-snap).
• The agent commits to a branch called agent/stage-1 and pushes there at handoff time. main stays at the unmodified template tip for the moment — that's fine; review happens on the branch.

When the collaborator pings you that they're done, open the project's agent/stage-1 branch in the Forgejo web UI, review, and merge into main from there.

Cutting a new template release

After polishing this template (e.g. fixing friction discovered in ISSUES.md of past projects), bump the version and push the tag:

git commit -am "polish: <summary>"
git tag -a v0.2.0 -m "<summary>"
git push origin main --tags

Future forks will start from the new tag. Existing projects keep their own history and don't auto-pull template changes (that's intentional — collaborators have already started building on top of their fork).

---

Project map

Path	What's in it
SKILL.md	The agent's canonical instruction manual. Read this first if you're an AI agent.
PROGRESS.md	Live workflow state — what phase, what's done, what's next.
ISSUES.md	Friction log — pain points the collaborator + agent hit, for skill polish.
HANDOVER.md	Filled in at the end. The level-design team reads this.
index.html	Vite entry; sets up the 9:16 portrait viewport with letterboxing.
src/main.ts	Boot wiring (Pixi → load level → game + renderer).
src/core/level.ts	The Level interface — the hard contract.
src/logic/game.ts	Pure game rules. No DOM, no Pixi, no randomness.
src/render/Renderer.ts	Pixi visuals + input.
src/levels/demo.json	The single hand-crafted level the demo plays.
src/assets/	Self-contained images + sounds wrapper. Empty registries by default.
example/	Read-only reference scaffold (a tap-counter game) mirroring src/. Look here for patterns.

Run the demo

npm install
npm run dev
# open the printed URL (usually http://localhost:5173) in your browser

The page hot-reloads on save. The demo runs in a portrait mobile viewport (logical 360×640, letterboxed on desktop). On retina displays the canvas backing pixels track the displayed area so text stays sharp.

Build for production

npm run build      # output goes to dist/
npm run preview    # serves dist/ locally to verify

---

Design choices baked into the template

• Mobile-first. Fixed 9:16 portrait viewport. Letterboxed on desktop, fills the screen on mobile.
• One playable level. No level selector, no progression, no menus beyond a minimal title/win banner. Nail one level + a clean Level JSON schema.
• Pure-logic / render / asset separation. Game rules in logic/, Pixi visuals in render/, content in assets/, per-level data in a JSON file matching the Level interface.
• Self-describing handover. When the agent says the project is done, HANDOVER.md + Level + demo.json are enough for a separate level-design team to author hundreds more levels without re-running the game.

---

Polishing this skill

After each real project that uses this template, read the resulting ISSUES.md to find friction points and feed them back into SKILL.md and the scaffold.