Initial Hop alpha
This commit is contained in:
cyph3rasi
@@ -0,0 +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.
|
||||
---
|
||||
|
||||
# Hop
|
||||
|
||||
Use Hop as the change-control boundary between agent work and accepted project state.
|
||||
|
||||
## Enforce the boundary
|
||||
|
||||
- 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:
|
||||
|
||||
```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 status --json
|
||||
```
|
||||
|
||||
Confirm the current working directory is `HOP_WORKSPACE` or direct every filesystem operation there.
|
||||
|
||||
If the Hop variables are missing, stop before editing. Explain that the controller must first run:
|
||||
|
||||
```bash
|
||||
hop start --agent <agent-name> "<exact prompt>"
|
||||
```
|
||||
|
||||
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.
|
||||
|
||||
## Execute the task
|
||||
|
||||
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:
|
||||
|
||||
```bash
|
||||
hop check "$HOP_STATE_ID" -- <test-command> [args...]
|
||||
```
|
||||
|
||||
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.
|
||||
|
||||
## Land only with explicit authority
|
||||
|
||||
When the user explicitly asks to land a proposal, validate the exact final composed tree:
|
||||
|
||||
```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.
|
||||
|
||||
@@ -0,0 +1,4 @@
|
||||
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."
|
||||
@@ -0,0 +1,9 @@
|
||||
// Package hopskill embeds the distributable Hop agent skill in the CLI binary.
|
||||
package hopskill
|
||||
|
||||
import "embed"
|
||||
|
||||
// Files contains the complete vendor-neutral Hop skill bundle.
|
||||
//
|
||||
//go:embed SKILL.md agents/openai.yaml references/protocol.md
|
||||
var Files embed.FS
|
||||
@@ -0,0 +1,108 @@
|
||||
# Hop agent protocol
|
||||
|
||||
## State graph
|
||||
|
||||
```text
|
||||
A accepted
|
||||
├─ P prompt, persisted before effects
|
||||
│ └─ C checkpoint
|
||||
│ └─ R proposal
|
||||
└─ P independent prompt
|
||||
|
||||
A + R ──land──> A next accepted state
|
||||
```
|
||||
|
||||
State prefixes:
|
||||
|
||||
| Prefix | Kind | Meaning |
|
||||
|---|---|---|
|
||||
| `A_` | accepted | Canonical project revision |
|
||||
| `P_` | prompt | Exact instruction and pre-effect context |
|
||||
| `C_` | checkpoint | Immutable workspace progress |
|
||||
| `R_` | proposal | Frozen candidate result |
|
||||
| `F_` | failed | Durable failed execution or validation state |
|
||||
| `X_` | cancelled | Durable cancelled state |
|
||||
|
||||
Prompt, checkpoint, and proposal states may reference identical Git trees while remaining distinct causal occurrences.
|
||||
|
||||
## Environment contract
|
||||
|
||||
| Variable | Purpose |
|
||||
|---|---|
|
||||
| `HOP_ROOT` | Canonical project root containing `.hop/hop.db` |
|
||||
| `HOP_STATE_ID` | Prompt state authorizing the current instruction |
|
||||
| `HOP_TASK_ID` | Logical task grouping related prompts and attempts |
|
||||
| `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.
|
||||
|
||||
## Command contract
|
||||
|
||||
### Human or controller
|
||||
|
||||
```bash
|
||||
hop init
|
||||
hop start --agent <name> "<exact initial prompt>"
|
||||
hop env <prompt-state>
|
||||
hop prompt --from <state> "<exact follow-up prompt>"
|
||||
hop land <proposal> -- <final validation command>
|
||||
hop undo
|
||||
```
|
||||
|
||||
`hop start` creates the task, attempt, prompt state, and detached workspace before returning. The controller may deliver the prompt only after exit `0`.
|
||||
|
||||
`hop prompt` captures a checkpoint of current workspace effects before creating the follow-up prompt state.
|
||||
|
||||
### Agent
|
||||
|
||||
```bash
|
||||
hop state "$HOP_STATE_ID" --json
|
||||
hop status --json
|
||||
hop check "$HOP_STATE_ID" -- <command>
|
||||
hop propose --summary "<summary>" "$HOP_STATE_ID"
|
||||
```
|
||||
|
||||
`hop check` snapshots the attempt and runs the command in a detached worktree materialized from that exact checkpoint. Edits made concurrently in the live workspace do not change the tested tree.
|
||||
|
||||
`hop propose` freezes the current nonignored workspace tree. Later workspace edits cannot change the proposal.
|
||||
|
||||
`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.
|
||||
|
||||
## Exit codes
|
||||
|
||||
| Code | Meaning |
|
||||
|---:|---|
|
||||
| `0` | Success |
|
||||
| `1` | Git, SQLite, filesystem, or internal error |
|
||||
| `2` | Invalid CLI usage |
|
||||
| `20` | Overlap or conservative conflict block |
|
||||
| `21` | Accepted or attempt head changed during compare-and-swap |
|
||||
| `22` | Validation command failed |
|
||||
|
||||
A failed `hop check` or final landing check persists its evidence. A blocked or failed landing does not advance accepted state.
|
||||
|
||||
## Human launch sequence
|
||||
|
||||
```bash
|
||||
hop init
|
||||
hop start --agent codex "Add password reset emails"
|
||||
```
|
||||
|
||||
Use the returned workspace and environment to launch the agent. For example, conceptually:
|
||||
|
||||
```bash
|
||||
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.
|
||||
|
||||
## Failure handling
|
||||
|
||||
- **Missing Hop environment:** stop before editing and request a Hop-controlled launch.
|
||||
- **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.
|
||||
Reference in New Issue
Block a user