Baseline your first scan, fix what is safe, and commit Charter in under 10 minutes.
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):
File
Purpose
AGENTS.md
Agent context and repo instructions
charter.yaml
Policy configuration
.gitignore
Common agent artifact patterns
ARCHITECTURE.md
High-level module layout
.env.example
Environment variable documentation
.claude/settings.json
Claude 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 on an existing repo with findings
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 .chartercharter 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 fix
charter fix --rule AE-CTX-004
Charter’s safe fixers cover exactly four rules:
AE-CTX-001 — Creates AGENTS.md
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.
AE-CTX-004 — Appends .gitignore entries
Adds agent artifact patterns (.charter/, *.charter-session, .claude/local/, .cursor/cache/) to your .gitignore. Review before committing to make sure no existing entries conflict.
AE-CI-002 — Creates the Charter GitHub Actions workflow
Creates .github/workflows/charter.yaml. Check the threshold value and that the SHA pins match what you want before committing.
AE-MCP-001 — Bumps an unpinned MCP package version
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.
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.
