Skip to main content
Rule ID: AE-CTX-001 · Severity: Blocker · Category: Context · Auto-fixable: Yes — charter fix --rule AE-CTX-001

​
Why this rule

Agents operate from what they can read in the repo. A missing or empty context file means the agent starts every session with no orientation — it guesses at the stack, invents build commands, and may edit files it should leave alone. A context file that exceeds the token budget gets truncated, which is often worse than no file at all because the agent receives partial, misleading instructions.

​
What triggers it

Charter looks for any of the following files in the repo root: AGENTS.md, CLAUDE.md, .cursor/rules, .windsurfrules, .github/copilot-instructions.md, opencode.md, codex.md, DESIGN.md, SKILL.md. The finding fires when:
  • No recognized context file exists
  • The file is empty or contains only placeholder text (e.g. “Add your project details here”)
  • The file exceeds the 600-token budget that agent context windows reliably fit

​
Examples

# No AGENTS.md or equivalent exists in the repo root
AGENTS.md (placeholder)
# My Project

Add your project details here.
AGENTS.md (over budget)
# My Project

[... 900+ tokens of exhaustive documentation ...]
# Section 47: Legacy Migration Notes
# Section 48: Deprecated API Compatibility
# Section 49: Historical Architecture Decisions

​
How to fix

1

Preview the scaffolded file

Run charter fix --rule AE-CTX-001 --dry-run to see what Charter will create before writing anything.
2

Create the context file

Run charter fix --rule AE-CTX-001 to scaffold a minimal AGENTS.md at the repo root.
3

Reflect your actual project

Edit the file to include your real stack, verification command, edit boundaries, and any hard constraints. Generic scaffolding still satisfies the rule syntactically but gives agents nothing useful.
4

Stay within budget

Aim for under 400 tokens. The value of a context file degrades when it grows past the 600-token budget — trim ruthlessly and link to longer docs rather than inlining them.

​
Score impact

Blocker severity: −20 to the base score. The hard cap at ≤ 59 applies while this finding is active — the repo cannot reach a passing score until AE-CTX-001 is resolved.

​
Edge cases

A repo using CLAUDE.md, DESIGN.md, or SKILL.md instead of AGENTS.md passes if the file satisfies the same content requirements. Charter accepts any recognized filename — the check is on content and budget, not the specific filename.
  • AE-CTX-002 — context file must stay consistent with the actual repo state
  • AE-CTX-004 — agent session artifacts must be gitignored
  • AE-CTX-006 — emphatic directive density
  • AE-CC-002 — edit scope must be declared

​
CLI

charter explain AE-CTX-001