​
Quickstart

  • Create global instructions
    • Add short, specific files under .charlie/instructions/ — one topic per file.
    • Keep them terse; prefer bullets over paragraphs.
  • Add one high‑value playbook
    • Put a single, narrowly scoped playbook in .charlie/playbooks/ (title ≤ 80 chars, 5–12 steps).
  • (Optional) Scope local instructions near code
    • For package‑specific guidance, use AGENTS.md, CLAUDE.md, or .cursor/rules/*.mdc inside subfolders.
  • Sanity‑check
    • Open a tiny PR that clearly violates an instruction; Charlie should flag it in review.
    • Kick off a small “do X” task; Charlie should auto‑select the relevant playbook.

​
Instructions vs. playbooks

Instructions
  • What: Repo‑specific instructions and conventions that shape Charlie’s behavior and outputs. Think “policies and expectations,” not prose.
  • Where: .charlie/instructions/*.md (global). Charlie also recognizes AGENTS.md, CLAUDE.md, .cursor/rules/*.mdc, and root .cursorrules.
  • When: Charlie follows instructions during planning, coding, and reviews.
  • Use cases: Coding style, development commands, review standards, naming, error‑handling patterns, project constraints, things to avoid, tiny examples.
Playbooks
  • What: Concise, step‑by‑step recipes for recurring tasks (e.g., “Add a new Prisma model,” “Open a high‑quality PR”).
  • Where: .charlie/playbooks/*.md (one playbook per file; the first H1 is the title).
  • When: Charlie loads playbooks when relevant to the task. Playbooks are never used during PR review.
  • Use cases: Repeatable workflows, checklists, small runbooks with exact steps and gotchas.
Why both? Instructions define the rules of the road (normative guidance). Playbooks are actionable how‑tos (procedural guidance) that Charlie loads when relevant.

​
Authoring Instructions

Instructions are always present in Charlie’s context. The entire instruction set is capped by a global token budget, so keep guidance tight and high‑signal.

​
What to include

  • Clear instructions: “Always/Prefer/Never” statements.
  • Concrete standards: file layout, naming, typing patterns; development commands; error handling; logging; dependency conventions; commit/PR norms.
  • Tiny Good/Bad examples (helpful but trimmed first under budget).
  • Glossary entries for repo‑specific terms and domain jargon.
  • Links to resources: URLs for repo paths with extended info (Note: links aren’t followed during PR review).
  • Directory‑scoped guidance where it truly differs (put AGENTS.md / CLAUDE.md / .cursor/rules/*.mdc next to the code).

​
What to exclude

  • Never: secrets, tokens, credentials.
  • Vague language like “should generally,” “consider” without a default. Use Always/Prefer/Never when X.
  • Philosophy, essays, or long rationale — link out to vendor docs instead.
  • Large code blocks, generated outputs, or changelogs.
  • One‑off “project diary” notes that won’t age well.
  • Duplicated guidance across files — keep one canonical instruction per topic.
  • Instructions that require capabilities you haven’t granted (e.g., “post to Slack” without Slack connected).

​
Style & structure

  • Voice: imperative, specific, short sentences, active verbs, concrete defaults.
  • Format: prefer Do/Don’t bullets over paragraphs.
  • Precision: name files, symbols, and scripts exactly; show the minimal command/snippet.
  • Organization: create a .charlie/instructions file for each topic (e.g. glossary, dev commands, TypeScript).

​
Authoring Playbooks

Playbooks load only when relevant to the task, and never during PR review. You can maintain many playbooks and make them highly specific.

​
What to include

  • Action-oriented title: that will be used to determine when a playbook is relevant.
  • Repeatable workflows with exact steps and gotchas (one outcome per file).
  • Concrete content: Overview, prerequisites (caps, env vars, context), numbered steps (1–2 lines each), exact commands.
  • Quality gates: “Verify” checks and minimal “Rollback” notes.
  • References: links or repo paths for background or to compose playbooks.

​
What to exclude

  • Never: Secrets, tokens, credentials.
  • Vague verbs (“handle,” “update”) without concrete actions.
  • Cross‑cutting “kitchen‑sink” playbooks; split into focused outcomes.
  • Duplicating the same content/steps across multiple files — consolidate and cross-reference.
  • Long rationale or essays — link out.
  • Giant code blocks, generated outputs, changelogs.
  • Anything meant for PR reviews (playbooks aren’t available during PR review).

​
Structure & style

  • File location: .charlie/playbooks/*.md (one playbook per file).
  • Title: the first H1 is the title (≤ 80 chars). This is required and must be the first line (no front-matter).
  • Sections (all but steps are optional):
    1. Overview (one sentence: the outcome)
    2. Prerequisites (capabilities, env vars, context)
    3. Steps (numbered; 1–2 lines each; include exact commands)
    4. Verify (what to run/see)
    5. Rollback (how to recover in case of failure)
    6. References (other playbooks, instructions, or URLs)
  • Commands: idempotent, copy‑pasteable; use clear placeholders like <SERVICE_NAME> — not ….
  • Not subtree‑scoped: path doesn’t limit applicability; relevance filtering does.