docs: run-first onboarding + a runnable recovery demo#11
Merged
Conversation
…uctization items) Adversarial product discussion with fugu surfaced three onboarding gaps for a stranger who has never heard of agend. This closes them: 1. Killer demo — demo/recovery-demo.sh: a REAL guarded session where an agent erases uncommitted + untracked work with `reset --hard`, then one `agentic-git snapshots restore` brings it back (unstaged). Single story, no git internals. It asserts every step, so it doubles as a cold-start acceptance check (AGENTIC_GIT_BIN=$(command -v agentic-git) to test an install). Robust to a wrapped `git` on PATH; runs the guard un-bypassed. 2. Cold-start path — README "Trying it" was STALE: it claimed `agentic-git run` was "the top roadmap item" (it shipped in PR #3) and only showed the manual symlink dance. Rewrote it as a run-first Quickstart (`cargo install` → `agentic-git run -- <agent>` → `snapshots restore`), demoting the manual wiring to an "embedding it yourself" subsection. 3. Framing — promoted **recovers** into the top capability list and added a `reset --hard`/`clean -fd` row to the Why table, per fugu's reframe that recovery ("plain git has no undo for that") is a first-class reason to adopt, not a footnote. Honest positioning (seatbelt-not-cage) already present, left intact. No src/ changes. Demo verified end-to-end (DEMO PASSED); shellcheck clean. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
fugu review (PR #11): the demo printed `git status → (clean)` and had the agent say "git status is clean" — but in a real `agentic-git run` worktree, plain `git status --porcelain` is NOT clean: the session's `.agend-managed` marker remains untracked (`?? .agend-managed`). A first-time user running the advertised command would see output the demo denied, and the step was never even asserted. Now the demo shows the REAL output honestly — `?? .agend-managed (only the session marker — none of your work)` — and actually runs + asserts that, filtering the marker, git has no record of the erased work to restore from. The agent's line no longer claims "clean". Demo re-verified end-to-end (DEMO PASSED); shellcheck clean. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
suzuke
added a commit
that referenced
this pull request
Jul 5, 2026
Bumps the shim to 0.2.0 for the one-command recovery (`snapshots restore`, #10) and run-first onboarding (#11). agentic-git-core stays 0.1.0 — the contract crate is unchanged, so the two versions move independently (the shim's `version` is now explicit rather than inherited from the workspace). Publishing: the release workflow publishes core first (0.1.0, already on crates.io → tolerated) then the shim 0.2.0. Co-authored-by: Claude Opus 4.8 <noreply@anthropic.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
What
The three onboarding artifacts from the adversarial product discussion with fugu — no
src/changes.demo/recovery-demo.sh— a real guarded session where an agent erases uncommitted + untracked work withreset --hard, then oneagentic-git snapshots restorebrings it back (unstaged). Single story, no git internals. Asserts every step → doubles as a cold-start acceptance check (AGENTIC_GIT_BIN=$(command -v agentic-git) ./demo/recovery-demo.shto test an install). Robust to a wrappedgiton PATH; runs the guard un-bypassed. Plusdemo/README.md.README "Trying it" was stale — it claimed
agentic-git runwas "the top roadmap item" (it shipped in PR feat: session mode —agentic-git run(#1) #3) and only showed the manual symlink dance. Rewrote as a run-first Quickstart (cargo install→agentic-git run -- <agent>→snapshots restore), demoting the manual wiring to an "embedding it yourself" subsection.Framing — promoted recovers into the top capability list and added a
reset --hard/clean -fdrow to the Why table, per fugu's reframe that recovery ("plain git has no undo for that") is a first-class adoption reason, not a footnote. The honest seatbelt-not-cage positioning was already present and is left intact.Verification
demo/recovery-demo.shruns end-to-end → DEMO PASSED (agent wipes work → one-command recovery → asserts tracked+untracked recovered, unstaged).shellcheckclean (only intentional SC2016 single-quote uses in the agent sub-script).🤖 Generated with Claude Code