Publish Agent-Workflow documentation

Agent-Workflow.-.md

@@ -0,0 +1,65 @@
+# Codex Desktop and agent workflow
+
+## Codex Desktop
+
+Users type into Codex normally. The installed skill makes prompt capture the
+agent's first repository action:
+
+```bash
+hop begin --agent codex --heredoc <<'HOP_PROMPT_EOF'
+<exact visible user message>
+HOP_PROMPT_EOF
+```
+
+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.
+
+## Follow-up messages
+
+A later `hop begin` with the same Codex task session checkpoints existing
+workspace effects, appends a new prompt state, and continues the same attempt.
+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 a Desktop skill, which can
+only guarantee capture before project effects.
+
+## Agent rules
+
+- Never edit the canonical project root directly.
+- Never mutate a frozen proposal.
+- 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.