Feature request: repository-managed, model-aware instructions and skills to operationalize the GPT-6 Astra guidance

What variant of Codex are you using?

Codex CLI 0.153.4 on macOS; the requested design should also clarify how it applies to Codex app and IDE users sharing the same repository.

What feature would you like to see?

A supported, documented way to maintain and select model-specific repository guidance, including AGENTS.md instructions and skills, while preserving a small shared baseline.

The motivation is a gap between OpenAI's new model-specific prompting recommendations and the repository-level mechanisms available to put those recommendations into practice. This is not primarily a request for different task personas or Codex-vs-Claude files.

Official guidance motivating this request

The September 11 article Rethinking skills and prompts for GPT-6 Astra explicitly says:

Guidance that helps Sol or Luna may overconstrain GPT-6 Astra

The surrounding paragraph points out that repository skills also affect other contributors whose agents may use different models, and asks maintainers to consider which models will consume their instructions.

The GPT-6 Astra initiative and follow-through guidance also explains a concrete behavioral difference:

It is also more likely to ask for clarification where earlier models would make assumptions.

That guide provides prompting adjustments for initiative, follow-through, instruction following, and verification. These recommendations make sense, but the cited guidance does not give a concrete repository-management design for contributors who continue to use different models at the same time.

The practical problem

Consider one repository with shared AGENTS.md and SKILL.md files:

• Contributor A uses GPT-6 Astra and simplifies previously useful procedural instructions following the official guidance.
• Contributor B still uses GPT-5.6 Sol or Luna and may need some of that guidance.
• The same contributor may switch models between sessions or during a session.

Changing the shared files for one model changes what the other models receive. Keeping every model's instructions together adds irrelevant context and asks the model to interpret conditional prose. Duplicating whole files creates drift. Personal profiles or symlinks require setup outside the repository and do not provide a shared model-to-guidance contract for the team.

The request is not that every model must always receive different instructions. It is that, when maintainers follow the official advice and identify a useful model-specific difference, Codex should provide a practical way to manage and apply it.

What is missing

Please provide a supported design and an end-to-end official example for:

1. Keeping model-independent repository constraints and workflow knowledge shared.
2. Keeping small, version-controlled model-specific differences alongside that baseline, for both persistent instructions and skills where needed.
3. Selecting the appropriate guidance using the actual selected model, or an explicit model/guidance mapping, without global file mutations or asking the model to identify itself and choose files.
4. Defining what happens when a user switches models: refresh the applicable guidance, or clearly require a new session. Guidance for the previous model should not silently remain active as if it were current.
5. Making the selected sources and fallback behavior inspectable, including behavior for an unknown or newly released model.
6. Supporting independent concurrent sessions and documenting the CLI/app/IDE boundaries.

I am deliberately not prescribing a filename convention, config key, or automatic migration of existing instructions. A documented supported composition mechanism could be sufficient; if the current mechanisms cannot express this, a native feature is needed. Existing trust boundaries and baseline project constraints should remain intact.

Current behavior checked

On CLI 0.153.4, a named profile placed only at <project>/.codex/astra.config.toml was not applied by codex exec --profile astra. The same file was read from $CODEX_HOME/astra.config.toml, including through a symlink. This was checked using an intentional type error (model = 42) and comparing startup behavior; the temporary files were removed afterward.

That workaround can select a personal configuration, but it does not solve portable, repository-managed guidance for several models. The profile lookup detail is supporting evidence, not the main feature request.

Related but distinct

• #31122 concerns different agent/harness overlays. This request concerns different models within Codex, specifically the management gap highlighted by OpenAI's Astra guidance.
• #10067 concerns named instruction variants for workflows.
• #42601 concerns profile-selected global instruction files.
• #35060 concerns instruction and skill compatibility diagnostics. Diagnostics would help identify a mismatch, but a composition/selection mechanism is still needed to maintain both supported variants.

I previously added a model-specific use-case comment to #31122, but opened this separately to make the official-guidance-to-product-design gap explicit.

What repository structure and selection lifecycle does OpenAI recommend for this situation today? If none is supported, could model-aware repository guidance be considered as a feature, with a documented reference workflow? I am happy to contribute reproduction details and design feedback.

Start by reproducing the reported behavior with codex exec --profile astra and the project/.codex/astra.config.toml and $CODEX_HOME/astra.config.toml locations. Review the related issues (#31122, #10067, #42601, and #35060) before defining the supported composition and selection lifecycle; done means the model-aware repository guidance design, fallback behavior, and CLI/app/IDE boundaries are documented.