docs/PROJECT_CHARTER.md
This document defines the product boundary for beads. It is the source of truth for deciding whether proposed work belongs in core, belongs in an integration or plugin, belongs in an orchestration layer, or should stay outside the project.
Beads is a focused issue tracker for AI-supervised development. It should stay small enough to remain reliable, understandable, and composable.
Beads owns issue tracking primitives:
Within those boundaries, the project should absorb useful contributor work when practical. If a contribution has value but does not fit as submitted, prefer preserving the value by simplifying it, moving it to metadata, routing it to an integration or plugin, cherry-picking the reusable part, or reimplementing the use case in a smaller design.
Beads should not know about orchestration layers built on top of it. Systems such as Gastown, Gas City, schedulers, swarms, release coordinators, and future workflow engines may use beads, but beads should not encode their concepts in core.
Core beads can expose stable issue data, metadata, CLI output, and documented extension points. The orchestration layer owns orchestration policy: agent routing, task assignment strategy, model choice, retry plans, scheduling, workflow semantics, and cross-system coordination.
When orchestration needs extra per-issue data, prefer issue metadata before adding first-class fields or commands.
Beads should not become a storage engine. Dolt provides storage, versioning, sync, merge behavior, concurrency, and crash safety. Beads should put data in and pull data out through the storage boundary.
Storage-engine details should not leak into beads packages unless they are part of a deliberate storage interface. Avoid beads-side flocks, engine introspection, storage-specific retry loops, crash-recovery workarounds, or schema poking that belongs in Dolt or the Dolt driver.
If the current storage interface cannot express a needed operation, widen the interface or route the issue to the driver instead of embedding storage-engine logic in core.
The database schema is considered stable. Schema changes are allowed when there is a pressing product or correctness need, but they should not be the first answer to extension requests.
Use issue metadata first when:
Promote metadata to first-class schema only when the field has broad, durable meaning for beads itself and the migration cost is justified.
Tracker integrations are adoption bridges, not a second product surface. They should map external tracker data into beads concepts and keep the dependency graph useful. They should not replicate tracker UIs, notification systems, credential vaults, webhook gateways, or cross-tracker automation.
See Integration Charter for the detailed policy for GitHub, GitLab, Jira, Linear, Azure DevOps, and similar tracker integrations.
These boundaries are fences, not bounce messages. Maintainers should not reject useful work reflexively just because the first version crosses a boundary.
For pull requests and proposals:
Use request-changes or rejection only after considering whether the project can absorb, transform, or reroute the useful part.