Reset

---
description: Removes files installed by /optimus:init and /optimus:permissions from the project. Compares each file against plugin templates and classifies as unmodified, likely generated, or user-modified. Always asks before deleting. Git-tracked files are noted as recoverable. Tests are never touched. Monorepo and multi-repo aware. Use for clean reinstall or to stop using optimus.
disable-model-invocation: true
---

# 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.