Use Cases

1. Solo Dev Managing a Side Project

You have a side project and a head full of ideas. You need structure without overhead.

Initialize Joy in your repo, dump your ideas as items, and prioritize them. Use joy roadmap to plan what ships first. Work through items one at a time with joy start and joy close. When you pick the project up after a break, joy ls --status open shows you exactly where you left off.

joy init
joy add epic "Core Features"
joy add story "User authentication" --parent CB-0001 --priority high
joy add idea "Dark mode" --priority low
joy roadmap

No signup, no trial, no browser. Just your terminal and your repo.

2. Small Team with Shared Backlog

A team of three to five developers sharing a Git repo. Everyone needs visibility into what is planned, in progress, and blocked.

Joy lives in the repo. Everyone runs joy init after cloning to set up their local environment. Items are added, discussed via comments, and tracked through status changes. Dependencies prevent stepping on each other's work. Milestones align the team on delivery targets.

joy ls --mine                    # What am I working on?
joy ls --blocked                 # What is stuck?
joy milestone show CB-MS-01      # Are we on track for the milestone?

Pull requests include backlog changes alongside code changes. Reviewers see the full picture.

3. AI-Assisted Development

Your AI coding tool reads the Joy backlog, understands priorities, picks up a task, implements it, and submits it for review - all through Joy commands.

joy ls --status open --priority high

joy start CB-0005 --author ai:claude@joy

joy comment CB-0005 "Implementation complete" --author ai:claude@joy
joy submit CB-0005 --author ai:claude@joy

The event log traces every AI action back to the human who authorized the session. Capabilities control what the AI can do. Gates require human approval at critical transitions.

4. Open Source with Community Governance

An open source project with maintainers and external contributors. You need transparency without bureaucracy.

Maintainers have full capabilities. Contributors can add ideas and bugs but cannot change status or close items without review. The commit-msg hook ensures every contribution references a backlog item. The event log is public and auditable.

joy add bug "Crash on empty input"

joy status CB-0042 open
joy assign CB-0042 contributor@example.com

5. Regulated Environment with Audit Trails

A team building software under compliance requirements. Every change needs traceability, every decision needs documentation.

Joy's event log records every action automatically. Decision items document architectural choices. The commit-msg hook links every code change to a backlog item. Judge (planned) provides independent audit reports.

joy add decision "Use PostgreSQL for persistence" --priority high
joy comment CB-0010 "Evaluated MySQL, PostgreSQL, SQLite. PostgreSQL chosen for JSONB support."
joy log --since 30d              # Audit trail for the last 30 days

No separate audit system needed. The trail is in Git, versioned and tamper-evident.