Hop/wiki/Agent-Workflow.md

Agent integrations and workflow

Skill-based integration

A compatible agent skill makes prompt capture the agent's first repository action. The integration supplies a stable agent and session identity. In a POSIX shell:

hop begin --agent my-agent --session stable-session-id --heredoc <<'HOP_PROMPT_EOF'
<exact visible user message>
HOP_PROMPT_EOF

In PowerShell:

$hopPrompt = @'
<exact visible user message>
'@
$hopPrompt | hop begin --agent my-agent --session stable-session-id --heredoc

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. After acceptance, Hop automatically pushes the accepted commit when the repository has an unambiguous upstream. The agent does not ask the user to run git push.

Skill-based capture stores the agent's verbatim transcription of the visible message and its attachment references. Because the skill runs after the client 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.

Codex Desktop example

The bundled Codex integration uses CODEX_THREAD_ID as its stable session key, defaults the agent name to codex, and lets the user type normally. Its bundle is installed at ${CODEX_HOME:-~/.codex}/skills/hop; the same files are also installed at ~/.agents/skills/hop for compatible clients.

Follow-up messages

A later hop begin with the same integration 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 an agent-side skill, which can only guarantee capture before project effects.

Agent rules

• Never edit the canonical project root directly.
• Never mutate a frozen proposal.
• Inspect landing warnings. If automatic push failed transiently, retry once with hop push; never force-push a diverged remote.
• 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.