Stop Giving Codex Vague Tasks: Goal Commands That Actually Work

You type "refactor the auth module" into Codex CLI and get back a diff that renames three functions, deletes a test file, and somehow breaks the session middleware. The task seemed clear to you. To the agent, it was an open field with no fences.

This isn't a prompt engineering trick. It's a structural problem. Vague tasks produce vague results because agentic coding systems operate differently than chat-based assistants. They plan, execute, and iterate autonomously. Without explicit boundaries, they'll optimize for whatever interpretation of the goal is easiest to satisfy — which is rarely what you actually wanted.

The qiaomu-goal-meta-skill repository addresses this directly. It takes vague or complex Codex tasks and converts them into structured /goal commands that include outcome definitions, verification criteria, constraints, boundaries, iteration policies, and completion evidence. The approach is worth understanding even if you never install the tool, because the underlying problem — and the fix — applies to any AI coding agent.

Why Vague Tasks Fail in Agentic Coding

Chat-based AI failures are visible immediately. You see the bad answer, adjust, and try again. Agentic failures compound. The agent makes a plan based on your prompt, writes code, runs it, reads the output, decides what to do next — all without you in the loop. A vague starting point cascades into misaligned execution at every step.

Three failure patterns show up repeatedly:

Scope creep. "Add error handling to the API layer" becomes "I should also improve the types, update the documentation, and centralize the error middleware." Each step seems logical in isolation, but the agent drifts further from what you needed.

Silent success. The agent completes its interpreted version of the task, produces output that looks reasonable, and stops. You review the diff and realize it solved the wrong problem. The code works, but not for the reason you intended.

Iteration without convergence. The agent loops on changes because the completion condition was never defined. It keeps refining, refactoring, or "improving" because nobody told it what "done" looks like.

These aren't edge cases. They're the default behavior when you give an autonomous system underspecified objectives.

What a Goal Command Actually Is

A /goal command is a structured task specification that leaves no ambiguity about what the agent should do, how to verify it did the right thing, and when to stop.

Think of it as a contract between you and the agent. Not a conversation — a specification. The kind of specification you'd write for a junior developer who's competent but has zero context about your project.

The qiaomu-goal-meta-skill repository implements this as a transformation layer. You provide a rough task description, and it outputs a structured goal command with these components filled in:

• Outcome definition (what "done" looks like)
• Verification criteria (how to check the outcome)
• Constraints (what not to do)
• Boundaries (where to stop looking or acting)
• Iteration policy (how many times to retry, when to escalate)
• Completion evidence (what to show you when finished)

Each component serves a specific purpose in preventing the failure patterns above.

Structuring Outcomes and Verification Criteria

The outcome definition is the most critical piece. It answers: what does the world look like when this task is complete?

Bad: "Refactor the authentication module"

Good: "Extract session validation logic from app/middleware/auth.ts into app/auth/session_validator.ts, keeping all existing tests passing, with no changes to the public API surface"

The difference is specificity about state, not just action. The agent needs to know what the system should look like after execution, not just what to attempt.

Verification criteria turn that outcome into testable conditions:

• All existing tests in tests/auth/ pass
• app/auth/session_validator.ts exists and exports validateSession
• app/middleware/auth.ts no longer contains session validation logic
• The public API in app/middleware/auth.ts remains unchanged — same exports, same signatures

These are binary conditions. Pass or fail. No interpretation required.

This matters because agents can self-verify. Given explicit criteria, the agent can run tests, check file existence, diff exports. Without them, the agent either relies on its own judgment about what "refactored" means or asks you repeatedly — neither of which scales.

Constraints and Boundaries

Constraints tell the agent what not to do. Boundaries tell it where not to go.

Constraints prevent the scope creep problem. Examples:

• "Do not modify any files outside app/auth/ and tests/auth/"
• "Do not add new dependencies"
• "Do not change error message strings (they're tracked by monitoring)"
• "Do not alter the database schema"

Boundaries limit exploratory behavior:

• "This task applies only to the session validation path, not token refresh or password reset"
• "Only consider TypeScript files — ignore any .js files in the codebase"
• "The scope is the auth module. Do not touch user models, billing, or notifications"

Without constraints, an agent optimizing for "better code" will find things to improve everywhere. Without boundaries, it will follow import chains across the entire codebase. Both waste compute and produce diffs you have to carefully audit for unintended changes.

The qiaomu-goal-meta-skill approach handles this by making constraints and boundaries explicit fields in the goal specification, not assumptions baked into the agent's behavior.

Iteration Policies and Completion Evidence

Iteration policies answer: what happens when verification fails?

Without a policy, agents fall into one of two traps. They either give up after the first attempt (because the task said "refactor" and they refactored, even though tests are now broken) or they loop indefinitely, making increasingly speculative changes trying to get tests green.

A reasonable iteration policy might specify:

• Maximum 3 attempts to get all verification criteria passing
• On each failed attempt, read the error output before modifying code
• If all 3 attempts fail, revert all changes and report the failure with the error output

This turns the agent from a desperate fixer into a systematic debugger. It also prevents the worst-case scenario: an agent that makes 47 commits trying to fix a typo it introduced 40 commits ago.

Completion evidence is what the agent shows you when it's done. Not just "task complete" — specific artifacts that prove it:

• A list of files modified
• The test output showing all passing criteria
• A diff of the changes
• Any verification commands you can re-run

The qiaomu-goal-meta-skill structures completion evidence as part of the goal definition, so the agent knows from the start what it needs to produce.

Building Goal Commands: A Practical Example

Here's what the transformation looks like in practice. Starting from a vague task:

/goal "Fix the flaky tests in the CI pipeline"

A structured goal command from qiaomu-goal-meta-skill would expand this into something like:

{
    "outcome": "All tests in the CI pipeline pass consistently across 5 consecutive runs",
    "verification": [
        "Run the full test suite 5 times with no failures",
        "Check that no tests are skipped or marked as xfail",
        "Confirm test execution time hasn't increased more than 10%"
    ],
    "constraints": [
        "Do not remove or skip tests to fix flakiness",
        "Do not add artificial delays (time.sleep) to fix timing issues",
        "Do not modify test runner configuration without explicit note"
    ],
    "boundaries": [
        "Scope is limited to tests in the CI pipeline config and tests/",
        "Do not modify application code outside test fixtures",
        "Do not change the CI infrastructure (containers, runners)"
    ],
    "iteration_policy": {
        "max_attempts": 5,
        "on_failure": "Read test output, identify root cause, make targeted fix",
        "on_max_attempts_reached": "Revert changes, report which tests remain flaky and suspected causes"
    },
    "completion_evidence": [
        "Output from 5 consecutive successful test runs",
        "Diff of all changes made",
        "Summary of root causes found and fixes applied"
    ]
}

Is this more work to write? Yes. But it's work you're already doing — just reactively, during code review, after the agent produced the wrong thing. Structuring the task upfront shifts that effort to where it has leverage: before execution begins.

From Vague to Structured: The Meta-Skill Pattern

The repository name includes "meta-skill" for a reason. The tool itself is a skill — a reusable transformation that takes vague input and produces structured output. But it's also modeling a meta-skill: the practice of thinking about tasks as specifications rather than instructions.

This pattern composes well. You can:

• Create goal templates for recurring task types (bug fixes, features, refactors)
• Build verification scripts that encode project-specific rules
• Share goal specifications across a team so everyone's agent interactions are consistent
• Layer additional meta-skills on top — like a skill that reviews goal specifications for completeness before passing them to the agent

The repository at joeseesun/qiaomu-goal-meta-skill implements this transformation in Python, and it's written to be composable with Codex's skill system.

Applicability Beyond Codex

While this repository targets Codex CLI specifically, the pattern generalizes. Any agentic coding tool — Claude Code, Aider, Cursor's agent mode, Devin — runs into the same structural problems. The specifics of the goal command format differ, but the six components (outcome, verification, constraints, boundaries, iteration policy, completion evidence) are universally useful.

If you're using a different tool, you can adopt the same structure in your prompts or in a custom skill system. The concrete mechanism matters less than the discipline of specifying all six components before giving the agent a task.

For Codex CLI users specifically, the qiaomu-goal-meta-skill repository offers a ready implementation. Clone it, install it as a skill, and start feeding it tasks you've been struggling to get right with flat prompts. Compare the results — you'll find the structured approach produces more predictable, auditable, and correct output.

The sooner you stop treating AI coding agents like chat partners and start treating them like specification executors, the sooner you get work you can actually trust.