feat(spec,examples): configure agent context discovery directories

[cdupuis]

Agent harnesses can miss the workspace-sibling profile: Codex stops project instruction discovery at the Git root, while other harnesses use global configuration files or project-root files. Add an optional absolute directory to agent-context@1 so Kits can select a discovery location for the profile containing runtime guidance and the per-Kit index. Existing descriptors retain their workspace-sibling default; staged context bodies retain their published paths.

Agent mixins can declare an explicit directory and filename. That destination wins over a generic workload's legacy filename, independently of composition order; identical explicit destinations coalesce and differing ones conflict. The shell-based Claude and Codex ACP sets also declare their agent profile explicitly, so they work with older published component mixins and coalesce with the updated ones. Preserve existing instructions outside runtime-managed sections so Cursor can use a checkout's AGENTS.md. Move the Codex mixin's CODEX_HOME into image environment so ACP launches receive it without a login shell.

Update Go types and validation, JSON Schemas, normative text, authoring/migration skills, and the verified workload/mixin pairs for Codex, Claude Code, Gemini CLI, OpenCode, Docker Agent, and Cursor. The discovery report records effective-environment overrides, loader conditions, and source links. Devin keeps its legacy declaration because an authoritative discovery location could not be verified. Cursor uses the example workdir; another checkout root requires a matching directory. Differing explicit agent profiles remain unsupported in this singleton capability.

The extension stays in agent-context@1, as requested, without a capability or schema version bump. No existing field is renamed or removed. Existing descriptors remain valid; older strict readers reject declarations using the new directory field. The sbx runtime handler lives outside this repository and needs to implement these duties before consuming the updated examples. Full live sbx conformance was not run.

Normative accounting:

• agent-context@1/workload-filename-is-profile now refers to the effective profile; the existing agent-context@1/body-readable check covers legacy behavior.
• agent-context@1/directory-honored has a new runtime check exercising two directories, a workload-owned destination, and an agent mixin overriding a legacy workload in both input orders.
• agent-context@1/explicit-profile-precedence and agent-context@1/existing-content-preserved are covered by that directory check; the workload fixture seeds existing instructions.
• agent-context@1/explicit-profile-conflict has a new refusal check composing differing explicit profiles.
• Fake-adapter mutations prove failures for ignored directories, fixed directories, the legacy workload winning, ignored filenames, overwritten existing instructions, and accepted conflicts. Unit tests cover validation, composition, and ordinary/grouped publication; the set end-to-end test reads the overriding profile back from a published artifact.

Validation passed: task validate, task lint, task test (unit and fake-adapter conformance), task test:e2e, and task kit:dev KIT=codex-mixin. The built Codex mixin's published descriptor and image environment were inspected. Pre-existing artifact-store and scheduling edits are excluded.

Release note

Kits can select agent instruction discovery directories in agent-context@1, including agent mixins composed over generic workloads, while preserving existing profile content.

[Copilot]

Copilot review overview

🟡 Changes recommended

The new config field must use a new capability version under the repository’s strict compatibility rules.

Review effort: Balanced
Findings: 1

Open (1)

• Bump agent-context capability version for new directory field · New

What changed in this PR

Proposes configurable agent-context discovery directories, updating validation, composition, conformance coverage, documentation, and agent examples.

Changes:

• Adds explicit directory/filename profile selection and merge precedence.
• Expands TCK fixtures and mutations for placement, preservation, and conflicts.
• Updates agent Kits and discovery documentation.

File	Description
tck/​sandbox/​testdata/​fixtures/​context-workload/​context-workload.yaml	Adds explicit-directory workload fixture.
tck/​sandbox/​testdata/​fixtures/​context-profile/​context-profile.yaml	Adds explicit-profile mixin fixture.
tck/​sandbox/​testdata/​fixtures/​context-conflict/​context-conflict.yaml	Adds conflicting-profile fixture.
tck/​sandbox/​testdata/​fake-adapter	Simulates profile placement and mutations.
tck/​sandbox/​sandbox_test.go	Registers new mutations.
tck/​sandbox/​fixtures_test.go	Updates fixture count.
tck/​sandbox/​coverage_test.go	Accounts for covered requirements.
tck/​sandbox/​checks.go	Adds directory and conflict checks.
spec/​validate.go	Validates explicit profile destinations.
spec/​types.go	Adds AgentContext.Directory.
spec/​schema_test.go	Tests directory schema constraints.
spec/​merge.go	Implements explicit-profile precedence.
spec/​agent_context_test.go	Tests validation and composition.
skills/​migrate-kit-to-v3/​FIELD-MAPPING.md	Updates migration guidance.
skills/​create-kit-v3/​SKILL.md	Updates authoring guidance.
schema/​kit.schema.json	Documents optional discovery directories.
schema/​capabilities/​com.docker.sandbox/​agent-context@1.schema.json	Adds the directory schema.
examples/​shell/​shell.yaml	Clarifies legacy fallback behavior.
examples/​opencode/​opencode.yaml	Declares OpenCode’s profile directory.
examples/​opencode-mixin/​opencode-mixin.yaml	Adds the OpenCode mixin profile.
examples/​gemini/​gemini.yaml	Declares Gemini’s profile directory.
examples/​gemini-mixin/​gemini-mixin.yaml	Adds the Gemini mixin profile.
examples/​docker-agent/​docker-agent.yaml	Declares Docker Agent’s profile directory.
examples/​docker-agent-mixin/​docker-agent-mixin.yaml	Adds the Docker Agent mixin profile.
examples/​cursor/​cursor.yaml	Targets Cursor’s project root.
examples/​cursor-mixin/​cursor-mixin.yaml	Adds the Cursor mixin profile.
examples/​codex/​codex.yaml	Declares Codex’s global profile.
examples/​codex-mixin/​codex-mixin.yaml	Adds the Codex mixin profile.
examples/​codex-mixin/​codex-mixin.dockerfile	Exposes CODEX_HOME to direct launches.
examples/​codex-acp-set/​codex-acp-set.yaml	Selects the Codex ACP profile.
examples/​claude/​claude.yaml	Declares Claude’s user profile.
examples/​claude-mixin/​claude-mixin.yaml	Adds the Claude mixin profile.
examples/​claude-acp-set/​claude-acp-set.yaml	Selects the Claude ACP profile.
docs/​spec/​SPEC-v3.md	Defines profile composition behavior.
docs/​spec/​conformance.md	Documents conformance fixtures.
docs/​spec/​capabilities/​com.docker.sandbox/​agent-context@1.md	Specifies directory runtime duties.
docs/​agent-context-placement.md	Records harness discovery locations.
cmd/​frontend/​set_e2e_test.go	Tests set profile precedence.

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.