Skip to content

getting-started.md

Latest commit

 

History

History
102 lines (70 loc) · 3.37 KB

getting-started.md

File metadata and controls

102 lines (70 loc) · 3.37 KB

Getting Started

Charter is a local-first governance toolkit with a built-in AI context compiler. It validates commit governance, detects stack drift, scores risk, and ships ADF (Attention-Directed Format) — a modular, AST-backed context system that replaces monolithic .cursorrules and claude.md files. Everything runs locally and in CI, with no SaaS dependency.

Install

Recommended: local dev dependency per repo.

npm install --save-dev @stackbilt/cli

pnpm workspace root:

pnpm add -Dw @stackbilt/cli

Global (optional, puts charter on your PATH):

npm install -g @stackbilt/cli

WSL2 users: If your project lives on the Windows filesystem (/mnt/c/...), see WSL2 + Windows Filesystem for path considerations, pnpm workarounds, and line-ending setup.

Bootstrap a Repo

# Preview what charter detects — no files written
npx charter setup --detect-only --format json

# Write governance baseline + optional CI workflow
npx charter setup --ci github --yes

# Mixed repos (frontend + backend): choose preset explicitly
npx charter setup --detect-only
npx charter setup --preset fullstack --ci github --yes

setup writes:

  • .charter/config.json — governance baseline config
  • .charter/patterns/*.json — blessed-stack pattern definitions
  • .charter/policies/*.md — human-readable policy summary
  • .github/workflows/charter-governance.yml — CI workflow (if --ci github)

Set Up ADF Context

ADF turns your LLM context into a compiled, modular system. Scaffold the .ai/ directory:

# Scaffold .ai/ with manifest, core, and state modules
npx charter adf init

# Verify everything parses and syncs
npx charter doctor --format json

This creates (for default presets):

.ai/
  manifest.adf    # Module registry: default-load vs on-demand with triggers
  core.adf        # Always-loaded: role, constraints, metric ceilings
  state.adf       # Session state: current task, decisions, blockers
  frontend.adf    # Frontend module scaffold (on-demand, triggers: React, CSS, UI)
  backend.adf     # Backend module scaffold (on-demand, triggers: API, Node, DB)

For documentation-heavy repos, use --preset docs to get decisions.adf and planning.adf instead of frontend/backend modules.

Edit .ai/core.adf to define your project constraints and LOC ceilings. The METRICS [load-bearing] section enforces hard limits that CI can gate on.

Verify the Setup

npx charter doctor --format json
npx charter

charter with no arguments prints a live governance snapshot: risk score, governed commit ratio, drift status.

doctor validates environment health including ADF readiness: manifest existence, module parse status, and sync lock integrity.

Run an Evidence Check

If you have ADF set up with metric ceilings, run the evidence pipeline:

# Validate all metric ceilings and produce a structured report
npx charter adf evidence --auto-measure

# CI mode: exits 1 if any ceiling is breached
npx charter adf evidence --auto-measure --ci --format json

What's Next