SurfContext Specification

Overview

SurfContext defines a standard file structure and format for providing project context to AI coding agents. It establishes a canonical source of truth (CONTEXT.md) and a machine-readable manifest (surfcontext.json) that together enable platform-specific config files to be generated from a single source.

The goals of this specification are:

• Single source of truth -- Write project context once, generate platform-specific files automatically
• Universal compatibility -- Work with any AI coding agent that reads project files
• Human-readable first -- All files are plain markdown, readable without special tooling
• Zero lock-in -- No proprietary formats, no required runtimes, no vendor dependency

Terminology

The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in RFC 2119.

File Hierarchy

A conforming SurfContext project MUST include a CONTEXT.md file at the project root. It SHOULD include a surfcontext.json manifest and a .context/ directory.

project-root/
  CONTEXT.md              # Canonical root context (human-authored)
  surfcontext.json        # Machine-readable config & platform targeting
  .context/
    agents/               # Agent definitions (YAML frontmatter + markdown)
      agent-name.md
    docs/                 # Knowledge documents (referenced by agents)
      architecture.md
      api-reference.md
    skills/               # Reusable skill definitions
      deploy.md
    queue.md              # Shared task queue
  CLAUDE.md               # Generated: Claude Code root context
  AGENTS.md               # Generated: Codex CLI root context
  .cursorrules            # Generated: Cursor rules

Root Context (CONTEXT.md)

The root context file is the primary document that AI agents read to understand a project. It MUST be named CONTEXT.md and placed at the project root.

Structure

A CONTEXT.md file SHOULD include the following sections:

# Project Name

Brief description of what this project does.

## Key Files

| Path | Purpose |
|------|---------|
| `src/app/` | Next.js App Router pages |
| `amplify/data/resource.ts` | Amplify data model schema |
| `.context/agents/` | Agent definitions |
| `.context/docs/` | Knowledge documents |

## Architecture

Describe the high-level architecture: frameworks, data flow,
deployment targets, and key design decisions.

```
Frontend (Next.js) --> API (AppSync) --> Database (DynamoDB)
                          |
                    Lambda Functions
```

## Stack & Development

**Stack**: Next.js 15, React 19, AWS Amplify Gen 2, TypeScript
**Package manager**: npm
**Run locally**: `npm run dev`
**Run tests**: `npm test`
**Lint**: `npm run lint`

## Conventions

- Use TypeScript strict mode
- Follow existing patterns in the codebase
- All data models include `tenantId` for multi-tenancy

Requirements

• MUST begin with an H1 heading containing the project name
• MUST include a Key Files table mapping paths to purposes
• SHOULD include an Architecture section with high-level system design
• SHOULD include a Stack & Development section with build/run/test commands
• SHOULD be under 200 lines to stay within typical AI context windows
• MAY include additional sections (Conventions, Working Style, Commands)
• MUST NOT contain secrets, API keys, or credentials

surfcontext.json

The manifest file provides machine-readable configuration for SurfContext tooling. It declares which platforms to target and how to generate platform-specific files.

Schema

{
  "version": "2.0",
  "source": "manual",
  "platforms": ["claude", "codex", "cursor"],
  "canonical": {
    "rootContext": "CONTEXT.md",
    "docsDir": ".context/docs",
    "agentsDir": ".context/agents",
    "skillsDir": ".context/skills"
  },
  "generation": {
    "claude": {
      "rootContext": "CLAUDE.md",
      "method": "sed-copy"
    },
    "codex": {
      "rootContext": "AGENTS.md",
      "method": "template-copy"
    },
    "cursor": {
      "rootContext": ".cursorrules",
      "method": "template-copy"
    }
  }
}

Field Reference

Agent Configurations

Agent definition files live in .context/agents/. Each file defines a specialized agent with specific responsibilities and tool access.

File Format

Agent files use YAML frontmatter followed by markdown content. The filename SHOULD match the name field (e.g., devops-architect.md).

---
name: devops-architect
description: AWS architecture, deployment, CI/CD, cost optimization
tools:
  - Read
  - Write
  - Bash
  - Grep
  - Glob
model: sonnet
---

# DevOps Architect

You are a DevOps specialist focused on AWS infrastructure.

## Responsibilities

- Review and optimize AWS architecture decisions
- Diagnose deployment failures in Amplify Gen 2
- Manage CI/CD pipelines and build configurations
- Monitor costs and recommend optimizations

## Key Context

- Infrastructure runs on AWS Amplify Gen 2
- AppSync GraphQL API with DynamoDB tables
- Lambda functions handle business logic
- Cognito manages authentication

## Rules

- Always check CloudWatch logs before making assumptions
- Prefer managed services over self-hosted solutions
- Document all infrastructure changes

Frontmatter Fields

Knowledge Documents

Knowledge documents live in .context/docs/ and provide deep context that agents can reference. These are plain markdown files covering topics like architecture decisions, API references, coding conventions, or domain knowledge.

• SHOULD use descriptive kebab-case filenames (e.g., api-reference.md)
• SHOULD begin with an H1 heading describing the document topic
• MAY be referenced from CONTEXT.md or agent definitions
• MUST NOT contain secrets or credentials

Skill Definitions

Skills are reusable task definitions that live in .context/skills/. They use the same YAML frontmatter + markdown format as agent definitions. Skills represent repeatable workflows that can be invoked by name.

---
name: deploy
description: Deploy the application to staging or production
disable-model-invocation: false
---

# Deploy

Run the deployment pipeline for the specified environment.

## Steps

1. Run lint checks: `npm run lint`
2. Run tests: `npm test`
3. Build the project: `npm run build`
4. Deploy to target environment

Task Queue

The task queue (.context/queue.md) is an OPTIONAL shared task list for coordinating work between multiple agents or between human and AI collaborators.

# Task Queue

## Pending

- [ ] **[claude]** Review PR #42 for security issues
- [ ] **[codex]** Run integration tests on billing module

## In Progress

- [x] **[claude]** Draft API documentation for v2 endpoints
  - Status: in-progress
  - Started: 2026-02-04

## Done

- [x] **[codex]** Fix TypeScript strict mode errors in shared/
  - Completed: 2026-02-03
  - Result: 14 errors fixed, all types explicit

• Tasks SHOULD include an assignee in brackets (e.g., [claude], [codex])
• Completed tasks SHOULD include a result summary
• Agents SHOULD mark tasks as in-progress before starting

Platform File Generation

SurfContext supports two generation methods for creating platform-specific files:

Naming Conventions

Versioning

The SurfContext specification follows Semantic Versioning. The current version is 2.0.

• Major version changes indicate breaking changes to the file structure or required fields
• Minor version changes add new optional features without breaking existing conforming projects

The version field in surfcontext.json MUST match the major version of the specification the project conforms to.