Propose Codex Automation

Scan a repo, infer how work flows through it, and propose a short ranked plan of Codex skills, custom agents, hooks, or plugins. Propose first; scaffold only after approval.

Operating Principles

1. Skill vs agent vs hook vs plugin

• Skill: repeatable, context-rich, steerable workflow.
• Custom agent: named reusable role for isolated or parallel subagent work.
• Hook: deterministic always-on automation.
• Plugin: packaged distribution unit for Codex artifacts.

1. Placement

• Project: .agents/skills, .codex/agents, repo plugin, or repo hooks when coupled

to this repo.

• Personal/global: ${CODEX_HOME:-~/.codex} only when project-agnostic.

1. Thin artifacts

Generated skills should reference source-of-truth docs such as AGENTS.md, README, manifests, and style guides instead of duplicating them.

1. ROI

Value is frequency times time saved times error reduction. Cost is build time, maintenance, and cognitive overhead. Propose only when value clearly beats cost.

1. Restraint

Always include a "Deferred / not worth it" section.

Procedure

1. Orient

• Read AGENTS.md, CLAUDE.md if present, README, manifests, CI, and existing

.agents/, .codex/, and plugin files.

• Skim recent git history to infer repeated work.
• For a large repo, delegate broad exploration to a read-only subagent when available.

2. Ask About Pain

Ask 2-3 targeted questions only if the user's pain points are not already clear:

• What repeated repo task feels tedious?
• What multi-step task would benefit from one command?
• What should always happen but sometimes gets forgotten?

Treat scan-based ideas as hypotheses.

3. Propose

Return 2-4 ranked proposals. For each include:

• name and purpose;
• artifact type;
• target placement;
• workflow pain addressed;
• ROI rationale;
• guardrails and source-of-truth docs it should reference.

Then list deferred ideas with reasons.

4. Scaffold Only Approved Items

For each approved item:

• Use the correct Codex format and location.
• Keep instructions thin and repo-grounded.
• Add helper scripts only when deterministic reliability matters.
• Validate syntax and naming.

5. Record The Plan

Offer to save the ranked plan to AUTOMATION-PLAN.md or another user-approved path.

Guardrails

• Never build during the proposal step.
• Never duplicate source-of-truth docs.
• Keep proposed automation few and high-confidence.
• Use Codex-native paths and formats for Codex artifacts.
• Never fabricate repo facts.