Skip to content

README.md

Latest commit

 

History

History
193 lines (137 loc) · 8.35 KB

README.md

File metadata and controls

193 lines (137 loc) · 8.35 KB

Charter

npm version License Discord

Local-first AI agent governance for your repo.

Tell your AI agents what they can and can't do. Charter gives you modular context loading (ADF), measurable ceilings on every module, commit-time validation, and pre-merge blast-radius analysis. Zero product dependencies. No network calls. No credentials stored.

npx @stackbilt/cli bootstrap --yes

Detects your stack, scaffolds .ai/, migrates existing CLAUDE.md / .cursorrules / GEMINI.md into on-demand modules with trigger keywords.

What you get

  • Modular agent context (ADF) — replace monolithic CLAUDE.md with trigger-driven on-demand module loading. Agents pull only the rules each task needs.
  • Measurable constraints — per-module metric ceilings (LOC, complexity, bloat) validated at commit time and in CI.
  • Codebase analysis — charter blast reverse-dependency graphs, charter surface route/schema fingerprints. Deterministic, zero runtime deps.
  • Drift + audit — anti-pattern scans, commit governance, CI-ready exit codes.
  • MCP server — charter serve exposes project context to Claude Code.

Compose with the broader Stackbilt ecosystem — audit-chain, worker-observability, llm-providers, adf — when you need them.

Install

npm install --save-dev @stackbilt/cli

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

WSL2 note: If your project lives on the Windows filesystem (/mnt/c/...), pnpm may fail with EACCES permission errors due to WSL2/NTFS cross-filesystem limitations with atomic renames. Use pnpm add --force to work around this, or move your project to a Linux-native path (e.g., ~/projects/) for best performance.

AI agent governance with ADF

Charter replaces monolithic agent config files (CLAUDE.md, .cursorrules, GEMINI.md) with ADF (Attention-Directed Format) -- a modular context system where agents load only the rules they need.

The problem: You write 10,000 tokens of flat rules. Your agent loads all of it. Half gets ignored. You don't know which half.

The fix: A manifest that declares modules, trigger keywords that load them on demand, token budgets, and weighted sections that tell the agent what matters.

charter bootstrap --yes   # detect stack, scaffold .ai/, migrate existing rules

How it works

.ai/
  manifest.adf    # Module registry: default vs on-demand with trigger keywords
  core.adf        # Always loaded: role, constraints, 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 loads core.adf + state.adf (always), adds frontend.adf (trigger match on "React"), skips backend.adf. The agent gets exactly the rules it needs.

Five-minute migration

Already have agent config files? Charter migrates them:

charter adf migrate --dry-run   # Preview what would happen
charter adf migrate             # Classify rules, route to ADF modules, replace originals

Your existing content gets classified by strength (imperative vs. advisory), routed to the right module, and originals become one-line pointers to .ai/. No content lost.

Metric ceilings

ADF modules can declare measurable constraints:

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

charter adf evidence --auto-measure validates these live. Pre-commit hooks reject code that exceeds ceilings. CI workflows gate merges. Charter enforces its own rules on its own codebase -- every commit.

MCP server for Claude Code

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

Claude Code can query getProjectContext, getArchitecturalDecisions, getProjectState, and getRecentChanges directly.

Commands

Govern

charter                                  # Repo risk/value snapshot
charter bootstrap --ci github            # One-command onboarding
charter doctor                           # Environment/config health check
charter validate                         # Commit governance (trailers)
charter drift                            # Pattern drift scanning
charter audit                            # Governance summary

ADF

charter adf init                         # Scaffold .ai/ directory
charter adf bundle --task "..."          # Merge context for a task
charter adf evidence --auto-measure      # Validate metric constraints
charter adf migrate                      # Migrate existing configs
charter adf sync --check                 # Verify files match lock
charter adf fmt .ai/core.adf --write     # Reformat to canonical form
charter adf metrics recalibrate          # Adjust ceilings to current state
charter serve                            # MCP server for Claude Code

Analyze

charter blast src/foo.ts                 # Blast radius: files that transitively import the seed
charter blast src/a.ts src/b.ts --depth 4  # Multi-seed, custom BFS depth
charter surface                          # Extract routes (Hono/Express) + D1 schema
charter surface --markdown               # Emit as markdown for .ai/surface.adf or AI context

Deterministic codebase analysis — no LLM calls, zero runtime dependencies. blast warns on large radiuses (≥20 files) as a CROSS_CUTTING signal; surface is a lightweight alternative to full AST walks for Cloudflare Worker projects.

All commands support --format json with nextActions hints for agent workflows.

Build (deprecated — moving to @stackbilt/build)

These four commands reach external Stackbilt endpoints and are being extracted into a separate @stackbilt/build npm package. Governance-only users don't need them. Migration tracked in RFC #112.

stackbilt run "description"              # Architect + scaffold in one step
charter architect "description"          # Generate stack selection
charter scaffold --output ./my-project   # Write files from last build
charter login --key sb_live_xxx          # Store API key (deprecated — prefer STACKBILT_API_KEY env var)

Exit codes

  • 0: success
  • 1: policy violation (CI mode)
  • 2: runtime/usage error

Modular packages

Charter is built as a monorepo. Individual packages are published to npm and usable independently:

Package Purpose
@stackbilt/adf ADF parser, formatter, patcher, bundler, evidence pipeline
@stackbilt/git Trailer parsing, commit risk scoring
@stackbilt/classify Heuristic change classification
@stackbilt/validate Governance validation
@stackbilt/drift Anti-pattern scanning
@stackbilt/blast Reverse dependency graph + blast radius analysis
@stackbilt/surface API surface extraction (routes + D1 schema)
@stackbilt/core Schemas, sanitization, error contracts
@stackbilt/types Shared TypeScript contracts
@stackbilt/ci GitHub Actions integration helpers

Development

pnpm install && pnpm run build && pnpm run test

Full publish workflow: see PUBLISHING.md.

License

Apache-2.0. See LICENSE.

Built by Kurt Overmier / Stackbilt

Buy me a coffee