charter
An agent harness for spec-driven development.
Star
Fork
Watch
charter spec index.md
4.2 kB · 66 lines
Markdown
at main

id: charter kind: architecture title: Charter status: active #

Charter spec #

Charter is a Jazz-native workspace for spec-driven development.

The spec is the product surface. Humans write intent into documents; Jazz syncs those documents and their derived coordination objects; agents register as consumers of the resulting event stream and act on explicit work packets.

This spec/ folder is Charter's own local Markdown projection. It is useful because files are legible and editable. It is not the metaphysical source of truth. The coordination truth is the Charter project graph in Jazz.

Purpose #

Charter exists to make a project spec executable without turning chat history, terminal scrollback, or a pile of tickets into the real requirements store.

A user should be able to:

  1. start Charter with charter watch.
  2. edit Markdown specs in Zed, Obsidian, or any filesystem editor.
  3. change documentation, architecture, prompts, or product notes as ordinary spec documents.
  4. see those file changes automatically become semantic project events.
  5. see actionable events become durable work items.
  6. let registered agent consumers receive packets, run, report, fail, block, ignore, or create follow-up work.
  7. follow the provenance chain from document span to event to work item to packet to run to result.

The spec is the magic thing. AI should happen on the backend because the spec changed, not because a user manually copied prose into another chatbot window like a Victorian clerk with npm installed.

Charter should be built as the whole real system: Jazz-backed documents, real runtime paths, durable events, durable work items, registered consumers, durable packets, executable requests, reports, failures, retries, and provenance. The product can start narrow, but the narrow path must be real end to end.

How it works #

Charter gives humans, filesystem editors, API clients, workers, and agents the same coordination surface:

  1. Spec documents live as Jazz-backed database objects.
  2. The spec/ folder is the first editing surface.
  3. charter watch ingests filesystem changes into the project graph.
  4. Meaningful document edits, comments, spans, prompt changes, and agent lifecycle changes enter a central event stream.
  5. Events can create durable work items.
  6. Registered consumer agents subscribe to event/document selectors.
  7. Charter builds context packets from the source event, affected spans, prompt documents, attached context documents, and consumer configuration.
  8. Agent runs report structured outcomes and raw execution evidence back into the same graph.

Canonical documents #

  • product-vision.md: the product center of gravity and Jazz collaboration pitch.
  • axioms.md: design invariants, including the requirement that Charter is built as a real product with real backends rather than product theater.
  • folder-contract.md: what counts as a spec document and how identity works.
  • runtime-architecture.md: shared Jazz project plane, machine-local controller plane, distributed worker plane, identities, and leases.
  • data-model.md: shared database objects, identities, provenance, and lifecycle state.
  • document-interactions.md: rich Markdown, span anchors, comments, documentation-as-contract, and follow-the-run chains.
  • frontend.md: local watch runtime, event-stream observability, subordinate process shape, and optional API surface.
  • work-queue.md: central event stream and durable work queue.
  • consumer-agents.md: database-registered agent consumers, subscriptions, packets, outcomes, and cascades.
  • agent-runtime.md: how consumers run against the spec graph.
  • context-subscriptions.md: proposed shared project working memory, context manifests, runner-specific delivery, and freshness enforcement across heterogeneous agents.
  • jazz-mapping.md: durable Jazz mapping and permission shape.
  • jazz-git-boundary.md: which Jazz history/branch capabilities Charter uses and where Git remains a separate source adapter.
  • importer.md: scanner, normalization, filesystem sync, and deletion behavior.
  • indexing.md: local lexical index and search behavior.
  • agent-harness.md: pluggable runner request/execution contract.