> ## Documentation Index
> Fetch the complete documentation index at: https://tashfiq.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# AE-CTX-001

> Agent context file must exist, be meaningful, and fit budget.

**Rule ID:** AE-CTX-001 · **Severity:** <Badge color="red">Blocker</Badge> · **Category:** Context · **Auto-fixable:** Yes

<Note>
  AE-CTX-001 is a Blocker. While it is active, the final Charter score is held at **≤59** — the repo cannot reach a passing score until a context file exists.
</Note>

## 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, so the agent receives an arbitrary prefix and silently loses the constraints that fell past the cutoff.

## 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

<Tabs>
  <Tab title="Failing">
    ```
    # No AGENTS.md or equivalent exists in the repo root
    ```

    ```markdown AGENTS.md (placeholder) theme={null}
    # My Project

    Add your project details here.
    ```

    ```markdown AGENTS.md (over budget) theme={null}
    # My Project

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

  <Tab title="Passing">
    ```markdown AGENTS.md theme={null}
    # My Project

    Stack: Go 1.26, Bun, Moonrepo
    Verification: moon run :check

    ## Hard constraints
    - No LLM calls in core
    - Never delete user files
    - Off-limits: .env*, secrets/, signing keys

    ## Edit scope
    - Default: Go source, tests, specs, docs
    - Ask before: CI workflows, Moon/mise config
    ```
  </Tab>
</Tabs>

## How to fix

<Steps>
  <Step title="Preview the scaffolded file">
    Run [`charter fix`](/cli/fix) with `--rule AE-CTX-001 --dry-run` to see what Charter will create before writing anything.
  </Step>

  <Step title="Create the context file">
    Run `charter fix --rule AE-CTX-001` to scaffold a minimal `AGENTS.md` at the repo root.
  </Step>

  <Step title="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.
  </Step>

  <Step title="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.
  </Step>
</Steps>

## Score impact

<Note>
  `Blocker` (−20 per finding). This finding engages the Blocker cap — the final [score](/docs/concepts/scoring-and-caps) is held at **≤59** while it is active. Caps are reserved for raw-secret and Blocker findings.
</Note>

## 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.

## Related rules

<CardGroup cols={2}>
  <Card title="AE-CTX-002" icon="file-text" href="/rules/AE-CTX-002">
    Context file must stay consistent with the actual repo state.
  </Card>

  <Card title="AE-CTX-004" icon="box" href="/rules/AE-CTX-004">
    Agent session artifacts must be gitignored.
  </Card>

  <Card title="AE-CTX-006" icon="chart-bar" href="/rules/AE-CTX-006">
    Emphatic directive density degrades adherence.
  </Card>

  <Card title="AE-CC-002" icon="shield-half" href="/rules/AE-CC-002">
    Edit scope must be declared explicitly.
  </Card>
</CardGroup>

## CLI

```bash theme={null}
charter explain AE-CTX-001
```