charter

Charter

AI-assisted project discipline plugin for Claude Code and Codex CLI.

You're the manager. The AI is your dev team. Charter is your PMO.

Charter enforces session-to-session continuity through living docs and lightweight rituals layered on top of superpowers. Install once, never re-explain your project again.

---

The Problem

AI-assisted projects drift. Each new session starts cold: the assistant doesn't know where you left off, which decisions were made and why, or what rituals your project enforces. You re-explain vision, re-derive architecture, and re-approve the same patterns every session.

Charter fixes this.

Without Charter — every session starts with:

"What are we building? Where did we leave off? What decisions did we make?"

With Charter — Claude opens with:

"You're on step 3: implementing the render pipeline. Last session you decided to use Puppeteer over wkhtmltopdf (see docs/decisions/). Next: write the HTML emit stage."

---

Install

Do not clone this repo. Cloning is for contributing to Charter itself. To use Charter on your projects, install it as a plugin using the commands below.

If Charter is listed in the official plugin directory:

/plugin install superpowers
/plugin install charter

Install directly from GitHub (always works, use this if the above doesn't):

/plugin install superpowers
/plugin marketplace add fjoad/charter
/plugin install charter@fjoad-charter

Charter has been submitted to the official Claude Code plugin directory and is pending review. Once accepted, /plugin install charter will work directly. Until then, use the GitHub install path above.

Then for a new project:

/charter-init

Or for an existing project:

/charter-attach

---

What It Does

At session start: Reads your STATUS.md and orients Claude before the first message. Zero re-explanation.

On every request: Classifies size (trivial/small/medium/major) and applies matching ritual depth. Typo fix → direct execution. Architecture change → full plan, checkpoint, verify, report.

At step completion: Enforces the finish checklist. Tests run. Docs updated. Status recorded. Standard report to you.

Checkpoint-based autonomy: Plans embed ## CHECKPOINT: user review markers. AI runs autonomously between checkpoints, pauses at each. You stay in control without micromanaging.

Branch-aware workflows (v0.2.0+): Feature branches get their own plan; the finish ritual adapts; STATUS.md stays conflict-free on merge. Backward compatible — existing projects keep working unchanged after update.

Working memory across compactions (v0.3.0+): docs/CONTEXT.md is the AI's working scratchpad — environment quirks, working patterns, don't-repeats, user emphases. Auto-loaded at session start. After /compact, /charter-recover restores orientation without re-scanning the transcript. Opt-in via /charter-adopt context.

Three-tier recovery model (v0.4.0+): /charter-recover (CONTEXT.md only, cheapest) → /charter-replay (dialogue-filtered transcript, medium) → raw transcript read (anti-pattern, never the right answer). The replay command's prompt is also useful as a standalone instruction in non-Charter sessions.

---

Commands

Charter runs automatically — you don't need these commands for day-to-day use. They're there when you want to explicitly trigger something or take over.

Command	When to use it
/charter-help	List everything Charter offers — commands, conventions, recovery tiers
/charter-init	Once, to bootstrap a new project
/charter-attach	Once, to attach Charter to an existing project
/charter-adopt	Opt into a new Charter convention in an existing project (e.g. /charter-adopt branches or /charter-adopt context)
/charter-remember	Capture something to docs/CONTEXT.md so it survives /compact
/charter-recover	After /compact, restore orientation — reads CONTEXT.md + STATUS.md + branch plan, auto-escalates to a transcript replay if working memory is thin
/charter-replay	Direct access to the dialogue-only transcript replay (recover runs this for you when needed)
/charter-preview	Dry-run for init / attach / adopt-* — lists what would be scaffolded without writing anything
/charter-next	Explicitly start the next step (Charter will nudge you anyway)
/charter-finish	Explicitly run the finish ritual (Charter will remind you anyway) — adapts to main vs feature branch
/charter-cost	See how many tokens Charter has added this session
/charter-off	Kill rituals for the rest of the session — just get things done

---

What Gets Scaffolded