addon-feature

---
name: addon-feature
description: Safely add features to a working system without breaking existing functionality. Creates a branch, builds the feature, verifies the original still works, then merges.
triggers:
  - "add a feature"
  - "add-on"
  - "without breaking what we have"
  - "new feature but don't break"
  - "/addon-feature"
---

# Add-On Feature — Safe Feature Addition

Add a feature to a working codebase with guardrails that prevent breaking existing functionality.

## Philosophy

The user has something that works. They want to add to it, not risk it. Every step protects the working state.

## Workflow

### Step 1: Snapshot the working state

Before touching anything:

1. Confirm the repo is clean: `git status`
   - If there are uncommitted changes, ask the user to commit or stash first. Do NOT proceed with a dirty working tree.
2. Record the current branch and commit hash — this is the **safe point**.
3. Create a feature branch:
   ```bash
   git checkout -b addon/<feature-name>
   ```

### Step 2: Identify the boundary

Before writing code, identify:

1. **What files exist today** that make the current feature work. List them.
2. **Which of those files need modification** for the add-on. Flag these as **risk files**.
3. **What new files** will be created. These are safe — they can't break anything.

Present this to the user:

```
Add-on plan:
  New files (safe):
    - components/app/visual-pane.tsx
    - ...

  Modified files (risk):
    - components/app/session-view.tsx
    - agent-py/src/agent.py

  Untouched files:
    - components/app/robot-avatar.tsx
    - components/app/avatar-panel.tsx
    - ...
```

Wait for user approval before proceeding.

### Step 3: Build new files first

Create all new files before modifying any existing ones. New files can't break anything.

### Step 4: Modify existing files minimally

When editing risk files:

- **Add, don't rewrite.** Add new imports, new state, new conditional branches. Don't restructure existing code.
- **Use feature flags or toggles.** The add-on should be off by default or toggled. The original behavior must remain the default path.
- **Preserve the original code path.** If the feature is toggled off, the code should execute identically to before the change.

### Step 5: Smoke test

After all changes:

1. **Test the original flow** — does the app still work exactly as before when the add-on is not activated?
2. **Test the add-on flow** — does the new feature work when activated?
3. If there's a test suite, run it: look for `pytest`, `pnpm test`, `npm test`, etc.

If the original flow is broken:

```
STOP. The add-on broke existing functionality.
Reverting risk file changes and trying a different approach.
```

Use `git diff` to identify what broke, fix it, and re-test.

### Step 6: Commit and merge

1. Commit on the feature branch with a clear message describing the add-on.
2. Switch back to the original branch and merge:
   ```bash
   git checkout <original-branch>
   git merge addon/<feature-name>
   ```
3. Delete the feature branch:
   ```bash
   git branch -d addon/<feature-name>
   ```

### Step 7: Report

```
Add-on complete: <feature name>

New files:      X created
Modified files: Y changed
Original flow:  verified working
Add-on flow:    verified working
```

## Rules

1. **Never modify a file you don't have to.** If you can achieve the feature with only new files and one small edit to an existing file, do that.
2. **The add-on must be toggleable.** A button, a flag, a config option — the user must be able to turn it off and get exactly the old behavior.
3. **If you break the original, stop immediately.** Don't push forward hoping it'll work out. Revert the risk file changes and rethink.
4. **New files before modifications.** Always create new files first, modify existing files last.
5. **Ask before modifying risk files.** Present the plan and get approval.