Imported from davetashner/unikittyville (AGENTS.md). Install upstream with npx skills add davetashner/unikittyville. Copyright stays with the author.

Agent Instructions

This project uses bd (beads) for issue tracking. Run bd onboard to get started.

Deployment

The game is deployed as part of norahtashner.com at https://norahtashner.com/games/unikittyville/.

Deployment has two parts: the HTML goes through the website repo + CI/CD, while audio files go directly to S3.

1. Deploy index.html (via website repo)

# Copy game HTML to the website's public directory
cp -f ~/Development/unikittyville/index.html ~/Development/norahtashner.com/public/games/unikittyville/

# Commit and push — CI/CD will build and deploy to S3/CloudFront
cd ~/Development/norahtashner.com
git add public/games/unikittyville/index.html
git commit -m "chore: update unikittyville game"
git push

2. Deploy audio files (direct to S3)

Audio files (mp3) are gitignored in the website repo. They must be uploaded directly to S3.

# Upload new or changed music files
aws s3 cp assets/music/FILENAME.mp3 \
  s3://norahtashner.com/games/unikittyville/assets/music/FILENAME.mp3 \
  --content-type "audio/mpeg" \
  --cache-control "public, max-age=31536000"

# Upload new or changed SFX files
aws s3 cp assets/sfx/FILENAME.mp3 \
  s3://norahtashner.com/games/unikittyville/assets/sfx/FILENAME.mp3 \
  --content-type "audio/mpeg" \
  --cache-control "public, max-age=31536000"

# Invalidate CloudFront cache for updated files
aws cloudfront create-invalidation \
  --distribution-id E3JF840O8YSE4Q \
  --paths "/games/unikittyville/assets/music/*"

IMPORTANT: The CI/CD workflow preserves games/unikittyville/assets/* on S3 (it excludes that path from sync/delete). So audio files persist across deploys once uploaded. But new audio files MUST be manually uploaded — they will NOT be deployed by git push alone.

Local copy (for local testing only)

To test locally via the website dev server, also copy mp3s to the website's public dir:

cp -rf ~/Development/unikittyville/assets/music/*.mp3 ~/Development/norahtashner.com/public/games/unikittyville/assets/music/
cp -rf ~/Development/unikittyville/assets/sfx/*.mp3 ~/Development/norahtashner.com/public/games/unikittyville/assets/sfx/

Do NOT copy source WAV files (assets/*/source/) — only MP3s are needed.

Quick Reference

bd ready              # Find available work
bd show <id>          # View issue details
bd update <id> --claim  # Claim work atomically
bd close <id>         # Complete work
bd sync               # Sync with git

Non-Interactive Shell Commands

ALWAYS use non-interactive flags with file operations to avoid hanging on confirmation prompts.

Shell commands like cp, mv, and rm may be aliased to include -i (interactive) mode on some systems, causing the agent to hang indefinitely waiting for y/n input.

Use these forms instead:

# Force overwrite without prompting
cp -f source dest           # NOT: cp source dest
mv -f source dest           # NOT: mv source dest
rm -f file                  # NOT: rm file

# For recursive operations
rm -rf directory            # NOT: rm -r directory
cp -rf source dest          # NOT: cp -r source dest

Other commands that may prompt:

• scp - use -o BatchMode=yes for non-interactive
• ssh - use -o BatchMode=yes to fail instead of prompting
• apt-get - use -y flag
• brew - use HOMEBREW_NO_AUTO_UPDATE=1 env var

Issue Tracking with bd (beads)

IMPORTANT: This project uses bd (beads) for ALL issue tracking. Do NOT use markdown TODOs, task lists, or other tracking methods.

Why bd?

• Dependency-aware: Track blockers and relationships between issues
• Version-controlled: Built on Dolt with cell-level merge
• Agent-optimized: JSON output, ready work detection, discovered-from links
• Prevents duplicate tracking systems and confusion

Quick Start

Check for ready work:

bd ready --json

Create new issues:

bd create "Issue title" --description="Detailed context" -t bug|feature|task -p 0-4 --json
bd create "Issue title" --description="What this issue is about" -p 1 --deps discovered-from:bd-123 --json

Claim and update:

bd update <id> --claim --json
bd update bd-42 --priority 1 --json

Complete work:

bd close bd-42 --reason "Completed" --json

Issue Types

• bug - Something broken
• feature - New functionality
• task - Work item (tests, docs, refactoring)
• epic - Large feature with subtasks
• chore - Maintenance (dependencies, tooling)

Priorities

• 0 - Critical (security, data loss, broken builds)
• 1 - High (major features, important bugs)
• 2 - Medium (default, nice-to-have)
• 3 - Low (polish, optimization)
• 4 - Backlog (future ideas)

Workflow for AI Agents

1. Check ready work: bd ready shows unblocked issues
2. Claim your task atomically: bd update <id> --claim
3. Work on it: Implement, test, document
4. Discover new work? Create linked issue:
   • bd create "Found bug" --description="Details about what was found" -p 1 --deps discovered-from:<parent-id>
5. Complete: bd close <id> --reason "Done"

Auto-Sync

bd automatically syncs with git:

• Exports to .beads/issues.jsonl after changes (5s debounce)
• Imports from JSONL when newer (e.g., after git pull)
• No manual export/import needed!

Important Rules

• ✅ Use bd for ALL task tracking
• ✅ Always use --json flag for programmatic use
• ✅ Link discovered work with discovered-from dependencies
• ✅ Check bd ready before asking "what should I work on?"
• ❌ Do NOT create markdown TODO lists
• ❌ Do NOT use external issue trackers
• ❌ Do NOT duplicate tracking systems

For more details, see README.md and docs/QUICKSTART.md.

Landing the Plane (Session Completion)

When ending a work session, you MUST complete ALL steps below. Work is NOT complete until git push succeeds.

MANDATORY WORKFLOW:

1. File issues for remaining work - Create issues for anything that needs follow-up
2. Run quality gates (if code changed) - Tests, linters, builds
3. Update issue status - Close finished work, update in-progress items
4. PUSH TO REMOTE - This is MANDATORY:

   git pull --rebase
   bd sync
   git push
   git status  # MUST show "up to date with origin"

5. Clean up - Clear stashes, prune remote branches
6. Verify - All changes committed AND pushed
7. Hand off - Provide context for next session

CRITICAL RULES:

• Work is NOT complete until git push succeeds
• NEVER stop before pushing - that leaves work stranded locally
• NEVER say "ready to push when you are" - YOU must push
• If push fails, resolve and retry until it succeeds