Hop
7139b9e1a7
Hop-State: A_06FN6FF8HFSFD9ANGK6BY4G Hop-Proposal: R_06FN6FDTK9G17RXFFT82ZYR Hop-Task: T_06FN6CFVXVVAP1KZAJ2X62R Hop-Attempt: AT_06FN6CFVXTRZ8ZDG28QR5Z0
96 lines
3.3 KiB
Markdown
96 lines
3.3 KiB
Markdown
# 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:
|
|
|
|
```bash
|
|
hop begin --agent my-agent --session stable-session-id --heredoc <<'HOP_PROMPT_EOF'
|
|
<exact visible user message>
|
|
HOP_PROMPT_EOF
|
|
```
|
|
|
|
In PowerShell:
|
|
|
|
```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:
|
|
|
|
```bash
|
|
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:
|
|
|
|
```bash
|
|
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:
|
|
|
|
```bash
|
|
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.
|