GnosysLabs/GitHop
2
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

hop: initial project state

Browse Source
This commit is contained in:
Hop
2026-07-11 08:35:07 -07:00
parent ed2cba60db
commit a70773826f
14 changed files with 960 additions and 174 deletions
Download Patch File Download Diff File Expand all files Collapse all files
skills/hop/SKILL.md
+77 -77
View File
@@ -1,106 +1,106 @@
---
name: hop
description: Work safely in Hop prompt-native version-control projects. Use whenever HOP_STATE_ID, HOP_TASK_ID, or HOP_ATTEMPT_ID is set; when a repository contains .hop/hop.db; or when the user asks to use Hop to isolate, checkpoint, validate, propose, land, inspect, continue, or undo coding-agent work instead of directly managing Git branches or commits.
description: 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
Use Hop as the change-control boundary between agent work and accepted project state.
Make prompt capture the first project action, then keep all effects inside the
returned Hop workspace.
## Enforce the boundary
## Capture the current prompt first
- Require a durable Hop prompt state before making repository changes.
- Work only in the assigned `HOP_WORKSPACE`; never edit the canonical project root.
- Do not run `git commit`, `git checkout`, `git switch`, `git branch`, `git rebase`, `git reset`, `git stash`, or `git worktree`. Hop owns snapshots and worktrees.
- Do not stage files. Hop captures every nonignored workspace change.
- Do not land your own proposal unless the user explicitly requests it. Default to stopping after proposal creation.
- Never resolve an overlap by silently merging. Preserve the proposal and request or create a reconciliation prompt.
## Verify the launch context
Before planning or editing:
Do not inspect repository files, plan from repository contents, run project
commands, edit, or delegate before capture. Run this from the selected project
directory:
```bash
command -v hop
test -n "$HOP_ROOT"
test -n "$HOP_STATE_ID"
test -n "$HOP_TASK_ID"
test -n "$HOP_ATTEMPT_ID"
test -n "$HOP_WORKSPACE"
hop state "$HOP_STATE_ID" --json
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 silently merge overlapping proposals.
Verify the captured state before making changes:
```bash
hop state <HOP_STATE_ID> --json
hop status --json
```
Confirm the current working directory is `HOP_WORKSPACE` or direct every filesystem operation there.
## Execute and submit
If the Hop variables are missing, stop before editing. Explain that the controller must first run:
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:
```bash
hop start --agent <agent-name> "<exact prompt>"
```
```bash
hop check <HOP_STATE_ID> -- <test-command> [args...]
```
Then relaunch or redirect the agent into the printed workspace with the printed environment. A skill loaded after prompt delivery cannot retroactively guarantee pre-delivery recording.
4. Fix failures in the live Hop workspace and rerun checks.
5. Freeze project changes as a proposal:
## Execute the task
```bash
hop propose --summary "<behavioral summary>" <HOP_STATE_ID>
```
1. Read the prompt state and current Hop status.
2. Inspect and modify only the assigned workspace.
3. Keep the change scoped to the recorded instruction.
4. Run relevant validation through Hop so evidence is bound to an immutable checkpoint:
6. Report the prompt state, proposal state, checks, and remaining risks.
```bash
hop check "$HOP_STATE_ID" -- <test-command> [args...]
```
For a read-only or informational turn, the prompt state is sufficient; do not
invent a proposal when the workspace tree is unchanged.
5. Fix failures in the workspace and rerun the check as needed.
6. Freeze the result as a proposal:
```bash
hop propose --summary "<behavioral summary>" "$HOP_STATE_ID"
```
7. Report the proposal ID, checks run, remaining risks, and any follow-up needed. Do not continue editing the frozen proposal; later changes require another prompt and proposal.
## Handle follow-up instructions
Every follow-up instruction needs a new prompt state before effects.
- If the controller supplies a new `HOP_STATE_ID`, inspect it and continue.
- If no new state was supplied, stop before acting and ask the controller to record the exact follow-up:
```bash
hop prompt --from <current-state> "<exact follow-up>"
```
The command first checkpoints prior effects and then creates the follow-up prompt state. Continue only from the returned prompt state.
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.
## Land only with explicit authority
When the user explicitly asks to land a proposal, validate the exact final composed tree:
Capture the landing request with `hop begin` first. Then, only when the user
explicitly authorizes landing, run:
```bash
hop land <proposal-state> -- <final-test-command> [args...]
```
- On success, report the accepted-state ID.
- On overlap, do not mutate or discard the proposal. Report the conflicting paths and request a reconciliation prompt based on the latest accepted state.
- On final validation failure, preserve the failed state and evidence, then request a corrective follow-up.
- If no final test command is available, state clearly that landing will be manual and unvalidated.
## Inspect and recover
Use these commands as needed:
```bash
hop status
hop graph
hop state <state-id>
hop diff <state-id>
hop history
hop doctor
```
Use `hop undo` only when the user explicitly asks to undo the latest accepted transition. It creates a new forward state; it does not erase history.
Read [references/protocol.md](references/protocol.md) when command semantics, state kinds, exit codes, or troubleshooting details are needed.
On overlap or validation failure, preserve the proposal and report the block.
Use `hop undo` only after a separately captured, explicit user request.
Read [references/protocol.md](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.
skills/hop/agents/openai.yaml
+5 -2
View File
@@ -1,4 +1,7 @@
interface:
display_name: "Hop Version Control"
short_description: "Safely coordinate and land agent work with Hop"
default_prompt: "Use $hop to complete this coding task in an isolated Hop state and submit a validated proposal."
short_description: "Capture every coding prompt before project effects"
default_prompt: "Use $hop to capture this prompt first, complete the task in its isolated workspace, and submit a validated proposal."
policy:
allow_implicit_invocation: true
skills/hop/references/protocol.md
+38 -6
View File
@@ -4,7 +4,7 @@
```text
A accepted
├─ P prompt, persisted before effects
├─ P prompt, persisted before project effects
│ └─ C checkpoint
│ └─ R proposal
└─ P independent prompt
@@ -35,7 +35,9 @@ Prompt, checkpoint, and proposal states may reference identical Git trees while
| `HOP_ATTEMPT_ID` | Current agent approach/run |
| `HOP_WORKSPACE` | Only directory the agent may modify |
Treat missing variables as an invalid agent launch. Do not infer an attempt from a nearby worktree when causality matters.
Interactive agents may begin without these variables. `hop begin` returns the
equivalent IDs and workspace, while `CODEX_THREAD_ID` binds later messages in
the same Codex task to the existing attempt.
## Command contract
@@ -57,6 +59,9 @@ hop undo
### Agent
```bash
hop begin --agent codex --heredoc <<'HOP_PROMPT_EOF'
<exact current user message>
HOP_PROMPT_EOF
hop state "$HOP_STATE_ID" --json
hop status --json
hop check "$HOP_STATE_ID" -- <command>
@@ -69,6 +74,17 @@ hop propose --summary "<summary>" "$HOP_STATE_ID"
`hop land` compares paths changed by the proposal with paths accepted since its base. Any shared changed path blocks landing. Disjoint proposals are composed with Git three-tree plumbing and may then be validated on the final tree.
`hop begin` is the Codex Desktop entry point. It initializes Hop when necessary,
captures the current message before the agent performs project work, and uses
`CODEX_THREAD_ID` as the default session key. A later `hop begin` in the same
Codex task checkpoints the prior workspace before appending the follow-up
prompt state.
Pass the original message to `hop begin` without model-side redaction. Hop's
sanitizer replaces detected credential values before any durable write and
returns only typed redaction counts. Do not place the value in any later
command, summary, output, or source file.
## Exit codes
| Code | Meaning |
@@ -82,7 +98,17 @@ hop propose --summary "<summary>" "$HOP_STATE_ID"
A failed `hop check` or final landing check persists its evidence. A blocked or failed landing does not advance accepted state.
## Human launch sequence
## Capture modes
### Codex Desktop skill
The user types normally in Codex Desktop. The Hop skill makes `hop begin` its
first project action and then directs every operation into the returned
workspace. This is a pre-project-effect boundary: Codex has already received
the prompt, but no repository inspection, command, or modification may precede
the durable prompt state.
### Controller-grade pre-delivery capture
```bash
hop init
@@ -96,13 +122,19 @@ eval "$(hop env P_...)"
<agent-command> "<the same exact prompt>"
```
The exact agent command is harness-specific. Until a Hop process adapter intercepts prompts automatically, follow-up prompts must also pass through `hop prompt` before the agent acts.
The exact agent command is harness-specific. This stronger mode stores the
prompt before the model receives it. A future trusted prompt-submission hook can
provide the same boundary inside compatible agent clients.
## Failure handling
- **Missing Hop environment:** stop before editing and request a Hop-controlled launch.
- **Missing Hop environment:** run `hop begin` before project work and use the returned state and workspace.
- **Check failure:** fix the live workspace, checkpoint/check again, then create a new proposal.
- **Frozen proposal needs changes:** record a follow-up prompt; never mutate the stored proposal.
- **Overlap on landing:** retain both lineages and reconcile through a new prompt against current accepted state.
- **Ref inconsistency:** run `hop doctor`; use `hop doctor --repair` only outside final validation.
- **Secrets:** prompt text and check output are stored locally without encryption in the alpha. Never place credentials in them.
- **Secrets:** Hop redacts high-confidence provider keys plus contextual tokens,
passwords, private keys, authorization headers, and credential-bearing URLs
before durable storage. It also sanitizes recorded check commands/output and
proposal summaries. Detection is defense in depth, not a substitute for
environment variables or a secret manager. Never repeat a detected secret.