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 while that work remains unfinished. If Hop prepares reconciliation, the session follows its fresh workspace. After the result lands, the next prompt starts a new task and attempt rooted at the latest accepted state. Completed workspaces are never reopened, and 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.