feat(cli): undo / uninstall a scaffold (cleanly remove what agent-init added)

[Lillevang]

Status: needs technical refinement. This is a UX-focused design sketch. It has a genuine open design question (how undo knows what to remove) that must be settled before implementation — see "Open questions."

Problem

If a user scaffolds the wrong flavor, or decides they don't want the agentic envelope after all, there is no way to cleanly reverse it. They must manually hunt down and delete .agent/, the symlink trio (AGENTS.md, CLAUDE.md, .agent/CLAUDE.md), .devcontainer/, Justfile, .pre-commit-config.yaml, the .gitignore block (once the visibility feature lands), and any fresh-project files — and do it without nuking their own content. That's error-prone and makes trying agent-init feel risky: there's no easy exit. A tool that's easy to undo is a tool people are willing to experiment with.

Goal

One command to cleanly remove what agent-init added — e.g. agent-init uninstall [target] (name TBD: uninstall / undo / remove / clean). Seamless, safe, and previewable. Removing a scaffold should feel as routine as creating one.

Proposed UX (illustrative — exact shape is a refinement item)

agent-init: uninstall scaffold from ./myapp

  remove   .agent/                  (created by agent-init)
  remove   .devcontainer/
  remove   Justfile
  remove   AGENTS.md, CLAUDE.md     (symlinks)
  keep     .agent/AGENTS.md         (modified since scaffold — left in place)   <- safety
  remove   .gitignore block         (agent-init fenced block; file kept)

Remove 11 items, keep 1 modified. Proceed? [y/N]

Design principles:

• Previewable: --dry-run shows exactly what would be removed before anything happens (reuses the plan machinery from feat(cli): conflict-aware plan preview for init (enhance --dry-run) #62). Same colored output + tally.
• Safe by default: confirmation prompt unless --yes; never deletes files the user modified since scaffolding, and never touches files that pre-existed or unrelated project files. Modified files are reported and kept.
• Reversible-minded: removes only what agent-init created; leaves the repo otherwise exactly as it was.
• Cleans the ignore block too: if the visibility feature (feat(cli): support local visibility — ignore the agent-init scaffold in the committed .gitignore #51/feat(cli): support global-default visibility — ignore the agent-init scaffold in all repos via core.excludesfile #52/feat(cli): support hidden visibility — fully hide the scaffold in one repo via .git/info/exclude (no committed trace) #53) wrote a fenced block to .gitignore / .git/info/exclude / global excludes, uninstall removes that block (leaving the file).

Provisional acceptance criteria (pending refinement)

• uninstall [target] removes the agent-init-created envelope, leaving unrelated files intact.
• Files modified since scaffolding are preserved (or require an explicit --force), with a clear report of what was kept and why.
• --dry-run previews the removal and writes nothing; a confirmation prompt guards real removal unless --yes.
• The fenced ignore block (from feat(cli): support local visibility — ignore the agent-init scaffold in the committed .gitignore #51/feat(cli): support global-default visibility — ignore the agent-init scaffold in all repos via core.excludesfile #52/feat(cli): support hidden visibility — fully hide the scaffold in one repo via .git/info/exclude (no committed trace) #53), if present, is removed; the host file is kept.
• Output uses the same reporting style as init (remove/keep + tally; color per init output: fix symlink paths, add clarity + color #58).
• Does not rewrite git history or touch unrelated git state.

Open questions (need technical refinement) — the core one is load-bearing

1. How does undo know what to remove without nuking user content? This is the central design decision:
   • Option A — install manifest. Write a small manifest at init time (e.g. .agent/.install-manifest listing created paths + a content hash per file). Undo removes exactly those paths and detects user-modified files via hash mismatch (keep + warn). Precise and safe, but adds a file and couples init/uninstall.
   • Option B — derive from the flavor registry at undo time. Reconstruct the created set from the flavor definition. No extra file, but requires knowing/recording which flavor was used, and is fragile if templates changed between versions.
   • Option C — hybrid. Prefer the manifest; fall back to registry-derivation when no manifest exists (e.g. scaffolds created before this feature).
   • Leaning Option A (manifest) for safety/precision, but this is explicitly a refinement decision.
2. Scope: full envelope only, or also remove fresh-project files (cmd/, go.mod, …)? The latter is much more dangerous — likely envelope-only by default, with the project files left alone.
3. Naming: uninstall vs undo vs remove vs clean.
4. Handling already-committed scaffold files: remove from the working tree only, or also git rm? (Probably remove files and let the user commit the deletion; don't auto-commit.)
5. Symlink-trio removal order and broken-symlink edge cases.

Related

• feat(cli): conflict-aware plan preview for init (enhance --dry-run) #62 — conflict-aware plan preview; uninstall reuses its --dry-run preview machinery.
• init output: fix symlink paths, add clarity + color #58 — output style/color the removal report should match.
• feat(cli): support local visibility — ignore the agent-init scaffold in the committed .gitignore #51 / feat(cli): support global-default visibility — ignore the agent-init scaffold in all repos via core.excludesfile #52 / feat(cli): support hidden visibility — fully hide the scaffold in one repo via .git/info/exclude (no committed trace) #53 — visibility ignore blocks that uninstall must also clean up.
• Honors the 2026-05-24 "stay small and simple" decision: one subcommand, safe defaults, no interactive wizard beyond a yes/no confirm.