| name | propose-automation |
| description | Scan the current repository, infer its workflow, and propose a short, ranked, high-ROI plan of Codex skills, custom agents, hooks, or plugins tailored to it; scaffold only approved items. Global and project-agnostic. Trigger when the user says "what Codex skills should this project have", "propose automation", "set up skills for this repo", "scaffold agents/hooks", "plan Codex automation", or "what should I automate". |
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
- 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.
- 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.
- Thin artifacts
Generated skills should reference source-of-truth docs such as
AGENTS.md, README,
manifests, and style guides instead of duplicating them.
- 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.
- 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.
