Hop/skills/hop/SKILL.md

name, description

name

description

hop

Capture local repository prompts as Hop states and perform agent work in isolated Hop workspaces. Use at the start of every Codex Desktop or CLI repository turn and follow-up, before inspecting files, running project commands, editing, reviewing, delegating, landing, or undoing—even when the user does not mention Hop. Also use whenever HOP_STATE_ID, HOP_TASK_ID, HOP_ATTEMPT_ID, CODEX_THREAD_ID, or .hop/hop.db is present.

Hop

Make prompt capture the first project action, then keep all effects inside the returned Hop workspace.

Capture the current prompt first

Do not inspect repository files, plan from repository contents, run project commands, edit, or delegate before capture. Run this from the selected project directory:

hop begin --agent codex --heredoc <<'HOP_PROMPT_EOF'
<copy the current user message verbatim>
HOP_PROMPT_EOF

Choose a different quoted delimiter if that exact delimiter appears in the message. Include visible attachment paths and references. Do not paraphrase, pre-redact, or omit a suspected credential in this one capture stream; Hop must see it to replace it deterministically before persistence. --heredoc removes only the shell-added final newline. Never copy the credential anywhere else.

hop begin performs the Desktop bootstrap:

• Initialize Hop automatically when the project has not used it before.
• Use CODEX_THREAD_ID to bind this Codex task to one Hop attempt.
• Create a prompt state and isolated workspace on the first turn.
• Checkpoint prior workspace effects and append a prompt state on follow-ups.
• Redact detected API keys, tokens, passwords, private keys, authorization headers, and credential-bearing connection strings before persistence.

Read the returned HOP_STATE_ID, HOP_TASK_ID, HOP_ATTEMPT_ID, and workspace. If capture fails or hop is unavailable, stop without project effects and report the error.

If Hop reports redactions, never repeat the credential in output, summaries, commands recorded as evidence, or proposal text. Refer to its environment variable or secret-manager name instead.

Enforce the workspace boundary

• Direct every shell command to the returned workspace.
• Use absolute paths beneath that workspace for file reads and edits.
• Never edit the selected canonical project root.
• Do not run git commit, git checkout, git switch, git branch, git rebase, git reset, git stash, or git worktree.
• Do not stage files. Hop captures every nonignored workspace change.
• Give a subagent project-changing work only after creating a distinct Hop prompt/attempt for that delegation.
• Never discard either side of concurrent work. Let Hop perform its three-way merge, then resolve only the genuine conflict hunks in the reconciliation workspace it returns.

Verify the captured state before making changes:

hop state <HOP_STATE_ID> --json
hop status --json

Execute and auto-accept

1. Inspect and modify only the Hop workspace.

2. Keep the change scoped to the captured prompt.

3. Bind validation evidence to an immutable checkpoint:

   hop check <HOP_STATE_ID> -- <test-command> [args...]
   

4. Fix failures in the live Hop workspace and rerun checks.

5. Freeze project changes as a proposal:

   hop propose --summary "<behavioral summary>" <HOP_STATE_ID>
   

6. Unless the user explicitly requested review-only mode, immediately land the proposal and validate the exact final tree:

   hop land <proposal-state> -- <final-test-command> [args...]
   

   Same-file edits with compatible hunks merge automatically.

7. If hop land reports a prepared reconciliation prompt/workspace, continue immediately in that returned workspace. Do not stop or ask the user to coordinate an ordinary code conflict:

   • adopt every returned HOP_* value and the fresh reconciliation workspace;
   • inspect every conflict candidate plus both returned proposal/current accepted states; compare their commits when a delete/rename, binary, mode, symlink, or directory conflict has no text markers;
   • resolve every conflict intelligently, preserving both compatible intents;
   • remove all merge markers;
   • run hop check with the returned prompt state (Hop requires checked reconciliation evidence before it will accept a new proposal);
   • create a new proposal and run hop land again; and
   • repeat if accepted state raced forward again.

8. Report the accepted result, validation, and remaining risks. Keep internal state and evidence IDs out of the normal response unless they help explain a failure or the user asks for them. Confirm that hop land reported the selected visible project root as synchronized.

For a read-only or informational turn, the prompt state is sufficient; do not invent a proposal when the workspace tree is unchanged.

Do not edit a frozen proposal. A user follow-up triggers this skill again; run hop begin again before acting. Session binding selects the existing attempt automatically, so the user never needs to carry state IDs.

Auto-accept by default

The captured task prompt authorizes accepting the local project changes needed to complete that task. Do not ask for separate landing permission and do not capture a second prompt merely to land. After checks pass and the proposal is frozen, run hop land as part of the same turn.

Use the strongest relevant final validation command. If the task truly has no runnable validation, hop land <proposal-state> is allowed and the final response must say that acceptance was not validated by a command.

Stop before acceptance only when:

• the user explicitly says review first, proposal only, do not land, or otherwise asks to approve the result before it is accepted;
• validation fails;
• Hop reports visible-root divergence; a conflict has genuine product ambiguity that cannot be resolved from both recorded intents; or
• acceptance would require a destructive, external, or out-of-scope action not authorized by the captured task.

Ordinary textual overlap is not a reason to stop. Hop first performs a real three-way content merge; genuine unresolved hunks enter the automatic reconciliation loop above. Preserve and report a block only when the intents are product-level incompatible, required validation cannot be repaired, or safe continuation needs new user authority. If visible-root synchronization is blocked, do not bypass it with hop accept, force checkout, reset, or file copying. Preserve the proposal and identify the user-owned paths that must be resolved. hop accept is reserved for an explicitly controller-only workflow; Desktop work always uses hop land. Use hop undo only after a separately captured, explicit user request.

Read references/protocol.md for state semantics, exit codes, recovery, and controller-grade pre-delivery capture. Skill-driven Desktop capture is a pre-project-effect boundary; it does not claim the prompt was stored before Codex received it.