Skip to main content
Use this path when you already have a working repository and want to add Charter without reshaping the repo all at once. The full adoption loop takes under 10 minutes on most repos.
1

Scaffold missing baseline files

Run charter init to create any missing baseline files — without touching what already exists:
charter init --path .
What gets created (only if the file is not already present):
FilePurpose
AGENTS.mdAgent context and repo instructions
charter.yamlPolicy configuration
.gitignoreCommon agent artifact patterns
ARCHITECTURE.mdHigh-level module layout
.env.exampleEnvironment variable documentation
.claude/settings.jsonClaude tool permissions (when Claude is detected)
Want to preview before writing anything?
charter init --path . --dry-run
init is create-missing-only. It will never overwrite an existing AGENTS.md or charter.yaml. Run it freely even on repos that are partially set up.
2

Run the baseline scan

Once the missing baseline files exist, run the first scan:
charter doctor
charter doctor first scan output
The output shows:
  • your current score
  • active findings grouped by rule
  • which findings are blockers (Hard caps: secret findings cap at 49, blocker findings cap at 59)
  • whether the repo already meets the standard gate
Don’t be alarmed by a low first score. Most repos score 40–60 before any fixes. The output tells you exactly what to address — treat the first scan as a triage pass, not a verdict on the repo.
If you want a machine-readable baseline for later comparison:
mkdir -p .charter
charter doctor --format json --out .charter/charter-baseline.json
3

Fix what Charter can fix safely

Review the auto-fix diffs before applying anything:
charter fix --dry-run
Charter’s safe fixers cover exactly four rules:
Generates an AGENTS.md template populated with your detected language, toolchain, and CI platform. Review the template — the generated content is a starting point, not a finished doc.
Adds agent artifact patterns (.charter/, .claude/, common cache paths) to your .gitignore. Review before committing to make sure no existing entries conflict.
Creates .github/workflows/charter.yaml. Check the threshold value and that the SHA pins match what you want before committing.
Updates floating @latest or semver-range MCP server references to an exact pinned version from Charter’s catalog. Verify the resolved version is the one you want.
Always run charter fix --dry-run first. Read each unified diff before applying. The diff is the contract.
Charter backs up any existing file it modifies to .charter/backups/<timestamp>/ before writing.
4

Review remaining findings

For each finding Charter cannot auto-fix, resolve it manually:

AE-SEC-001 / AE-SEC-002

Remove the secret, rotate the credential, and replace it with an environment variable reference. Never suppress a live secret finding.

AE-TEST-001

Add a test suite. Charter looks for evidence of a test runner in your toolchain config and CI — a test file or package.json script is enough to pass.

AE-ENV-001

Add a toolchain file (mise.toml, .tool-versions, or a language-native equivalent) so the repo’s runtime versions are reproducible.

AE-MCP-003

Add an auth header to each remote MCP server entry. Use an env var reference — never a literal credential value.
5

Suppress accepted risks

If a finding is a confirmed false positive or an intentionally accepted exception, record it explicitly:
charter suppress AE-CI-002 \
  --reason "CI integration planned for Q3" \
  --expires 90d
This writes a governed entry to .charter-suppress.yml with the rule ID, your reason, and an expiry date that re-surfaces later.
Suppress only when the repo state is intentionally accepted. If the underlying problem is real, fix it — don’t suppress it. Suppression is an audit trail, not a mute button.
Permanent suppressions require --approver. Without it, AE-SUPPRESS-002 fires as a High finding on every scan.
6

Commit

Stage the files Charter created or modified:
git add AGENTS.md charter.yaml .gitignore
git commit -m "chore: add Charter agent-readiness baseline"
Then open a pull request to add CI. Use the workflow file Charter generated at .github/workflows/charter.yaml, or follow the GitHub Actions guide.
What score to target: 80 is the standard threshold. A first-pass fix run typically moves a blank repo from 40–60 up to 75–90 within 30 minutes. You do not need to reach a perfect score on day one — you need a repo state that is explainable, reviewable, and repeatable.

​
Quick reference loop

charter init --path .
charter doctor
charter fix --dry-run
charter fix
charter doctor