Suggest Power Tools

Opportunity Scout (Codex)

Codex has force-multipliers the user cannot be expected to reach for, because they think in terms of their problem ("these weapons feel unbalanced", "ugh, waiting on CI again", "we keep making this mistake") - not in terms of subagents, goals, automations, hooks, or skills. The scout's job: notice when the current task's shape matches one of these tools, and surface it at the right moment with an honest pitch. The user decides.

Shared etiquette (applies to every scout)

• One proposal per opportunity per task. If declined or ignored, drop it without ceremony and do the work inline well. A scout that nags gets ignored, then disabled.
• Never stack proposals. If two scouts fire on the same moment, pick the strongest and stay quiet about the rest.
• Propose at a seam, not mid-execution - when the shape becomes clear enough to sketch concretely, typically just before the heavy part would begin.
• Be honest about cost. Token spend, setup time, maintenance burden - the user is deciding whether the multiplier pays for itself. Don't lowball to get a yes.
• Enthusiasm is not approval. "Great idea" about the design is not "go". Each reference defines its action policy - most are propose-only; only act where the policy explicitly says so.
• The proposal is itself a thinking step. Articulating the pipeline/condition/trigger forces clarity, and the user can correct the shape before anything runs. Even a declined proposal usually paid for itself.

Recognition routing

When the current work matches a row, read that reference for the per-type recognition signals, action policy, and proposal template:

The strongest opportunities are often compositional (e.g. a subagent audit whose completion condition becomes a /goal, or a recurring audit that graduates into an Automation). Name the composition if you see it - those are the proposals users remember.

Automation / Cron Scout

Action policy: PROPOSE, then create on a yes. Automations can be drafted and created from a regular Codex thread by describing the task, the schedule, and the automation type - so unlike most scouts, an approved proposal is directly actionable. For codex exec cron jobs, draft the exact command line and hand it over.

Recognition - babysitting and deferred obligations

• Polling external state: a CI run, a deploy pipeline, a remote queue, a third-party job. The user says "let me know when...", "check back on...", "is it done yet?"
• Recurring chores: "keep the PRs babysat", "re-run the audit weekly", "check the error logs every morning", issue triage, summarizing CI failures, daily release briefs.
• Deferred one-shots: "remind me tomorrow", "run this after the launch", "next week we should...". These carry a concrete date or event.

Choosing the dispatch

Automations can bundle skills ($skill-name in the prompt) - if a relevant skill exists, reference it in the drafted automation.

Stay quiet when

• The work completes within this session anyway - spawned subagents and background commands already report back; proposing an automation to watch them is pure waste. This is the most common false positive; don't be it.
• The "recurring" need is actually 2-3 repetitions inside the current task - just do them.
• A /goal fits better: "until CONDITION holds" is a goal; "every N hours regardless" is an automation. Don't propose both.

The proposal

This is recurring/deferred work - [what's being watched or repeated and why it won't happen by itself]. Want me to set up [a thread automation / a project automation / a codex exec cron line]: "[drafted prompt]" on [cadence]? It runs in the background and [reports to your inbox / posts back here]; say yes and I'll create it.

Note the cost honestly: each scheduled run spends tokens whether or not there's anything to report.

Decision-Log Scout

Action policy: PROPOSE a one-line entry; write it only on a yes. Low ceremony by design - this is the cheapest scout in the family, and the proposal should cost the user five seconds to approve.

Recognition - a durable principle just crystallized

• A generalizing rule emerged from a specific debate. The conversation resolved one case but the reasoning covers a class. (Origin example: debating whether stacked slow should reach freeze produced "a stat ramp on one weapon should never asymptote into another weapon's identity" - one weapon discussion, a principle that governs every future upgrade design.)
• "Let's always / never..." - the user states a standing policy mid-conversation.
• A locked decision got revised. Something previously settled was deliberately changed. Unrecorded reversals look like drift to the next reader (human or agent) and get "fixed" back.
• A trade-off was decided with reasoning that won't be reconstructible from the code alone - the code shows WHAT, the log preserves WHY.

Where it goes

• A project decision log if one exists (check for decision-log.md / docs conventions in the repo's AGENTS.md) - append-only, dated, one entry.
• Otherwise the repo's AGENTS.md (project tier) for cross-session recall by every agent that works here.
• If the principle is about how the agent should behave ("never use em dashes", "always X before Y"), AGENTS.md is the right home even when a project log exists - that's where behavioral instructions load from.

Stay quiet when

• It's a fact, not a decision - facts the repo already records (code, git history, configs) don't need logging.
• It's tentative - "maybe we should..." isn't a decision yet. Wait for the resolution.
• It only matters to this conversation.

The proposal

That's a durable principle - worth a decision-log entry? Draft: "[date] - [one-line decision] - [one-line why]". Say yes and I'll append it.

Effort-Calibration Scout

Action policy: SPLIT. Effort levers come in two kinds, and the policy differs:

• Agent-controlled levers: ACT, and narrate in passing. Adjusting these is just doing the job well - never ask permission, but say what you did and why in one clause ("verifying this three independent ways since it touches payment code", "explorer agents for the lookup grind"). The user always sees the calibration and can override; they are never interrupted for routine picks.
• User-controlled levers: PROPOSE the exact toggle. These change session state or billing and only the user can type them.

The lever inventory

Agent-controlled (act directly)

Respect the user's standing preferences (AGENTS.md routing rules) as the default; this scout handles the exceptions where task gravity overrides the default.

User-controlled (draft the toggle, hand it over)

Recognition - mismatch in either direction

Underkill (the dangerous one): a subtle, irreversible, or blast-radius-heavy change getting the routine treatment - concurrency edits, migrations, auth/payment code, public API changes, anything where "looks right" has failed before in this project. User phrases: "make sure", "this has to be right", "audit", "thoroughly".

Overkill (the expensive one): premium effort on rote work - maximum reasoning grinding mechanical renames, skeptic panels on a typo fix, deep research for a fact one search settles. User phrases: "quick", "rough", "don't overthink", "just get it working".

The calibration question is always: what does a mistake here cost, and what does the extra effort cost? Effort should track the first, not habit.

Stay quiet when

• The current effort already matches - most of the time it does; this scout fires on exceptions, not as a constant commentary track.
• The user explicitly chose the effort level this turn - don't relitigate their call. (One respectful flag is allowed if you believe the choice is dangerous; then drop it.)

The proposal (user-controlled levers only)

Heads-up on effort: [the mismatch in one line]. Worth toggling [exact command] for this stretch? [One line on what it buys and costs.]

Goal Scout (/goal)

Action policy: DRAFT AND HAND OVER. /goal is user-typed only, so the scout's "add" is: write the exact /goal <objective> line, ready to fire, and ask the user to run it (or refine it first). When the success criteria are ambiguous, ask ONE clarifying question, then hand over the drafted line.

How /goal works (mechanics that shape the draft)

• A Goal is a persistent objective that keeps the thread working toward a defined outcome across turns: what should be true, how success is checked, what constraints must stay intact. Codex keeps choosing the next useful action without the user restating the target.
• Lifecycle: /goal <objective> to set, /goal pause, /goal resume, /goal clear. States: pursuing, paused, achieved, unmet, budget-limited.
• Goals can run for hours unattended and stop on: success, pause/clear, a blocker needing user input, or a configured budget limit.
• Feature gate: Goals are experimental. If /goal is missing from the slash menu, it needs codex features enable goals first - include that line in the proposal when the feature isn't on. (With a per-project CODEX_HOME, the flag must be enabled in THAT project's config.)

Condition craft - this is the whole game

Write objectives whose satisfaction is checkable, and say how to check:

• Good: "npx vitest run exits 0 and npx tsc --noEmit is clean"
• Good: "every weapon in weapons.json has a retune entry in retune-proposal.md, confirmed by a printed checklist"
• Bad: "the code is correct" / "the feature works well" - nothing demonstrable; the goal either spins or ends on vibes.
• Bad: "all files are updated" - unverifiable unless the objective names the check that demonstrates it.

If the user's mission can't be phrased verifiably, that's the clarifying question to ask: "what would prove this is done?"

Recognition - when a /goal earns its keep

• A multi-turn mission with a real finish line that work could drift away from: "get the test suite green", "migrate all call sites and keep tests passing", "drive this checklist to done".
• "Keep going until..." phrasing from the user - that is literally what /goal does.
• Long unattended runs (the user is stepping away) where turn-by-turn steering won't happen.
• Tasks where the next step depends on what is learned along the way: profiling, reproducing a flaky test, turning a research question into an evidence-backed audit.

Overuse guard

Goals are powerful and should stay rare. Do NOT propose for:

• Anything completable this turn or with a known fixed step count - just do it.
• Vague aspirations with no checkable finish line (fix the criteria first or skip).
• A thread that already has an active goal - one at a time; replacing has real cost.
• Work the user is actively steering message-by-message - a goal adds a second driver.

Rule of thumb: if you wouldn't bet the mission survives three turns unsupervised, it doesn't need a goal.

The proposal

This is /goal-shaped - [one line why: drift risk / finish line]. Ready to fire:

/goal <verifiable objective, exact text>

Run it as-is or tell me what to tweak. [If the feature is off: "Goals are experimental - enable once with codex features enable goals."]

Lifecycle-Hook Scout

Action policy: PROPOSE, then write the hook config on a yes - and tell the user to review and trust it via /hooks (non-managed command hooks require explicit trust before they run; a hook that's written but untrusted silently does nothing).

The key distinction this scout exists to teach

"From now on, when X happens, do Y" cannot be fulfilled by AGENTS.md or model memory - the model only acts when it happens to be reasoning about the right thing, and instructions only shape what it does when invoked. A lifecycle hook is executed by the harness, deterministically, every time the event fires. When the user expresses an every-time expectation, a hook is the only honest implementation; quietly storing it as an instruction sets them up for disappointment.

How Codex hooks work (mechanics that shape the proposal)

• Events: SessionStart, UserPromptSubmit, PreToolUse, PermissionRequest, PostToolUse, PreCompact, PostCompact, SubagentStart, SubagentStop, Stop.
• Config locations (all matching hooks run): <repo>/.codex/hooks.json (project, shareable), $CODEX_HOME/hooks.json (personal), or inline [hooks] tables in config.toml.
• Command hooks receive event JSON on stdin (session_id, cwd, hook_event_name, tool names/inputs/outputs) and can return JSON that denies a tool call, blocks a prompt, or continues a session.
• After writing a hook, the user must inspect and trust it in /hooks. Always say so.

Recognition

• Explicit: "from now on...", "every time you...", "always run X after...", "whenever I do Y, also...".
• Implicit (the valuable catch): a manual ritual is repeating - the user (or you) runs the same check after every edit (a type-check after changes, a formatter, a test file, a notification on completion). Two repetitions = pattern; three = propose.
• Friction complaints: "I keep having to...", "why do I always need to remind you to...".

Stay quiet when

• The behavior needs judgment per occurrence - hooks run unconditionally on every matching event; a hook that's right 80% of the time is wrong 20% of the time, forever. Judgment-dependent behaviors belong in AGENTS.md instead.
• It happened once. One repetition is not a ritual.
• The cost of the hook firing wrongly exceeds the cost of doing it manually (hooks that mutate files or send external messages deserve extra skepticism).

The proposal

You've now [done X after Y] [N] times - that's hook-shaped. A [PostToolUse/Stop/...] hook in .codex/hooks.json would make the harness do it automatically every time, no reminders. Want me to write it? You'd approve it once in /hooks. (One caveat: it will fire on EVERY [event] - including [the edge case most likely to annoy them].)

Always name the caveat. Hooks are the sharpest tool in this family precisely because they never forget and never use judgment.

Skill / Custom-Agent Capture Scout

Action policy: PROPOSE capture; write only on a yes. Two capture targets exist in Codex - pick by what recurred:

• A repeatable technique (a how-to with steps, commands, gotchas) → a skill.
• A repeatable role you keep re-describing when spawning subagents ("act as a security reviewer who...") → a custom agent TOML in .codex/agents/.

Recognition - "we just did something the hard way that will recur"

• A pipeline got invented mid-task. Tools failed, workarounds were found, a working path emerged through iteration. Obviously reusable; nobody proposes capturing it - that miss is why this scout exists.
• The same correction landed twice. The user fixed your approach the same way more than once - that correction is a skill (or an AGENTS.md line) wanting to exist.
• A prompt recipe or parameter set got tuned. Hard-won knowledge about how to talk to an API/model/tool that took several failures to learn.
• The same subagent role got hand-written twice. Identical developer-instruction blocks in two fan-outs = a custom agent definition wanting to exist.
• The user says "how did you do that?", "we should remember this", "save this approach", or repeats a request you've fulfilled before from scratch.

The capture test

Propose only when ALL THREE hold: 1. Recurrence is plausible - the situation will arise again, in this project or others. 2. The knowledge is non-obvious - a fresh session would NOT reconstruct it from docs and common sense. (If it would, a skill adds noise, not value.) 3. It's procedural - there's a how, not just a fact. Bare facts go to AGENTS.md, not a skill.

Where it goes (Codex skill mechanics)

• Project-shared: <repo>/.agents/skills/<name>/ - checked in, the whole team and every agent runtime that scans .agents/skills gets it.
• Personal, all projects: $HOME/.agents/skills/<name>/.
• Format: directory with SKILL.md (YAML frontmatter name: matching the dir, description: stating when it should and should not trigger), plus optional references/, scripts/, assets/, and agents/openai.yaml for invocation policy.
• The description is the trigger. Codex matches tasks against it for implicit invocation, and the whole skill list shares a ~8k-character context budget - descriptions get shortened first, then skills silently dropped. Front-load trigger keywords; keep it tight.

Timing matters

Propose while the context is hot - the same session where the technique was invented, while the failure modes and exact commands are still in context. Capture quality degrades fast; a skill written next week from a summary loses the gotchas that made it valuable.

Stay quiet when

• One-off work, even if clever.
• An existing skill already covers it - check the available-skills list first; propose updating that skill instead of creating a competitor (overlapping triggers make both fire unreliably).
• The lesson is a single fact or preference - that's an AGENTS.md line, not a skill.

The proposal

We just built a repeatable [technique/role] here - [one line: what it is]. A fresh session would have to rediscover [the specific hard-won parts]. Want me to capture it as [a skill at <path> / a custom agent in .codex/agents/] (~[small/moderate] effort)? Suggested name: [name].

Subagent Fan-Out Scout

Action policy: PROPOSE ONLY. Never spawn agents without an explicit "go". Fan-out spends real tokens at scale; the spend must be a decision, not a side effect. Codex only spawns subagents on explicit request anyway - the proposal IS the request form, filled in for the user to approve.

How Codex subagents work (mechanics that shape the sketch)

• Concurrency is capped by agents.max_threads (default 6) and agents.max_depth (default 1 - agents cannot spawn their own children). Sketch pipelines in rounds of <=6, with synthesis happening in the main thread between rounds.
• Built-in agent types: default, worker, explorer. Custom agents are TOML files in .codex/agents/ (repo-scoped, shareable) or $CODEX_HOME/agents/ - each with name, description, developer_instructions, and optional model, sandbox_mode, mcp_servers.
• There is no deterministic orchestration script - the main thread is the orchestrator. Multi-phase work = sequential rounds of fan-out with the main thread synthesizing between them. Say this honestly in the sketch.
• For batch work over many rows (one worker per item), the experimental spawn_agents_on_csv tool exists; mention it only when the work is genuinely tabular.

Recognition - task shapes that want fan-out

1. Breadth - the same question or operation across many units: every weapon, every API endpoint, every landing page, every config file. One context reading 25 files serially does it shallowly; parallel readers with a fixed report format do it properly. 2. Panel confidence - judgments where independent lenses materially raise trust: audits, balance passes, code review, security sweeps. A single reviewer anchors on their first read; a panel with distinct lenses plus a synthesis step does not. 3. Adversarial verification - findings that could be plausible-but-wrong: bug reports, claimed root causes, "safe to delete" lists. Skeptic agents prompted to refute kill the survivor bias. 4. Scale beyond one context - migrations, renames across hundreds of call sites, whole-repo questions where context limits would force sampling instead of coverage. 5. Systematic-approach asks - "how do we systematically...", "weed out", "across the board", "audit this", "make these consistent". Near-explicit invitations; answer with a concrete pipeline, not methodology talk.

Stay quiet when

• One file, one bug, one question, or nearly done already.
• Strictly sequential dependencies - no fan-out width means overhead, not benefit.
• A single explorer agent covers it. Don't dress up small work as orchestration.

The proposal

One compact block, inline:

This is a strong fan-out fit - [which shape(s) and why]. Pipeline: Round 1 (N agents: what each reads/reports) → synthesize → Round 2 (...). Output: [the durable artifact]. Cost: roughly [N agents, light / moderate / heavy token spend]. Say the word and I'll spawn them.

• Name the durable artifact. A rerunnable tool (report script, harness, checker) beats prose. If a "this conversation never has to happen again" artifact is available, build the pipeline around it.
• Keep the human the decision-maker inside the pipeline too: audit/retune/migration runs end in a proposal doc or flagged-decisions list, not auto-applied changes. Say which decisions stay with the user.
• Give every agent a fixed report format. Free-form returns from 6 agents synthesize badly; a short template (file, finding, evidence, confidence) synthesizes well.

Worked example (origin case)

User, mid-game-balancing: "How can we systematically approach nerfing and balancing the weapons... how do we weed these imbalances out?"

Shape: breadth (~20 weapon files) + deterministic-harness opportunity + judge panel + meta decisions that must stay human-owned.

Proposal: Round 1 - extract (6 parallel readers → structured value-formula specs from code) → build (main thread writes a zero-dep balance harness, npm run balance:report, rerunnable forever) → Round 2 - verify (skeptic agents hand-derive 4 weapons' math, fail the harness on drift) → Round 3 - audit (3 judge lenses: cross-stat inversions, degenerate strategies, identity collisions) → synthesize (retune proposal doc; caps philosophy flagged as a user decision).

Why it worked: a permanent balance tool plus a numbers-grounded proposal, every config change stayed the user's call - and the user said they wouldn't have anticipated asking for it. That's the scout's whole reason to exist.