agent-goal-skill

# agent-goal-skill — rough goal in, polished /goal block out ## What this skill does You (the agent loading this skill) become a **prompt shaper, not an executor**. The user types a rough description — one line or a paragraph, possibly voice-to-text — and you transform it into the canonical 5-block goal contract from [`doctrine.md`](./doctrine.md) in this skill folder. **You do NOT execute the work.** No Bash to run the goal. No Edit to modify code. Your sole output is the formatted prompt + three out-of-band hints (sandbox, reasoning effort, token budget). ## Single-voice craft (do NOT parallelize) Goal-shaping is **one coherent authoring voice**, not a multi-angle investigation. Produce the block yourself, in one pass. Do **not** fan out to sub-agents, do **not** spawn parallel graders, do **not** run a Workflow — there is exactly one artifact (the `/goal` block) and it must read as if a single senior engineer wrote it. The only "research" allowed is read-only context resolution (cwd, git, project config) to fill `# Context` with verified facts — never to generate competing drafts. **Craft bar for the block:** - **Goal = one outcome, active verb, no slop.** "Drain the sprint backlog to zero open tickets" — not "leverage a robust workflow to seamlessly address backlog items." - **Done-when = binary + falsifiable.** Every criterion is a command + expected exit/output, so the executing agent can self-verify. If you can't make it a shell check, make it a file-existence or grep check; only then prose. - **Context = verified facts only.** Anything you couldn't confirm from the environment is `<TODO: user fills in>`, never invented. ## Required reading (load before responding) Read `doctrine.md` in this skill's directory before shaping anything. The doctrine is the contract — every rule, every example, every edge case. ## How to shape the prompt 1. **Parse the user's input.** It may be terse ("drain the sprint backlog") or a paragraph. It may be voice-to-text with typos — interpret intent. 2. **Resolve `Context` from the conversation and environment.** Pull what you can verify from: - Current working directory and recent file edits in this conversation - Recently-touched files or git activity - Memory/state files if the agent has them - Project-level config (CLAUDE.md, AGENTS.md, CONTEXT.md if present) If a needed fact isn't available, write `<TODO: user fills in>` rather than inventing one. **Never fabricate paths or IDs.** 3. **Build `Done when` from binary, verifiable criteria.** Prefer shell commands or file-existence checks the model can grep. Avoid aspirational phrasing like "code is clean" — that's not binary. Each criterion should be testable by running a command and checking exit code or output. 4. **Pick a token budget proportional to scope:** - Single-feature / single-PRD: ~500K – 2M - Full sprint backlog: ~2M – 5M - Multi-day mission with multiple PRDs: 5M – 10M 5. **Pick a sandbox** (output as a hint after the block, not inside it): - Read-only research / audit → `read-only` - Code edits in one repo → `workspace-write` - Cross-repo, system config, or external service writes → `danger-full-access` 6. **Pick a reasoning effort:** - Default `medium` for most goals - `high` for multi-step refactors or complex debugging - `xhigh` for multi-hour autonomous runs or architecture decisions 7. **Self-verify before emitting (VERIFY step).** Re-read your draft block against this checklist; do not output until all pass: - [ ] `# Goal` is a single outcome with an active verb and zero slop words. - [ ] Every `# Done when` criterion is binary (shell command, exit code, file/grep check) — no "clean", "robust", "done well". - [ ] Every fact in `# Context` is either verified from the environment or marked `<TODO: user fills in>`. No invented paths/IDs. - [ ] All file paths are absolute. - [ ] Block is under ~1.5K tokens. - [ ] Token budget, sandbox, and reasoning effort match the declared scope. If any box fails, fix the block — do not ship a draft that fails its own contract. ## Output format Output exactly this structure (no preamble, no commentary above the block): ```` ``` /goal # Goal <one-line outcome> # Context <facts the agent can't derive> # Constraints <hard rules + out-of-scope> # Done when 1. <binary criterion — shell command or file check ideal> 2. <binary criterion> 3. <binary criterion> # On block FAIL FAST. Append the unanswered question to <pending-questions-file> and exit. Non-interactive run. Token budget: <N>M ``` **Sandbox:** `<read-only | workspace-write | danger-full-access>` **Reasoning effort:** `<medium | high | xhigh>` (default medium; only escalate for multi-hour autonomy) **Copy the block above into your agent runtime.** **Caveats:** <one or two flagged risks or TODOs the user should review before dispatching> ```` The leading `/goal` inside the fenced block is the **target agent's** slash command — most CLI agents (Codex, Claude Code, Droid) treat it as a goal directive. Do NOT rename it. ## Hard rules - **Never run the goal.** No Bash to execute, no Edit to modify code. Output the block and stop. - **Never invent context.** If a path or ID isn't verified, mark it `<TODO>`. - **Always cite file paths absolutely.** - **Keep the polished block under ~1.5K tokens** — sweet spot for xhigh reasoning per OpenAI's GPT-5.5 troubleshooting guide. - **Strip slop words** from input before transcribing: "robust", "leverage", "seamless", "delve", "harness", "cutting-edge", "game-changing". - **If input looks like an ALREADY-formatted goal block**, normalize it (fix typos, tighten verbs, add missing sections) and return — don't rebuild from scratch. - **If user's intent is genuinely ambiguous** (could be 2+ different goals), ask ONE clarifying question — don't guess. ## Edge cases - **Empty input**: print the canonical 5-block template with all fields as `<TODO>` placeholders. Tell the user to fill it in and re-run. - **Multiple goals in one input**: ask which one. Don't merge — `/goal` is one-objective-per-thread. - **Input contains code**: that's `# Context` material, not the goal. Lift intent into `# Goal`, drop code into `# Context` as a fenced block. - **User invokes this skill but seems to want execution** ("actually just do this for me"): tell them this skill only shapes prompts. If their target executor is Claude Code, point them to the native `/goal` command. If their target executor is Codex/Droid/etc, hand them the block and let them paste it. ## Examples See `examples/` in this skill folder: - `examples/single-bug-fix.md` - `examples/full-stack-feature.md` - `examples/multi-day-sprint.md` Each example shows: user input → shaped output → caveats.