# Codex Task Brief Runbook

## Project Context To Prepare
- Project goal
- Current repository or workflow context
- Goal
- Repo context
- Files involved
- Constraints
- Acceptance criteria

## Input Template
Project:

Goal:

Current context:

Constraints:

Available files, notes, or data:

Expected output:
- Task brief
- Requirements
- Non-goals
- Acceptance checks

## Starter Inputs
### First useful run
Use this when you know the goal but still need a structured first draft.

Create a Codex brief for adding saved filters to a Next.js agent directory using localStorage only.

Context:
- Current state:
- Constraints:
- Audience:
- Success criteria:

### Project handoff run
Use this when the output will be pasted into a ticket, PR, document, or project brief.

Goal: produce Task brief for a real project.
Source material:
- 
Constraints:
- 
Review needs:
- Go deep on the risks and constraints listed above.
- Mark assumptions.
- Flag missing context.

### Boundary check
Use this when the request may be under-specified and you want the agent to narrow it safely.

Plan a vague redesign request where the user only says the agents page should feel better.

Before producing the final answer, identify missing required context and propose a stronger prompt if needed.

## Setup Context Notes
- Prepare the goal, known files, acceptance criteria, non-goals, and validation commands before running it.
- Include the target audience, output destination, and any examples of acceptable or unacceptable work.
- Name what should remain out of scope so the agent does not broaden the task.

## Good Input Example
Goal: add an installable-only filter to the agents page.
Repo context: Next.js App Router, agent search lives in src/components/agents/agent-search-panel.tsx and filtering lives in src/lib/search.ts.
Constraints: keep static data, no URL persistence in this pass.
Acceptance criteria: checkbox filters installable agents, clear filters resets it, build and data checks pass.

## Weak Input Example
Make the agents page better for Codex.

## Weak Input Diagnostics
### Help me with Codex Task Brief.
- Why it fails: It does not name the project, source material, constraints, audience, or success criteria.
- Stronger input: Create a Codex brief for adding saved filters to a Next.js agent directory using localStorage only. Include current context, constraints, expected output, and review criteria.

### Make this better.
- Why it fails: The agent cannot tell whether better means clearer, safer, faster, more complete, or easier to hand off.
- Stronger input: Improve the output for Coding handoff. Optimize for Task brief, keep assumptions explicit, and list the changes made.

## Expected Output Shape
- Goal in one or two sentences
- Context: only the repo facts the coding agent needs
- Numbered, testable requirements, with anything added under "Suggested (not required)"
- Non-goals
- Acceptance checks: commands and observable results
- Open questions, only when something blocks implementation

## Output Checklist
- Every constraint, edge case, and risk named in the request has an exact rule and a matching acceptance check
- Requirements include only what the user asked for
- Non-goals are explicit
- Assumptions are marked [ASSUMPTION] and nothing is invented
- Risky actions (production data, deploys, skipping tests) stay with a human

## Failure Modes
- The brief invents file paths, APIs, or behavior
- Acceptance checks are taste preferences instead of observable results
- Non-goals are missing, so the coding agent widens the scope
- Risky steps (production data, deploys, skipping tests) are handed to the coding agent

## Handoff Tips
- Paste relevant project files, notes, or constraints before asking for the final output.
- Ask for a first draft, then request a stricter revision using the checklist.
- Keep the generated output with the project ticket, PR, proposal, or team document.