refactor(agents): flatten agents directory#621
Merged
Conversation
Move all 50 agent files out of category subfolders (review/, research/, workflow/, design/, document-review/, docs/) into the flat plugins/compound-engineering/agents/ directory. Filenames and name: frontmatter values are unchanged; only the parent directory moves. The subfolder organization was a human-readability aid, not a harness requirement. The Claude Code parser walks recursively, and every other target writer (Codex, OpenCode, Gemini, Kiro, Droid, Copilot, Pi) writes agents to a flat output regardless of input layout. Flattening removes a coupling point between source structure and Codex agent naming. Subsequent commits in this series rewrite the 117 category-prefixed references in skill/agent content, update the AGENTS.md conventions, and update the test fixtures that hardcoded nested paths. Per docs/plans/2026-04-21-001-refactor-flatten-agents-directory-plan.md Unit 1. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Convert 117 occurrences of `<category>:ce-<agent-name>` to bare `ce-<agent-name>` across 16 files in the compound-engineering plugin. The ce- prefix is sufficient for uniqueness; the `<category>:` segment was only meaningful because the Codex converter's getAgentCategory() rebuilt it from the source path, which now returns null for every agent after Unit 1's flatten. Applied via a narrow perl regex matching only the six known category names (review, research, workflow, design, document-review, docs) when followed directly by `:ce-`. Post-sweep grep for the pattern returns zero. Insertions and deletions balance exactly (117 each), confirming the rewrite was surface-only. Per docs/plans/2026-04-21-001-refactor-flatten-agents-directory-plan.md Unit 3. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Root AGENTS.md: rewrite "Agent References in Skills" to mandate bare ce-<agent-name>. Plugin AGENTS.md: collapse the Directory Structure tree to a flat agents/ listing; update the Naming Convention paragraph to state bare ce-<agent-name> as the reference form; update the "New agent" bullet under Adding Components to drop the <category> path segment. Verified plugins/compound-engineering/README.md has no prose implying agents/<category>/ — the topical agent tables describe conceptual groupings, not directory paths. Per docs/plans/2026-04-21-001-refactor-flatten-agents-directory-plan.md Unit 4. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
When writing Codex custom agents, delete any same-basename sibling directory under agentsRoot if the retained agent declares zero sidecarDirs. Previously, cleanupRemovedAgents only swept the sibling directory when the TOML itself was being removed — a same-name agent that lost its sidecar between plugin versions left an orphan directory indefinitely. The new sweep is narrowly scoped: it only runs against base names of agents in the current install and only when the agent declares no sidecars, so unrelated directories under agentsRoot are untouched. Gated by isSafeManagedPath to match the existing cleanup safety pattern. Tests cover the three scenarios: orphan removed when agent has no sidecars, sidecar preserved when agent declares one, unrelated directory left alone. Per docs/plans/2026-04-21-001-refactor-flatten-agents-directory-plan.md Unit 4b. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Update sourcePath fixtures and expected Codex agent names across the
test suite to reflect agents now living directly under
plugins/compound-engineering/agents/ with no category subfolders:
- tests/codex-converter.test.ts: flip the namespaced-Task test to the
flat layout with bare ce-<agent> expected names. Add a new test that
pins the nested-layout fallback: any third-party plugin still using
agents/<category>/<name>.md passed through convertClaudeToCodex must
continue to produce <category>-ce-<agent> Codex agent names.
- tests/pi-writer.test.ts, tests/review-skill-contract.test.ts,
tests/legacy-cleanup.test.ts, tests/pipeline-review-contract.test.ts,
tests/kiro-writer.test.ts: strip the <category>/ segment from every
hardcoded plugins/compound-engineering/agents/* path. Several of
these (legacy-cleanup.test.ts in particular) perform live filesystem
reads and would throw ENOENT if left pointing at the old nested
locations.
- tests/review-skill-contract.test.ts: update the
stack-specific-reviewers contract test to assert bare ce-<agent>
references in SKILL.md / persona-catalog.md, matching the new
convention.
Also simplify cleanupLegacyAgentSkillDirs: the `agent.name.includes("-ce-")`
branch relied on compound names like review-ce-foo to extract a legacy
ce-<final> variant. Every current agent now starts with ce- with no
embedded -ce-, so that branch produced nonsense entries (ce-ce-<name>)
and swept nothing. Remove the dead branch; keep the primary
legacySkillNames.add(sanitizePathName(agent.name)) which still catches
stale skill directories under ~/.codex/skills/<plugin>/<agent-name>/.
bun test passes with 830 tests green. bun run release:validate reports
no drift: compound-engineering at 50 agents, 45 skills, 0 MCP servers.
Per docs/plans/2026-04-21-001-refactor-flatten-agents-directory-plan.md
Unit 5.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
tmchow
changed the title
![chatgpt-codex-connector[bot]](https://avatars.githubusercontent.com/in/1144995?s=60&v=4){kind=small}
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: 25f1c8b975
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
In cleanupLegacyAgentSkillDirs, re-add the branch that extracts the final segment after `-ce-` from a compound agent name and seeds `ce-<final-segment>` as a legacy-cleanup candidate. The branch was removed in 25f1c8b as dead code for compound-engineering itself, but it's load-bearing for nested-layout third-party plugins passed through the CLI: their agent names keep the `<category>-ce-<name>` shape, and without the split a stale `~/.codex/skills/<plugin>/ce-<name>/` directory from a prior flat-alias install is never swept. For compound-engineering the branch remains inert (names don't contain embedded `-ce-`), so this is purely additive coverage for other shapes. Guard the split on `agent.name.includes("-ce-")` so no-op candidates are not seeded for flat-only layouts. Add a comment naming the cross-layout-migration intent so the branch isn't flagged as dead code again. Regression test in tests/codex-writer.test.ts pins the behavior against a nested-layout bundle. Addresses PR #621 review feedback. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Agent references are now plain
ce-<agent-name>— one canonical form, not a category-qualified<category>:ce-<agent>namespace tied to directory layout. All 50 agents live flat underplugins/compound-engineering/agents/. Codex TOML filenames drop the category prefix too (review-ce-correctness-reviewer.toml→ce-correctness-reviewer.toml).Previously, the category segment was structural coupling: the Codex converter rebuilt it from each agent's
sourcePath, and 117 references across 16 files had to stay aligned with the six subfolder names. Flattening removes the coupling — the filename is the identifier, and there is one canonical reference form.Why these commits ship together
refactor(agents): flatten agents directorygit mvrenames out of six category subfolders into flatagents/. No content change.refactor(agents): rewrite category-prefixed refs to bare ce- formrefactor(agents): update AGENTS.md conventions for flat layoutAGENTS.mdand pluginAGENTS.md— agent-reference convention, Directory Structure, Naming Convention, Adding Components.feat(codex): clean up orphan sidecar dirs for retained agentssrc/targets/codex.ts: for retained agents with nosidecarDirs, delete any same-basename sibling directory underagentsRoot. Gated byisSafeManagedPath. Three new tests.refactor(tests): update fixtures for flat agents layoutsourcePathfixtures. New test pins the nested-layout dead-code fallback. Dead-ce-split branch incleanupLegacyAgentSkillDirsremoved.A partial landing would break things: moving files without updating references would leave the Codex converter unable to resolve source
<category>:ce-<agent>refs (the new flat-layout converter no longer registers those aliases); updating references without moving files would leave 50 agents in subfolders that the convention no longer documents; and flipping the convention docs without both would hand contributors contradictory guidance.Design decisions
ce-prefix alone carries uniqueness. The category segment was redundant defense-in-depth against short-name collisions across plugins — thece-prefix already prevents them. Dropping the category tier removes a fake hierarchy without weakening the actual guarantee.getAgentCategory()stays as dead-code fallback. Compound-engineering won't exercise it, but any third-party plugin passed through the CLI that still uses subfolders continues producing<category>-ce-<agent>Codex names. A test intests/codex-converter.test.tspins the behavior; deletion is deferred.cleanupRemovedAgentsinsrc/targets/codex.ts) sweeps the 50 stale<category>-ce-<agent>.tomlfiles on nextbun install --to codex, including same-name sibling directories. A fresh install converges on the new names without a compatibility alias.cleanupRemovedAgentsonly removed sidecar dirs when the TOML itself was being removed — a same-name agent that lost its sidecar left an orphan indefinitely. The new sweep runs for every retained agent that declares zerosidecarDirs, closing that gap for future cases.Test plan
bun test— 830 pass / 0 failbun run release:validate— no drift (compound-engineering currently has 50 agents, 45 skills, 0 MCP servers)bun install --to codexagainst a working Codex install — the 50 prior<category>-ce-<agent>.tomlfiles were removed, theresearch-ce-session-historian/orphan sidecar directory was removed, 50 barece-<name>.tomlfiles were written, the install manifest lists the new namesbun install --to codexon your own Codex install to verify the rename-and-cleanup path behaves the same against your manifest statece-<name>references resolve correctly for you in Claude Code — there is no programmatic test that proves the runtime subagent resolver accepts bare names; the refactor depends on itNotes for reviewers
The pre-implementation doc review surfaced seven P2 concerns that were deliberately not resolved in this PR (concrete triggering incident,
ce-as a reserved prefix across the marketplace, upgrade-archetype enumeration, and so on). They live under### From 2026-04-21 reviewindocs/plans/2026-04-21-001-refactor-flatten-agents-directory-plan.md— worth a glance if any are blocking for you.Plan:
docs/plans/2026-04-21-001-refactor-flatten-agents-directory-plan.md