RayShark/codex-goal-writer

Codex Goal Writer

Create one paste-ready Codex /goal command that a future Codex thread can execute without relying on fragile conversation memory. Do not start the goal or implement the work unless the user explicitly asks.

Output Contract

Default output:

1. Assumptions with at most 5 bullets, only if assumptions matter.
2. Ready to copy with one fenced code block containing exactly one /goal ... command.
3. Notes with at most 3 bullets explaining key design choices or remaining risks.

If the user asks for only the command, output only the fenced code block.

The command prefix must be /goal. The body may use the user's language.

Official Constraints

• Treat /goal text as both starting prompt and completion criteria.
• Keep the objective non-empty and under 4,000 characters.
• For long instructions, write or reference a markdown file and keep the /goal short.
• If /goal is unavailable, mention enabling [features].goals = true or codex features enable goals.
• Do not invent unsupported slash flags such as /goal --tokens. If a budget is useful, express it as a textual stop or pause condition.

Decision Flow

1. Existing Plan Or Markdown Plan

Use this path when a plan, PRD, issue, OpenSpec/OSpec change, PLAN.md, GOAL.md, tasks.md, or implementation document is mentioned or obvious.

Rules:

• Include the exact path in the command, preferably repo-relative.
• Tell Codex to read the plan first and treat it as the source of truth.
• Add an anti-forgetting clause: re-read the path before continuing after context compaction, resume, or uncertainty.
• Include the requested slice if the user only wants part of the plan.
• Keep detailed task lists in the file, not in the /goal text.

Shape:

/goal Execute the implementation plan at <path> as the source of truth. Read it before changing files and re-read it after any context compaction, resume, or uncertainty. Complete <full plan or slice>, preserve <constraints>, verify with <checks/evidence>, and stop with a blocker report if <blocked conditions>.

2. Useful Conversation Context

Use this path when prior turns define the task.

Rules:

• Latest user instruction wins over older context.
• Preserve explicit constraints: read-only, no edits, no commits, specific files, no new dependencies, required tests, review-only, language, or output format.
• Include exact file paths, commands, issue IDs, PR links, and artifact paths when known.
• Ignore stale prior intentions that conflict with the latest request.

Shape:

/goal <latest intended outcome>, using the current conversation only as background. Scope: <files/subsystems>. Constraints: <must preserve>. Done when: <verifiable criteria>. Verify by <commands/evidence>. Stop if <blocked conditions>.

3. No Useful Context

Use this path when the user asks for a goal but has not supplied a concrete task.

Rules:

• Do lightweight discovery only: current directory, repo name, README*, AGENTS.md, CONTEXT.md, obvious plan docs, package manifests, and test scripts.
• Do not invent product direction.
• Generate a discovery-first, small closed-loop objective.
• Prefer "discover -> choose one highest-value narrow issue -> fix or document -> verify" over "optimize the whole project."
• If there is no repo or safe target at all, ask one concise question or output a repo-agnostic discovery goal.

Shape:

/goal In <path>, inspect the current project state, identify the highest-value small actionable issue or optimization opportunity that can be verified locally, complete one conservative closed-loop improvement, preserve unrelated work, verify with the relevant discovered checks, and report evidence plus remaining follow-ups. Stop if no safe verifiable target is found or required context is missing.

Goal Anatomy

Every strong goal should contain these ideas, using compact labels:

• Objective: concrete end state, not an activity.
• Scope: files, folders, subsystem, issue, plan path, or discovery area.
• Constraints: what must not change.
• Boundaries: allowed writes, forbidden paths, external services, production data, credentials, or destructive operations.
• Done when: measurable acceptance criteria.
• Verification: commands, logs, artifacts, screenshots, benchmark thresholds, CI checks, or source-backed citations.
• Iteration policy: how to react to failures, how many focused improvement rounds, and when to re-check.
• Stop/Pause if: concrete blockers, conflicting requirements, missing credentials, unsafe scope expansion, unavailable environment, repeated failed verification, or human decisions.
• Output evidence: final summary must include what changed, evidence, commands run, failures, residual risk, and next steps.

For research-only goals, require claim-to-evidence mapping, file/URL citations, uncertainty labels, and no code edits unless explicitly allowed.

Quality Gates

Before showing the command:

• Ensure a fresh Codex session could act without hidden context.
• Ensure the latest user intent is represented.
• Ensure plan/doc paths are included when available.
• Ensure the goal is finite and auditable.
• Replace vague terms such as "improve", "optimize", "clean up", "全部", "彻底", "everything", or "make it good" with measurable criteria, or state the assumption.
• Use exact commands when known; otherwise say "discover and run the repo's relevant documented checks."
• Do not leave placeholders like <path>, [TODO], TBD, or 待定 in final copyable output.
• Do not allow broad permissions such as "edit anything" unless the user explicitly requested that and risk is low.
• Do not claim success from budget exhaustion, time spent, or absence of obvious errors.

If the goal is weak, ask at most 3 targeted questions. If missing details are low-risk, make assumptions and proceed.

References And Tools

• Read references/examples.md when the case is ambiguous or the user wants variants.
• Read references/source-patterns.md when explaining the design rationale or comparing practices.
• Use scripts/lint_goal_command.py when auditing a saved goal file or when you can cheaply validate a drafted command.