This is the durable design policy for every plugin, skill, hook, script, MCP mapping, and marketplace entry in this repository. The migration playbook applies it when translating a capability from another host.
MUST and MUST NOT are release gates. SHOULD describes the default; a pull
request may depart from it only with a written, tested reason.
A plugin MUST deliver an independently useful vertical slice of one cohesive user capability. Organize around the user goal and its acceptance criteria, not around a source host's folders or a generic technical layer.
Publisher metadata may identify Melodic Software. Runtime behavior MUST NOT depend on a particular user, employer, organization, repository, machine, absolute path, subscription, workspace policy, or undocumented directory layout. A plugin MUST remain useful when installed by itself.
This repository is the Codex-only source of truth. Claude Code, Cursor, and Codex packages have independent manifests, releases, tests, and native adapters. Ideas may be ported deliberately in either direction; runtime cross-loading and automatic cross-repository synchronization are prohibited.
Repository context is the primary adaptation mechanism. Before deciding how to act, a plugin MUST discover context in this order:
- The current request, authorization, and explicit invocation inputs.
- The active
AGENTS.mdinstruction chain from repository root to the current working directory. - Native repository evidence relevant to the goal: manifests, configuration, CI, tests, documentation, established code patterns, and current changes.
- Available Codex capabilities, tools, connectors, hooks, platform, and trust state.
- Plugin defaults and optional fallbacks.
More specific authorized context wins over a generic default. The plugin MUST surface a material conflict instead of silently replacing repository policy. It MUST NOT infer employer policy, personal taste, or credentials from publisher metadata, machine state, or a sibling plugin.
Repository discovery must be proportional. Inspect only the context needed for the user goal and avoid collecting unrelated repository or personal data.
Select the smallest current Codex surface that owns the behavior:
| Need | Native owner |
|---|---|
| One invocation's choice | Prompt or explicit skill input |
| Repeatable workflow | Focused skill |
| Durable repository convention | Consumer AGENTS.md |
| Project or personal setting | Native Codex configuration |
| Live external data or controlled action | MCP server or supported connector |
| Lifecycle enforcement | Hook with explicit trust review |
| Independent delegated role | Current native Codex agent surface, when the documented package contract supports it |
| Scheduled follow-up | Codex automation, outside the plugin package |
| Installable distribution | Plugin manifest and marketplace |
A plugin MUST NOT introduce a second configuration, credential, scheduling, or policy system when a current native surface can express the requirement. When a native gap is real, the change MUST document the missing capability and isolate the workaround behind a replaceable adapter.
agents/openai.yaml is the skill's harness-facing sidecar, not a custom
execution agent. It carries exactly three concerns: interface presentation
(display name, short description, icons, brand color, default prompt),
dependencies.tools declarations of the MCP tools the skill expects, and
policy (allow_implicit_invocation, product restrictions). Keep all three
synchronized with the owning SKILL.md.
A dependencies.tools entry is a declaration, not a connection: it names an
MCP dependency for discovery and presentation and does not install,
authenticate, or start a server. It is therefore subject to the same
outbound-port rules as any other integration — declare only what the skill
actually consumes, keep the capability check and fallback in the skill, and
never place a credential or a private endpoint in the sidecar.
Package or migrate a custom agent only when current official Codex documentation defines the discovery and packaging contract; otherwise express the cohesive workflow as a skill or use normal task coordination.
Treat host and environment integrations as adapters around a cohesive core:
- Core: user-goal decisions, validation rules, transformations, and output contracts that do not depend on Codex or a source host.
- Inbound ports: user intent, explicit skill inputs, repository context, and hook or automation events.
- Outbound ports: filesystem operations, shell or CLI execution, MCP tools, connectors, network access, UI, and external writes.
- Adapters: the smallest Codex-native implementation of one port, including capability detection, validation, approvals, and fallback behavior.
The core MUST NOT locate another plugin, read a personal config path directly, or depend on a concrete connector when a narrow capability interface is enough. Adapters SHOULD be replaceable without rewriting the domain workflow.
Use an abstraction only when it protects a real boundary or variation. Do not create speculative frameworks. Interfaces MUST be segregated by the smallest capability a workflow consumes; read and write capabilities MUST remain distinct when the underlying tool permits it.
- Each skill MUST have one recognizable trigger and outcome.
- Related instructions, tests, references, scripts, and assets SHOULD live with the capability that owns them.
- Internal representation and host-specific details MUST be encapsulated behind the owning skill, script, or adapter.
- Plugins MUST NOT share mutable runtime state or private file layouts.
- Collaboration between plugins requires a documented public seam, explicit user intent, and a useful standalone fallback.
- Cross-cutting helpers are justified only after more than one real vertical slice needs the same stable contract.
This produces high cohesion inside a capability and low coupling between capabilities without sacrificing simple, direct implementations.
Configuration SHOULD flow through native surfaces in this order:
- explicit invocation input;
- active repository instructions or project configuration;
- personal Codex configuration;
- authenticated MCP or connector configuration; and
- a documented plugin default.
Defaults MUST be quiet, safe, reversible, and non-blocking when a safe choice exists. Required questions MUST be limited to material choices that cannot be derived from authorized context. Optional integrations MUST be capability-detected and MUST have either a useful fallback or a clear unsupported result.
Extension points MUST describe their input, output, error, and trust boundary. Do not expose an entire tool or environment when a smaller port is sufficient.
- Keep credentials and secret values outside the package.
- Separate read, preview, write, and destructive operations.
- Preserve unrelated working-tree changes and scope writes to the request.
- Make external state changes visible and follow Codex approval boundaries.
- Treat hooks as executable trust boundaries and keep them optional unless the capability cannot be correct without enforcement.
- Detect platform-specific behavior and provide a safe unsupported path.
- Never assume a third-party executable, connection, network route, or product entitlement exists without checking.
Idempotent or safely retryable behavior is preferred. When an operation cannot be safely retried, its contract MUST say so and verification MUST cover partial failure.
Every plugin action MUST complete the live-documentation preflight in
AGENTS.md. official-docs.md contains upstream pointers,
not copied rules. Pull requests record the live URLs and verification date.
Repository prose SHOULD explain our decision, boundary, and test—not restate an upstream manual. If a current product contract changes, update the affected implementation, tests, source pointer, and local decision together.
A plugin is releasable only when all of these are true:
- It has a clear user goal and cohesive vertical-slice boundary.
- It follows current native Codex contracts verified from live sources.
- It adapts through authorized repository context before defaults.
- Its core is isolated from host and environment adapters where variation is material.
- It has no user, organization, machine, sibling-plugin, or source-host runtime dependency.
- Paths are relative to the plugin, marketplace, or active repository root.
- Configuration uses native surfaces or documents a narrow native gap.
- Optional capabilities have tested fallback behavior.
- Writes preserve unrelated changes and respect trust and approval boundaries.
- Direct, indirect, negative, incomplete, context-variation, platform, and missing-dependency cases are tested.
- The package passes repository, plugin, and skill validators.
One-off behavior is acceptable only when the capability is intentionally specific, the boundary is named, and the implementation still follows the same context, safety, adapter, and validation rules.