# Power-Cycling Skill Design

**Date:** 2025-11-06
**Status:** Superseded for this repo (see note below)
**Type:** Custom Claude Skill

> **Superseded.** AMSOIL DLP no longer generates its power-cycle script dynamically. The script is now
> committed at `scripts/power-cycle.sh` (plus `scripts/clean-start.sh`), and the skill lives in this
> repo at `.claude/skills/power-cycling/SKILL.md`. That deliberately departs from Design Principle 4
> below ("all files gitignored, never pollutes repository") so that a fresh clone, and anyone without
> the personal skill installed, gets a working `npm run power-cycle`.
>
> This document is kept as the historical design record, and remains an accurate description of the
> generic, machine-local version of the skill. The detection logic and script-generation guidelines
> below are what `scripts/power-cycle.sh` was written from.

## Overview

A standalone Claude skill that intelligently restarts applications with proper cache clearing. Designed to be a quick utility for ensuring you're always viewing the latest iteration of your application without stale cached pages or build data.

## Problem Statement

When developing applications, cached data and build artifacts can cause confusion by showing stale content. Manually killing processes, clearing caches, and restarting requires remembering framework-specific commands. This skill automates the entire power-cycle process with intelligent detection and zero configuration burden.

## Design Principles

1. **Zero maintenance** - No static templates, Claude generates scripts dynamically
2. **Simple by default** - One command does everything needed
3. **Project-aware** - Auto-detects framework and generates appropriate script
4. **Non-intrusive** - All files gitignored, never pollutes repository
5. **Monorepo-friendly** - Works from any subdirectory via tree walking + global registry

## Architecture

### File Structure

```
~/.claude/skills/power-cycling/SKILL.md     # Skill definition
~/.claude/power-cycle-registry.json          # Global project registry

[Project Root]/
├── .claude-power-cycle.json                 # Per-project config (gitignored)
├── pc-scripts/                              # Script directory (gitignored)
│   └── power-cycle.sh                       # Generated restart script
└── .gitignore                               # Updated with ignore entries
```

### Configuration Format

**Per-project config** (`.claude-power-cycle.json`):

```json
{
  "command": "bash pc-scripts/power-cycle.sh"
}
```

**Global registry** (`~/.claude/power-cycle-registry.json`):

```json
{
  "/absolute/path/to/project": {
    "configPath": "/absolute/path/to/project/.claude-power-cycle.json",
    "lastUsed": "2025-11-06T12:30:00Z"
  }
}
```

## Config Lookup Flow

1. Start in current working directory
2. Walk up directory tree looking for `.claude-power-cycle.json`
3. If found → read config and execute command
4. If not found → check global registry for project root path
5. If in registry → read that project's config
6. If nowhere → trigger auto-setup

This approach solves the monorepo/subdirectory problem: running from `/project/backend/` or `/project/frontend/` will find the root config and prevent duplicate scripts.

## Auto-Detection Logic

Detection runs in sequence, can match multiple frameworks:

1. **Docker** - `docker-compose.yml` or `docker-compose.yaml`
2. **Next.js** - `next.config.js`, `next.config.mjs`, or `next.config.ts`
3. **Node.js** - `package.json` with `dev` script
4. **Python/Django** - `manage.py`
5. **Go** - `go.mod`
6. **Generic** - Fallback

### Script Generation Guidelines

Claude generates scripts dynamically based on detection results:

**Next.js:**

- Kill processes matching `next dev`
- Kill processes on dev port (check package.json, default 3000)
- Clear `.next` directory
- Clear `node_modules/.cache` if exists
- Clear `*.tsbuildinfo` files
- Run dev command (`npm`/`yarn`/`pnpm` based on lockfile)

**Docker:**

- `docker compose down`
- `docker compose up -d` (or foreground based on package.json)

**Generic Node.js:**

- Kill process on dev port
- Run dev script from package.json

**All scripts include:**

- Progress echo statements
- `set -e` for error handling
- Header comments documenting behavior
- Executable permissions

### Priority Rules

- Docker + Next.js → prioritize Docker (likely contains Next.js)
- Node.js + specific framework → use specific approach
- Ambiguous cases → skill can ask user

## Skill Behavior

### Trigger Patterns

Skill activates automatically when user says:

- "power-cycle", "power cycle", "powercycle"
- "restart the app/application/server"
- "kill and restart"
- "clear cache and restart/reload"
- "fresh start"

Or explicitly via:

- `/power-cycle` slash command

### First-Time Setup Flow

1. Skill detects no config in tree and not in global registry
2. Announces: "No power-cycle setup found. Setting up for this project..."
3. Runs detection logic to identify project type(s)
4. Generates `pc-scripts/power-cycle.sh` based on detection
5. Creates `.claude-power-cycle.json` config
6. Updates global registry with project path
7. Adds to `.gitignore`:
   ```
   .claude-power-cycle.json
   pc-scripts/
   ```
8. Announces what was created
9. Executes the power-cycle

### Subsequent Runs

1. Finds config via lookup flow
2. Announces: "Power-cycling application..."
3. Executes command from config
4. Shows script output

## Edge Cases and Error Handling

### Monorepo/Subdirectory Handling

- Walk up tree to find existing config (prevents duplicates)
- Global registry stores absolute paths for lookups from subdirectories
- Users can manually create subdirectory-specific configs if truly needed

### Port Detection

- Parse `package.json` scripts for `--port` or `-p` flags
- Framework defaults: Next.js (3000), Django (8000), Node (3001)
- Include port in kill commands

### Multiple Framework Detection

- Docker + Next.js → prioritize Docker
- Node.js + specific framework → use specific
- Ambiguous → ask user

### Error Scenarios

**Script fails to kill process:**

- Continue anyway, new start might succeed

**Port still in use after kill:**

- Retry with `sleep 2` and kill again

**Script missing but config exists:**

- Regenerate script (may have been deleted)

**Command in config fails:**

- Show error, suggest regenerating setup

**Registry corruption:**

- Warn and recreate empty registry

**Project relocated:**

- Remove stale registry entries
- Next run regenerates config

**Permission issues:**

- Clear error about file permissions
- Suggest checking ownership/permissions

**Fresh clone (no node_modules):**

- Script works regardless
- `npm run dev` failure is expected project setup issue

**Server already stopped:**

- Kill commands finding nothing don't error
- Starting fresh is fine

**Manual config edits:**

- Respect user's custom commands
- Never overwrite without explicit regeneration request

### Platform Differences

- **Linux/Mac:** Generate `.sh` with bash shebang, use `pkill`
- **Windows:** Generate `.bat` with `taskkill`
- Adjust commands per platform

### Skill Updates

Users can delete `pc-scripts/` and `.claude-power-cycle.json` to regenerate with improved detection logic.

## Future Extensions

This design keeps things simple for now. Potential future additions:

- `pc-scripts/hard-reload.sh` - Nuclear option (rm -rf node_modules, reinstall)
- `pc-scripts/nuclear-clean.sh` - Complete wipe and rebuild
- Multiple restart strategies in config (out of scope for v1)

## Success Criteria

1. ✅ Works from any project subdirectory
2. ✅ Auto-detects framework correctly
3. ✅ Generates working script on first run
4. ✅ All files properly gitignored
5. ✅ No duplicate scripts in monorepos
6. ✅ Handles common error cases gracefully
7. ✅ Zero maintenance burden

## Implementation Notes

- Skill is standalone in `~/.claude/skills/power-cycling/`
- Not part of superpowers marketplace (custom user skill)
- Claude will see it in available skills list
- Uses dynamic generation instead of static templates
- Prioritizes simplicity and YAGNI principles