Reset — Remove optimus-generated files

Reset — Remove optimus-generated files

Remove files installed by /optimus:init and /optimus:permissions from the project. Does NOT uninstall the plugin itself — only removes files from the project's .claude/ directory (and subproject docs for monorepos).

Safety Rules

These rules are absolute and override all other instructions:

• NEVER touch test files, test directories, or test configuration — even if created by /optimus:unit-test
• NEVER touch files outside .claude/, subproject CLAUDE.md, subproject docs/, and workspace root CLAUDE.md
• NEVER delete .claude/settings.json without first extracting user-added content (use surgical removal — Step 4)
• ALWAYS show the categorized file list and get user confirmation before removing anything

Workflow

Step 1 — Detect project context

Multi-repo workspace detection

Read $CLAUDE_PLUGIN_ROOT/skills/init/references/multi-repo-detection.md and run the detection algorithm.

Determine project type:

• Multi-repo workspace — root has no .git/, 2+ child directories have .git/ directories. Each child repo has its own .claude/ directory. Workspace root may have a local CLAUDE.md (not version-controlled)
• Monorepo — single git repo with multiple subproject directories (e.g., packages/, apps/). Root has .claude/, subprojects may have their own CLAUDE.md and docs/ directories
• Single project — standard single repo with .claude/ directory

Check for optimus files

For multi-repo workspaces: enumerate all child repos and check each for .claude/ directories. Also check for a workspace root CLAUDE.md. If no child repo has .claude/ and no workspace root CLAUDE.md exists → inform the user "Nothing to reset — no optimus files found" → stop.

For single project / monorepo: check if .claude/ directory exists. If not → inform the user "Nothing to reset — no optimus files found" → stop.

If .claude/.optimus-version does not exist, warn that the project may not have been initialized by optimus, but proceed with template comparison anyway.

Inventory optimus-managed files

Scan for all files that optimus skills may have created. Only list files that actually exist:

Root .claude/ directory:

• .claude/CLAUDE.md
• .claude/.optimus-version
• .claude/settings.json
• .claude/docs/coding-guidelines.md
• .claude/docs/testing.md
• .claude/docs/styling.md
• .claude/docs/architecture.md
• .claude/docs/skill-writing-guidelines.md
• .claude/agents/code-simplifier.md (legacy — from previous optimus versions)
• .claude/agents/test-guardian.md (legacy — from previous optimus versions)
• .claude/hooks/format-python.py
• .claude/hooks/format-node.js
• .claude/hooks/format-rust.sh
• .claude/hooks/format-go.sh
• .claude/hooks/format-csharp.sh
• .claude/hooks/format-java.sh
• .claude/hooks/format-cpp.sh
• .claude/hooks/format-dart.sh
• .claude/hooks/restrict-paths.sh

Monorepo subprojects (scan for these patterns):

• <subproject>/CLAUDE.md — subproject overview files
• <subproject>/docs/testing.md — subproject testing docs
• <subproject>/docs/styling.md — subproject styling docs
• <subproject>/docs/architecture.md — subproject architecture docs

Multi-repo workspace root:

• CLAUDE.md at workspace root (local-only file)

Step 2 — Classify each file

For each file found in Step 1, determine two things:

1. Origin classification — was it generated by optimus, and has it been modified?
2. Git tracking — is it tracked by git? (recoverable via git checkout if deleted)

Check git tracking by running git ls-files --error-unmatch <file> for each file. Note: in multi-repo workspaces, run this from the correct repo directory.

Classification by comparison strategy

Verbatim templates (exact content match):

For these files, read both the project file and the corresponding template from the plugin. If content is identical → classify as UNMODIFIED. If different → classify as MODIFIED.

Project file	Template source
.claude/agents/code-simplifier.md	$CLAUDE_PLUGIN_ROOT/agents/code-simplifier.md (legacy — agents now live at plugin level)
.claude/agents/test-guardian.md	$CLAUDE_PLUGIN_ROOT/agents/test-guardian.md (legacy — agents now live at plugin level)
.claude/hooks/format-python.py	$CLAUDE_PLUGIN_ROOT/skills/init/templates/hooks/format-python.py
.claude/hooks/format-node.js	$CLAUDE_PLUGIN_ROOT/skills/init/templates/hooks/format-node.js
.claude/hooks/format-rust.sh	$CLAUDE_PLUGIN_ROOT/skills/init/templates/hooks/format-rust.sh
.claude/hooks/format-go.sh	$CLAUDE_PLUGIN_ROOT/skills/init/templates/hooks/format-go.sh
.claude/hooks/format-csharp.sh	$CLAUDE_PLUGIN_ROOT/skills/init/templates/hooks/format-csharp.sh
.claude/hooks/format-java.sh	$CLAUDE_PLUGIN_ROOT/skills/init/templates/hooks/format-java.sh
.claude/hooks/format-cpp.sh	$CLAUDE_PLUGIN_ROOT/skills/init/templates/hooks/format-cpp.sh
.claude/hooks/format-dart.sh	$CLAUDE_PLUGIN_ROOT/skills/init/templates/hooks/format-dart.sh
.claude/hooks/restrict-paths.sh	$CLAUDE_PLUGIN_ROOT/skills/permissions/templates/hooks/restrict-paths.sh

Near-exact template (coding-guidelines.md):

The template body (everything after line 1) is verbatim — only line 1 has [PROJECT NAME] substituted by init. Compare the project file's content from line 2 onward against the template's content from line 2 onward. If identical → UNMODIFIED. If different → MODIFIED.

Template: $CLAUDE_PLUGIN_ROOT/skills/init/templates/docs/coding-guidelines.md

Generated docs (heuristic — content filled in by init):

These files have ALL content filled in by init from project analysis — no template comparison is possible. Use heuristic fingerprinting:

Project file	Template fingerprint (line 1 HTML comment)	Template section headings
.claude/CLAUDE.md	<!-- Keep this file and .claude/docs/ updated when project structure, conventions, or tooling changes -->	Conventions, Commands, Project Structure, Before Writing Code, Documentation
.claude/docs/testing.md	(no comment — check heading) First line: # Testing	Test Runner, Running Tests, Test Structure, Writing Tests, Workflow, Coverage
.claude/docs/skill-writing-guidelines.md	(no comment — check heading) First line: # Skill-writing guidelines for	Foundation, Writing Style, Degrees of Freedom, Description Quality (frontmatter), Progressive Disclosure, Directory Layout, Shared References, Workflows and Feedback Loops, Common Patterns, Evaluation and Iteration, Anti-patterns, Documentation
.claude/docs/styling.md	(no comment — check heading) First line: # Styling	Stack, Conventions, File Organization, Adding New Components
.claude/docs/architecture.md	(no comment — check heading) First line: # Architecture	ANY of these heading sets: (1) code-only: Overview, Directory Map, Data Flow, Key Patterns, Dependencies Between Modules (2) skill-authoring: Overview, Directory Map, Skill Organization, Agent Boundaries, Reference Hierarchy, Orchestration Patterns (3) hybrid: Overview, Directory Map, Code Architecture, Skill Architecture

For CLAUDE.md: check if line 1 matches the template comment. Also check for monorepo variant: <!-- Keep this file, .claude/docs/, and subproject CLAUDE.md files updated when project structure changes -->.

For subproject CLAUDE.md files: check for <!-- Keep this file and docs/ updated when this subproject's conventions change -->.

For workspace root CLAUDE.md: check for <!-- Local workspace file — not version-controlled. Each repo has its own .claude/CLAUDE.md. -->.

For docs (testing.md, skill-writing-guidelines.md, styling.md, architecture.md): check if the ## section headings match the template's headings in the same order.

If fingerprints match → classify as LIKELY_GENERATED. If fingerprints don't match → classify as MODIFIED.

Always safe:

.claude/.optimus-version — pure version tracking file with no user content → always classify as UNMODIFIED.

Complex (settings.json):

.claude/settings.json → classify as COMPLEX. This file is handled separately in Step 4 via surgical key removal.

Classification summary

Each file gets one of:

• UNMODIFIED — exact match with plugin template (safe to remove)
• LIKELY_GENERATED — has optimus fingerprints, content was filled in by init
• MODIFIED — differs from template or lacks optimus fingerprints (user customized)
• COMPLEX — settings.json (surgical removal in Step 4)

Step 3 — Present reset plan and ask user

Present the full categorized file list to the user. For each file, show:

• The file path
• Its classification (UNMODIFIED / LIKELY_GENERATED / MODIFIED)
• Whether it is git-tracked (if yes, note: "recoverable via git checkout")

Group by classification. Example format:

## Unmodified (exact match with plugin template)
- .claude/agents/code-simplifier.md (git-tracked)
- .claude/hooks/format-node.js (git-tracked)
- .claude/.optimus-version (git-tracked)

## Likely generated by optimus
- .claude/CLAUDE.md (git-tracked)
- .claude/docs/testing.md (git-tracked)

## Modified by user
- .claude/docs/coding-guidelines.md (git-tracked) — user added custom rules

## settings.json
- .claude/settings.json — will remove optimus entries, preserve user config

For multi-repo workspaces, group files by repo (e.g., ### repo-name/).

Then ask the user using AskUserQuestion:

• Header: "Reset"
• Question: "Review the files above. Which should be removed?"
• Options:
  1. "Remove all" (Recommended) — remove all optimus files (UNMODIFIED + LIKELY_GENERATED + MODIFIED). Safe when git-tracked
  2. "Keep modified" — remove UNMODIFIED + LIKELY_GENERATED, keep MODIFIED files
  3. "Unmodified only" — remove only UNMODIFIED (most conservative)
  4. "Abort" — cancel reset, do not remove anything

If user selects "Abort" → inform the user that no files were removed → stop.

Step 4 — Clean settings.json (surgical removal)

If .claude/settings.json exists, do NOT delete it outright. Surgically remove optimus-contributed entries:

1. Read the current .claude/settings.json
2. Read the init template: $CLAUDE_PLUGIN_ROOT/skills/init/templates/settings.json
3. Read the permissions template: $CLAUDE_PLUGIN_ROOT/skills/permissions/templates/settings.json

Remove PostToolUse hooks from init: In hooks.PostToolUse, remove any entry whose hooks array contains commands referencing .claude/hooks/format- (init's formatter hooks). If the PostToolUse array becomes empty after removal, remove the PostToolUse key.

Remove PreToolUse hooks from permissions: In hooks.PreToolUse, remove any entry whose hooks array contains commands referencing .claude/hooks/restrict-paths.sh (permissions hook). If the PreToolUse array becomes empty after removal, remove the PreToolUse key.

Remove permissions entries from permissions: Compare permissions.allow against the permissions template's permissions.allow list. Remove entries that match. Also remove any mcp__* entries — but only if a .mcp.json file exists in the relevant project root (for multi-repo workspaces, check each child repo's root independently; for single projects and monorepos, check the project root). If no .mcp.json exists, leave mcp__* entries untouched (they may have been manually added by the user). If permissions.allow becomes empty, remove the key.

Compare permissions.deny against the permissions template's permissions.deny list. Remove entries that match. If permissions.deny becomes empty, remove the key.

If permissions object becomes empty, remove it. If hooks object becomes empty, remove it.

Final check: If the entire JSON object is empty ({}), delete the file entirely. Otherwise, write the cleaned JSON back with proper formatting (2-space indentation).

Step 5 — Execute removals

Based on the user's choice from Step 3:

1. Delete the selected files (using rm for each file)
2. Clean settings.json per Step 4 (always — regardless of user's choice, since surgical removal preserves user content)

Multi-repo workspace handling:

• Process each child repo independently
• Delete workspace root CLAUDE.md if it was classified and selected for removal

Monorepo handling:

• Process root .claude/ directory (same as single project)
• Delete subproject CLAUDE.md files that were classified and selected for removal
• Delete subproject docs/ files (testing.md, styling.md, architecture.md) that were classified and selected for removal

Step 6 — Clean empty directories

After file removal, check these directories and remove any that are now empty:

• .claude/hooks/
• .claude/agents/
• .claude/docs/
• .claude/ (only if completely empty — no files or subdirectories remain)

For monorepos: also check subproject docs/ directories.

For multi-repo workspaces: check each repo's .claude/hooks/, .claude/agents/, .claude/docs/, and .claude/ directories.

Step 7 — Report results

Present a summary to the user:

• Files removed — count and list
• Files kept — count and list with reason (user-modified, user chose to keep, etc.)
• settings.json — entries removed, or file deleted, or "no changes needed"
• Directories cleaned — empty directories that were removed

Step 8 — Next step

Recommend the next step based on intent:

• To reinstall optimus project files → /optimus:init (and /optimus:permissions for safety guardrails)
• To uninstall the plugin itself → /plugin uninstall optimus@optimus-claude (Claude Code command, not an optimus skill)

Tell the user: Tip: for best results, start a fresh conversation for the next skill — each skill gathers its own context from scratch.