coilyco-flight-deck/agentic-os

Watch

Evaluate retiring agent-compose and AGENTS.codex.md #333

New issue

Closed

opened 2026-07-07 23:57:32 +00:00 by coilyco-ops · 1 comment

coilyco-ops commented

2026-07-07 23:57:32 +00:00

Owner

The current agent context stack includes AGENTS.codex.md as an agent-compose override slice. That slice exists to provide Codex-specific load-point behavior, but the broader compose layer may no longer be worth keeping.

Evaluate whether agent-compose should be retired, simplified, or replaced by a different mechanism.

Questions to answer:

Is the compose layer still pulling enough weight to justify its complexity?
Do we still need a Codex-specific override file, or can the same behavior move elsewhere?
What breaks if agent-compose goes away?
What should replace the current load-point/override model if it is retired?

Outcome expected:

a recommendation to keep, retire, or replace
the migration shape if any
a clear inventory of affected files and hosts

The current agent context stack includes `AGENTS.codex.md` as an `agent-compose` override slice. That slice exists to provide Codex-specific load-point behavior, but the broader compose layer may no longer be worth keeping. Evaluate whether `agent-compose` should be retired, simplified, or replaced by a different mechanism. Questions to answer: - Is the compose layer still pulling enough weight to justify its complexity? - Do we still need a Codex-specific override file, or can the same behavior move elsewhere? - What breaks if `agent-compose` goes away? - What should replace the current load-point/override model if it is retired? Outcome expected: - a recommendation to keep, retire, or replace - the migration shape if any - a clear inventory of affected files and hosts

coilyco-ops added the

autonomy

async-consult

label

2026-07-08 16:35:04 +00:00

coilyco-ops added the

priority

label

2026-07-09 21:38:52 +00:00

coilyco-ops commented

2026-07-09 21:44:42 +00:00

Author

Owner

🔎 ward agent advisor

ward agent advisor --harness codex ran a one-shot standard research pass on this question:

Read the issue title, body, and comment thread below as the research brief. Identify the decisions, options, open questions, and risks, then give a clear advisory recommendation that can be posted back on the issue.

Recommendation

Replace, not retire.

Keep agent-compose as the host-level composer for per-harness load points, host-class overlays, and the mount-eligibility manifest.
Retire the sibling override mechanism (AGENTS.<harness>.md as section-patching overrides of a base file).
Replace it with ordinary harness-scoped source files that are listed explicitly in agent_compose_sources and gated with frontmatter like harnesses: [codex] or harnesses: [claude].

That keeps the parts that are clearly earning their keep, and removes the part that looks over-engineered for current usage.

Why

1. The compose layer is still pulling real weight

In the current repo and mounted substrate, agent-compose is doing more than just splicing a Codex rule into AGENTS.md:

It owns the actual global load points for Claude, Codex, and optionally OpenCode via symlinks from ~/.claude/CLAUDE.md, ~/.codex/AGENTS.md, and ~/.config/opencode/AGENTS.md.
It is the source of truth for the mount-eligibility manifest (mount-eligibility.json), which infrastructure docs explicitly describe as data that ward reads instead of re-deriving scope.
It supports host-class composition across personal/work/public slices via the infrastructure role.
It supports a host-local drop dir (~/.config/agent-compose/sources/) for untracked doctrine.
It drives context-budget attribution in check_context_budget.py.
It has a freshen hook that recomposes at Claude SessionStart so source edits do not wait for the next converge.

If agent-compose disappeared entirely, those jobs would still need a home. Recreating them elsewhere would mostly be a rename plus migration cost.

2. The override subfeature does not appear to justify its complexity

The section-override mechanism in agentic_os/generators/generate_agent_compose.py adds bespoke behavior:

discover_override()
_override_sections()
apply_overrides()
divergence logic that treats overrides as part of the output signature
dedicated override tests in tests/test_agent_compose.py

But the real files currently using it do not need section replacement:

AGENTS.codex.md adds a Codex-only ## Reading files section.
AGENTS.claude.md adds a Claude-only ## Ward-managed lockdown files section.
The private Codex overlay in /substrate/agentic-os-kai/AGENTS.codex.md is already implemented as a standalone harness-scoped source, not as a patch over another file.

That is the strongest signal in the repo: Codex-specific behavior already works today without the override model.

3. The Codex-specific file is still useful, but not as an override

The public Codex rule in AGENTS.codex.md is small, but it addresses a real harness difference: Codex tends to accumulate context through shell output, so the "read slices, not whole files" rule is good eager doctrine.

What is not justified is the current mechanism used to attach it.

What breaks if `agent-compose` goes away entirely

A full removal would break or force rewrites in at least these areas.

In `agentic-os`

Composer entrypoint and logic:
- agentic_os/generators/generate_agent_compose.py
- tests/test_agent_compose.py
Session freshness wiring:
- scripts/agent-compose-freshen.sh
- scripts/install-agent-compose-freshen.py
Hook and validation surface:
Docs that would become wrong:

In `infrastructure`

The mounted infrastructure docs and role files show that agent-compose is the current convergence point for host setup:

role defaults and tasks:
host-class source selection:
- /substrate/infrastructure/ansible/inventory/group_vars/hostclass_personal.yml
- /substrate/infrastructure/ansible/inventory/group_vars/mac.yml
docs and runbooks:
- /substrate/infrastructure/docs/ansible-agent-compose-role.md
- /substrate/infrastructure/docs/FEATURES.md

Likely host impact

Per the infrastructure docs, the affected hosts are:

personal Macs using public base + Kai-private overlays
work Macs using public base + work overlay
WSL/Linux hosts using the same compose role
OpenCode hosts where the opencode load point is enabled
native Windows is already a manual edge case, but any future converge path there would also need replacement

What should replace the current load-point/override model

Recommended replacement model

Keep this model:

one host-level composer
one ordered source list per host
harness filtering via frontmatter
symlinked harness load points
manifest emitted from the same resolution pass

Replace only this part:

remove sibling section patching (AGENTS.<harness>.md discovered as an implicit override of a base file)

With this:

treat harness-specific files as normal explicit sources
put ---\nharnesses: [codex]\n--- or harnesses: [claude] in those files
list them directly in infrastructure's agent_compose_sources in the intended order

That makes the system simpler in two ways:

the compose engine no longer needs heading-merge semantics
harness divergence is expressed in one obvious place: the ordered source list

Why this is better than moving the behavior elsewhere entirely

Moving the Codex rule into a skill or a harness base prompt would make it less versioned alongside the rest of the eager doctrine, and in the skill case it would become lazy-loaded instead of startup-loaded. The current rule is precisely about startup reading discipline, so keeping it in eager context is reasonable.

Migration shape

Phase 1. Replace override files with normal harness-scoped sources

Add frontmatter to AGENTS.codex.md and AGENTS.claude.md.
Update their headers/comments so they describe themselves as standalone compose sources, not sibling patch files.
Update infrastructure source lists to include them explicitly, after the base AGENTS.md.
Mirror the same pattern anywhere else using harness-specific files.

Phase 2. Simplify the composer

Remove override discovery and section-merge code from generate_agent_compose.py.
Remove the override-specific tests.
Keep source selection, symlinking, manifest generation, and stale-output cleanup.

Phase 3. Repoint docs and checks

Update docs to describe harness-scoped sources, not override slices.
Keep context-budget, agent-compat, and the manifest model unchanged, since they can continue to consume the compose plan.

Open questions

Is any repo outside the mounted substrate using true heading replacement rather than simple additive harness files? I found no evidence of real production use here, but the migration should confirm there are no out-of-tree users.
Does ward currently consume mount-eligibility.json in code on the active branch, or is infrastructure/docs ahead of ward implementation? The docs clearly treat the manifest as authoritative, so the migration should confirm the live consumer path before changing the file contract.

Risks

Biggest risk if retired wholesale: duplicating scope logic in infrastructure or ward and creating a second source of truth for mount eligibility.
Biggest risk in the recommended migration: missing an external user of heading-replacement overrides.
Operational risk: if explicit source ordering is changed carelessly, harness slices can change silently. That is manageable with targeted tests and a before/after dry-run diff.

Bottom line

Do not retire agent-compose outright. It still owns enough real behavior to justify existing as the composition layer.

Do retire the override mechanism and AGENTS.codex.md-as-override. Keep the Codex-specific doctrine, but make it a normal harness-scoped source. That captures the current benefit with materially less machinery.

Researched and posted automatically by ward agent advisor --harness codex (ward#179). This is one-shot research, not a carried change - verify before acting on it.

— Codex, via ward agent

### 🔎 ward agent advisor `ward agent advisor --harness codex` ran a one-shot **standard** research pass on this question: > Read the issue title, body, and comment thread below as the research brief. Identify the decisions, options, open questions, and risks, then give a clear advisory recommendation that can be posted back on the issue. --- ## Recommendation **Replace, not retire.** - **Keep `agent-compose` as the host-level composer** for per-harness load points, host-class overlays, and the mount-eligibility manifest. - **Retire the sibling override mechanism** (`AGENTS.<harness>.md` as section-patching overrides of a base file). - **Replace it with ordinary harness-scoped source files** that are listed explicitly in `agent_compose_sources` and gated with frontmatter like `harnesses: [codex]` or `harnesses: [claude]`. That keeps the parts that are clearly earning their keep, and removes the part that looks over-engineered for current usage. ## Why ### 1. The compose layer is still pulling real weight In the current repo and mounted substrate, `agent-compose` is doing more than just splicing a Codex rule into `AGENTS.md`: - It owns the **actual global load points** for Claude, Codex, and optionally OpenCode via symlinks from `~/.claude/CLAUDE.md`, `~/.codex/AGENTS.md`, and `~/.config/opencode/AGENTS.md`. - It is the source of truth for the **mount-eligibility manifest** (`mount-eligibility.json`), which infrastructure docs explicitly describe as data that **ward reads instead of re-deriving scope**. - It supports **host-class composition** across personal/work/public slices via the infrastructure role. - It supports a **host-local drop dir** (`~/.config/agent-compose/sources/`) for untracked doctrine. - It drives **context-budget attribution** in `check_context_budget.py`. - It has a **freshen hook** that recomposes at Claude SessionStart so source edits do not wait for the next converge. If `agent-compose` disappeared entirely, those jobs would still need a home. Recreating them elsewhere would mostly be a rename plus migration cost. ### 2. The override subfeature does not appear to justify its complexity The section-override mechanism in `agentic_os/generators/generate_agent_compose.py` adds bespoke behavior: - `discover_override()` - `_override_sections()` - `apply_overrides()` - divergence logic that treats overrides as part of the output signature - dedicated override tests in `tests/test_agent_compose.py` But the **real files currently using it do not need section replacement**: - [`AGENTS.codex.md`](/workspace/agentic-os/AGENTS.codex.md) adds a Codex-only `## Reading files` section. - [`AGENTS.claude.md`](/workspace/agentic-os/AGENTS.claude.md) adds a Claude-only `## Ward-managed lockdown files` section. - The private Codex overlay in [`/substrate/agentic-os-kai/AGENTS.codex.md`](/substrate/agentic-os-kai/AGENTS.codex.md) is already implemented as a **standalone harness-scoped source**, not as a patch over another file. That is the strongest signal in the repo: **Codex-specific behavior already works today without the override model**. ### 3. The Codex-specific file is still useful, but not as an override The public Codex rule in [`AGENTS.codex.md`](/workspace/agentic-os/AGENTS.codex.md) is small, but it addresses a real harness difference: Codex tends to accumulate context through shell output, so the "read slices, not whole files" rule is good eager doctrine. What is not justified is the current mechanism used to attach it. ## What breaks if `agent-compose` goes away entirely A full removal would break or force rewrites in at least these areas. ### In `agentic-os` - Composer entrypoint and logic: - [`agentic_os/generators/generate_agent_compose.py`](/workspace/agentic-os/agentic_os/generators/generate_agent_compose.py) - [`tests/test_agent_compose.py`](/workspace/agentic-os/tests/test_agent_compose.py) - Session freshness wiring: - [`scripts/agent-compose-freshen.sh`](/workspace/agentic-os/scripts/agent-compose-freshen.sh) - [`scripts/install-agent-compose-freshen.py`](/workspace/agentic-os/scripts/install-agent-compose-freshen.py) - Hook and validation surface: - [`agentic_os/pre_commit/check_agent_compose_drift.py`](/workspace/agentic-os/agentic_os/pre_commit/check_agent_compose_drift.py) - [`agentic_os/pre_commit/check_agent_compose_size.py`](/workspace/agentic-os/agentic_os/pre_commit/check_agent_compose_size.py) - [`agentic_os/pre_commit/check_agent_compose_dedup.py`](/workspace/agentic-os/agentic_os/pre_commit/check_agent_compose_dedup.py) - [`agentic_os/pre_commit/check_context_budget.py`](/workspace/agentic-os/agentic_os/pre_commit/check_context_budget.py) - [`scripts/agent-compat.py`](/workspace/agentic-os/scripts/agent-compat.py) - [`.pre-commit-hooks.yaml`](/workspace/agentic-os/.pre-commit-hooks.yaml) - [`pyproject.toml`](/workspace/agentic-os/pyproject.toml) - [`.ward/ward.yaml`](/workspace/agentic-os/.ward/ward.yaml) - Docs that would become wrong: - [`README.md`](/workspace/agentic-os/README.md) - [`docs/features-agents-sessions.md`](/workspace/agentic-os/docs/features-agents-sessions.md) - [`docs/context-budget.md`](/workspace/agentic-os/docs/context-budget.md) - [`docs/mount-eligibility-manifest.md`](/workspace/agentic-os/docs/mount-eligibility-manifest.md) - [`docs/FEATURES.md`](/workspace/agentic-os/docs/FEATURES.md) ### In `infrastructure` The mounted infrastructure docs and role files show that `agent-compose` is the current convergence point for host setup: - role defaults and tasks: - [`/substrate/infrastructure/ansible/roles/agent-compose/defaults/main.yml`](/substrate/infrastructure/ansible/roles/agent-compose/defaults/main.yml) - [`/substrate/infrastructure/ansible/roles/agent-compose/tasks/main.yml`](/substrate/infrastructure/ansible/roles/agent-compose/tasks/main.yml) - [`/substrate/infrastructure/ansible/roles/agent-compose/templates/agent-compose.yaml.j2`](/substrate/infrastructure/ansible/roles/agent-compose/templates/agent-compose.yaml.j2) - host-class source selection: - [`/substrate/infrastructure/ansible/inventory/group_vars/hostclass_personal.yml`](/substrate/infrastructure/ansible/inventory/group_vars/hostclass_personal.yml) - [`/substrate/infrastructure/ansible/inventory/group_vars/mac.yml`](/substrate/infrastructure/ansible/inventory/group_vars/mac.yml) - docs and runbooks: - [`/substrate/infrastructure/docs/ansible-agent-compose-role.md`](/substrate/infrastructure/docs/ansible-agent-compose-role.md) - [`/substrate/infrastructure/docs/FEATURES.md`](/substrate/infrastructure/docs/FEATURES.md) ### Likely host impact Per the infrastructure docs, the affected hosts are: - **personal Macs** using public base + Kai-private overlays - **work Macs** using public base + work overlay - **WSL/Linux hosts** using the same compose role - **OpenCode hosts** where the opencode load point is enabled - **native Windows** is already a manual edge case, but any future converge path there would also need replacement ## What should replace the current load-point/override model ### Recommended replacement model Keep this model: - one host-level composer - one ordered source list per host - harness filtering via frontmatter - symlinked harness load points - manifest emitted from the same resolution pass Replace only this part: - **remove sibling section patching** (`AGENTS.<harness>.md` discovered as an implicit override of a base file) With this: - treat harness-specific files as **normal explicit sources** - put `---\nharnesses: [codex]\n---` or `harnesses: [claude]` in those files - list them directly in infrastructure's `agent_compose_sources` in the intended order That makes the system simpler in two ways: - the compose engine no longer needs heading-merge semantics - harness divergence is expressed in one obvious place: the ordered source list ### Why this is better than moving the behavior elsewhere entirely Moving the Codex rule into a skill or a harness base prompt would make it less versioned alongside the rest of the eager doctrine, and in the skill case it would become lazy-loaded instead of startup-loaded. The current rule is precisely about **startup reading discipline**, so keeping it in eager context is reasonable. ## Migration shape ### Phase 1. Replace override files with normal harness-scoped sources - Add frontmatter to `AGENTS.codex.md` and `AGENTS.claude.md`. - Update their headers/comments so they describe themselves as standalone compose sources, not sibling patch files. - Update infrastructure source lists to include them explicitly, after the base `AGENTS.md`. - Mirror the same pattern anywhere else using harness-specific files. ### Phase 2. Simplify the composer - Remove override discovery and section-merge code from `generate_agent_compose.py`. - Remove the override-specific tests. - Keep source selection, symlinking, manifest generation, and stale-output cleanup. ### Phase 3. Repoint docs and checks - Update docs to describe harness-scoped sources, not override slices. - Keep `context-budget`, `agent-compat`, and the manifest model unchanged, since they can continue to consume the compose plan. ## Open questions - Is any repo outside the mounted substrate using true heading replacement rather than simple additive harness files? I found no evidence of real production use here, but the migration should confirm there are no out-of-tree users. - Does ward currently consume `mount-eligibility.json` in code on the active branch, or is infrastructure/docs ahead of ward implementation? The docs clearly treat the manifest as authoritative, so the migration should confirm the live consumer path before changing the file contract. ## Risks - **Biggest risk if retired wholesale:** duplicating scope logic in infrastructure or ward and creating a second source of truth for mount eligibility. - **Biggest risk in the recommended migration:** missing an external user of heading-replacement overrides. - **Operational risk:** if explicit source ordering is changed carelessly, harness slices can change silently. That is manageable with targeted tests and a before/after dry-run diff. ## Bottom line **Do not retire `agent-compose` outright.** It still owns enough real behavior to justify existing as the composition layer. **Do retire the override mechanism and `AGENTS.codex.md`-as-override.** Keep the Codex-specific doctrine, but make it a normal harness-scoped source. That captures the current benefit with materially less machinery. --- Researched and posted automatically by `ward agent advisor --harness codex` (ward#179). This is one-shot research, not a carried change - verify before acting on it.   — Codex, via `ward agent`