foooz

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

Beads Workflow Integration

This project uses beads_rust (br) for issue tracking. Issues live in .beads/: beads.db is the local SQLite source of truth (gitignored) and issues.jsonl is the versioned export.

Essential Commands

# View ready issues (open, unblocked, not deferred)
br ready              # the single work-discovery entrypoint

# List and search
br list --status=open # All open issues
br show <id>          # Full issue details with dependencies
br search "keyword"   # Full-text search

# Create and update
br create "title" -t task -p 2 --description-file notes.md
br update <id> --acceptance-criteria "..."   # br create has no such flag; set it after
br q "title"          # Quick capture, prints only the new ID
br update <id> --claim        # Atomic: assignee=actor + status=in_progress
br close <id> --reason="Completed: <proof>"
br close <id1> <id2>  # Close multiple issues at once
br delete <id> --hard # Remove issue and prune its tombstone from JSONL

# Sync / diagnostics
br sync --status      # Are there unexported changes?
br sync --flush-only  # Force export DB to .beads/issues.jsonl
br robot-docs guide   # Official agent guide, printed by the binary

Every mutating command auto-exports the JSONL, so br sync --flush-only is a safety net rather than a required step. Check br sync --status if unsure.

br update -s closed is refused on purpose; terminal states must go through br close so close-policy and dependency rewiring run.

Key Concepts

• Dependencies: Issues can block other issues. br ready shows only open, unblocked work.
• Status: use the canonical open → in_progress → closed. open is our "todo", in_progress is our "doing". The CLI also accepts free-form words like todo/doing, but br ready only surfaces open, so anything else disappears from work discovery.
• Priority: P0=critical, P1=high, P2=medium, P3=low, P4=backlog (use numbers 0-4, not words)
• Types: task, bug, feature, epic, chore, docs, question
• Blocking: br dep add <issue> <depends-on> to add dependencies

Best Practices

• Check br ready at session start to find available work
• Update status as you work (in_progress → closed)
• Create new issues with br create when you discover tasks
• Use descriptive titles and set appropriate priority/type
• Close reasons should carry proof, not just "done"
• Tasks live here, never in .cursor/context/. Context notes hold feature scope, language, and decisions; anything actionable becomes an issue.

Everything between the two br-agent-instructions comments above is regenerated by br agents --update. Repo-specific rules go below this line, never inside it.

Version Control: Jujutsu, not git

This repo uses jj. There is no staging area and no git add: every edit in the working copy already belongs to the working commit @. Never reach for raw git commands.

Per-Task Sequence

One feature, one described commit. Always start a feature with jj new and always end it with jj describe. A commit must never be left with (no description set) once its work is finished.

# 1. pick and claim
br ready
br update <id> --claim

# 2. fresh working commit BEFORE touching any file
jj new

# 3. do the work; build with `odin build . -vet -strict-style`

# 4. close the issue while still inside this commit. br writes
#    .beads/issues.jsonl straight away, so the issue state lands in the same
#    commit as the code that satisfies it.
br close <id> --reason="<proof>"

# 5. name the commit immediately, do not wait to be asked
jj describe -m ":hammer: short present tense summary"

# 6. open the next empty working commit and verify
jj new
jj log

Description format is :<emoji>: <3-4 words>. Write it as soon as the work is done and state which message you used; the user can always re-run jj describe to reword. Do not stall a feature waiting for message approval.

If work has already started in an undescribed @ before you remembered jj new, describe @ for what it actually contains, then jj new and carry on. jj describe -r <rev> renames any earlier commit, so nothing is ever stuck.

There are no automated tests yet, so step 4 ends at "it builds and the change was verified by eye". When a task adds testable logic, leave one runnable check behind and run it here.

Session Protocol

jj status                       # What does the working commit hold?
br sync --status                # Beads exported? flush only if dirty
jj describe -m ":hammer: ..."   # Name @ if it still holds real changes
jj new                          # Leave a clean empty working commit

# publishing, only when asked
jj bookmark set main -r @-      # jj bookmarks do not follow new commits
jj git push

Never end a session with an undescribed, non-empty @; that is the state rollbacks cannot reason about.

Deeper notes and the reasoning behind this ordering: .cursor/context/2026-08-04-beads-jj-workflow.md.

Beads labels + priority (repo rule)

Every br create must include both:

• -p — P0 crash/unplayable … P2 default feature … P4 backlog
• -l — fixed labels, usually one area:* and one kind:*

br create "title" -t feature -p 2 -l "area:gameplay,kind:feature" --description-file notes.md

Full vocab and cheat-sheet: .cursor/context/2026-08-04-beads-jj-workflow.md.

Teaching-comment policy (verbose proc docs for a fullstack reader learning Odin/raylib; curiosity agreements get written into comments): .cursor/context/2026-08-05-teaching-comments.md.