Vision

Git-Native by Design

Your backlog should live where your code lives. Joy stores everything as plain YAML files in a .joy/ directory inside your repo. That means your backlog is:

• Versioned - Every change is a Git commit. Roll back, branch, compare.
• Diffable - Code review your backlog changes just like code changes.
• Mergeable - Feature branches can carry their own backlog updates.
• Portable - Clone the repo, get the backlog. No setup, no sync, no account.

There is no database, no server, no API. If Git works, Joy works.

Design Philosophy

Four principles guide every decision in Joy's development:

Fewer commands, more power. Ten commands cover 95% of daily use. Complexity lives in flags and options, not in a sprawling command hierarchy. You do not need to learn a taxonomy of subcommands to be productive. joy add, joy ls, joy start, joy close - that is already enough to manage a project.

Warnings, not walls. Joy validates your actions and warns you when something looks wrong, but it does not block you from doing what you intend. Circular dependencies are rejected because they are always a mistake. But starting work on an item that has unfinished dependencies? Joy warns you and lets you decide. The tool respects your judgment.

Text files are the API. Everything Joy stores is a YAML file in .joy/. You can read it with cat, diff it with git diff, search it with grep, and script against it with any language. There is no proprietary format, no binary blob, no hidden state. If Joy disappears tomorrow, your data is still readable.

AI is a team member, not a feature. AI tools are not a checkbox on a feature list. They are registered project members with identity, capabilities, delegation chains, and cost tracking. The same governance model that applies to human team members applies to AI. This is not "AI integration" - it is a collaboration architecture.

Terminal-First

Developers live in the terminal. Joy meets you there. No browser tab to switch to, no web UI to load, no mouse to reach for. Ten commands cover 95% of daily use:

joy add       joy ls        joy show      joy start     joy close
joy edit      joy deps      joy milestone joy roadmap   joy log

Everything else is a variation or shortcut.

Data Model

Item Types

Joy has seven item types, each serving a distinct purpose:

Status Workflow

Items move through a defined lifecycle:

Status transitions can be gated: projects define which transitions require human approval, which AI can perform autonomously, and which are blocked entirely. Zero gates means zero ceremony. Add them when your team or your compliance requirements demand it.

Dependencies and Milestones

Items can depend on other items. Joy detects circular dependencies and rejects them. Milestones group items into delivery targets with progress tracking. Children inherit their parent's milestone automatically. joy roadmap shows the full picture.

AI Integration

The Five Pillars

Joy's AI governance is built on five pillars that together form the Trust Model:

1. Trustship - Identity, capabilities, delegation. Every AI tool has a member entry with defined permissions, just like a human team member.
2. Guardianship - Runtime validation and gates. Capability checks prevent unauthorized actions. Gates require human approval at critical transitions.
3. Orchestration - Jobs, modes, and dispatch. Work is routed to the right actor based on capabilities, availability, and cost.
4. Traceability - Every action produces a structured event committed to Git. Append-only, tamper-evident, always auditable.
5. Settlement - Per-job cost tracking and budget enforcement. AI usage becomes a traceable, controllable line item.

Tool Mode vs. Agent Mode

Tool Mode (available). External AI agents call Joy's CLI as a tool. The agent reads the backlog, picks up tasks, and manages items through the same commands a human uses. Joy provides identity and governance; the AI tool provides the runtime.

Agent Mode (planned). Joy actively dispatches work to AI tools. It prepares context, invokes the tool, tracks the outcome, and records the cost. Joy is the dispatcher - the AI tool is the executor.

The distinction matters: in Tool Mode, the AI decides what to work on. In Agent Mode, Joy decides. Both modes use the same governance model.

Dispatch

Dispatch is the mechanism that bridges Joy (planning) and Jot (execution). When a Joy item reaches a status gate, dispatch can create a Jot task for the assigned person, invoke an AI tool to begin implementation, or notify a human reviewer. Dispatch respects trust boundaries - an AI tool can only receive work that falls within its capabilities and budget.

Through joyint.com, dispatch connects planning to execution across machines and team members. Locally, Joy and Jot share joy-core and can communicate directly.

ForgeSync Planned

Joy integrates with external code forges through ForgeSync. Supported platforms:

• GitHub - Authenticate via gh CLI or API token
• GitLab - Authenticate via glab CLI or API token
• Gitea (self-hosted) - Authenticate via API token

ForgeSync uses a mirror pattern: your local .joy/ directory is the source of truth. Changes flow from local to joyint.com to the external forge. Teams can continue using GitHub Issues or GitLab Issues while Joy handles planning, governance, and AI orchestration behind the scenes.

AI as Collaborator

AI tools already write code and review pull requests. Joy gives them a proper seat at the table: identity, capabilities, and an audit trail. An AI tool can read the backlog, pick up a task, implement it, and submit it for review - all through the same commands a human uses.

The Trust Model governs what AI can do, who authorized it, and what it cost. Start without governance (solo, implicit trust) and add it when your team or compliance needs it.

Simple by Default

Joy starts with zero ceremony. No configuration required, no workflows to define, no roles to set up. Create items, work through them, close them. Add dependencies, milestones, and governance only when the complexity of your project demands it.

Start Solo, Scale to Team

The same workflow works for one person and for twenty. Solo: you are the only member, everything is implicit. Team: add members, define capabilities, use the event log for accountability. Enterprise: add gates, audit trails, and cost controls. The commands stay the same.

Built with Joy

Joy is built with Joy. The backlog, milestones, and roadmap for Joy itself are managed using Joy. This dogfooding ensures that every workflow, every edge case, and every inconvenience is felt by the people building the tool. If something is awkward to use, it gets fixed - not documented.