---
name: eck:clean-deprecated
version: "0.7.4"
description: Remove deprecated skills, agents, and primitives from a managed project after pull-from-global-catalog flags them. Run this after /eck:pull-from-global-catalog reports deprecated items.
disable-model-invocation: false
---

# Clean Deprecated Components

Remove deprecated components (skills, agents, primitives) from a managed project. Components are considered deprecated when they exist in the project but have been removed from the global catalog — typically because they were renamed or replaced.

This skill is the companion to `/eck:pull-from-global-catalog`, which flags deprecated items but intentionally does not delete them. Running this skill after a pull completes the cleanup cycle.

---

## Visual Framework

Follow these conventions for all terminal output displayed to the user via the Bash tool.

### Output Mode Awareness

Before producing output, read the user's preferred output mode:

```bash
cat $ECK_HOME/user-preferences.json 2>/dev/null
```

Extract the `outputMode` field and adapt verbosity:

- **guided** — Add explanatory prose after key steps. Describe what is happening and why.
- **standard** (default) — Balanced. Show steps with brief context for non-obvious decisions.
- **concise** — Steps and summary box only. No prose, no explanations.

If the file is missing or `outputMode` is absent, use **standard**.

### ANSI Colors

Declare these variables at the top of **every** Bash tool call (shell state does not persist between calls):

```bash
source $ECK_HOME/colors.sh
```

Every color sequence **must** end with `${RESET}`. No exceptions.

### Stage Banners

Mark major stage transitions with a clean bold header. One blank line before and after.

```bash
echo ""
printf '%b\n' "${ORANGE}${BOLD}Stage Name${RESET}"
echo ""
```

### Status Symbols

| Symbol | Meaning          | Color       |
| ------ | ---------------- | ----------- |
| `[*]`  | Active / running | `${CYAN}`   |
| `[x]`  | Completed        | `${GREEN}`  |
| `[!]`  | Error            | `${RED}`    |
| `[-]`  | Skipped          | `${DIM}`    |
| `[>]`  | In progress      | `${YELLOW}` |
| `[ ]`  | Pending          | `${DIM}`    |

No emoji in output. Use only these bracket symbols for status.

### Summary Blocks

Display at checkpoints and at the end of the skill. One blank line before and after.

```bash
echo ""
printf '%b\n' "${ORANGE}${BOLD}Title${RESET}"
echo ""
printf '%b\n' "Label: Value"
echo ""
```

### Error Format

```bash
printf '%b\n' "${RED}[!]${RESET} Error message here"
printf '%b\n' "    ${DIM}Recovery guidance here.${RESET}"
```

### Spacing Rules

- One blank line before and after stage banners and summary boxes.
- No blank lines within step lists.
- Maximum output line width: 70 characters.

### Statusline Stage Updates

At the **start** of each stage, update the statusline:

```bash
bash $ECK_HOME/update-stage.sh "{Statusline text from table}"
```

At **skill completion** (success or error), reset:

```bash
bash $ECK_HOME/update-stage.sh
```

---

## Task Registration

| Stage | Subject                 | Active Form                | Statusline    |
| ----- | ----------------------- | -------------------------- | ------------- |
| 1     | Stage 1: Scan           | Scanning for deprecated    | Scan (1/4)    |
| 2     | Stage 2: Review         | Reviewing deprecated items | Review (2/4)  |
| 3     | Stage 3: Remove         | Removing deprecated items  | Remove (3/4)  |
| 4     | Stage 4: Update Catalog | Updating catalog           | Catalog (4/4) |

## Usage

```bash
/eck:clean-deprecated                          # Clean current project
/eck:clean-deprecated <project-path>           # Clean specific project
/eck:clean-deprecated --dry-run                # Preview only, no deletions
```

---

## Stage 1: Scan for Deprecated Components

### Inputs

- Target project path (argument or current working directory)
- `<TARGET_PATH>/.claude/project-catalog.yaml`
- `$ECK_HOME/global-catalog.yaml`

### Activities

1. Verify the target has `.claude/project-catalog.yaml`. If not:

   ```bash
   printf '%b\n' "${RED}[!]${RESET} No project-catalog.yaml found"
   printf '%b\n' "    ${DIM}Run /eck:audit-current-project first.${RESET}"
   ```

   STOP.

2. Read the project catalog and identify all entries with `status: "deprecated"`.

3. For each deprecated entry, verify the file still exists on disk. Skip entries where the file has already been removed.

4. Cross-reference against the global catalog to find the replacement component (the component in the global catalog that now occupies the same functional role). The replacement is typically identified by:
   - Same category and similar name (e.g., `plan-adr` replaced by `design-adr`)
   - Explicit notes in prior sync_history entries mentioning the rename

5. Build the removal list with replacement mappings.

### Outputs

- List of deprecated components with on-disk verification
- Replacement mapping where identifiable

### Exit Criteria

- At least one deprecated component found on disk, OR skill exits early with "nothing to clean"

---

## Stage 2: Review

### Inputs

- Removal list from Stage 1

### Activities

1. Display the deprecated items found:

   ```bash
   echo ""
   printf '%b\n' "${ORANGE}${BOLD}Deprecated Components${RESET}"
   echo ""
   printf '%b\n' "Found {N} deprecated components:"
   echo ""
   printf '%b\n' "${YELLOW}[>]${RESET} skills/plan-adr/SKILL.md"
   printf '%b\n' "    ${DIM}Replaced by: design-adr${RESET}"
   printf '%b\n' "${YELLOW}[>]${RESET} skills/plan-arch/SKILL.md"
   printf '%b\n' "    ${DIM}Replaced by: design-arch${RESET}"
   echo ""
   ```

2. If `--dry-run` flag was provided:

   ```bash
   printf '%b\n' "${DIM}[-]${RESET} Dry run — no files will be deleted"
   ```

   Display the summary and STOP.

3. Ask for confirmation using AskUserQuestion:
   - Question: "Remove {N} deprecated components? Replacements are already installed."
   - Options: "Yes, remove all", "Review individually", "Cancel"

4. If "Review individually": present each item with Y/n choice. Build a filtered removal list.

### Outputs

- Approved removal list

### Exit Criteria

- User has confirmed which items to remove

---

## Stage 3: Remove

### Inputs

- Approved removal list from Stage 2

### Activities

1. For each approved item:

   a. Determine the component type from its path:
   - `skills/*/` — delete the entire skill directory
   - `agents/*.md` — delete the single agent file
   - `primitives/**/*.md` — delete the single primitive file
   - `hooks/*.sh` or `hooks/*.js` — delete the single hook file

   b. Delete the file or directory:

   ```bash
   # For skill directories
   rm -rf "{TARGET_PATH}/.claude/skills/{skill-name}/"

   # For individual files
   rm -f "{TARGET_PATH}/.claude/{relative-path}"
   ```

   c. Report each removal:

   ```bash
   printf '%b\n' "${GREEN}[x]${RESET} Removed: {relative-path}"
   ```

2. If any removal fails:

   ```bash
   printf '%b\n' "${RED}[!]${RESET} Failed to remove: {relative-path}"
   printf '%b\n' "    ${DIM}{error message}${RESET}"
   ```

   Continue with remaining items — do not abort on individual failures.

### Outputs

- Deprecated files/directories deleted from disk
- Per-item status reported

### Exit Criteria

- All approved items processed (removed or error reported)

---

## Stage 4: Update Catalog and Registry

### Inputs

- List of successfully removed items from Stage 3
- `<TARGET_PATH>/.claude/project-catalog.yaml`
- `$ECK_HOME/registry.yaml`

### Activities

1. **Update project-catalog.yaml:**
   - Remove entries for all successfully deleted components
   - Decrement `total_components` by the number of removed items
   - Update `last_audit` timestamp

2. **Update registry.yaml** (if it exists):

   **Reference:** `ops:registry-update` primitive for the canonical read-modify-write procedure.

   a. Load the target project's entry from registry.

   b. Update the `inventory` section:
   - Decrement `total` for each affected component type (skills, agents, etc.)
   - Remove the `deprecated` count field if it reaches zero
   - Remove `deprecated` from `totals` if it reaches zero

   c. Append `sync_history` entry:

   ```yaml
   - date: "{DATE}"
     action: "clean-deprecated"
     performed_by: "/eck:clean-deprecated"
     summary: "Removed {N} deprecated components: {list}"
   ```

   d. Set `last_modified_at` to current ISO-8601 date.

   e. Recompute `project_summary` per the `ops:registry-update` primitive.

   f. Atomic write: backup to `.bak`, write to `.tmp`, then rename.

3. **Display summary:**

   ```bash
   echo ""
   printf '%b\n' "${ORANGE}${BOLD}Clean Deprecated Complete${RESET}"
   echo ""
   printf '%b\n' "Project: {PROJECT_NAME}"
   printf '%b\n' "${GREEN}[x]${RESET} Removed: {N} deprecated components"
   printf '%b\n' "${GREEN}[x]${RESET} Catalog updated: {total_components}"
   printf '%b\n' "${GREEN}[x]${RESET} Registry updated"
   echo ""
   printf '%b\n' "${CYAN}[*]${RESET} Review changes: git diff"
   printf '%b\n' "${CYAN}[*]${RESET} Commit: git add -A && git commit"
   echo ""
   ```

4. Reset statusline:
   ```bash
   bash $ECK_HOME/update-stage.sh
   ```

### Outputs

- project-catalog.yaml updated (deprecated entries removed, totals adjusted)
- registry.yaml updated (inventory adjusted, sync_history appended)
- Summary displayed

### Exit Criteria

- All catalog/registry updates persisted
- User has seen the completion summary

---

## Error Handling

Reference: `output:error-handler` primitive for standardized error formatting.

| Error                | Recovery                                            |
| -------------------- | --------------------------------------------------- |
| No project catalog   | Direct to `/eck:audit-current-project`              |
| No deprecated items  | Exit cleanly with "nothing to clean" message        |
| File deletion failed | Report error, continue with remaining items         |
| Registry not found   | Skip registry update with warning, catalog still OK |
| Atomic write failed  | Log error, original registry remains intact         |

---

## Related Documents

- [/eck:pull-from-global-catalog](../pull-from-global-catalog/SKILL.md) — Flags deprecated items during catalog pulls
- [/eck:audit-current-project](../audit-current-project/SKILL.md) — Health check and drift detection
- [/eck:project-status](../project-status/SKILL.md) — View project registry dashboard
- [ops:registry-update primitive](../../../project/primitives/core/ops/registry-update.md) — Canonical registry write procedure
