Getting Started

Add SurfContext to your project in under 5 minutes. No dependencies, no build step, no lock-in.

Fastest way to start

Generate your SurfContext starter kit

Fill in your project details and download a ready-to-use SurfContext package.

Generates CONTEXT.surf, CLAUDE.md, AGENTS.md, surfcontext.json, and .context/ directory

After downloading:
  1. Unzip into your project root
  2. Edit CONTEXT.surf with your full project details, keeping the ## Core section
  3. Open your project in any supported AI coding agent — it discovers your context automatically
Or set up manually
1

Create CONTEXT.surf

Create a CONTEXT.surf file in your project root. This is your canonical project context — the single source of truth that all AI agents will read. SurfDoc (.surf) is the native format; CONTEXT.md remains a supported alias if you declare "format": ".md".

CONTEXT.surf
---
title: "My Project"
type: doc
updated: 2026-08-26
---

# My Project

Brief description of what this project does and why it exists.

## Core

The guaranteed-context head. Sync copies this section verbatim into
CLAUDE.md and AGENTS.md with a hash stamp, so the rules ride the
harness's auto-load path instead of waiting to be discovered.

- Verify remembered facts against the live source before acting on them
- CONTEXT.surf is canonical; never edit a generated file

## Key Files

| Path | Purpose |
|------|---------|
| `src/` | Application source code |
| `tests/` | Test files |
| `.context/agents/` | Agent definitions |
| `.context/docs/` | Knowledge documents |

## Architecture

Describe your system architecture at a high level. Include
frameworks, data flow, and deployment targets.

## Stack & Development

**Stack**: TypeScript, React, Node.js
**Run locally**: `npm run dev`
**Run tests**: `npm test`
**Lint**: `npm run lint`

## Conventions

- List any coding conventions your project follows
- Include naming patterns, file organization rules, etc.
2

Create .context/ directory

Set up the context directory with subdirectories for agents, knowledge docs, and guides.

Terminal
mkdir -p .context/agents .context/docs .context/guides

Add your first agent definition:

.context/agents/code-reviewer.surf
---
name: code-reviewer
description: Reviews code for quality, security, and best practices
tools:
  - Read
  - Grep
  - Glob
model: sonnet
---

# Code Reviewer

You review pull requests and code changes for:

- Security vulnerabilities
- Performance issues
- Code style consistency
- Test coverage gaps

## Rules

- Always explain *why* something is a problem, not just *what*
- Suggest specific fixes, not vague improvements
- Check for proper error handling in all async operations
3

Add surfcontext.json

Create a surfcontext.json manifest to declare your target platforms and generation settings.

surfcontext.json
{
  "version": "5.2",
  "source": "manual",
  "format": ".surf",
  "platforms": ["claude", "codex", "cursor"],
  "canonical": {
    "rootContext": "CONTEXT.surf",
    "docsDir": ".context/docs",
    "agentsDir": ".context/agents",
    "guidesDir": ".context/guides"
  },
  "generation": {
    "claude": {
      "rootContext": "CLAUDE.md",
      "method": "core-distillate"
    },
    "codex": {
      "rootContext": "AGENTS.md",
      "method": "core-distillate"
    }
  },
  "discoveryOrder": [
    "CONTEXT.surf",
    "surfcontext.json",
    ".context/docs/",
    ".context/guides/",
    ".context/agents/",
    "plans/"
  ]
}
4

Generate platform files (optional)

Generate platform-specific config files from your canonical context. The generated root file must carry the ## Core section inline with a hash stamp — a file that merely points at CONTEXT.surf is non-conformant. Use the reference sync (or the SurfContext CLI) rather than a plain copy.

Terminal
# Inject the "## Core" section into every harness root file,
# stamped with its sha256 so drift is detectable.
bash tools/surfcontext-sync.sh

# Verify: the linter is a separate invocation from the generator.
python3 tools/ards-lint.py

# You can also use the SurfContext CLI when available:
# surf sync
5

Open in your AI tool

Open your project in any supported AI coding agent. It will automatically discover and read your project context.

That's it. Your final project structure looks like this:
Final Structure
my-project/
  CONTEXT.surf            # Your canonical context (source of truth)
  surfcontext.json        # Platform targeting + discovery order
  .context/
    agents/
      code-reviewer.surf  # Your agent definition
    docs/                 # Evergreen knowledge docs
    guides/               # Living how-to documents
  CLAUDE.md               # Platform-specific (generated)
  AGENTS.md               # Platform-specific (generated)

Next steps

  • → Read the full specification for detailed requirements and examples
  • → Add knowledge docs to .context/docs/ for architecture decisions, API references, and domain knowledge
  • → Define more agents in .context/agents/ for specialized tasks
  • → Add living guides to .context/guides/ for implementation how-tos with gotcha callouts (what's new in v5.2)
  • → Check out the tools page for automated setup options