Hop/wiki/Agent-Workflow.md

Codex Desktop and agent workflow

Codex Desktop

Users type into Codex normally. The installed skill makes prompt capture the agent's first repository action:

hop begin --agent codex --heredoc <<'HOP_PROMPT_EOF'
<exact visible user message>
HOP_PROMPT_EOF

The agent adopts the returned HOP_STATE_ID, HOP_TASK_ID, HOP_ATTEMPT_ID, and HOP_WORKSPACE, then confines reads, commands, edits, and tests to that workspace.

The normal lifecycle is:

hop check P_... -- go test ./...
hop propose --summary "Implemented the requested behavior" P_...
hop land R_... -- go test ./...

No second landing authorization is requested unless the user explicitly asks for review-first behavior.

Desktop capture stores the agent's verbatim transcription of the visible message and its attachment references. Because the skill runs after Codex receives the message, it cannot prove byte-for-byte fidelity with the raw submission. A trusted prompt-submission hook or controller is the deterministic capture boundary.

Follow-up messages

A later hop begin with the same Codex task session checkpoints existing workspace effects, appends a new prompt state, and continues the same attempt. The user does not carry state IDs between messages.

Controller-grade capture

A harness that can persist before delivering a prompt to the model can use:

hop init
hop start --agent my-agent --heredoc <<'HOP_PROMPT_EOF'
Add password reset emails
HOP_PROMPT_EOF
eval "$(hop env P_...)"

Only deliver the prompt after hop start exits successfully. Controller-managed follow-ups use:

hop prompt --from P_... --heredoc

This provides a stronger pre-delivery boundary than a Desktop skill, which can only guarantee capture before project effects.

Agent rules

• Never edit the canonical project root directly.
• Never mutate a frozen proposal.
• Do not bypass hop land with Git reset, checkout, worktree, or manual copying.
• Run validation against immutable checkpoints and the final integrated tree.
• Let Hop merge compatible concurrent work.
• Resolve genuine reconciliation workspaces without asking the user to perform source-control mechanics, unless the underlying product intents are ambiguous.