SurfContext Specification

Overview

The Agent-Ready Documentation Standard (ARDS) defines a file structure and set of conventions that make software repositories fully navigable by AI coding agents across all major platforms. ARDS provides a canonical source of truth (.context/) from which platform-specific files (CLAUDE.md, AGENTS.md, .cursorrules) are generated, solving the fragmentation problem caused by incompatible AI tool formats.

Version 3.0 introduces nine new sections: living guides, session checkpoints, evidence epistemology, formalized discovery order, multi-agent coordination contracts, cross-repository references, IP safety protocols, MCP integration, and context budget management. All v3 additions are backward-compatible.

What ARDS Is

• A file structure specification for AI-navigable repositories
• A set of document type definitions (root context, agents, skills, docs, guides, plans, research)
• A discovery protocol that agents follow to build context
• A generation pipeline from canonical source to platform-specific output

What ARDS Is Not

• Not a replacement for any single platform's format -- it generates them
• Not a runtime protocol (that's MCP)
• Not a build system or package manager
• Not required to use any specific AI tool

Design Principles

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.

Required Structure

project-root/
  CONTEXT.md                          # Root context (required)
  surfcontext.json                    # Configuration (recommended)
  .context/
    agents/                           # Agent definitions (1 file per agent)
      agent-name.md
    docs/                             # Evergreen knowledge docs
      architecture.md
      conventions.md

Full Structure (All Optional Additions)

project-root/
  CONTEXT.md                          # Root context (canonical)
  surfcontext.json                    # ARDS configuration
  CLAUDE.md                           # Generated for Claude Code
  AGENTS.md                           # Generated for Codex CLI
  .context/
    agents/                           # Agent definitions
      agent-name.md
    skills/                           # Reusable expertise (directory per skill)
      skill-name/
        SKILL.md
    docs/                             # Evergreen knowledge docs
      architecture.md
    guides/                           # Living how-to documents
      deploying-to-aws.md
    queue.md                          # Multi-agent task queue
  plans/                              # Time-stamped deliverables
    [category]/
      YYYY-MM-DD-topic.md
    sessions/                         # Session checkpoints
      YYYY-MM-DD-checkpoint.md
  research/                           # Academic manuscripts
    [project-name]/
      manuscript/v[N]/

Naming Conventions

Root Context (CONTEXT.md)

CONTEXT.md is the single most important file in any ARDS-compliant repository. It is auto-loaded by Claude Code every turn (as CLAUDE.md), read first by Codex (as AGENTS.md), and serves as the primary orientation for any AI agent or human contributor.

Structure

# Project Name

Brief description of what this project does.

## Key Files

| Path | Purpose |
|------|---------|
| `src/app/` | Next.js App Router pages |
| `.context/agents/` | Agent definitions |
| `.context/docs/` | Knowledge documents |
| `.context/guides/` | Living how-to guides |

## Architecture

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

## Stack & Development

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

## Active Work

Current state: what's deployed, in progress, blocked, planned.

## Agents

| Agent | Scope |
|-------|-------|
| devops-architect | AWS architecture, deployment, CI/CD |
| code-reviewer | Code quality, security, best practices |

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 include an Active Work section with current state
• SHOULD be under 200 lines (product repos) or 300 lines (command centers)
• MAY include Agents, Commands, and Cross-Repo Dependencies sections
• 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, how to generate platform-specific files, and v3 features like discovery order, IP safety, and MCP integration.

Schema (v3.0)

{
  "version": "3.0",
  "platforms": ["claude", "codex", "cursor"],
  "canonical": {
    "rootContext": "CONTEXT.md",
    "docsDir": ".context/docs",
    "agentsDir": ".context/agents",
    "skillsDir": ".context/skills",
    "guidesDir": ".context/guides",
    "checkpointsDir": "plans/sessions",
    "plansDir": "plans"
  },
  "generation": {
    "claude": {
      "rootContext": "CLAUDE.md",
      "method": "sed-copy"
    },
    "codex": {
      "rootContext": "AGENTS.md",
      "method": "template-copy"
    }
  },
  "discoveryOrder": [
    "CONTEXT.md",
    "surfcontext.json",
    ".context/docs/",
    ".context/guides/",
    ".context/agents/",
    ".context/skills/",
    ".context/queue.md",
    "plans/"
  ],
  "ipSafety": {
    "enabled": true,
    "owner": "Example Corp",
    "noAiCoAuthor": true,
    "noSecrets": true
  },
  "mcp": {
    "serverName": "@surfcontext/mcp-server",
    "tools": [
      "surfcontext_read_context",
      "surfcontext_list_agents",
      "surfcontext_list_docs",
      "surfcontext_list_guides",
      "surfcontext_search"
    ]
  }
}

Field Reference

Agent Configurations

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

File Format

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

## Scope

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

## Context Files

Read before starting work:
- `.context/docs/architecture.md` -- system structure
- `.context/guides/deploying-to-aws.md` -- deployment guide

## Cross-Agent Coordination

| Direction | Agent | What Flows | Format |
|-----------|-------|-----------|--------|
| Receives from | product-strategist | Feature specs | `plans/product/*.md` |
| Sends to | dev-workflow | Deploy status | `plans/dev/*.md` |

Frontmatter Fields

Scoping Rules

• One job per agent -- don't combine frontend + deployment + testing
• 3-5 per product repo -- enough coverage without overlap
• Up to 25 for command centers -- strategy repos coordinate many domains
• Stack-appropriate tools -- don't give every agent every tool

Skill Definitions

Skills define reusable expertise with progressive disclosure. Unlike agents, skills support slash-command invocation, supporting files, and cross-platform portability via the Agent Skills standard.

---
name: patent-draft
description: Draft patent applications following USPTO conventions.
allowed-tools: Read, Write, Edit, Glob, Grep
model: opus
---

# Patent Drafting Skill

[Skill content -- expertise, procedures, templates]

Skills vs Agents

Knowledge Documents

Knowledge documents live in .context/docs/ and store evergreen reference material too detailed for CONTEXT.md but essential for agent work. Read on demand, not every turn.

• MUST include a > Last updated: YYYY-MM-DD date
• SHOULD use descriptive kebab-case filenames
• SHOULD begin with an H1 heading
• MUST NOT contain secrets or credentials
• SHOULD NOT exceed 400 lines

Guides v3

Guides are living how-to documents in .context/guides/ that accumulate battle-tested implementation knowledge over time. They are distinct from every other document type:

# Guide: Deploying to AWS Amplify

> Platform: AWS Amplify Gen 2
> Last updated: 2026-02-10
> Confidence: high

## Table of Contents

- [Initial Setup](#initial-setup)
- [Common Issues](#common-issues)

## Initial Setup

Deploy using `npx ampx pipeline-deploy` with CI=1 flag.

> **Gotcha** (learned 2026-02-08): CDK tokens like
> `cdk.Stack.of().stackName` are unresolved at synth time.
> Use `process.env.AWS_BRANCH` for branch-specific naming.

## Common Issues

Check CloudWatch logs before assuming the issue is in your code.

> **Gotcha** (learned 2026-02-09): `force-dynamic` on root
> layout forces SSR on every request and crashes when client
> providers aren't available server-side.

Key Properties

• Table of contents -- required; guides are long-form, agents need navigation
• Last updated date -- required; signals freshness
• Confidence level -- required; low / medium / high
• Gotcha callouts -- blockquote with **Gotcha** prefix and date
• Living by design -- agents SHOULD update the relevant guide after completing work

Plan Documents

Plan docs in plans/ capture point-in-time analysis, decisions, strategies, and deliverables. Named with YYYY-MM-DD-descriptive-slug.md format, organized by category subdirectory.

Research Documents

Research docs in research/ are academic manuscripts with versioned drafts. Each project has its own directory with manuscript/v[N]/ and analysis/ subdirectories.

• Never overwrite a previous version -- create a new directory
• Analysis docs use YYYY-MM-DD naming
• README.md at project root describes status and venue

Session Checkpoints v3

Session checkpoints are structured handoff documents that preserve work state across context boundaries -- when a conversation ends, an agent is swapped, or a developer switches machines.

# Session Checkpoint: Sprint Review

> Date: 2026-02-10 14:30
> Session: sprint-review
> Status: Checkpoint

## Accomplished

- Deployed billing integration
- Fixed production outage (FeedbackButton outside Providers)

## Remaining

- Wire Stripe webhook for subscription events
- Add usage tracking for metered billing

## Files Modified

| File | Change |
|------|--------|
| `src/app/billing/page.tsx` | Added tier subscription buttons |
| `amplify/backend.ts` | Fixed declaration ordering |

## Next Steps

1. Test subscription flow end-to-end
2. Deploy to production

When to Checkpoint

• Context getting long -- better to checkpoint with margin than lose work
• Switching agents -- when handing work between agent types
• End of session -- before closing a conversation
• Switching machines -- when continuing on a different computer
• Before risky operations -- before large refactors or deployments

Discovery Order v3

Discovery order defines the sequence in which agents should navigate an ARDS-compliant repository. This was implicit in v2; v3 makes it explicit and configurable.

Evidence Epistemology v3

Evidence epistemology defines how agents handle claims, sources, and uncertainty in documents they produce. This prevents strategy built on unverified claims from compounding errors.

Claim Tags

Evidence Hierarchy

Multi-Agent Coordination v3

Multi-agent coordination defines how multiple AI agents share work within and across repositories using the shared task queue at .context/queue.md.

# Agent Task Queue

## Pending

### TASK-001: Review PR for Security Issues

| Field | Value |
|-------|-------|
| Assigned to | **claude** |
| Priority | High |
| Status | **pending** |

**What to do:**
1. Review all changed files for OWASP top 10
2. Check for credential leaks

**Expected result:** Security assessment with pass/fail

---

## In Progress

## Done

Queue Protocol

1. Agent creates task in Pending with clear steps
2. Assigned agent starts -- moves to In Progress
3. On completion -- fills Result, moves to Done
4. Tasks older than 2 weeks -- move to Archive

Agent Contracts

When agents depend on each other's output, the dependency is documented in both agent configs with a Format column specifying the expected file pattern (new in v3).

Cross-Repository References v3

Cross-repo references define how projects link to and read from sibling repositories using a hub-and-spoke model.

• Never duplicate company-wide context in product repos -- reference strategy
• Product repos are self-contained for development; cross-refs are for business context
• Strategy reads product state, not implementation code
• Use the repo registry (.context/docs/repo-registry.md) as the master index

IP Safety v3

IP safety defines pre-write verification checks that protect intellectual property from misattribution, accidental disclosure, and brand contamination.

Configure in surfcontext.json under the ipSafety block. Tools implementing ARDS should read this and enforce rules during file writes and pre-commit checks.

MCP Integration v3

The Model Context Protocol (MCP) provides a standard way for AI agents to access tools and data. ARDS defines how .context/ content can be exposed as MCP tools.

Standard Tool Names

Context Budget Management v3

Context budget management treats the AI agent's context window as a finite computational resource that must be allocated deliberately.

Progressive Disclosure Protocol

1. Load CONTEXT.md -- provides the map
2. Identify needed docs -- from key files table and task requirements
3. Load only relevant docs/guides -- not the entire .context/ directory
4. Checkpoint when long -- save state before context fills
5. Prune completed context -- when a subtask finishes, its context can be released

Token Budget Guidance

Optimization Strategies

• Move rarely-needed content to .context/docs/. If agents read it < 20% of sessions, extract from CONTEXT.md.
• Use tables over prose. A 3-column table conveys the same info at ~1/3 the tokens.
• Link, don't summarize. Path + one-line description, not a summary.
• Prune Active Work. Remove completed items from CONTEXT.md.

Platform Compatibility

ARDS as Superset

ARDS is not competing with AGENTS.md, Agent Skills, or MCP. It is a superset that defines the full documentation architecture and generates files for every other format.

Quality Scoring

Each dimension scores 0-3 (0 = missing, 1 = minimal, 2 = partial, 3 = fully compliant). Total: up to 99 points for a command center with all optional features.

Freshness Monitoring

Migration Guide

All v3 additions are optional. A valid v2 project is already a valid v3 project.

v2.0 to v3.0

1. Update surfcontext.json -- bump version to "3.0", add new fields (guidesDir, checkpointsDir, discoveryOrder, ipSafety, mcp)
2. Create .context/guides/ -- move or create living how-to documents with confidence levels and gotcha callouts
3. Create checkpoint directory -- start writing session checkpoints to plans/sessions/
4. Add claim tags -- tag claims in strategic documents with [verified], [unverified], [assumption], [internal estimate]
5. Add discovery order -- document your project's discovery order in surfcontext.json
6. Configure IP safety -- add ipSafety block to surfcontext.json if relevant
7. Add agent contracts -- include Format column in Cross-Agent Coordination tables

From platform-specific to ARDS

1. Create .context/ with agents/ and docs/
2. Write CONTEXT.md from existing root context
3. Move agent/doc files to .context/
4. Create surfcontext.json
5. Set up generation (symlinks or sync script)
6. Test platform-specific tool still works