Charter CLI/02Charter Kit

Charter Kit

npm version

Charter is one piece of the Stackbilt ecosystem — open-source governance and context tooling alongside AEGIS Core, evidence-core, audit-chain, and the Stackbilder platform.

The Problem

You write a CLAUDE.md. You add a .cursorrules. You paste instructions into GEMINI.md. Your AI agent loads all of it into the context window – 10,000 tokens of flat, unstructured rules competing with the actual work.

Half get ignored. You don’t know which half.

The Solution

Charter is an open-source CLI that replaces monolithic agent config files with ADF (Attention-Directed Format) – a modular context system where agents load only the rules they need for the current task.

Instead of one big file, you get a manifest. The manifest declares modules, trigger keywords that load them on demand, token budgets, and weighted sections that tell the agent what’s load-bearing vs. advisory.

npm install --save-dev @stackbilt/cli
npx charter bootstrap --yes   # detect stack, scaffold .ai/, migrate existing rules

Five-Minute Adoption

Already have agent config files? Charter migrates them:

# See what would happen (dry run)
charter adf migrate --dry-run

# Migrate: classifies rules by strength, routes to ADF modules, replaces originals with thin pointers
charter adf migrate

Your CLAUDE.md / .cursorrules / GEMINI.md content gets classified (imperative vs. advisory vs. neutral), routed to the right module (frontend rules to frontend.adf, backend rules to backend.adf), and your originals become one-line pointers to .ai/. No content lost, no rewrite needed.

How ADF Works

Charter manages context through the .ai/ directory:

.ai/
  manifest.adf    # Module registry: default-load vs on-demand with trigger keywords
  core.adf        # Always-loaded: role, constraints, output format, metric ceilings
  state.adf       # Session state: current task, decisions, blockers
  frontend.adf    # On-demand: loaded when task mentions "react", "css", etc.
  backend.adf     # On-demand: loaded when task mentions "endpoint", "REST", etc.

When you run charter adf bundle --task "Fix the React login component", Charter:

  1. Reads the manifest
  2. Loads core.adf and state.adf (always loaded)
  3. Sees “React” matches a trigger keyword – loads frontend.adf
  4. Skips backend.adf (no matching triggers)
  5. Merges the loaded modules into a single context payload with token budget tracking

The agent gets exactly the rules it needs. Nothing more.

Format Example

ADF: 0.1

TASK:
  Build the user dashboard

CONTEXT:
  - React 18 with TypeScript
  - TailwindCSS for styling
  - REST API at /api/v2

CONSTRAINTS [load-bearing]:
  - No external state libraries
  - Must support SSR

METRICS [load-bearing]:
  entry_loc: 142 / 500 [lines]
  handler_loc: 88 / 300 [lines]

STATE:
  CURRENT: Implementing layout grid
  NEXT: Add data fetching
  BLOCKED: Waiting on API schema

Sections use emoji decorations for attention signaling, support four content types (text, list, key-value map, and metric with value/ceiling/unit), and follow a canonical ordering the formatter enforces. [load-bearing] vs [advisory] weight annotations distinguish measurable constraints from preferences. Metric entries (key: value / ceiling [unit]) define hard ceilings that the evidence command validates automatically.

Self-Governance: Charter Enforces Its Own Rules

This isn’t theoretical. Charter uses ADF to govern its own codebase. The .ai/ directory in this repository contains the same modules and metric ceilings that any adopting repo would use.

Every commit runs through a pre-commit hook that executes charter adf evidence --auto-measure. If a source file exceeds its declared LOC ceiling, the commit is rejected. We can’t ship code that violates our own governance rules – even by accident, even at 2am.

Here is the actual output from Charter’s own evidence check (v1.0.0):

  ADF Evidence Report
  ===================
  Modules loaded: core.adf, state.adf
  Token estimate: ~494
  Token budget: 4000 (12%)

  Auto-measured:
    adf_commands_loc: 618 lines (packages/cli/src/commands/adf.ts)
    adf_bundle_loc: 175 lines (packages/cli/src/commands/adf-bundle.ts)
    adf_sync_loc: 213 lines (packages/cli/src/commands/adf-sync.ts)
    adf_evidence_loc: 272 lines (packages/cli/src/commands/adf-evidence.ts)
    adf_migrate_loc: 474 lines (packages/cli/src/commands/adf-migrate.ts)
    bundler_loc: 125 lines (packages/adf/src/bundler.ts)
    parser_loc: 214 lines (packages/adf/src/parser.ts)
    cli_entry_loc: 191 lines (packages/cli/src/index.ts)

  Section weights:
    Load-bearing: 3
    Advisory: 1
    Unweighted: 0

  Constraints:
    [ok] adf_commands_loc: 618 / 650 [lines] -- PASS
    [ok] adf_bundle_loc: 175 / 200 [lines] -- PASS
    [ok] adf_sync_loc: 213 / 250 [lines] -- PASS
    [ok] adf_evidence_loc: 272 / 380 [lines] -- PASS
    [ok] adf_migrate_loc: 474 / 500 [lines] -- PASS
    [ok] bundler_loc: 125 / 500 [lines] -- PASS
    [ok] parser_loc: 214 / 300 [lines] -- PASS
    [ok] cli_entry_loc: 191 / 200 [lines] -- PASS

  Sync: all sources in sync

  Verdict: PASS

What this shows:

  • Metric ceilings enforce LOC limits on source files. Each metric in a .adf module declares a ceiling. --auto-measure counts lines live from the sources referenced in the manifest.
  • Self-correcting architecture. When bundler_loc hit 413/500, Charter’s own evidence gate flagged the pressure. The file was split into three focused modules (manifest.ts, merger.ts, bundler.ts) – now 125/500. The system caught the problem and the system verified the fix.
  • CI gating. Generated governance workflows run doctor --adf-only --ci and adf evidence --auto-measure --ci on every PR, blocking merges on ceiling breaches.
  • Available to any repo. This is the same system you get by running charter adf init in your own project.

Quick Reference

# Scaffold .ai/ with starter modules
charter adf init

# Letter-grade AI-readiness audit + badge
charter score
charter score --badge --write

# Render .ai/ to CLAUDE.md, AGENTS.md, .cursorrules, GEMINI.md (CI drift gate)
charter adf compile --target all --write
charter adf compile --target all --check

# Reformat to canonical form
charter adf fmt .ai/core.adf --write

# Apply a typed patch
charter adf patch .ai/state.adf --ops '[{"op":"ADD_BULLET","section":"STATE","value":"Reviewing PR #42"}]'

# Bundle context for a task (trigger-based module loading)
charter adf bundle --task "Fix the React login component"

# Migrate existing agent configs into ADF
charter adf migrate --dry-run

# Verify .adf files haven't drifted from locked hashes
charter adf sync --check

# Validate metric constraints
charter adf evidence --auto-measure

# Recalibrate metric ceilings
charter adf metrics recalibrate --headroom 15 --reason "Scope expansion" --dry-run

# Expose ADF context as an MCP server (for Claude Code / any MCP client)
charter serve

Why Charter

  • Modular AI context – trigger-routed .ai/ modules replace monolithic config files
  • Five-minute migration – classify and route existing CLAUDE.md / .cursorrules / GEMINI.md rules automatically
  • Multi-vendor compile – charter adf compile --target all renders .ai/ to CLAUDE.md, AGENTS.md, .cursorrules, and GEMINI.md; --check gates CI on drift
  • MCP server – charter serve exposes your ADF context as an MCP server; charter_brief replaces 15–30 cold-boot discovery calls
  • AI-readiness audit – charter score grades your repo A–F across agent config, grounding, architecture, testing, governance, and freshness; --badge --write emits a shields.io endpoint for your README
  • Evidence-based governance – metric ceilings with auto-measurement, structured pass/fail reports, CI gating
  • Self-regulating – pre-commit hooks enforce constraints before code lands
  • Commit governance – validate Governed-By and Resolves-Request trailers, score commit risk
  • Drift detection – scan for stack drift against blessed patterns
  • Stable JSON output – every command supports --format json with nextActions hints for agent workflows

ADF is an open specification at adf-spec/adf (Apache-2.0, vendor-neutral org). Charter is the reference implementation. A conformance suite is in progress.

Install

npm install --save-dev @stackbilt/cli

For pnpm workspaces: pnpm add -Dw @stackbilt/cli. For global install: npm install -g @stackbilt/cli.

Getting Started

Human Workflow

charter                              # Repo risk/value snapshot
charter bootstrap --ci github        # One-command onboarding
charter doctor                       # Validate environment/config
charter validate                     # Check commit governance
charter drift                        # Scan for stack drift
charter audit                        # Governance summary
charter adf init                     # Scaffold .ai/ context directory

Claude Code Integration (MCP)

charter serve exposes your .ai/ modules as an MCP server. For connecting AI agents to the broader Stackbilt platform (scaffolding, image generation, architecture flows), see the MCP Gateway.

Add Charter’s own MCP server to .claude/settings.json:

{
  "mcpServers": {
    "charter": {
      "command": "charter",
      "args": ["serve"]
    }
  }
}

Claude Code can call these tools directly — no manual adf bundle needed:

Tool Description
charter_brief Call first. Pre-digested repo brief — routes, hotspots, governance. Replaces 15–30 cold-boot discovery calls.
charter_context Session continuity snapshot reader/refresher.
getProjectContext ADF bundle resolved for the current task.
getProjectState Constraint validation results across all loaded modules.
getArchitecturalDecisions Load-bearing constraints from core.adf.
getRecentChanges Recent git commits classified by type.
charter_blast Blast radius for one or more source files.
charter_surface API surface — HTTP routes and D1/SQLite schema tables.
updateEvidence Write-back: measures metrics, patches ADF, returns before/after diff.

Agent Workflow

Prefer JSON mode and exit-code handling:

charter --format json
charter setup --ci github --yes --format json
charter doctor --format json
charter validate --format json --ci
charter drift --format json --ci
charter audit --format json
charter adf bundle --task "describe the task" --format json
charter adf evidence --auto-measure --format json --ci
charter adf sync --check --format json

Agent contract:

  • Inputs: git repo + optional existing .charter/
  • Stable machine output: --format json with nextActions hints where applicable
  • Exit codes: 0 success, 1 policy violation, 2 runtime/usage error
  • CI behavior: with --ci, treat 1 as gating failure and surface actionable remediation
  • Evidence: adf evidence --ci exits 1 on metric ceiling breaches; warnings (at boundary) don’t fail
Trailer Adoption Ramp

Teams often score lower early due to missing governance trailers. Use this ramp:

  • Stage 1: run charter validate --ci --format json in PR CI and fail on policy violations.
  • Stage 2: add a commit template in the repo that includes Governed-By and Resolves-Request.
  • Stage 3: track audit trend; trailer coverage should rise naturally as PR gating normalizes behavior.

Cross-Platform Support

Charter works across WSL, PowerShell, CMD, macOS, and Linux. All git operations use a unified invocation layer with cross-platform PATH resolution. Line endings are normalized via .gitattributes.

Command Reference

For complete flag documentation and advanced usage, see the CLI Reference.

  • charter: show repo risk/value snapshot and recommended next action
  • charter bootstrap [--ci github] [--preset <name>] [--yes] [--skip-install] [--skip-doctor]: one-command onboarding (detect + setup + ADF + migrate + install + doctor)
  • charter setup [--ci github] [--preset <worker|frontend|backend|fullstack|docs>] [--detect-only] [--no-dependency-sync]: detect stack and scaffold .charter/ baseline
  • charter init [--preset <worker|frontend|backend|fullstack>]: scaffold .charter/ templates only
  • charter doctor [--adf-only]: validate environment/config state (--adf-only runs strict ADF wiring checks)
  • charter validate [--ci] [--range <revset>]: validate commit governance and citations
  • charter drift [--path <dir>] [--ci]: run drift scan
  • charter audit [--ci] [--range <revset>]: produce governance audit summary
  • charter classify <subject>: classify change scope heuristically
  • charter hook install --commit-msg [--force]: install commit-msg trailer normalization hook
  • charter hook install --pre-commit [--force]: install pre-commit ADF routing + evidence gate
  • charter adf init [--ai-dir <dir>] [--force]: scaffold .ai/ context directory
  • charter adf fmt <file> [--check] [--write]: parse and reformat ADF files to canonical form
  • charter adf fmt --explain: show canonical formatter section ordering
  • charter adf patch <file> --ops <json> | --ops-file <path>: apply typed delta operations
  • charter adf create <module> [--triggers "a,b,c"] [--load default|on-demand]: create and register a module
  • charter adf bundle --task "<prompt>" [--ai-dir <dir>]: resolve manifest and output merged context
  • charter adf sync --check [--ai-dir <dir>]: verify .adf files match locked hashes
  • charter adf sync --write [--ai-dir <dir>]: update .adf.lock with current hashes
  • charter adf evidence [--task "<prompt>"] [--ai-dir <dir>] [--auto-measure] [--context '{"k":v}'] [--context-file <path>]: validate metric constraints and produce evidence report
  • charter adf metrics recalibrate [--headroom <percent>] [--reason "<text>"|--auto-rationale] [--dry-run]: recalibrate metric baselines/ceilings
  • charter adf migrate [--dry-run] [--source <file>] [--no-backup] [--merge-strategy append|dedupe|replace]: migrate existing agent config files into ADF modules
  • charter serve [--name <name>] [--ai-dir <dir>]: start an MCP server (stdio) exposing ADF context as tools and resources for Claude Code and other MCP clients
  • charter telemetry report [--period <30m|24h|7d>]: summarize local CLI telemetry
  • charter why: explain adoption rationale and expected payoff

Global options: --config <path>, --format text|json, --ci, --yes.

Exit Code Contract

  • 0: success/pass
  • 1: policy violation in CI mode
  • 2: runtime/config/usage error

CI Integration

Charter CI governance pairs naturally with the Stackbilder platform — use Charter to enforce commit governance and ADF metric ceilings, and the platform’s REST API or MCP gateway for architecture generation and scaffolding. For unattended Claude Code task queues with Charter blast-radius gating, see cc-taskrunner. For LLM cost routing during Charter-governed sessions, see bildy.

  • Reusable template: .github/workflows/governance.yml
  • Generated in target repos by charter setup --ci github: .github/workflows/charter-governance.yml
  • The governance workflow runs validate, drift, ADF wiring integrity (doctor --adf-only --ci), ADF ceiling evidence (adf evidence --auto-measure --ci), and audit on every PR.

Workspace Layout

packages/
  types/      Shared contracts
  core/       Schemas, sanitization, errors
  adf/        ADF parser, formatter, patcher, bundler, evidence pipeline
  git/        Trailer parsing and risk scoring
  classify/   Heuristic classification
  validate/   Governance validation
  drift/      Pattern drift scanning
  cli/        `charter` command
  ci/         GitHub Actions integration helpers

Development

  • pnpm run clean
  • pnpm run typecheck
  • pnpm run build
  • pnpm run test

SemVer and Stability Policy

Charter uses Semantic Versioning for this repository and for published @stackbilt/* packages.

Until 1.0.0, Charter may still evolve quickly, but breaking changes should remain exceptional, deliberate, and clearly documented. The goal of 1.0.0 is simple: a connected coding agent or developer can rely on Charter’s machine-facing contracts without source archaeology.

The following surfaces are semver-governed:

  • Package APIs – exported functions, classes, and types from published @stackbilt/* packages
  • CLI behavior – command names, flags, exit codes, and machine-readable --format json output
  • ADF behavior – parse, format, patch, bundle, sync, and evidence semantics
  • Generated artifacts – thin pointer files, .ai/manifest.adf, .adf.lock, and related scaffolded outputs
  • Governance schemas – evidence, audit, drift, doctor, and scorecard JSON envelopes

Versioning rules:

  • PATCH – bug fixes, docs, internal refactors, and non-breaking UX improvements
  • MINOR – additive commands, flags, fields, modules, templates, and advisory checks that do not break existing consumers
  • MAJOR – incompatible changes to CLI contracts, JSON schemas, ADF semantics, generated artifact conventions, or other machine-facing behavior that agents may rely on

For agent-facing workflows, schema stability is treated as a core product promise, not a nice-to-have.

Research & White Papers

The papers/ directory contains Charter’s research narrative:

Entry Point Purpose
Papers Index Research papers, UX feedback, and release planning docs
UX Feedback Index Journey-bucketed ADX findings
Release Plans Index Versioned plans mapping feedback to implementation
@stackbilt/adf API Full ADF package API documentation

Release Docs

  • PUBLISHING.md: first release/publish workflow
  • CHANGELOG.md: user-visible change history
  • CONTRIBUTING.md: contribution conventions
  • SECURITY.md: vulnerability reporting

License

Apache-2.0. See LICENSE.

Buy me a coffee

EDIT ON GITHUB
←PREVIOUS
Ecosystem
01
NEXT→
CLI Reference
03