{ "schemaVersion": 2, "updatedAt": "2026-10-15", "contracts": [ { "harness": "codex", "resources": [ { "resource": "skills", "resolution": { "status": "established", "value": "all-visible" }, "conflict": { "status": "established", "value": "coexist" }, "evidence": ["codex-skills-docs", "codex-skill-host-roots-source"], "reference": "https://learn.chatgpt.com/docs/build-skills#where-codex-loads-local-skills", "locations": [ { "path": "$CWD/.agents/skills", "scope": "repository", "traversal": "scan current directory, then each parent to $REPO_ROOT", "position": { "kind": "listing", "index": 1, "evidence": ["codex-skills-docs"] }, "recognition": { "status": "established", "value": "supported", "basis": "documented" } }, { "path": "$HOME/.agents/skills", "scope": "user", "role": "preferred", "position": { "kind": "listing", "index": 2, "evidence": ["codex-skills-docs"] }, "recognition": { "status": "established", "value": "supported", "basis": "documented" } }, { "path": "$CODEX_HOME/skills", "scope": "user", "role": "compatibility", "recognition": { "status": "established", "value": "supported", "evidence": ["codex-skill-host-roots-source"], "basis": "source" }, "notes": [ "Defaults to ~/.codex/skills; follows CODEX_HOME when overridden.", "Still scanned for backward compatibility at source revision 1983c48fd186614529e4fad418ac38a1ae00c6b6. Use ~/.agents/skills for new user skills." ], "lifecycle": { "status": "established", "value": "deprecated", "evidence": ["codex-skill-host-roots-source"] }, "review": { "sourceRevision": { "status": "established", "value": "1983c48fd186614529e4fad418ac38a1ae00c6b6", "evidence": ["codex-skill-host-roots-source"] } } }, { "path": "/etc/codex/skills", "scope": "admin", "position": { "kind": "listing", "index": 3, "evidence": ["codex-skills-docs"] }, "recognition": { "status": "established", "value": "supported", "basis": "documented" } }, { "path": "", "scope": "system", "position": { "kind": "listing", "index": 4, "evidence": ["codex-skills-docs"] }, "recognition": { "status": "established", "value": "supported", "basis": "documented" } }, { "path": "/skills", "scope": "plugin", "position": { "kind": "listing", "index": 5, "evidence": ["codex-skills-docs"] }, "recognition": { "status": "established", "value": "supported", "basis": "documented" } } ], "notes": [ "Two skills with the same name are not merged; both may appear.", "Symlinked skill directories are followed.", "Numbered locations reflect the documentation listing; the unnumbered deprecated root is source-confirmed, not a documented precedence position." ], "ordering": { "migratedFrom": "documented-scan-order", "listing": { "status": "established", "value": "documentation-listing", "evidence": ["codex-skills-docs"] }, "discovery": { "status": "unknown" }, "notes": [ "Reclassified 2026-10-14: v1 orderStatus was \"documented-scan-order\". The v1 notes state: \"Numbered locations reflect the documentation listing; the unnumbered deprecated root is source-confirmed, not a documented precedence position.\" Positions are retained as listing only; runtime scan order is not established." ] } }, { "resource": "hooks", "resolution": { "status": "established", "value": "merge-all" }, "conflict": { "status": "established", "value": "all-matching-run" }, "evidence": ["codex-hooks-docs"], "reference": "https://learn.chatgpt.com/docs/hooks#where-codex-looks-for-hooks", "locations": [ { "path": "/requirements.toml", "scope": "managed", "recognition": { "status": "established", "value": "supported", "basis": "documented" } }, { "path": "~/.codex/hooks.json", "scope": "user", "recognition": { "status": "established", "value": "supported", "basis": "documented" } }, { "path": "~/.codex/config.toml#[hooks]", "scope": "user", "recognition": { "status": "established", "value": "supported", "basis": "documented" } }, { "path": "/.codex/hooks.json", "scope": "project", "condition": "project layer is trusted", "recognition": { "status": "established", "value": "supported", "basis": "documented" } }, { "path": "/.codex/config.toml#[hooks]", "scope": "project", "condition": "project layer is trusted", "recognition": { "status": "established", "value": "supported", "basis": "documented" } }, { "path": "/hooks/hooks.json", "scope": "plugin", "condition": "hook definition is trusted", "recognition": { "status": "established", "value": "supported", "basis": "documented" } } ], "notes": [ "All matching sources merge; higher-precedence config layers do not replace lower hook layers.", "Matching command hooks launch concurrently, so list order is not execution order." ], "ordering": { "migratedFrom": "concurrent-no-precedence", "execution": { "status": "established", "value": "matching-hooks-run-concurrently" } } }, { "resource": "instructions", "resolution": { "status": "established", "value": "path-applicable" }, "conflict": { "status": "established", "value": "more-specific-wins" }, "evidence": ["codex-agents-md-docs"], "reference": "https://learn.chatgpt.com/docs/agent-configuration/agents-md#how-codex-discovers-guidance", "locations": [ { "path": "/{AGENTS.override.md,AGENTS.md}", "scope": "user", "condition": "first non-empty file wins", "position": { "kind": "loading", "index": 1 }, "recognition": { "status": "established", "value": "supported", "basis": "documented" } }, { "path": "/{AGENTS.override.md,AGENTS.md,}", "scope": "project-and-directory", "condition": "at most one non-empty file per directory; override then base then fallback", "position": { "kind": "loading", "index": 2 }, "recognition": { "status": "established", "value": "supported", "basis": "documented" } } ], "notes": [ "Instruction discovery follows the working path and stops at the current directory; it is distinct from skill discovery.", "Files compose root-to-current-directory until the configured combined-byte limit is reached." ], "ordering": { "migratedFrom": "broad-to-specific", "loading": { "status": "established", "value": "broad-to-specific" } } }, { "resource": "subagents", "resolution": { "status": "established", "value": "name-precedence" }, "conflict": { "status": "established", "value": "custom-name-overrides-built-in" }, "evidence": ["codex-subagents-docs"], "reference": "https://learn.chatgpt.com/docs/agent-configuration/subagents#custom-agents", "locations": [ { "path": ".codex/agents", "scope": "project", "position": { "kind": "precedence", "index": 1 }, "recognition": { "status": "established", "value": "supported", "basis": "documented" } }, { "path": "~/.codex/agents", "scope": "user", "position": { "kind": "precedence", "index": 2 }, "recognition": { "status": "established", "value": "supported", "basis": "documented" } }, { "path": "", "scope": "system", "position": { "kind": "precedence", "index": 3 }, "recognition": { "status": "established", "value": "supported", "basis": "documented" } } ], "notes": [ "A custom agent with the same name as a built-in agent takes precedence.", "Each custom agent is a standalone TOML configuration layer." ], "ordering": { "migratedFrom": "project-before-user-before-built-in", "precedence": { "status": "established", "value": "project-before-user-before-built-in" } } }, { "resource": "plugins", "resolution": { "status": "established", "value": "enabled-set" }, "conflict": { "status": "established", "value": "namespaced-components" }, "evidence": ["codex-plugins-docs"], "reference": "https://developers.openai.com/codex/plugins#install-and-use-a-plugin", "locations": [ { "path": "", "scope": "user", "recognition": { "status": "established", "value": "supported", "basis": "documented" } }, { "path": "", "scope": "team", "recognition": { "status": "established", "value": "supported", "basis": "documented" } }, { "path": "", "scope": "session", "recognition": { "status": "established", "value": "supported", "basis": "documented" } } ], "notes": [ "The public contract is installation/enabling, not a stable cache path. Do not treat an implementation cache as an authoring root." ], "ordering": { "migratedFrom": "unspecified", "overall": { "status": "unknown" } } } ], "distribution": "Codex CLI" }, { "harness": "claude-code", "resources": [ { "resource": "instructions", "resolution": { "status": "established", "value": "merge-applicable" }, "conflict": { "status": "established", "value": "context-guidance-not-enforced-policy" }, "evidence": ["claude-memory-docs"], "reference": "https://code.claude.com/docs/en/memory#how-claude-md-files-load", "locations": [ { "path": "/CLAUDE.md", "scope": "managed", "condition": "platform-specific managed path", "recognition": { "status": "established", "value": "supported", "basis": "documented" }, "position": { "kind": "loading", "index": 1, "evidence": ["claude-memory-docs"] } }, { "path": "~/.claude/CLAUDE.md", "scope": "user", "condition": "unless excluded by instructionFiles mode", "recognition": { "status": "established", "value": "supported", "basis": "documented" }, "position": { "kind": "loading", "index": 2, "evidence": ["claude-memory-docs"] } }, { "path": "~/.claude/rules/**/*.md", "scope": "user", "condition": "unscoped rules load at launch; rules with paths frontmatter load when Claude works with a matching file", "recognition": { "status": "established", "value": "supported", "basis": "documented" }, "position": { "kind": "loading", "index": 3, "evidence": ["claude-memory-docs"] } }, { "path": "/{CLAUDE.md,.claude/CLAUDE.md,CLAUDE.local.md}", "scope": "project", "condition": "applicable instructionFiles mode", "recognition": { "status": "established", "value": "supported", "basis": "documented" }, "position": { "kind": "loading", "index": 4, "evidence": ["claude-memory-docs"] } }, { "path": "/{AGENTS.md,.claude/AGENTS.md}", "scope": "project", "condition": "Claude Code 2.1.277+; enabled built-in agents-md; fallback or combined mode", "recognition": { "status": "established", "value": "supported", "basis": "documented" }, "position": { "kind": "loading", "index": 5, "evidence": ["claude-memory-docs"] } }, { "path": "/.claude/rules/**/*.md", "scope": "project", "condition": "unscoped rules load at launch; rules with paths frontmatter load when Claude works with a matching file; skipped when project is excluded from --setting-sources", "recognition": { "status": "established", "value": "supported", "basis": "documented" }, "position": { "kind": "loading", "index": 6, "evidence": ["claude-memory-docs"] } }, { "path": "/{CLAUDE.md,CLAUDE.local.md,AGENTS.md}", "scope": "directory", "condition": "loaded on demand; AGENTS.md requires applicable mode and local fallback check", "recognition": { "status": "established", "value": "supported", "basis": "documented" } } ], "notes": [ "See the Claude instruction contract for structured modes, exclusions, and version caveats." ], "ordering": { "migratedFrom": "documented-precedence-layers", "loading": { "status": "established", "value": "managed-then-user-then-project-root-to-working-directory", "evidence": ["claude-memory-docs"], "notes": [ "Within each directory CLAUDE.local.md follows CLAUDE.md; in combined mode a directory's AGENTS.md follows its CLAUDE.md files.", "User rules load before project rules.", "Files are concatenated, not overridden; later text is read last, and the model may follow either side of a conflict." ] }, "notes": [ "Reclassified 2026-10-15 from the documented load order at code.claude.com/docs/en/memory#how-claude-md-files-load." ] } }, { "resource": "mcp-server-configuration", "resolution": { "status": "established", "value": "scope-precedence" }, "conflict": { "status": "established", "value": "higher-scope-precedence-wins" }, "evidence": ["claude-mcp-docs", "claude-settings-mcp-live-observation"], "reference": "https://code.claude.com/docs/en/mcp#mcp-installation-scopes", "locations": [ { "path": "~/.claude.json#mcpServers", "scope": "user", "recognition": { "status": "established", "value": "supported", "basis": "documented" } }, { "path": "~/.claude.json#projects..mcpServers", "scope": "local", "recognition": { "status": "established", "value": "supported", "basis": "documented" } }, { "path": ".mcp.json#mcpServers", "scope": "project", "recognition": { "status": "established", "value": "supported", "basis": "documented" } }, { "path": "~/.claude/settings.json#mcpServers", "scope": "user", "recognition": { "status": "established", "value": "unsupported", "evidence": [ "anthropic-claude-code-24477", "claude-settings-mcp-live-observation", "claude-settings-mcp-2.1.284-live-observation" ], "basis": "observed" }, "observations": [ { "version": "2.1.34", "result": "ignored", "evidence": ["anthropic-claude-code-24477"] }, { "version": "2.1.251", "result": "ignored", "evidence": ["claude-settings-mcp-live-observation"] }, { "version": "2.1.284", "result": "ignored", "evidence": ["claude-settings-mcp-2.1.284-live-observation"] } ], "notes": [ "No evidence establishes that this location was supported previously.", "The version at which this behavior began is unknown." ] } ], "ordering": { "migratedFrom": "documented-precedence-layers", "overall": { "status": "unknown" }, "notes": [ "V1 records scope precedence but no scope sequence. Its collision rule is retained separately; no exact ordering is inferred." ] } }, { "resource": "skills", "resolution": { "status": "established", "value": "all-visible" }, "conflict": { "status": "established", "value": "namespaced-when-plugin; otherwise documented separately" }, "evidence": ["claude-skills-docs", "claude-agents-skills-2.1.300-observation"], "reference": "https://code.claude.com/docs/en/skills#where-skills-live", "locations": [ { "path": ".claude/skills", "scope": "project", "traversal": "recursive discovery", "recognition": { "status": "established", "value": "supported", "basis": "documented" } }, { "path": "~/.claude/skills", "scope": "user", "recognition": { "status": "established", "value": "supported", "basis": "documented" } }, { "path": "", "scope": "managed", "recognition": { "status": "established", "value": "supported", "basis": "documented" } }, { "path": "/skills", "scope": "plugin", "recognition": { "status": "established", "value": "supported", "basis": "documented" } }, { "path": ".agents/skills", "scope": "project", "recognition": { "status": "established", "value": "unsupported", "basis": "observed", "evidence": ["claude-agents-skills-2.1.300-observation"] }, "observations": [ { "version": "2.1.300", "result": "ignored", "evidence": ["claude-agents-skills-2.1.300-observation"] } ] }, { "path": "~/.agents/skills", "scope": "user", "recognition": { "status": "established", "value": "unsupported", "basis": "observed", "evidence": ["claude-agents-skills-2.1.300-observation"] }, "observations": [ { "version": "2.1.300", "result": "ignored", "evidence": ["claude-agents-skills-2.1.300-observation"] } ] } ], "notes": [ "Claude Code 2.1.300 did not automatically discover project .agents/skills or user ~/.agents/skills in the 2026-10-15 isolated startup-inventory probe. Both .claude/skills controls were discovered; moving the identical .agents fixtures into .claude/skills made them appear. Invocation was not tested because the isolated home had no login.", "The documentation does not promise that this display order is duplicate-name precedence." ], "ordering": { "migratedFrom": "unspecified", "overall": { "status": "unknown" } } }, { "resource": "hooks", "resolution": { "status": "established", "value": "merge-all" }, "conflict": { "status": "established", "value": "decision-precedence-is-event-specific" }, "evidence": ["claude-hooks-docs"], "reference": "https://code.claude.com/docs/en/hooks#hook-locations", "locations": [ { "path": "", "scope": "managed", "recognition": { "status": "established", "value": "supported", "basis": "documented" } }, { "path": "~/.claude/settings.json#hooks", "scope": "user", "recognition": { "status": "established", "value": "supported", "basis": "documented" } }, { "path": ".claude/settings.json#hooks", "scope": "project", "recognition": { "status": "established", "value": "supported", "basis": "documented" } }, { "path": ".claude/settings.local.json#hooks", "scope": "project-local", "recognition": { "status": "established", "value": "supported", "basis": "documented" } }, { "path": "/hooks/hooks.json", "scope": "plugin", "recognition": { "status": "established", "value": "supported", "basis": "documented" } }, { "path": "/SKILL.md#hooks", "scope": "session", "recognition": { "status": "established", "value": "supported", "basis": "documented" } }, { "path": "#hooks", "scope": "subagent", "recognition": { "status": "established", "value": "supported", "basis": "documented" } } ], "notes": [ "Hook entries merge across settings levels rather than replacing each other.", "Matching handlers may run in parallel; event decision precedence is separate from source order.", "allowManagedHooksOnly can exclude user, project, local, and most plugin hooks." ], "ordering": { "migratedFrom": "parallel-within-match", "execution": { "status": "established", "value": "matching-handlers-may-run-in-parallel" } } }, { "resource": "plugins", "resolution": { "status": "established", "value": "enabled-set" }, "conflict": { "status": "established", "value": "plugin-components-namespaced" }, "evidence": ["claude-plugins-docs", "claude-plugin-loading-current-docs"], "reference": "https://code.claude.com/docs/en/plugins/loading#find-plugins-on-disk", "locations": [ { "path": "~/.claude/plugins", "scope": "user", "role": "installed-plugin-state", "recognition": { "status": "established", "value": "supported", "basis": "documented" } }, { "path": "", "scope": "user-or-managed", "recognition": { "status": "established", "value": "supported", "basis": "documented" } }, { "path": "", "scope": "session", "role": "development", "recognition": { "status": "established", "value": "supported", "basis": "documented" } } ], "notes": [ "Installed plugins may be copied into a cache; plugin code must resolve assets through ${CLAUDE_PLUGIN_ROOT}, not its authoring path." ], "ordering": { "migratedFrom": "unspecified", "overall": { "status": "unknown" } } } ], "distribution": "Claude Code" }, { "harness": "cursor-agent", "resources": [ { "resource": "skills", "resolution": { "status": "established", "value": "all-visible" }, "conflict": { "status": "unknown", "migratedFrom": "unspecified" }, "evidence": ["cursor-skills-docs"], "reference": "https://cursor.com/docs/skills#skill-directories", "locations": [ { "path": ".agents/skills", "scope": "project", "role": "portable", "recognition": { "status": "established", "value": "supported", "basis": "documented" } }, { "path": ".cursor/skills", "scope": "project", "role": "native", "recognition": { "status": "established", "value": "supported", "basis": "documented" } }, { "path": ".claude/skills", "scope": "project", "role": "compatibility", "recognition": { "status": "established", "value": "supported", "basis": "documented" } }, { "path": ".codex/skills", "scope": "project", "role": "compatibility", "recognition": { "status": "established", "value": "supported", "basis": "documented" } }, { "path": "~/.agents/skills", "scope": "user", "role": "portable", "recognition": { "status": "established", "value": "supported", "basis": "documented" } }, { "path": "~/.cursor/skills", "scope": "user", "role": "native", "recognition": { "status": "established", "value": "supported", "basis": "documented" } }, { "path": "~/.claude/skills", "scope": "user", "role": "compatibility", "recognition": { "status": "established", "value": "supported", "basis": "documented" } }, { "path": "~/.codex/skills", "scope": "user", "role": "compatibility", "recognition": { "status": "established", "value": "supported", "basis": "documented" } }, { "path": "/skills", "scope": "plugin", "recognition": { "status": "established", "value": "supported", "basis": "documented" } } ], "notes": [ "Discovery is recursive.", "User roots do not transfer to cloud agents or remote workers.", "The documentation lists roots but does not establish duplicate-name precedence." ], "ordering": { "migratedFrom": "unspecified", "overall": { "status": "unknown" } } }, { "resource": "hooks", "resolution": { "status": "established", "value": "merge-all" }, "conflict": { "status": "established", "value": "all-applicable-sources" }, "evidence": ["cursor-hooks-docs"], "reference": "https://cursor.com/docs/hooks#configuration-sources", "locations": [ { "path": "", "scope": "enterprise", "recognition": { "status": "established", "value": "supported", "basis": "documented" } }, { "path": "", "scope": "team", "recognition": { "status": "established", "value": "supported", "basis": "documented" } }, { "path": "/hooks", "scope": "plugin", "recognition": { "status": "established", "value": "supported", "basis": "documented" } }, { "path": "/.cursor/hooks.json", "scope": "project", "recognition": { "status": "established", "value": "supported", "basis": "documented" } }, { "path": "~/.cursor/hooks.json", "scope": "user", "condition": "local agents only", "recognition": { "status": "established", "value": "supported", "basis": "documented" } } ], "notes": [ "The source list is not a guaranteed handler execution order.", "Cloud agents omit user hooks and several event types; command hooks only.", "Working directory differs by source scope." ], "ordering": { "migratedFrom": "unspecified", "overall": { "status": "unknown" } } }, { "resource": "instructions", "resolution": { "status": "established", "value": "merge-applicable" }, "conflict": { "status": "established", "value": "earlier-layer-wins" }, "evidence": ["cursor-rules-docs"], "reference": "https://cursor.com/docs/rules#how-rules-work", "locations": [ { "path": "", "scope": "team", "position": { "kind": "precedence", "index": 1 }, "recognition": { "status": "established", "value": "supported", "basis": "documented" } }, { "path": ".cursor/rules/**/*.mdc", "scope": "project", "position": { "kind": "precedence", "index": 2 }, "recognition": { "status": "established", "value": "supported", "basis": "documented" } }, { "path": "/AGENTS.md", "scope": "project", "notes": [ "AGENTS.md is documented as a project instruction source; its placement in the project precedence layer is an inference." ], "position": { "kind": "precedence", "index": 2 }, "recognition": { "status": "established", "value": "supported", "basis": "documented" } }, { "path": "", "scope": "user", "position": { "kind": "precedence", "index": 3 }, "recognition": { "status": "established", "value": "supported", "basis": "documented" } } ], "notes": ["Project rules may activate always, by glob, by relevance, or manually."], "ordering": { "migratedFrom": "documented-precedence-layers", "precedence": { "status": "established", "value": "team-before-project-before-user", "direction": "high-to-low", "allowsTies": true } } }, { "resource": "subagents", "resolution": { "status": "established", "value": "name-precedence" }, "conflict": { "status": "established", "value": "first-precedence-wins" }, "evidence": ["cursor-subagents-docs"], "reference": "https://cursor.com/docs/subagents#file-locations", "locations": [ { "path": ".cursor/agents", "scope": "project", "position": { "kind": "precedence", "index": 1 }, "recognition": { "status": "established", "value": "supported", "basis": "documented" } }, { "path": ".claude/agents", "scope": "project", "role": "compatibility", "position": { "kind": "precedence", "index": 2 }, "recognition": { "status": "established", "value": "supported", "basis": "documented" } }, { "path": ".codex/agents", "scope": "project", "role": "compatibility", "position": { "kind": "precedence", "index": 3 }, "recognition": { "status": "established", "value": "supported", "basis": "documented" } }, { "path": "~/.cursor/agents", "scope": "user", "position": { "kind": "precedence", "index": 4 }, "recognition": { "status": "established", "value": "supported", "basis": "documented" } }, { "path": "~/.claude/agents", "scope": "user", "role": "compatibility", "position": { "kind": "precedence", "index": 5 }, "recognition": { "status": "established", "value": "supported", "basis": "documented" } }, { "path": "~/.codex/agents", "scope": "user", "role": "compatibility", "position": { "kind": "precedence", "index": 6 }, "recognition": { "status": "established", "value": "supported", "basis": "documented" } } ], "notes": [ "Project definitions take precedence over user definitions; native Cursor roots take precedence over compatibility roots for duplicate names." ], "ordering": { "migratedFrom": "native-before-compatibility", "precedence": { "status": "established", "value": "project-before-user-native-before-compatibility", "direction": "high-to-low" } } }, { "resource": "plugins", "resolution": { "status": "established", "value": "enabled-set" }, "conflict": { "status": "unknown", "migratedFrom": "unspecified" }, "evidence": ["cursor-plugins-docs"], "reference": "https://cursor.com/docs/plugins#test-plugins-locally", "locations": [ { "path": "~/.cursor/plugins/local", "scope": "user", "role": "local-development", "recognition": { "status": "established", "value": "supported", "basis": "documented" } }, { "path": "", "scope": "user-or-team", "recognition": { "status": "established", "value": "supported", "basis": "documented" } }, { "path": "", "scope": "session", "role": "local-development", "recognition": { "status": "established", "value": "supported", "basis": "documented" } } ], "notes": [ "Plugin-relative paths use ${PLUGIN_ROOT}; do not persist author-machine absolute paths." ], "ordering": { "migratedFrom": "unspecified", "overall": { "status": "unknown" } } } ], "distribution": "Cursor Agent CLI" }, { "harness": "opencode", "variant": "v1-stable", "default": false, "resources": [ { "resource": "skills", "resolution": { "status": "established", "value": "all-visible" }, "conflict": { "status": "unknown", "migratedFrom": "variant-dependent", "notes": [ "Depends on version: see 1.18.18-native-probe (last assignment wins) and 2.0.20-native-probe (later source wins by ID)." ] }, "evidence": ["opencode-skills-docs"], "reference": "https://opencode.ai/docs/skills/#place-files", "locations": [ { "path": ".opencode/skills", "scope": "project", "traversal": "walk ancestors to git worktree", "recognition": { "status": "established", "value": "supported", "basis": "documented" } }, { "path": ".claude/skills", "scope": "project", "role": "compatibility", "traversal": "walk ancestors to git worktree", "recognition": { "status": "established", "value": "supported", "basis": "documented" } }, { "path": ".agents/skills", "scope": "project", "role": "portable", "traversal": "walk ancestors to git worktree", "recognition": { "status": "established", "value": "supported", "basis": "documented" } }, { "path": "~/.config/opencode/skills", "scope": "user", "recognition": { "status": "established", "value": "supported", "basis": "documented" } }, { "path": "~/.claude/skills", "scope": "user", "role": "compatibility", "recognition": { "status": "established", "value": "supported", "basis": "documented" } }, { "path": "~/.agents/skills", "scope": "user", "role": "portable", "recognition": { "status": "established", "value": "supported", "basis": "documented" } } ], "notes": [ "V1 stable and V2 discovery/validation/precedence differ; consumers must select a versioned contract.", "The previous numbered search sequence was not duplicate-name precedence. Documentation enumerates roots and asks for unique names; it does not promise a winning root.", "This historical v1-stable contract is not a version-wide runtime claim. See 1.18.18-native-probe for release-specific duplicate resolution." ], "ordering": { "migratedFrom": "documented-roots-no-precedence-guarantee", "precedence": { "status": "unknown" } } }, { "resource": "hooks", "resolution": { "status": "established", "value": "plugin-load-order" }, "conflict": { "status": "established", "value": "middleware/event-specific" }, "evidence": ["opencode-plugins-docs", "opencode-plugin-tests"], "reference": "https://opencode.ai/docs/plugins/#events", "locations": [ { "path": "~/.config/opencode/plugins", "scope": "user", "recognition": { "status": "established", "value": "supported", "basis": "documented" } }, { "path": ".opencode/plugins", "scope": "project", "recognition": { "status": "established", "value": "supported", "basis": "documented" } }, { "path": "opencode.json#plugin", "scope": "configured-npm", "recognition": { "status": "established", "value": "supported", "basis": "documented" } } ], "notes": [ "OpenCode hooks are in-process plugin handlers, not separate hook files.", "Handler mutation/block behavior is event-specific." ], "ordering": { "migratedFrom": "derived-from-plugin-order", "execution": { "status": "established", "value": "plugin-handlers-follow-plugin-load-order" }, "notes": [ "V1 recorded positions 1 (global) and 2 (project); no documented ordering is established for those numbers. The execution-follows-plugin-order claim is retained separately." ] } }, { "resource": "plugins", "resolution": { "status": "established", "value": "load-all" }, "conflict": { "status": "established", "value": "event-specific" }, "evidence": ["opencode-plugins-docs"], "reference": "https://opencode.ai/docs/plugins/#load-order", "locations": [ { "path": "", "scope": "user", "position": { "kind": "loading", "index": 1 }, "recognition": { "status": "established", "value": "supported", "basis": "documented" } }, { "path": "", "scope": "project", "position": { "kind": "loading", "index": 2 }, "recognition": { "status": "established", "value": "supported", "basis": "documented" } }, { "path": "~/.config/opencode/plugins", "scope": "user", "position": { "kind": "loading", "index": 3 }, "recognition": { "status": "established", "value": "supported", "basis": "documented" } }, { "path": ".opencode/plugins", "scope": "project", "position": { "kind": "loading", "index": 4 }, "recognition": { "status": "established", "value": "supported", "basis": "documented" } } ], "ordering": { "migratedFrom": "documented", "loading": { "status": "established", "value": "global-config-before-project-config-before-user-directory-before-project-directory" } } } ], "distribution": "opencode-ai (1.x)" }, { "harness": "opencode", "variant": "1.18.18-native-probe", "default": false, "resources": [ { "resource": "skills", "resolution": { "status": "established", "value": "one-per-name" }, "conflict": { "status": "established", "value": "last-assignment-wins" }, "evidence": [ "opencode-skills-docs", "opencode-skill-selection-1.18.18-source", "opencode-skill-selection-dev-source", "opencode-skill-roots-1.18.18-probe" ], "reference": "https://github.com/anomalyco/opencode/blob/31406ccc51b4bd2a4e1e086b2bcaa5f7f804f26d/packages/opencode/src/skill/index.ts#L103-L140", "locations": [ { "path": ".opencode/skills", "scope": "project", "traversal": "walk ancestors to git worktree", "recognition": { "status": "established", "value": "supported", "basis": "observed" } }, { "path": ".claude/skills", "scope": "project", "role": "compatibility", "traversal": "walk ancestors to git worktree", "recognition": { "status": "established", "value": "supported", "basis": "observed" } }, { "path": ".agents/skills", "scope": "project", "role": "portable", "traversal": "walk ancestors to git worktree", "recognition": { "status": "established", "value": "supported", "basis": "observed" } }, { "path": "~/.config/opencode/skills", "scope": "user", "recognition": { "status": "established", "value": "supported", "basis": "observed" }, "notes": [ "Default XDG_CONFIG_HOME; actual native root is $XDG_CONFIG_HOME/opencode/skills." ] }, { "path": "~/.claude/skills", "scope": "user", "role": "compatibility", "recognition": { "status": "established", "value": "supported", "basis": "observed" } }, { "path": "~/.agents/skills", "scope": "user", "role": "portable", "recognition": { "status": "established", "value": "supported", "basis": "observed" } } ], "notes": [ "Installed 1.18.18 and tag source are separate evidence; binary-to-source reproducibility was not established.", "Warns with existing and duplicate paths, then overwrites state.skills[name]; all() returns the surviving entries.", "Discovered matches load with unbounded concurrency. Repeated isolated runs selected different paths with unchanged identical and divergent fixtures. No preferred root is established.", "Debug discovery is not agent advertisement or invocation. Permissions filter availability separately.", "Cross-harness visibility follows readable roots, not installer enablement intent. Removing one projection does not establish absence if another readable copy remains.", "Built-in customize-opencode is seeded before disk loads so a disk copy can override it. This does not establish precedence among disk roots." ], "ordering": { "migratedFrom": "concurrent-load-no-root-precedence", "loading": { "status": "established", "value": "concurrent-load" }, "precedence": { "status": "unknown" } } } ], "distribution": "opencode-ai (1.x)", "review": { "version": { "status": "established", "value": "1.18.18", "evidence": ["opencode-skill-roots-1.18.18-probe"] }, "sourceRevision": { "status": "established", "value": "31406ccc51b4bd2a4e1e086b2bcaa5f7f804f26d", "evidence": ["opencode-skill-selection-1.18.18-source"] } } }, { "harness": "opencode", "variant": "2.0.20-native-probe", "default": false, "resources": [ { "resource": "skills", "resolution": { "status": "established", "value": "one-per-id" }, "conflict": { "status": "established", "value": "later-source-wins-by-id" }, "evidence": [ "opencode-v2.0.20-skill-precedence-docs", "opencode-v2.0.20-skill-config-source", "opencode-v2.0.20-skill-compatibility-source", "opencode-v2.0.20-skill-identity-source", "opencode-v2.0.20-config-discovery-source", "opencode-v2.0.20-skill-list-source", "opencode-v2.0.20-skill-roots-probe" ], "reference": "https://github.com/anomalyco/opencode/blob/84c9be93a56304a108f1a22df0c5d62c26d5b6ca/services/www/src/docs/content/skills.mdx?plain=1#L161-L179", "locations": [ { "path": "", "scope": "system", "role": "built-in", "position": { "kind": "precedence", "index": 1 }, "recognition": { "status": "established", "value": "supported", "basis": "source" } }, { "path": "~/.claude/skills", "scope": "user", "role": "compatibility", "recognition": { "status": "established", "value": "supported", "basis": "source" }, "position": { "kind": "precedence", "index": 2 } }, { "path": ".claude/skills", "scope": "project", "role": "compatibility", "recognition": { "status": "established", "value": "supported", "basis": "source" }, "traversal": "ancestors from farthest to nearest; native probe also found a skill above the git root", "position": { "kind": "precedence", "index": 3 } }, { "path": "~/.agents/skills", "scope": "user", "role": "portable", "recognition": { "status": "established", "value": "supported", "basis": "source" }, "position": { "kind": "precedence", "index": 4 } }, { "path": ".agents/skills", "scope": "project", "role": "portable", "recognition": { "status": "established", "value": "supported", "basis": "source" }, "traversal": "ancestors from farthest to nearest; native probe also found a skill above the git root", "position": { "kind": "precedence", "index": 5 } }, { "path": "~/.config/opencode/skills", "scope": "user", "recognition": { "status": "established", "value": "supported", "basis": "source" }, "notes": [ "Default XDG_CONFIG_HOME; actual native root is $XDG_CONFIG_HOME/opencode/skills." ], "position": { "kind": "precedence", "index": 6 } }, { "path": ".opencode/skills", "scope": "project", "recognition": { "status": "established", "value": "supported", "basis": "source" }, "traversal": "config ancestors from farthest to nearest; pinned source walks to filesystem root", "position": { "kind": "precedence", "index": 7 } }, { "path": "#skills[]", "scope": "configured", "recognition": { "status": "established", "value": "supported", "basis": "source" }, "traversal": "explicit directories or HTTP catalogs, in config entry and array order", "notes": [ "Local explicit sources were probed in both array orders; HTTP catalogs were source-inspected only." ], "position": { "kind": "precedence", "index": 8 } } ], "notes": [ "Pinned V2.0.20 tag 84c9be93a56304a108f1a22df0c5d62c26d5b6ca and published @opencode/cli-darwin-arm64 2.0.20; distinct from opencode-ai 1.x and the earlier dev branch snapshot.", "IDs derive from the containing directory or a source-root Markdown filename. Frontmatter name is a display label; equal names with different IDs coexist.", "Source loops and sorted file loops are sequential. Later valid definitions replace earlier entries by ID; observed selections stayed stable across unchanged fixtures and file-size perturbations.", "Order is low to high duplicate-ID precedence for this version, unlike the unproven root order in the 1.18.18 contract.", "Within one source, files are sorted before loading; directory root-probe/SKILL.md replaced flat root-probe.md in the native probe.", "Exact repeated source definitions are deduplicated at first registration; repeating a registered directory in explicit config does not raise its precedence.", "No duplicate warnings were observed in these probes; neither pinned loader emits a duplicate warning. Warning absence is not proof that duplicate instances are absent.", "GET /api/skill returns registered entries with id, name and path; its first response can precede plugin activation. Probe waits for skill plugins to be active and three identical inventory snapshots.", "Native inventory does not prove model advertisement or invocation. V2 advertises permitted described skills unless autoinvoke is false and resolves invocation by ID, according to pinned source.", "Cross-harness visibility persists; installer enablement intent does not prevent a compatible copy from being discovered. Removing the winning copy can expose a lower-precedence copy.", "Sources also scan singular skill directories and configured URL catalogs; those roots were not natively probed here. Built-in override ordering is documented/source-backed, not separately probed.", "Ancestor discovery uses fs.up without a git-root stop at this source revision; it must not inherit the v1-stable traversal claim." ], "ordering": { "migratedFrom": "documented-low-to-high-precedence", "precedence": { "status": "established", "value": "later-source-wins-by-id", "direction": "low-to-high" } } } ], "distribution": "@opencode/cli (2.x)", "review": { "version": { "status": "established", "value": "2.0.20", "evidence": ["opencode-v2.0.20-skill-roots-probe"] }, "sourceRevision": { "status": "established", "value": "84c9be93a56304a108f1a22df0c5d62c26d5b6ca", "evidence": ["opencode-v2.0.20-skill-config-source"] } } }, { "harness": "pi", "resources": [ { "resource": "skills", "resolution": { "status": "established", "value": "all-visible" }, "conflict": { "status": "unknown", "migratedFrom": "version-sensitive" }, "evidence": ["pi-skills-docs"], "reference": "https://github.com/earendil-works/pi/blob/main/packages/coding-agent/docs/skills.md#choose-where-it-loads", "locations": [ { "path": "~/.pi/agent/skills", "scope": "user", "role": "native", "recognition": { "status": "established", "value": "supported", "basis": "documented" } }, { "path": "~/.agents/skills", "scope": "user", "role": "portable", "recognition": { "status": "established", "value": "supported", "basis": "documented" } }, { "path": ".pi/skills", "scope": "project", "role": "native", "recognition": { "status": "established", "value": "supported", "basis": "documented" } }, { "path": ".agents/skills", "scope": "project", "role": "portable", "traversal": "walk ancestors to repository root, or filesystem root outside git", "recognition": { "status": "established", "value": "supported", "basis": "documented" } }, { "path": "", "scope": "configured", "recognition": { "status": "established", "value": "supported", "basis": "documented" } }, { "path": "", "scope": "package", "recognition": { "status": "established", "value": "supported", "basis": "documented" } }, { "path": "", "scope": "process", "recognition": { "status": "established", "value": "supported", "basis": "documented" } } ], "notes": [ "--no-skills disables discovery but does not cancel explicit --skill paths.", "Pin pi version before relying on root Markdown discovery or duplicate precedence." ], "ordering": { "migratedFrom": "version-sensitive", "overall": { "status": "unknown" } } }, { "resource": "hooks", "resolution": { "status": "established", "value": "extension-load-order" }, "conflict": { "status": "established", "value": "middleware/event-specific" }, "evidence": ["pi-extensions-docs"], "reference": "https://github.com/earendil-works/pi/blob/main/packages/coding-agent/docs/extensions.md#extension-locations", "locations": [ { "path": "~/.pi/agent/extensions/*.ts", "scope": "user", "recognition": { "status": "established", "value": "supported", "basis": "documented" } }, { "path": "~/.pi/agent/extensions/*/index.ts", "scope": "user", "recognition": { "status": "established", "value": "supported", "basis": "documented" } }, { "path": ".pi/extensions/*.ts", "scope": "project", "condition": "project trusted", "recognition": { "status": "established", "value": "supported", "basis": "documented" } }, { "path": ".pi/extensions/*/index.ts", "scope": "project", "condition": "project trusted", "recognition": { "status": "established", "value": "supported", "basis": "documented" } }, { "path": "", "scope": "configured", "recognition": { "status": "established", "value": "supported", "basis": "documented" } }, { "path": "", "scope": "package", "recognition": { "status": "established", "value": "supported", "basis": "documented" } }, { "path": "", "scope": "process", "recognition": { "status": "established", "value": "supported", "basis": "documented" } } ], "notes": [ "Handlers that chain mutations run in extension load order; later handlers see earlier changes.", "Project extensions cannot participate in project_trust because they load only after trust resolves." ], "ordering": { "migratedFrom": "documented-for-chained-events", "execution": { "status": "established", "value": "chained-handlers-run-in-extension-load-order" } } }, { "resource": "plugins", "resolution": { "status": "established", "value": "extension-load-order" }, "conflict": { "status": "established", "value": "component-specific" }, "evidence": ["pi-extensions-docs"], "reference": "https://github.com/earendil-works/pi/blob/main/packages/coding-agent/docs/extensions.md#extension-locations", "locations": [ { "path": "~/.pi/agent/extensions", "scope": "user", "role": "auto-discovered", "recognition": { "status": "established", "value": "supported", "basis": "documented" } }, { "path": ".pi/extensions", "scope": "project", "role": "auto-discovered", "recognition": { "status": "established", "value": "supported", "basis": "documented" } }, { "path": "settings.json#extensions", "scope": "configured", "recognition": { "status": "established", "value": "supported", "basis": "documented" } }, { "path": "", "scope": "package", "recognition": { "status": "established", "value": "supported", "basis": "documented" } }, { "path": "", "scope": "process", "recognition": { "status": "established", "value": "supported", "basis": "documented" } } ], "notes": [ "pi calls this surface extensions/packages rather than plugins.", "Duplicate commands receive numeric suffixes in load order instead of silently replacing each other." ], "ordering": { "migratedFrom": "documented-partially", "overall": { "status": "unknown" }, "notes": [ "V1 labeled loading \"documented-partially\" but did not record a complete sequence. No complete ordering is inferred during migration." ] } }, { "resource": "mcp-server-configuration", "resolution": { "status": "established", "value": "project-over-global" }, "conflict": { "status": "established", "value": "project-server-name-replaces-global" }, "evidence": ["pi-mcp-docs"], "reference": "https://github.com/earendil-works/pi/blob/d86654abb8862e201933517d6f1fce9f88dd117f/packages/coding-agent/docs/mcp.md#configure-servers", "locations": [ { "path": "~/.pi/agent/mcp.json#mcpServers", "scope": "user", "recognition": { "status": "established", "value": "supported", "basis": "documented" } }, { "path": ".pi/mcp.json#mcpServers", "scope": "project", "recognition": { "status": "established", "value": "supported", "basis": "documented" }, "condition": "project trusted" } ], "notes": [ "Applies to built-in MCP in 0.99.1. An extension registering /mcp replaces built-in session discovery; SDK sessions must opt in." ], "ordering": { "migratedFrom": "documented", "precedence": { "status": "established", "value": "project-server-name-replaces-global" } }, "review": { "version": { "status": "established", "value": "0.99.1", "evidence": ["pi-mcp-docs"] }, "sourceRevision": { "status": "established", "value": "d86654abb8862e201933517d6f1fce9f88dd117f", "evidence": ["pi-mcp-docs"] } } } ], "distribution": "pi coding agent" }, { "harness": "opencode", "variant": "2.x", "default": true, "distribution": "@opencode/cli (2.x)", "review": { "version": { "status": "established", "value": "2.0.29", "evidence": ["refresh-opencode-2.0.29-skill-docs"] }, "sourceRevision": { "status": "established", "value": "042d0832f5f3a73eaa039a58a7d565776f6d4290", "evidence": ["refresh-opencode-2.0.29-skill-file"] } }, "resources": [ { "resource": "skills", "resolution": { "status": "established", "value": "one-per-id" }, "conflict": { "status": "established", "value": "later-source-wins-by-id" }, "evidence": [ "refresh-opencode-2.0.29-skill-docs", "refresh-opencode-2.0.29-skill-config", "refresh-opencode-2.0.29-skill-compatibility", "refresh-opencode-2.0.29-skill-file" ], "reference": "https://github.com/anomalyco/opencode/blob/042d0832f5f3a73eaa039a58a7d565776f6d4290/services/www/src/docs/content/skills.mdx#L26-L208", "locations": [ { "path": "", "scope": "system", "role": "built-in", "position": { "kind": "precedence", "index": 1 }, "recognition": { "status": "established", "value": "supported", "basis": "source" } }, { "path": "~/.claude/skills", "scope": "user", "role": "compatibility", "recognition": { "status": "established", "value": "supported", "basis": "source" }, "position": { "kind": "precedence", "index": 2 } }, { "path": ".claude/skills", "scope": "project", "role": "compatibility", "recognition": { "status": "established", "value": "supported", "basis": "source" }, "traversal": "compatibility ancestors from farthest toward current directory", "position": { "kind": "precedence", "index": 3 } }, { "path": "~/.agents/skills", "scope": "user", "role": "portable", "recognition": { "status": "established", "value": "supported", "basis": "source" }, "position": { "kind": "precedence", "index": 4 } }, { "path": ".agents/skills", "scope": "project", "role": "portable", "recognition": { "status": "established", "value": "supported", "basis": "source" }, "traversal": "compatibility ancestors from farthest toward current directory", "position": { "kind": "precedence", "index": 5 } }, { "path": "~/.config/opencode/skills", "scope": "user", "recognition": { "status": "established", "value": "supported", "basis": "source" }, "notes": [ "Default XDG_CONFIG_HOME; actual native root is $XDG_CONFIG_HOME/opencode/skills." ], "position": { "kind": "precedence", "index": 6 } }, { "path": ".opencode/skills", "scope": "project", "recognition": { "status": "established", "value": "supported", "basis": "source" }, "traversal": "project directories from project root toward current directory", "position": { "kind": "precedence", "index": 7 } }, { "path": "#skills[]", "scope": "configured", "recognition": { "status": "established", "value": "supported", "basis": "source" }, "traversal": "compatibility ancestors from farthest toward current directory", "notes": [ "Local explicit sources were probed in both array orders; HTTP catalogs were source-inspected only." ], "position": { "kind": "precedence", "index": 8 } } ], "notes": [ "Released 2.0.29 source/documentation review; this is not a rerun of the retained 2.0.20 native probe.", "Later registered sources replace earlier definitions by path-derived ID; frontmatter name is a display label.", "Native config scans also accept the singular skill directory; explicit sources may be local directories or HTTP catalogs." ], "ordering": { "migratedFrom": "documented-low-to-high-precedence", "precedence": { "status": "established", "value": "later-source-wins-by-id", "direction": "low-to-high" } } }, { "resource": "plugins", "resolution": { "status": "established", "value": "load-all" }, "conflict": { "status": "unknown", "notes": [ "Handler interactions depend on hook and plugin; no global collision policy asserted." ] }, "reference": "https://github.com/anomalyco/opencode/blob/042d0832f5f3a73eaa039a58a7d565776f6d4290/services/www/src/docs/content/plugins.mdx#L5-L83", "evidence": ["refresh-opencode-2.0.29-plugin-docs"], "locations": [ { "path": "~/.config/opencode/plugins", "scope": "user", "recognition": { "status": "established", "value": "supported", "basis": "source" } }, { "path": ".opencode/plugins", "scope": "project", "recognition": { "status": "established", "value": "supported", "basis": "source" } }, { "path": "opencode.json(c)#plugins", "scope": "project", "recognition": { "status": "established", "value": "supported", "basis": "source" } } ], "notes": [ "Direct .ts/.js files and immediate package directories are discovered; configured relative entries resolve from their config file.", "Hook handlers are plugin code, with event-specific control." ], "ordering": {} }, { "resource": "hooks", "resolution": { "status": "established", "value": "load-all" }, "conflict": { "status": "unknown", "notes": [ "Handler interactions depend on hook and plugin; no global collision policy asserted." ] }, "reference": "https://github.com/anomalyco/opencode/blob/042d0832f5f3a73eaa039a58a7d565776f6d4290/services/www/src/docs/content/plugins.mdx#L5-L83", "evidence": ["refresh-opencode-2.0.29-plugin-docs"], "locations": [ { "path": "~/.config/opencode/plugins", "scope": "user", "recognition": { "status": "established", "value": "supported", "basis": "source" } }, { "path": ".opencode/plugins", "scope": "project", "recognition": { "status": "established", "value": "supported", "basis": "source" } }, { "path": "opencode.json(c)#plugins", "scope": "project", "recognition": { "status": "established", "value": "supported", "basis": "source" } } ], "notes": [ "Direct .ts/.js files and immediate package directories are discovered; configured relative entries resolve from their config file.", "Hook handlers are plugin code, with event-specific control." ], "ordering": {} }, { "resource": "instructions", "resolution": { "status": "established", "value": "combine" }, "conflict": { "status": "established", "value": "no-conflict-resolution" }, "ordering": { "loading": { "status": "established", "value": "global-then-current-directory-toward-ancestor-boundary" }, "notes": ["Instruction order does not establish a winning conflicting instruction."] }, "reference": "https://opencode.ai/v2/docs/instructions/#scope", "evidence": [ "memory-opencode-opencode-ai-v2-docs-instructions", "memory-opencode-packages-core-src-config-plugin-instruction-ts", "instructions-opencode-packages-core-src-tool-plugin-read-ts", "instructions-opencode-packages-util-src-global-ts" ], "locations": [ { "path": "~/.config/opencode/AGENTS.md", "scope": "user", "recognition": { "status": "established", "value": "supported", "basis": "documented" } }, { "path": "$OPENCODE_CONFIG_DIR/AGENTS.md", "scope": "configured", "recognition": { "status": "established", "value": "supported", "basis": "documented" } }, { "path": "AGENTS.md", "scope": "project", "traversal": "current workspace toward home; outside home, stop at project root", "recognition": { "status": "established", "value": "supported", "basis": "documented" } }, { "path": "/AGENTS.md", "scope": "directory", "traversal": "added when a file is read or directory is listed", "recognition": { "status": "established", "value": "supported", "basis": "documented" } } ], "notes": [ "V2 recognizes AGENTS.md only; CLAUDE.md fallback is not supported.", "OPENCODE_DISABLE_PROJECT_CONFIG=1 skips project discovery while retaining the global file.", "Loaded files combine without harness conflict resolution." ] }, { "resource": "subagents", "resolution": { "status": "established", "value": "agent-definition-merge" }, "conflict": { "status": "unknown" }, "ordering": {}, "reference": "https://opencode.ai/v2/docs/tools#subagent", "evidence": [ "delegation-opencode-opencode-ai-v2-docs-tools", "delegation-opencode-opencode-ai-v2-docs-agents", "delegation-opencode-packages-core-src-tool-plugin-subagent-ts", "delegation-opencode-packages-tui-src-component-prompt-autocomplete-tsx", "delegation-opencode-opencode-ai-v2-docs-commands", "delegation-opencode-packages-core-src-plugin-agent-ts", "delegation-opencode-packages-core-src-config-plugin-agent-ts", "delegation-opencode-packages-schema-src-config-agent-ts", "delegation-opencode-opencode-ai-v2-docs-migrate-v1", "delegation-opencode-packages-core-src-session-subagent-completion-ts", "steering-opencode-packages-tui-src-config-keybind-ts", "delegation-opencode-opencode-ai-v2-docs-config", "delegation-opencode-opencode-ai-v2-docs-permissions", "delegation-opencode-packages-schema-src-config-experimental-ts", "delegation-opencode-packages-tui-src-routes-session-composer-subagents-tab-tsx" ], "locations": [ { "path": "~/.config/opencode/agents/.md", "scope": "user", "recognition": { "status": "established", "value": "supported", "basis": "documented" } }, { "path": "agents key in global config", "scope": "user", "recognition": { "status": "established", "value": "supported", "basis": "documented" } }, { "path": ".opencode/agents/.md", "scope": "project", "recognition": { "status": "established", "value": "supported", "basis": "documented" } }, { "path": "agents key in project config", "scope": "project", "recognition": { "status": "established", "value": "supported", "basis": "documented" } } ], "notes": [ "The same agent roots define primary agents and subagents; mode selects their role.", "Legacy numeric precedence metadata is not projected as a separately established scan or load sequence." ] }, { "resource": "mcp-server-configuration", "resolution": { "status": "established", "value": "whole-server-replacement" }, "conflict": { "status": "established", "value": "higher-precedence-config-replaces-server-object" }, "ordering": {}, "reference": "https://opencode.ai/v2/docs/config/#locations", "evidence": [ "instructions-opencode-opencode-ai-v2-docs-config", "mcp-opencode-opencode-ai-v2-docs-mcp-servers", "mcp-opencode-packages-core-src-config-plugin-mcp-ts", "mcp-opencode-packages-core-src-config-plugin-policy-ts" ], "locations": [ { "path": "~/.config/opencode/opencode.json(c)", "scope": "user", "recognition": { "status": "established", "value": "supported", "basis": "documented" } }, { "path": "opencode.json(c)", "scope": "project", "traversal": "current directory toward filesystem root", "recognition": { "status": "established", "value": "supported", "basis": "documented" } }, { "path": ".opencode/opencode.json(c)", "scope": "project", "traversal": "applicable ancestor configuration directories", "recognition": { "status": "established", "value": "supported", "basis": "documented" } } ], "notes": [ "Managed system configuration and macOS MDM settings have higher priority.", "A same-name server object is replaced as a whole; fields do not merge.", "Project servers connect without a trust prompt; managed integration policies can block activation." ] } ] } ], "migratedAt": "2026-10-14" }