everyinc--compound-engineering-plugin/docs/brainstorms/2026-06-19-agentless-plugin-surface-reduction-requirements.md

title, date, topic

title	date	topic
Agentless plugin surface reduction	2026-06-19	agentless-plugin-surface-reduction

Agentless Plugin Surface Reduction

Summary

Move Compound Engineering away from standalone plugin agents and toward skill-local subagent prompt assets. Public skills should represent user-facing jobs, not convenience wrappers around specialist agents. Surviving skills that need subagents will dispatch generic subagents using prompt definitions stored inside that skill's own directory, such as references/agents/*.md or references/personas/*.md.

The goal is maximum deletion: remove redundant public skills, delete plugins/compound-engineering/agents/, and make the Codex plugin fully self-contained through native skills rather than a hybrid native-skill plus Bun-installed custom-agent setup.

Problem Frame

Compound Engineering currently defines specialist behavior in two forms:

• standalone agent files under plugins/compound-engineering/agents/
• skill-local prompt/persona files under skill references/ directories

The standalone-agent model creates portability and install friction. Codex native plugins load the CE skills, but standalone agent registration has required a second Bun install path that converts Claude Markdown agents to Codex TOML agents. That split is brittle, profile-sensitive, and prevents the Codex plugin from behaving as a normal self-contained plugin.

Other plugin ecosystems, including Superpowers, use a cleaner pattern: the skill owns the workflow and carries prompt templates for subagents in its own directory. That gives the skill custom subagent behavior without requiring a platform-level custom-agent registry.

Decisions

• Delete standalone CE agents. Remove plugins/compound-engineering/agents/ after moving still-needed behavior into surviving skills as local prompt assets.
• Delete redundant public skills. Public skills must map to real user jobs. Skills that only make an agent easy to call should be removed.
• Prefer skill-local duplication over shared agent infrastructure. Duplicating prompt text across a few skills is acceptable when it removes cross-platform agent registration and makes each skill self-contained.
• Do not preserve compatibility wrappers. This migration intentionally uses maximum deletion. Removed skills and agents go into legacy cleanup registries; no deprecated skill stubs or one-release grace wrappers.
• Keep generic converter support where it serves non-CE plugins. The CLI may still convert agents for other plugin payloads, but CE-specific Codex installation should no longer require generated custom agents.

Skill Decisions

Delete

Skill	Disposition
ce-agent-native-audit	Delete; fold useful checklist material into ce-agent-native-architecture or ce-code-review only if needed.
ce-clean-gone-branches	Delete.
ce-dhh-rails-style	Delete.
ce-frontend-design	Delete; salvage durable frontend rules into ce-work, ce-work-beta, and ce-polish where relevant.
ce-gemini-imagegen	Delete.
ce-release-notes	Delete.
ce-report-bug	Delete.
ce-sessions	Delete as a public product surface; fold discovery/extraction scripts and historian synthesis into ce-compound only for compounding/documentation workflows.
ce-slack-research	Delete; fold Slack research prompts into ce-brainstorm, ce-ideate, and ce-plan.
ce-update	Delete.

Keep

Skill	Notes
ce-agent-native-architecture	Keep as a domain guide for agent-native systems.
ce-brainstorm	Keep; localize Slack research prompt.
ce-code-review	Keep; localize code-review personas.
ce-commit	Keep.
ce-commit-push-pr	Keep.
ce-compound	Keep; absorb session-history workflow.
ce-compound-refresh	Keep.
ce-debug	Keep.
ce-demo-reel	Keep.
ce-doc-review	Keep; localize document-review personas.
ce-dogfood-beta	Keep.
ce-ideate	Keep; localize research prompts.
ce-optimize	Keep; localize research prompts.
ce-plan	Keep; localize research and deepening prompts.
ce-polish	Keep; absorb frontend-design rules where useful.
ce-product-pulse	Keep.
ce-promote	Keep.
ce-proof	Keep.
ce-resolve-pr-feedback	Keep; localize PR comment resolver prompt.
ce-riffrec-feedback-analysis	Keep.
ce-setup	Keep.
ce-simplify-code	Keep.
ce-strategy	Keep.
ce-test-browser	Keep.
ce-test-xcode	Keep.
ce-work	Keep; localize Figma/design-sync prompt if still needed.
ce-work-beta	Keep.
ce-worktree	Keep.
lfg	Keep.

Agent Decisions

Preserve as Skill-Local Prompt Assets

Agent	Destination
ce-adversarial-document-reviewer	ce-doc-review/references/personas/
ce-coherence-reviewer	ce-doc-review/references/personas/
ce-design-lens-reviewer	ce-doc-review/references/personas/
ce-feasibility-reviewer	ce-doc-review/references/personas/
ce-product-lens-reviewer	ce-doc-review/references/personas/
ce-scope-guardian-reviewer	ce-doc-review/references/personas/
ce-security-lens-reviewer	ce-doc-review/references/personas/
ce-adversarial-reviewer	ce-code-review/references/personas/
ce-agent-native-reviewer	ce-code-review/references/personas/
ce-api-contract-reviewer	ce-code-review/references/personas/
ce-correctness-reviewer	ce-code-review/references/personas/
ce-julik-frontend-races-reviewer	ce-code-review/references/personas/
ce-maintainability-reviewer	ce-code-review/references/personas/
ce-performance-reviewer	ce-code-review/references/personas/
ce-previous-comments-reviewer	ce-code-review/references/personas/
ce-project-standards-reviewer	ce-code-review/references/personas/
ce-reliability-reviewer	ce-code-review/references/personas/
ce-security-reviewer	ce-code-review/references/personas/
ce-swift-ios-reviewer	ce-code-review/references/personas/
ce-testing-reviewer	ce-code-review/references/personas/
ce-pr-comment-resolver	ce-resolve-pr-feedback/references/agents/
ce-figma-design-sync	ce-work/references/agents/ and ce-work-beta/references/agents/
ce-session-historian	ce-compound/references/agents/; move supporting scripts from ce-sessions.
ce-slack-researcher	Workflow-tuned local copies in ce-brainstorm, ce-ideate, and ce-plan.
ce-learnings-researcher	Local copies in ce-code-review, ce-ideate, ce-optimize, and ce-plan; slim per workflow if practical.
ce-repo-research-analyst	Local copies in ce-plan and ce-optimize.
ce-web-researcher	Local copies in ce-plan and ce-ideate.
ce-best-practices-researcher	Local copies in ce-plan and ce-compound, or merge with framework-docs prompt where it improves clarity.
ce-framework-docs-researcher	Local copies in ce-plan and ce-compound, or merge with best-practices prompt where it improves clarity.
ce-data-migration-reviewer	Local copies in ce-code-review and ce-plan.
ce-deployment-verification-agent	Local copies in ce-code-review and ce-plan.
ce-data-integrity-guardian	Local copies in ce-plan and ce-compound, or merge into nearby data prompts if redundant.
ce-security-sentinel	Local copies in ce-plan and ce-compound, or merge into nearby security prompts if redundant.
ce-performance-oracle	Local copies in ce-plan and ce-compound, or merge into nearby performance prompts if redundant.
ce-pattern-recognition-specialist	Local copies in ce-plan and ce-compound, or fold into repo research/maintainability prompts if redundant.
ce-spec-flow-analyzer	ce-plan/references/agents/
ce-architecture-strategist	ce-plan/references/agents/
ce-git-history-analyzer	ce-plan/references/agents/
ce-issue-intelligence-analyst	ce-ideate/references/agents/

Delete

Agent	Reason
ce-ankane-readme-writer	No runtime consumer.
ce-design-implementation-reviewer	No runtime consumer.
ce-design-iterator	Only consumed by deleted ce-frontend-design; salvage useful frontend rules elsewhere if needed.
ce-code-simplicity-reviewer	Delete as a standalone agent; preserve code simplification as an important capability owned by ce-simplify-code.

Requirements

• R1. No surviving CE skill may dispatch a standalone ce-* agent by name.
• R2. Every surviving subagent dispatch must identify a skill-local prompt asset or inline local prompt block as the source of specialist behavior.
• R3. No plugins/compound-engineering/agents/ directory remains after migration.
• R4. Deleted skills and agents are added to both legacy cleanup registries:
  • src/utils/legacy-cleanup.ts
  • src/data/plugin-legacy-artifacts.ts
• R5. Plugin README and docs catalogs no longer advertise standalone agents.
• R6. Codex docs no longer require bunx @every-env/compound-plugin install compound-engineering --to codex for CE custom agents once CE no longer ships standalone agents.
• R7. CE-specific converter tests are updated so current CE output is skills-only for Codex. Generic non-CE agent conversion coverage may remain.
• R8. bun run release:validate passes after manifest, README, and marketplace metadata are updated.
• R9. Behavioral validation for modified skills uses the repo's skill-validation path rather than stale in-session plugin agent dispatch.
• R10. Install documentation is overhauled everywhere it appears, including plugin READMEs, marketplace/catalog README content, and tracked Markdown docs, so users no longer see obsolete custom-agent install guidance.
• R11. bun test passes after converter, writer, cleanup, and plugin inventory changes.
• R12. The implementation run is tracked under a single /goal objective tied to this requirements doc so long-running work can resume without losing the source of truth.
• R13. High-risk surviving skills produce skill-eval receipts after migration, comparing revised behavior against a pre-migration snapshot where possible.
• R14. Static validation proves there are no surviving CE standalone-agent dependencies: no plugins/compound-engineering/agents/ directory, no surviving skill dispatches a standalone ce-* agent by name, and deleted artifacts are present in both cleanup registries.

Validation Strategy

Use /goal for continuity, not as the proof mechanism. The goal should reference this requirements doc and remain active until implementation, docs, cleanup registries, automated tests, release validation, and eval receipts are complete.

Skill-level evals should use skill-eval with old_skill baselines for revised skills. Snapshot each target skill before edits when possible, then run the same prompts against the migrated skill and the snapshot. Store artifacts under /tmp/skill-eval/<skill-name>/<run-id>/ with prompts, transcripts, outputs, grading, benchmark summaries, and review notes.

Minimum eval coverage:

Skill	Eval purpose
ce-code-review	Prove localized reviewer personas still produce schema-valid, confidence-gated findings on a small diff.
ce-doc-review	Prove localized document-review personas still classify requirements/plan documents, synthesize findings, and apply safe-auto fixes correctly.
ce-plan	Prove localized research/deepening prompts still produce a structured plan from a requirements doc without standalone agent dispatch.
ce-compound	Prove folded session-history support works only inside the compounding workflow and no standalone ce-sessions path is required.
ce-brainstorm	Prove localized Slack research prompt can be invoked as workflow context without the deleted ce-slack-research skill.
ce-ideate	Prove localized research prompts still ground ideas and preserve the expected artifact shape.
ce-optimize	Prove localized repo/learnings research prompts still support optimization setup without standalone agents.
ce-resolve-pr-feedback	Prove the localized PR comment resolver prompt still evaluates review feedback and emits actionable resolution guidance.
ce-work / ce-work-beta	Prove any localized Figma/design-sync prompt remains accessible where the work skills need it; explicitly state the stable/beta sync decision.
ce-simplify-code	Prove code simplification remains available even though ce-code-simplicity-reviewer is deleted as a standalone agent.

Automated validation should include:

• bun test
• bun run release:validate
• targeted static scans for removed skill names, removed agent names, stale install instructions, and forbidden standalone ce-* agent dispatches
• native Codex plugin smoke validation when the local Codex plugin install path is available; otherwise record the unavailable command/tooling as a validation gap

Open Implementation Notes

• Prefer moving agent bodies mechanically first, then slimming/merging prompts only where the consuming skill's context clearly warrants it.
• For shared prompts, duplication must happen inside each consuming skill directory. Do not create cross-skill shared files.
• The implementation plan should sequence this migration by workflow cluster to keep reviewable diffs:
  1. Delete no-consumer agents and wrapper skills.
  2. Localize ce-code-review and ce-doc-review personas.
  3. Localize planning/research prompts.
  4. Fold sessions into ce-compound.
  5. Localize remaining one-off prompts.
  6. Remove CE standalone agent install assumptions from Codex docs, READMEs, Markdown guides, and tests.
  7. Run static checks, automated tests, release validation, and skill-eval receipts for the high-risk surviving skills.