stax
Normative reference

Runtime File Contracts

Exact file ownership and target mappings for runtimes

Overview

To support runtimes "very correctly," stax must define not just abstract layers but also the exact file contracts expected by each runtime.

This document defines:

  • which files are package-managed
  • which files are local-only or stateful
  • which files MUST NOT be packaged
  • how adapters map canonical layers and surfaces into exact runtime files

Exactness claims in this document SHOULD be interpreted together with adapter runtimeVersionRange declarations and conformance results. A mapping is only truly exact when it has been tested against the relevant runtime version range.

Ownership classes

Every runtime file SHOULD be classified into one of these classes.

ClassMeaningPackage by default?
managed-userDeclarative user-wide config/instructionsSometimes
managed-projectDeclarative project/repo filesYes
managed-workspaceDeclarative workspace filesYes
local-overrideUser-local, non-shared overridesNo
stateRuntime state, caches, transcripts, logsNo
secretCredentials or secret-bearing filesNo

Consumers MUST NOT package state or secret files.

Consumers SHOULD NOT package local-override files unless the user explicitly opts in.

Claude Code

The file-contract details below are based on Claude Code documentation for settings, memory, skills, and MCP.

Claude scopes

ScopeFiles
User~/.claude/CLAUDE.md, ~/.claude/skills/**, ~/.claude/agents/*.md, ~/.claude/settings.json, ~/.claude.json
ProjectCLAUDE.md or .claude/CLAUDE.md, .claude/skills/**, .claude/agents/*.md, .claude/settings.json, .mcp.json
Local override.claude/settings.local.json

Claude ownership classification

PathClassstax support
CLAUDE.md / .claude/CLAUDE.mdmanaged-projectYes
.claude/skills/**managed-projectYes
.mcp.jsonmanaged-projectYes
.claude/settings.jsonmanaged-projectYes
.claude/settings.local.jsonlocal-overrideNo by default
~/.claude/CLAUDE.mdmanaged-userOptional
~/.claude/skills/**managed-userOptional
~/.claude/settings.jsonmanaged-userOptional
~/.claude.jsonmanaged-userOptional, but SHOULD be avoided when project scope is possible
.claude/agents/*.md / ~/.claude/agents/*.mdmanaged-project / managed-userYes via 37 — Subagents and Agent Bundles

Claude exact mapping rules

In exact mode, @stax/claude-code SHOULD materialize:

stax sourceExact target
surfaces/instructions.md or merged prompt outputCLAUDE.md
skills/.claude/skills/
MCP layer.mcp.json
supported adapter config.claude/settings.json

CLAUDE.md composition order

When a consumer must synthesize CLAUDE.md, it SHOULD render sections in this order:

  1. surfaces/instructions.md
  2. prompt
  3. rendered persona summary or surfaces/persona.md
  4. canonical rules translated to Markdown
  5. surfaces/tools.md
  6. surfaces/identity.md
  7. surfaces/user.md
  8. surfaces/heartbeat.md

In exact mode, if CLAUDE.md must be synthesized because no exact source document exists, the consumer MUST warn or fail according to policy.

Claude files that MUST NOT be packaged

  • auth tokens
  • caches
  • session transcripts
  • .claude/settings.local.json unless explicitly requested
  • undocumented internal state files

Codex

The file-contract details below are based on Codex documentation for AGENTS.md, config, MCP, skills, sandboxing, and approvals.

Codex scopes

ScopeFiles
User~/.codex/config.toml, ~/.codex/AGENTS.md or ~/.codex/AGENTS.override.md, $HOME/.agents/skills/**
Project.codex/config.toml, AGENTS.md / AGENTS.override.md discovered from repo root down to cwd, .agents/skills/** discovered from repo root down to cwd
System / admin/etc/codex/config.toml, /etc/codex/skills/**
State~/.codex/auth.json, ~/.codex/history.jsonl, logs, caches

Codex ownership classification

PathClassstax support
~/.codex/config.tomlmanaged-userOptional
.codex/config.tomlmanaged-projectYes
~/.codex/AGENTS.mdmanaged-userOptional
~/.codex/AGENTS.override.mdlocal-overrideNo by default
AGENTS.md in repomanaged-projectYes
AGENTS.override.md in repolocal-override or team-specific override by policyNo by default
.agents/skills/** in repomanaged-projectYes
$HOME/.agents/skills/**managed-userOptional
/etc/codex/skills/**managed-user or admin-managed external policyNo by default for portable packages
~/.codex/auth.jsonsecretNo
~/.codex/history.jsonlstateNo
~/.codex/logs/**, cachesstateNo

Codex exact mapping rules

In exact mode, @stax/codex SHOULD materialize:

stax sourceExact target
surfaces/instructions.md or merged prompt outputAGENTS.md
supported adapter config.codex/config.toml
skills.agents/skills/**
MCP layer[mcp_servers.*] tables in .codex/config.toml

Codex instruction discovery semantics

Codex instruction loading is path-sensitive.

Consumers targeting Codex SHOULD preserve these semantics:

  1. user scope: ~/.codex/AGENTS.override.md wins over ~/.codex/AGENTS.md
  2. project scope: from repo root to cwd, Codex checks each directory for AGENTS.override.md, then AGENTS.md
  3. at most one instruction file per directory is included
  4. files closer to cwd override earlier guidance because they appear later in the combined prompt

stax supports both a canonical instruction surface and a canonical instruction tree. Therefore:

  • a single stax agent MAY target one exact project AGENTS.md
  • artifacts that include 38 — Instruction Trees MAY represent an entire discovered multi-directory AGENTS hierarchy

Codex files that MUST NOT be packaged

  • ~/.codex/auth.json
  • ~/.codex/history.jsonl
  • logs and caches
  • approval history or ephemeral trust state
  • local override files unless explicitly requested

OpenClaw

The file-contract details below are based on OpenClaw workspace and system-prompt documentation.

OpenClaw scopes

ScopeFiles
Workspace<workspace>/AGENTS.md, SOUL.md, TOOLS.md, IDENTITY.md, USER.md, HEARTBEAT.md, BOOTSTRAP.md, skills/**, memory/**, optional MEMORY.md
User~/.openclaw/skills/**, ~/.openclaw/openclaw.json when managed as a runtime profile
Runtime state~/.openclaw/credentials/**, ~/.openclaw/agents/**/sessions/**

OpenClaw ownership classification

PathClassstax support
<workspace>/AGENTS.mdmanaged-workspaceYes
<workspace>/SOUL.mdmanaged-workspaceYes
<workspace>/TOOLS.mdmanaged-workspaceYes
<workspace>/IDENTITY.mdmanaged-workspaceYes
<workspace>/USER.mdmanaged-workspaceYes
<workspace>/HEARTBEAT.mdmanaged-workspaceYes
<workspace>/BOOTSTRAP.mdmanaged-workspaceYes
<workspace>/skills/**managed-workspaceYes
<workspace>/memory/**managed-workspaceYes
~/.openclaw/skills/**managed-userOptional
~/.openclaw/openclaw.jsonmanaged-user in a runtime-profile artifact; otherwise extrinsic runtime configNot in agent artifacts; yes in @stax/openclaw/profile
~/.openclaw/credentials/**secretNo
~/.openclaw/agents/**/sessions/**stateNo

OpenClaw exact mapping rules

In exact mode, @stax/openclaw MUST preserve separate files and MUST NOT collapse them into a single prompt.

stax sourceExact target
surfaces/instructions.md<workspace>/AGENTS.md
surfaces/persona.md<workspace>/SOUL.md
surfaces/tools.md<workspace>/TOOLS.md
surfaces/identity.md<workspace>/IDENTITY.md
surfaces/user.md<workspace>/USER.md
surfaces/heartbeat.md<workspace>/HEARTBEAT.md
surfaces/bootstrap.md<workspace>/BOOTSTRAP.md
skills/<workspace>/skills/
memory/<workspace>/memory/

If a required OpenClaw surface is missing in exact mode, the consumer SHOULD either:

  1. fail, or
  2. write no file and emit a clear warning that OpenClaw will inject a missing-file marker at runtime

OpenClaw files that MUST NOT be packaged in agent artifacts

  • ~/.openclaw/credentials/**
  • session transcripts and logs
  • generated runtime state

~/.openclaw/openclaw.json is intentionally excluded from agent artifacts, but MAY be packaged separately via 21 — Profile: @stax/openclaw/profile.

Cursor

The file-contract details below are based on Cursor IDE documentation for rules, MCP, skills, and hooks.

Cursor scopes

ScopeFiles
Project.cursor/rules/*.mdc, .cursor/mcp.json, .cursor/skills/**, .cursor/hooks.json, AGENTS.md
User~/.cursor/rules/*.mdc, ~/.cursor/mcp.json, ~/.cursor/skills/**, ~/.cursor/hooks.json
Legacy.cursorrules (project root, deprecated)

Cursor ownership classification

PathClassstax support
.cursor/rules/*.mdcmanaged-projectYes
.cursor/mcp.jsonmanaged-projectYes
.cursor/skills/**managed-projectYes
AGENTS.mdmanaged-projectYes
.cursorrulesmanaged-projectYes (legacy)
~/.cursor/rules/*.mdcmanaged-userOptional
~/.cursor/mcp.jsonmanaged-userOptional
~/.cursor/skills/**managed-userOptional
.cursor/hooks.jsonlocal-overrideNo by default
~/Library/Application Support/Cursor/stateNo

Cursor exact mapping rules

In exact mode, @stax/cursor SHOULD materialize:

stax sourceExact target
surfaces/instructions.md or merged prompt outputAGENTS.md
canonical rules.cursor/rules/*.mdc with trigger frontmatter
MCP layer.cursor/mcp.json
skills.cursor/skills/**

Cursor files that MUST NOT be packaged

  • ~/Library/Application Support/Cursor/ (app state, caches, auth)
  • .vscode/settings.json (editor settings)
  • env values containing secrets in .cursor/mcp.json
  • auth tokens, session state, caches

GitHub Copilot

The file-contract details below are based on GitHub Copilot documentation for custom instructions, MCP, skills, and agents.

Copilot scopes

ScopeFiles
Workspace.github/copilot-instructions.md, .github/instructions/*.instructions.md, .github/agents/*.agent.md, .github/skills/**, .github/prompts/*.prompt.md, .vscode/mcp.json, AGENTS.md
User~/.copilot/instructions/*.instructions.md, ~/.copilot/agents/*.agent.md, ~/.copilot/skills/**

Copilot ownership classification

PathClassstax support
.github/copilot-instructions.mdmanaged-projectYes
.github/instructions/*.instructions.mdmanaged-projectYes
.vscode/mcp.jsonmanaged-projectYes
.github/skills/**managed-projectYes
AGENTS.mdmanaged-projectYes
.github/agents/*.agent.mdmanaged-projectOptional
.github/prompts/*.prompt.mdmanaged-projectNo by default
~/.copilot/instructions/*.instructions.mdmanaged-userOptional
~/.copilot/skills/**managed-userOptional
VS Code user settings.jsonlocal-overrideNo

Copilot exact mapping rules

In exact mode, @stax/github-copilot SHOULD materialize:

stax sourceExact target
surfaces/instructions.md or merged prompt output.github/copilot-instructions.md
canonical rules (glob-scoped).github/instructions/<rule-id>.instructions.md with applyTo frontmatter
canonical rules (always)embedded in .github/copilot-instructions.md
MCP layer.vscode/mcp.json with servers root key and explicit type fields
skills.github/skills/**

Copilot files that MUST NOT be packaged

  • VS Code user settings
  • auth tokens or GitHub credentials
  • .github/prompts/*.prompt.md (user-authored, not stax-managed)
  • .github/agents/*.agent.md unless explicitly opted in

Windsurf

The file-contract details below are based on Windsurf (formerly Codeium) documentation for rules, workflows, and MCP.

Windsurf scopes

ScopeFiles
Project.windsurf/rules/*.md, .windsurf/workflows/*.md, AGENTS.md
User~/.codeium/windsurf/memories/global_rules.md, ~/.codeium/windsurf/global_workflows/*.md, ~/.codeium/windsurf/mcp_config.json
Legacy.windsurfrules (project root, deprecated)
System (enterprise)/Library/Application Support/Windsurf/rules/*.md (macOS), /etc/windsurf/rules/*.md (Linux)

Windsurf ownership classification

PathClassstax support
.windsurf/rules/*.mdmanaged-projectYes
.windsurf/workflows/*.mdmanaged-projectYes
AGENTS.mdmanaged-projectYes
.windsurfrulesmanaged-projectYes (legacy)
~/.codeium/windsurf/memories/global_rules.mdmanaged-userOptional
~/.codeium/windsurf/global_workflows/*.mdmanaged-userOptional
~/.codeium/windsurf/mcp_config.jsonmanaged-userOptional (user-scoped only)
~/.codeium/windsurf/memories/ (auto-generated)stateNo
~/Library/Application Support/Windsurf/stateNo

Windsurf exact mapping rules

In exact mode, @stax/windsurf SHOULD materialize:

stax sourceExact target
surfaces/instructions.md or merged prompt outputAGENTS.md
canonical rules.windsurf/rules/*.md with trigger frontmatter
skills (as workflows).windsurf/workflows/*.md

MCP is user-scoped only in Windsurf. The adapter MUST warn that project-level MCP is not supported.

Windsurf files that MUST NOT be packaged

  • ~/.codeium/windsurf/memories/ (auto-generated memories)
  • ~/Library/Application Support/Windsurf/ (app state, caches, auth)
  • ~/.codeium/.codeiumignore (enterprise-specific)
  • auth tokens, credential files, session state

OpenCode

The file-contract details below are based on OpenCode by Anomaly for config, instructions, skills, commands, and MCP.

OpenCode scopes

ScopeFiles
Projectopencode.jsonc, AGENTS.md, .opencode/command/*.md, .opencode/skill/**/SKILL.md, .opencode/agent/*.md, .opencode/plugin/*.ts
User~/.config/opencode/opencode.jsonc, ~/.config/opencode/AGENTS.md, ~/.opencode/command/*.md, ~/.opencode/skill/**/SKILL.md
Enterprise/Library/Application Support/opencode/ (macOS), /etc/opencode/ (Linux), C:\ProgramData\opencode\ (Windows)
State~/.local/state/opencode/, ~/.cache/opencode/, .opencode/plans/

OpenCode ownership classification

PathClassstax support
opencode.jsoncmanaged-projectYes
AGENTS.mdmanaged-projectYes
.opencode/command/*.mdmanaged-projectYes
.opencode/skill/**/SKILL.mdmanaged-projectYes
.opencode/agent/*.mdmanaged-projectOptional
~/.config/opencode/opencode.jsoncmanaged-userOptional
~/.config/opencode/AGENTS.mdmanaged-userOptional
~/.opencode/command/*.mdmanaged-userOptional
~/.opencode/skill/**/SKILL.mdmanaged-userOptional
.opencode/plans/stateNo
.opencode/node_modules/stateNo
.opencode/package.jsonstateNo
~/.local/state/opencode/stateNo
~/.cache/opencode/stateNo
*.local.md fileslocal-overrideNo by default

OpenCode exact mapping rules

In exact mode, @stax/opencode SHOULD materialize:

stax sourceExact target
surfaces/instructions.md or merged prompt outputAGENTS.md
MCP layeropencode.jsonc under mcp (local: command as string array, environment as object)
adapter config (model, agents)opencode.jsonc
skills.opencode/skill/**/SKILL.md
skills (as commands).opencode/command/*.md

OpenCode files that MUST NOT be packaged

  • .opencode/plans/ (runtime-generated plan state)
  • .opencode/node_modules/, .opencode/package.json, .opencode/bun.lock (auto-generated plugin artifacts)
  • ~/.local/state/opencode/ (SQLite databases, runtime state)
  • ~/.local/share/opencode/ (binaries, logs)
  • ~/.cache/opencode/ (cached data)
  • OAuth tokens and auth state
  • API keys in provider config
  • *.local.md files (local instruction overrides)

Exactness requirements

To claim support for a runtime "correctly," an adapter SHOULD:

  1. declare the exact runtime version range it targets
  2. enumerate exact file paths and scopes
  3. define byte-preserving mappings where possible
  4. fail or warn on lossy synthesis in exact mode
  5. ship conformance tests against a real runtime version

Materialization

Consumer contract for translating artifacts to runtime-native files

Workspace Sources

Cacheable source artifacts and agent references

On this page

OverviewOwnership classesClaude CodeClaude scopesClaude ownership classificationClaude exact mapping rulesCLAUDE.md composition orderClaude files that MUST NOT be packagedCodexCodex scopesCodex ownership classificationCodex exact mapping rulesCodex instruction discovery semanticsCodex files that MUST NOT be packagedOpenClawOpenClaw scopesOpenClaw ownership classificationOpenClaw exact mapping rulesOpenClaw files that MUST NOT be packaged in agent artifactsCursorCursor scopesCursor ownership classificationCursor exact mapping rulesCursor files that MUST NOT be packagedGitHub CopilotCopilot scopesCopilot ownership classificationCopilot exact mapping rulesCopilot files that MUST NOT be packagedWindsurfWindsurf scopesWindsurf ownership classificationWindsurf exact mapping rulesWindsurf files that MUST NOT be packagedOpenCodeOpenCode scopesOpenCode ownership classificationOpenCode exact mapping rulesOpenCode files that MUST NOT be packagedExactness requirements