@hiver/skills 1.0.1

package/README.md

@@ -0,0 +1,394 @@
+# @hiver/skills
+
+A CLI tool to install and manage shared Claude Code skills & agents across Hiver repositories.
+
+Skills are reusable AI prompt workflows (markdown files) that live in collections. This CLI copies them into the right directory for your IDE — Claude Code, Cursor, or Windsurf.
+
+---
+
+## For Consumers
+
+### Install skills interactively
+
+```bash
+npx @hiver/skills add
+```
+
+This walks you through:
+1. **Pick your IDE** — Claude Code, Cursor, or Windsurf
+2. **Pick a collection** — `common` (generic) or `web` (React/Hiver-specific)
+3. **Pick type** — Skills or Agents (only shown if both exist)
+4. **Pick items** — Select which skills/agents to install
+
+Dependencies are auto-resolved and installed.
+
+### Other commands
+
+```bash
+npx @hiver/skills list                          # List all available skills & agents
+npx @hiver/skills add discuss-problem create-prd # Install specific skills directly
+npx @hiver/skills update                         # Check for updates (shows diff, asks before overwriting)
+npx @hiver/skills remove discuss-problem         # Remove an installed skill
+npx @hiver/skills help                           # Show help
+```
+
+### Navigation
+
+- **Arrow keys** — move up/down
+- **Space** — toggle selection (multi-select)
+- **Enter** — confirm
+- **Esc** — go back to previous step
+
+---
+
+## For Contributors
+
+### Prerequisites
+
+- Node.js >= 18
+- Yarn
+
+### Setup
+
+```bash
+git clone <repo-url>
+cd hiver-skills
+yarn install
+yarn build
+```
+
+### Test locally
+
+```bash
+# Run any command directly
+node dist/cli.js list
+node dist/cli.js add
+node dist/cli.js help
+
+# Or link globally to test as a consumer would
+yarn link
+cd /path/to/any/project
+hiver-skills add
+```
+
+### Creating a new skill (AI-assisted)
+
+This repo includes a built-in `/create-skill` skill that guides you through the entire process of creating a new skill or agent using AI. It works in both Claude Code and Cursor.
+
+**In Claude Code:**
+```
+/create-skill
+```
+
+**In Cursor:** The `create-skill.md` rule is auto-loaded from `.cursor/rules/`.
+
+The skill will:
+1. Ask you what the skill should do, who it's for, and where it belongs
+2. Discuss edge cases, dependencies, and scope boundaries through back-and-forth
+3. Validate its understanding with you before writing anything
+4. Create the properly structured `SKILL.md` (or agent `.md`) file with correct frontmatter
+5. Verify it shows up in the CLI
+
+This is the recommended way to add new skills — it ensures consistency with existing patterns and catches issues early.
+
+### Project structure
+
+```
+hiver-skills/
+├── .claude/skills/create-skill/  # AI skill to help devs create new skills (Claude Code)
+├── .cursor/rules/                # Same skill for Cursor
+├── src/                          # Source code (React + Ink CLI)
+│   ├── cli.jsx                   # Entry point — routes to commands
+│   ├── commands/
+│   │   ├── Add.jsx               # Interactive install wizard
+│   │   ├── List.jsx              # List available skills/agents
+│   │   ├── Update.jsx            # Diff-based update flow
+│   │   └── Remove.jsx            # Remove installed skills/agents
+│   ├── components/
+│   │   ├── Select.jsx            # Single-select menu (for target, collection)
+│   │   ├── MultiSelect.jsx       # Multi-select with checkboxes (for skills)
+│   │   ├── Confirm.jsx           # Yes/no prompt
+│   │   ├── DiffView.jsx          # Colored diff display
+│   │   └── StatusMessage.jsx     # Success/warning/error messages
+│   └── utils/
+│       ├── collections.js        # Scan collections, parse frontmatter, resolve deps
+│       ├── installer.js          # Copy/remove skills to IDE target directories
+│       ├── targets.js            # IDE target configs (paths for Claude, Cursor, Windsurf)
+│       └── diffUtil.js           # Compute diffs between local and latest files
+│
+├── collections/                  # Skill & agent markdown files
+│   ├── common/                   # Repo-agnostic skills (work in any project)
+│   │   ├── skills/
+│   │   └── agents/
+│   └── web/                      # Hiver web app specific
+│       ├── skills/
+│       └── agents/
+│
+├── dist/                         # Built output (do not edit directly)
+│   └── cli.js                    # Bundled CLI binary
+│
+├── build.js                      # esbuild config
+├── package.json
+└── .github/workflows/            # CI/CD pipelines
+```
+
+---
+
+## How to: Common tasks
+
+### Add a new skill
+
+1. Decide which collection it belongs to:
+   - `collections/common/skills/` — if it's repo-agnostic (no hardcoded paths, no specific frameworks)
+   - `collections/web/skills/` — if it's specific to the Hiver web app
+   - Create a new collection directory if needed (e.g., `collections/extension/skills/`)
+
+2. Create a directory for the skill:
+   ```bash
+   mkdir collections/common/skills/my-new-skill
+   ```
+
+3. Create a `SKILL.md` file inside it with YAML frontmatter:
+   ```markdown
+   ---
+   name: my-new-skill
+   description: Short description of what this skill does. This shows up in the CLI.
+   dependencies: []
+   ---
+
+   # My New Skill
+
+   Instructions for the AI go here...
+   ```
+
+4. If the skill has supporting reference files, put them in subdirectories:
+   ```
+   my-new-skill/
+   ├── SKILL.md
+   └── references/
+       ├── patterns.md
+       └── examples.md
+   ```
+   The entire directory gets copied when a consumer installs the skill.
+
+5. Build and test:
+   ```bash
+   yarn build
+   node dist/cli.js list        # Verify it shows up
+   node dist/cli.js add         # Test installing it
+   ```
+
+### Add a new agent
+
+1. Create a markdown file in the appropriate `agents/` directory:
+   ```bash
+   # For repo-agnostic agents
+   touch collections/common/agents/my-agent.md
+
+   # For web-specific agents
+   touch collections/web/agents/my-agent.md
+   ```
+
+2. Add YAML frontmatter:
+   ```markdown
+   ---
+   name: my-agent
+   description: Short description shown in the CLI.
+   dependencies: [write-test-cases]
+   ---
+
+   Agent instructions here...
+   ```
+
+3. Build and verify:
+   ```bash
+   yarn build
+   node dist/cli.js list
+   ```
+
+### Add a new collection (for a new repo/team)
+
+1. Create the collection directory structure:
+   ```bash
+   mkdir -p collections/my-repo/{skills,agents}
+   ```
+
+2. Add skills and/or agents inside it (follow the steps above).
+
+3. That's it — the CLI auto-discovers collections by scanning the `collections/` directory. No registration needed.
+
+### Add a new IDE target
+
+1. Open `src/utils/targets.js`
+
+2. Add a new entry:
+   ```js
+   export const targets = {
+     claude: { name: 'Claude Code', skillsDir: '.claude/skills', agentsDir: '.claude/agents' },
+     cursor: { name: 'Cursor', skillsDir: '.cursor/rules', agentsDir: '.cursor/rules' },
+     windsurf: { name: 'Windsurf', skillsDir: '.windsurfrules', agentsDir: '.windsurfrules' },
+     // Add new target here:
+     newIde: { name: 'New IDE', skillsDir: '.newide/skills', agentsDir: '.newide/agents' },
+   };
+   ```
+
+3. The CLI picks it up automatically in the target selection step.
+
+### Declare dependencies between skills/agents
+
+Add a `dependencies` field in the YAML frontmatter:
+
+```markdown
+---
+name: build-feature
+description: Orchestrates full feature build
+dependencies: [build-milestone, write-test-cases]
+---
+```
+
+When a consumer installs `build-feature`, the CLI will auto-install `build-milestone` and `write-test-cases` if they're not already selected.
+
+Dependencies are resolved across all collections — a `common` skill can depend on a `web` agent, etc.
+
+### Modify the CLI UI
+
+The CLI is built with [Ink](https://github.com/vadimdemedes/ink) (React for the terminal).
+
+- **Components** are in `src/components/` — standard React components using Ink's `<Box>`, `<Text>`, `useInput`
+- **Commands** are in `src/commands/` — each command is a React component with step-based state machine
+- **Routing** is in `src/cli.jsx` — maps CLI args to command components
+
+After any source change:
+```bash
+yarn build                    # Rebuild
+node dist/cli.js <command>    # Test
+```
+
+### Add a new CLI command
+
+1. Create `src/commands/MyCommand.jsx`:
+   ```jsx
+   import React from 'react';
+   import { Text, useApp } from 'ink';
+
+   export function MyCommand() {
+     const { exit } = useApp();
+     setTimeout(() => exit(), 100);
+     return <Text color="green">Hello from my command!</Text>;
+   }
+   ```
+
+2. Register it in `src/cli.jsx`:
+   ```jsx
+   import { MyCommand } from './commands/MyCommand.jsx';
+
+   // Inside the App switch:
+   case 'my-command':
+     return <MyCommand />;
+   ```
+
+3. Add it to the help text in the `Help` component in the same file.
+
+---
+
+## Build & Release
+
+### Build
+
+```bash
+yarn build
+```
+
+This runs esbuild to bundle `src/cli.jsx` into `dist/cli.js` — a single ESM file with a shebang that can run directly with Node.
+
+### GitHub Workflows
+
+There are 4 workflows in `.github/workflows/`:
+
+| Workflow | File | Trigger | Purpose |
+|----------|------|---------|---------|
+| **Verify PR** | `verify-pull-request.yml` | Auto on PR open/sync | Runs `yarn install` + `yarn build` to verify the PR compiles |
+| **Stable Release** | `publish-to-npm.yml` | Manual (workflow_dispatch) | Publishes a stable version to NPM |
+| **Beta Release** | `publish-to-npm-beta.yml` | Manual (workflow_dispatch) | Publishes a beta version to NPM from any branch |
+
+### How to release a change
+
+#### Step 1: Get your PR merged
+
+1. Create a feature branch and make your changes
+2. Open a PR to `main`
+3. The **Verify PR** workflow runs automatically — it must pass before merging
+4. Get review and merge to `main`
+
+#### Step 2a: Stable release (for production-ready changes)
+
+1. Go to **GitHub Actions** → **"Npm release process"**
+2. Click **"Run workflow"**
+3. Enter the **version number** (e.g., `1.2.0`)
+4. Click **"Run workflow"**
+
+What it does:
+- Checks out `main`
+- Installs dependencies and builds
+- Bumps the version in `package.json`
+- Publishes to NPM (`npm publish`)
+- Commits the version bump and pushes
+- Generates a changelog from merged PRs and commits it
+
+After release, consumers get the new version with:
+```bash
+npx @hiver/skills@latest add
+```
+
+#### Step 2b: Beta release (for testing before stable)
+
+Use this when you want others to test a change before making it the default version.
+
+1. Go to **GitHub Actions** → **"Beta Release Process"**
+2. Click **"Run workflow"**
+3. Enter the **branch** to publish from (e.g., `feat/new-skill` or `main`)
+4. Enter the **beta version** (e.g., `1.2.0-beta.1`)
+   - Always use the format `x.y.z-beta.N`
+   - Increment `N` for subsequent beta releases (`beta.1`, `beta.2`, etc.)
+5. Click **"Run workflow"**
+
+What it does:
+- Checks out the specified branch
+- Installs dependencies and builds
+- Bumps the version in `package.json` (does not commit)
+- Publishes to NPM with the `beta` tag
+
+Consumers can test the beta with:
+```bash
+npx @hiver/skills@beta add
+```
+
+The `beta` tag means `npx @hiver/skills add` (without a tag) still uses the latest stable version — beta is opt-in only.
+
+#### When to use which?
+
+| Scenario | Workflow |
+|----------|----------|
+| Merged a new skill, ready for everyone | **Stable release** |
+| Updated skill content, small fix | **Stable release** (patch bump) |
+| WIP feature on a branch, need someone to test | **Beta release** from that branch |
+| Big change, want to validate before going stable | **Beta release** first, then **Stable release** |
+
+### Required secrets
+
+These GitHub secrets must be configured in the repository settings:
+
+| Secret | Purpose |
+|--------|---------|
+| `NPM_TOKEN_NEW` | NPM authentication token for publishing |
+| `CI_SYSTEM_GITHUB_WORKFLOW` | GitHub PAT for pushing commits (version bumps, changelog) |
+| `GITHUB_TOKEN` | Auto-provided by GitHub Actions (used for PR checks) |
+
+---
+
+## Key design decisions
+
+- **Copy-on-install** (like shadcn/ui) — skills are copied into the consumer's project, not symlinked. Consumers own the files and can customize them.
+- **Markdown-only skills** — skills are `.md` files with YAML frontmatter. No executable code in skills.
+- **Auto-discovery** — collections, skills, and agents are discovered by scanning the filesystem. No central registry file to maintain.
+- **Single build output** — esbuild bundles all JSX into one `dist/cli.js`. Dependencies stay external (loaded from `node_modules` at runtime).

package/build.js

@@ -0,0 +1,15 @@
+import esbuild from 'esbuild';
+
+await esbuild.build({
+  entryPoints: ['src/cli.jsx'],
+  bundle: true,
+  platform: 'node',
+  format: 'esm',
+  outfile: 'dist/cli.js',
+  banner: { js: '#!/usr/bin/env node' },
+  packages: 'external',
+  jsx: 'automatic',
+  jsxImportSource: 'react',
+});
+
+console.log('Build complete → dist/cli.js');

package/collections/common/skills/create-prd/SKILL.md

@@ -0,0 +1,43 @@
+---
+name: create-prd
+description: This skill is used to create a proper tech spec PRD for a problem statment. Use it only when the user is explicitly asking to create a PRD. 
+---
+
+# Create tech spec PRD document
+
+Helps the user to create a proper PRD document by dividing the entire feature into multiple tasks order from independent to non-independent.
+
+
+## When to Use
+
+- Use this skill when user wanted to create a PRD based upon a problem statment which he already discussed and finalized on the solutions
+- do not use this if a summary document isnt provided
+
+## Phase Isolation
+
+> **This should run in a FRESH conversation** — not the same one where `discuss-problem` ran. The summary document is the input, not the prior discussion history.
+> **Start a NEW conversation for the next phase.** Once this skill produces `Prd.md`, the user should open a fresh conversation to run `prd-to-milestone`.
+
+## Instructions
+
+- Take summary of the initial discussions as input  from the user
+- Analyze the summary in context of the current codebase
+- Ask right questions if you are not clear on the problem statment or with the summary provided
+- Go through the strategy and approaches fianalized and break down it into tasks to achieve
+- in every milestone describe in detail 
+   - Goal to achieve
+   - Concerns if any
+   - strategy and approach to use
+   - will it cause code break in the existing flows
+   - is the change is a breaking change
+   - Do add figma prototype screenshots if possible if its related to feature building or modification
+   - is the milestone dependent on the other milestone or not ?
+- order the tasks from independent tasks which needed to be implemented first before starting another one
+- take inputs from the user if he has any
+- once both of you are on the same page create a Prd.md file  which includes
+    - Problem statment
+    - figma links
+    - Summary
+    - Objective
+    - Tasks with all the things discussed so far.
+- create this Prd in the same directory where the initial summary was created

package/collections/common/skills/discuss-problem/SKILL.md

@@ -0,0 +1,55 @@
+---
+name: discuss-problem
+description: This skill is used to discuss a problem statment which can be either building a feature, solving a bug etc. Use it only when user explicitly asks to discuss or grill down on a problem statment.
+---
+
+# Discuss problem
+
+> **MODE: DISCUSSION ONLY.**
+> This skill is strictly for analysis and discussion. No source code will be written or modified under any circumstance. The ONLY file you may create is the final `summary.md`.
+
+Help the user to grill down on a problem to its core discussing all sorts of the strategies, options to solve the problem. Discussing all the issues, edge cases, which can come up while solving the problem and getting on same page for solving the problem using the finalized approach or strategy.
+
+## Forbidden actions — NEVER do these
+
+- Do NOT write, create, or edit any source code files
+- Do NOT use `StrReplace`, `Write`, or `Shell` tools to make code changes
+- Do NOT implement any solution, even partially
+- Do NOT generate code snippets as part of a "just to show you" step
+- The ONLY permitted file operation is creating the final `summary.md`
+
+## When to Use
+
+- Use this skill when user wants to discuss a problem statement like implementing a new feature, modifying an existing feature, or solving a bug
+- This skill is helpful for grilling down on a problem statement before even starting creating PRDs or development
+
+## Token Budget
+
+- **Cap discussions at 5-7 exchanges.** After 7 rounds of back-and-forth, actively push toward convergence — summarize the current state, list open questions, and ask "are we ready to finalize?"
+- If the problem genuinely needs more discussion, continue but be aware of context limits.
+
+## Phase Isolation
+
+> **Start a NEW conversation for the next phase.** Once this skill produces `summary.md`, the user should open a fresh conversation to run `create-prd`. The summary document carries all necessary context — the discussion history does not need to transfer.
+
+## Instructions
+
+1. Take input from the user related to the problem they want to discuss or grill down
+2. If the problem is related to building a new feature, check with the user if prototype designs are available
+3. If Figma designs are available, use the Figma MCP tool to get the prototype details and analyze them
+4. Keep asking if the user has more Figma designs available until all designs are provided; keep using the Figma MCP tool to load them into memory
+5. Analyze the problem statement in context of the current codebase — use read and search tools to explore, never write tools
+6. Ask the right questions until you are clear on the problem statement
+7. Go through the codebase and figure out how the problem can be solved — discussion only
+8. Provide your thoughts and opinions on how to tackle this
+9. Figure out problems, issues, and edge cases which can come up while solving the problem
+10. Take inputs from the user if they have any
+11. Keep discussing until you and the user are on the same page (aim for convergence within 5-7 exchanges)
+12. Keep discussing until all the issues being presented are resolved
+
+### Final step — summary only, no code
+
+Once both of you are on the same page:
+- Create a `summary.md` file under a new directory at the root of the codebase, named after the problem
+- The summary must include: problem statement, all options discussed, finalized approach, known issues and their resolutions, and open questions if any
+- **Do NOT write any source code in this step or any step. The summary is plain markdown only.**

package/collections/common/skills/explore-codebase/SKILL.md

@@ -0,0 +1,79 @@
+---
+name: explore-codebase
+description: Explore a module, file, or directory with scoped, token-efficient analysis. Produces a structured summary focused only on what is relevant to the current task context.
+---
+
+# Explore Codebase
+
+Analyze a module, file, or directory to produce a focused summary that helps the user or calling agent understand the code before modifying it.
+
+## When to Use
+
+- When the user or an agent needs to understand a module, file, or directory before making changes
+- When investigating how a specific feature, component, or data flow works
+
+## Inputs
+
+The caller MUST provide:
+1. **Starting path** — the module, directory, or file to explore
+2. **Context / goal** (optional but strongly recommended) — what the caller wants to achieve (e.g., "need to add a new filter option to the sidebar", "investigating why email sync fails"). If no context is given, ask the user before exploring.
+
+## Instructions
+
+### Step 1: Scope the exploration
+
+- Start by listing the top-level contents of the given path (use `ls` or Glob)
+- Identify which files/subdirectories are **relevant to the stated goal**
+- **Skip** files that are clearly unrelated (e.g., test fixtures, unrelated sibling modules, generated files, assets like images/fonts)
+- **Max depth: 3 levels** from the starting path. Do NOT recurse beyond 3 levels unless the caller explicitly asks for deeper exploration or a specific deeper file is clearly critical.
+
+### Step 2: Read only what matters
+
+- Read the **entry-point files first** (index.js/ts, main component, route definitions, barrel exports)
+- From entry points, follow **only the imports/dependencies relevant to the goal**
+- Do NOT read every file in the directory. Read a file only if:
+  - It is an entry point or barrel export
+  - It is directly imported by an already-read relevant file
+  - It contains the component, hook, function, or class the goal is about
+- **Budget: aim to read no more than 10-15 files** for a typical exploration. If you need more, pause and confirm with the user.
+
+### Step 3: Trace relevant flows only
+
+Focus your analysis on flows relevant to the goal:
+- **UI flow**: Which components render what? What props/state drive the behavior in question?
+- **Data flow**: Where does the relevant data come from? (Redux store, Zustand, React Query, props, API call)
+- **API layer**: Which API endpoints are called? What fetcher/hook is used?
+- **Business logic**: What transformations, validations, or side effects apply to the relevant feature?
+
+Do NOT try to document every flow in the module — only the ones that matter for the goal.
+
+### Step 4: Produce a structured summary
+
+Return findings in this format:
+
+```
+## Module: <path>
+**Goal context**: <what the caller wants to do>
+
+### Key Files
+- `path/to/file.tsx` — <one-line role description>
+- `path/to/hook.ts` — <one-line role description>
+(list only files you actually read and found relevant)
+
+### How It Works
+<2-5 sentences describing the relevant flow: UI → state → API → business logic>
+
+### Key Dependencies
+- Internal: <other modules/components this depends on>
+- External: <npm packages, APIs, services>
+
+### Modification Notes
+<Anything the caller should know before making changes: gotchas, shared state, side effects, tightly coupled areas>
+```
+
+## Rules
+
+- **Relevance over completeness** — a focused 10-file analysis beats a 50-file exhaustive scan
+- **Stop early if the goal is answered** — if you find what the caller needs in 3 files, stop there
+- **Never read files speculatively** — every file read should have a reason tied to the goal
+- **If the scope is too large** (e.g., the caller points at a top-level directory with 20+ subdirectories), ask the caller to narrow down before exploring

package/collections/common/skills/prd-to-milestone/SKILL.md

@@ -0,0 +1,40 @@
+---
+name: prd-to-milestone
+description: This skill is used to create a proper implementation detail of a particular task taken from a Prd document. Use it only when the user or agent has explicitly asked for it.
+---
+
+# PRD to milestone
+
+Helps the user to pick one milestone from a PRD and create a proper plan with implementation detail from top to bottom on how to achieve this.
+
+## When to Use
+
+- Use this skill when user or agent wants to create an implementation detail for a specific task in a PRD document.
+
+## Phase Isolation
+
+> **This should run in a FRESH conversation** — not the same one where `create-prd` ran. The PRD document is the input, not the prior conversation.
+> **Start a NEW conversation for the next phase.** Once this skill produces milestone documents, the user should open a fresh conversation to run `build-feature`.
+
+## Instructions
+
+- Get the task data which we need to implement
+- Analyze the milestone data in context of the current codebase
+- Ask right questions if you are not clear on the problem statement
+- Go through the strategy and approaches finalized in the milestone provided
+- Use the right tools to explore the codebase — especially to determine the architectural approach (see below)
+- For each milestone, describe the following:
+   - **Goal** — what this milestone achieves at a product/behaviour level
+   - **Architectural approach** — explore the codebase to determine this:
+     - `React-only` — if the feature is a standalone interactive component driven by Redux/React Query
+   - **Feature flag needed?** Yes / No. If yes, specify the key name following the `rls-` prefix convention (e.g., `rls-my-feature-name`)
+   - **High-level areas affected** — which modules or subsystems are involved (e.g., "Gmail sidebar", "Backbone conversation module", "React sidebar panel") — do NOT list exact files or lines
+   - **Breaking changes** — anything that could regress existing behaviour
+   - **Skills to activate** — explicitly list which `build-milestone` skills should be invoked for this milestone:
+     - `scaffold-react-feature` + `build-component` (for Pure React features)
+     - `connect-api` (if new API calls are needed)
+   - **Acceptance criteria** — write 2–3 product-level conditions that define "done" for this milestone:
+     - Each criterion describes a user-observable outcome at a high level
+     - These are the coverage target for the `write-test-cases` skill — not detailed test cases
+- Create a separate `<milestone_name>.md` document for each milestone with all the details above.
+- Create the documents under a folder named `milestones` in the same directory where the PRD document is present.

package/collections/common/skills/refractor-and-clean/SKILL.md

@@ -0,0 +1,41 @@
+---
+name: refactor-and-clean
+description: Refactor code for readability, maintainability, and cleanliness following standard guidelines. Use only when the user or agent has explicitly asked for refactoring or cleanup.
+---
+
+# Refactor and Clean
+
+Improve code quality in a file or directory — readability, maintainability, consistency — without changing external behavior.
+
+## Inputs
+
+- **Required:** file or directory path.
+- **Optional:** specific focus (e.g., "just naming", "break up large functions").
+
+## Workflow
+
+1. **Read** target file(s). Identify framework (React/Backbone/vanilla JS/TS).
+2. If invoked by user, ask: "Full pass or specific focus? Any conventions to preserve?" If by agent, proceed directly.
+3. **Analyze** for: dead code, large functions (>40 lines), vague naming, duplication (3+), magic values, deep nesting, responsibility violations.
+4. **Apply rules** (priority order below). Skip any rule where the code is already clean.
+5. **Verify** no behavior change — trace logic, check exports/props unchanged, update import sites for renames.
+6. **Summarize** changes by category (removed, renamed, extracted, restructured).
+
+## Refactoring Rules (priority order)
+
+1. **Remove dead code** — unused imports/vars/functions, commented-out blocks, unreachable branches. Skip if kept for feature flags.
+2. **Improve naming** — describe what, not how. `camelCase` vars/functions, `PascalCase` components, `UPPER_SNAKE_CASE` constants. Booleans as questions (`isVisible`). Skip if external API contract.
+3. **Extract constants** — hardcoded strings/numbers/config into named constants. File-top if local, shared `constants` file if cross-file. Skip if single-use and self-explanatory.
+4. **Break large functions** — split >40 lines or 3+ nesting levels. Prefer pure helpers. React: extract sub-components. Backbone: private methods. Skip if simple sequential pipeline.
+5. **Reduce duplication** — extract shared function/hook for 3+ repetitions. Skip if only 2 and abstraction hurts clarity.
+6. **Simplify control flow** — early returns over nested if/else, lookup objects over long chains, async/await over nested callbacks, no multi-line ternaries.
+7. **Single responsibility** — one job per function/component. Split container+presentational if needed. Skip if <50 lines.
+8. **Minimal comments** — only explain **why**, not what. Remove stale comments. JSDoc for non-obvious exports.
+9. **Organize structure** — constants -> types -> helpers -> main export. Imports: external, internal, relative (grouped).
+
+## Hard Rules
+
+- **Never change behavior.** Flag bugs found during refactoring — don't fix silently.
+- **Respect existing conventions.** Don't introduce conflicting patterns.
+- **Readability > DRY.** Don't over-abstract.
+- **Preserve git blame.** Don't reformat untouched code.