Outcome First Agent Loop

Two Agent Skills for outcome-first planning handoff, validation design, development goal setting, and independent closeout review.

• outcome-first-agent-loop: English version.
• outcome-first-agent-loop-zh: Chinese version.

The skill is intentionally instruction-only. It does not add a new command runner or orchestration framework. It acts as an overlay for existing planning, development, and review workflows so agents explain outcomes first, write validation standards into plans, set short development goals, and avoid self-passing completion without independent review.

Why This Exists

Agent development usually has three stages:

plan -> execute -> review

Execution is no longer the main bottleneck. A capable agent can often implement the plan autonomously. The bottleneck has moved to the two places where humans still have to intervene: reading the plan and deciding whether the work is actually done.

Long plan.md files are useful for agents, but humans do not want to review every detail. HTML plans are easier for humans to scan, but they are a worse source of truth for agents: they can lose implementation detail, are harder to diff precisely, and cost more tokens to regenerate and reread.

Outcome First Agent Loop keeps the full plan as the agent-native artifact, then adds a short human direction check. After that, it turns validation and goal setting into explicit handoffs: the main builder agent gets a compact goal, while independent reviewer subagents check plan coverage, code quality, real CLI/E2E evidence, and whether completion can be claimed.

For the full reasoning behind the workflow, read docs/rationale.md.

Demo

outcome-first-agent-loop-promo-github.mp4

If your Markdown viewer does not render embedded video, open the demo video.

What It Produces

This skill keeps the full plan available for the agent, but turns the human handoff into four concrete outputs:

1. A short direction check for the human: direction, boundary, risks.
2. A validation contract: what must be checked, what evidence counts, what fails.
3. A short development goal: plan source, required evidence, independent review gate.
4. A closeout review path: bounded reviewer subagents check plan coverage, code quality, real CLI/E2E evidence, and whether completion can be claimed.

Quick Start

Install the English skill:

npx skills add GRD-Chang/outcome-first-agent-loop --skill outcome-first-agent-loop -g -a codex -y

Then invoke it inside your agent session:

Use $outcome-first-agent-loop to explain this plan.
Use $outcome-first-agent-loop to design validation standards for this plan.
Use $outcome-first-agent-loop to set a short development goal from this plan.
Use $outcome-first-agent-loop to check whether this work can be closed out.

The Chinese skill is also available:

npx skills add GRD-Chang/outcome-first-agent-loop --skill outcome-first-agent-loop-zh -g -a codex -y

使用 $outcome-first-agent-loop-zh 讲一下这个 plan。
使用 $outcome-first-agent-loop-zh 设计验收标准。
使用 $outcome-first-agent-loop-zh 按 plan 开始开发前设置 goal。
使用 $outcome-first-agent-loop-zh 判断是否完成。

Install

Install either skill with the skills CLI:

npx skills add GRD-Chang/outcome-first-agent-loop --skill outcome-first-agent-loop -g -a codex -y
npx skills add GRD-Chang/outcome-first-agent-loop --skill outcome-first-agent-loop-zh -g -a codex -y

Install from a local checkout:

npx skills add /path/to/outcome-first-agent-loop --skill outcome-first-agent-loop -g -a codex -y
npx skills add /path/to/outcome-first-agent-loop --skill outcome-first-agent-loop-zh -g -a codex -y

Replace codex with another supported agent name if you are installing for a different client. Specifying the agent avoids unrelated adapter warnings on systems with multiple agent integrations.

List discoverable skills before installing:

npx skills add /path/to/outcome-first-agent-loop --list

Repository Layout

skills/
  outcome-first-agent-loop/
    SKILL.md
    agents/openai.yaml
    references/
  outcome-first-agent-loop-zh/
    SKILL.md
    agents/openai.yaml
    references/

The runtime skill folders stay clean: SKILL.md, optional UI metadata, and reference files only. Human-facing installation and maintenance notes live at the repository root.

Use

Mention the skill explicitly or let the agent invoke it when your request matches. The skill is an agent-facing workflow overlay, not a shell command you run directly.

Use $outcome-first-agent-loop to explain this plan.
Use $outcome-first-agent-loop to design validation standards for this plan.
Use $outcome-first-agent-loop to set a short development goal from this plan.
Use $outcome-first-agent-loop to check whether this work can be closed out.

Chinese:

使用 $outcome-first-agent-loop-zh 讲一下这个 plan。
使用 $outcome-first-agent-loop-zh 设计验收标准。
使用 $outcome-first-agent-loop-zh 按 plan 开始开发前设置 goal。
使用 $outcome-first-agent-loop-zh 判断是否完成。

Validate

Codex includes a local validator through the built-in skill creator:

python ~/.codex/skills/.system/skill-creator/scripts/quick_validate.py skills/outcome-first-agent-loop
python ~/.codex/skills/.system/skill-creator/scripts/quick_validate.py skills/outcome-first-agent-loop-zh

You can also verify npx skills discovery:

npx skills add . --list

License

MIT.