@robosoft/skillhub-cli 0.1.2 → 0.3.3

package/skillhub-registry/docs/exception-process.md

@@ -0,0 +1,194 @@
+# Rule Exception Process
+
+**Status:** Pilot — solo decision-making; process formalizes when team grows
+**Last updated:** 2026-05-06
+**Owner:** Raj Shah
+
+This guide explains what counts as a legitimate deviation from a template rule, how to document it in code, and when a recurring exception should become a rule change instead. Read [`contributing.md`](contributing.md) first if your case is "the rule itself is wrong" rather than "this specific situation justifies a deviation."
+
+> **TL;DR:** Most rules can be deviated from when the deviation is documented and justified. This doc explains when an exception is legitimate, how to document it, and when to escalate to changing the rule itself.
+
+---
+
+## What Is an Exception
+
+The rules in this template are **strong defaults, not absolute laws**. They encode patterns that are right *most* of the time — but most-of-the-time is not all-of-the-time. A 50-line function might genuinely be more readable than the four 12-line helpers you'd extract from it. A magic number in a one-line throwaway script might genuinely be clearer than a named constant.
+
+An **exception** is a deliberate, documented deviation from a rule for a specific case. The crucial word is **documented**. Silent deviations are what the template exists to prevent — they make code feel arbitrary and unauditable. A deviation that is intentional and explained, on the other hand, is healthy: it means the developer engaged with the rule, decided it didn't fit, and recorded why.
+
+The rest of this guide is about how to tell those two cases apart.
+
+---
+
+## When an Exception Is Legitimate
+
+Four common situations where deviating is the right call:
+
+### The rule's rationale doesn't apply to this case
+
+Each rule has a `> **Why:**` blockquote — that's the test. If the *why* isn't relevant here, the rule isn't either.
+
+> **Example:** `rules/code-standards.md` caps functions at ~40 lines because functions over that size almost always mix multiple responsibilities. A 60-line declarative configuration object doesn't have multiple responsibilities — it's one block of data. The rule's rationale doesn't apply.
+
+### Following the rule would harm the code more than help
+
+Rules optimize for the common case. Some specific cases invert the trade-off.
+
+> **Example:** "No magic values" exists to document intent. In a one-line throwaway script that retries three times, extracting `const RETRIES = 3` adds noise without adding clarity — there's no "intent" to document beyond what the literal already conveys.
+
+### The rule conflicts with an external constraint
+
+You don't always control the surface you're writing against.
+
+> **Example:** A library's API forces a callback signature like `(err, data) => {}`. Our naming convention says boolean predicates start with `is/has/should`, but `err` here is a positional contract from the library. Renaming it would break the contract.
+
+### The codebase's existing pattern conflicts
+
+This one is already built into `rules/general.md` as foundation #1: **match the existing codebase before applying these rules.**
+
+> **Example:** A legacy module uses React class components throughout. The React skill says functional only — but introducing one functional component into a class-component file creates a stylistic split that's harder to read than just matching the existing style.
+
+If your case fits one of these four shapes, the exception is probably legitimate. Document it (see below) and move on.
+
+---
+
+## When an Exception Is NOT Legitimate
+
+The harder cases. These all *feel* like exceptions to the developer making them; they are not:
+
+- **"It's faster this way"** — without a measurement, this is premature optimization. The performance skill exists for exactly this situation: profile first, then optimize. A guess is not a rationale.
+- **"I'll fix it later"** — that's a `TODO`, not an exception. Exceptions are deliberate; deferred work is just deferred work.
+- **"The rule is too strict"** — without articulating *why* it's too strict for this specific case, this is just preference. If you can't name what makes this case different from the cases the rule was designed for, follow the rule.
+- **"Other people do it this way"** — appeal to popularity is not a rationale. Plenty of widely-used patterns are widely wrong.
+- **Wanting to use a clever pattern when the boring one would work.** Cleverness is not a justification. The template biases hard toward boring solutions; an exception that exists because boring would have worked is not an exception, it's a preference.
+
+A useful test: **could you write the EXCEPTION comment in two sentences without using the words "I think," "I prefer," or "it feels"?** If not, follow the rule.
+
+---
+
+## How to Document an Exception (In Code)
+
+The mechanic is a comment at the deviation point. Four parts:
+
+1. The marker `EXCEPTION:` so it's grep-able.
+2. The rule being deviated from (path or skill name).
+3. The rationale — *why* this case escapes the rule's purpose.
+4. (Optional) A follow-up plan if the deviation is temporary.
+
+### Example 1 — function-size deviation
+
+```javascript
+// EXCEPTION: rules/code-standards.md function-size limit
+// This config object is 60 lines but extracting it would split a single
+// declarative structure across multiple files, hurting readability.
+// The 40-line limit exists to prevent functions doing too many things;
+// a config object isn't doing anything procedurally.
+const ROUTE_CONFIG = {
+  // ... 60 lines of declarative config
+};
+```
+
+### Example 2 — React skill deviation
+
+```javascript
+// EXCEPTION: skills/react/SKILL.md — class component instead of functional
+// The legacy AdminPanel module uses class components throughout. Adding
+// a functional component here would create a stylistic split. Will be
+// migrated when the entire AdminPanel is rewritten in Q3.
+class AdminCard extends React.Component { /* ... */ }
+```
+
+The second example also shows the optional follow-up plan ("Will be migrated when the entire AdminPanel is rewritten in Q3"). Include that when the deviation is temporary; omit it when it's permanent.
+
+Match the comment style to the language. The `EXCEPTION:` marker is the constant — everything else adapts. In Python:
+
+```python
+# EXCEPTION: rules/code-standards.md nesting depth
+# This four-level loop reflects the four-dimensional structure of the
+# tax form schema. Flattening it would obscure the nesting that's
+# inherent to the data, not accidental in the code.
+```
+
+---
+
+## How to Decide on Exceptions (Today, Pilot Phase)
+
+Right now, the only person granting exceptions is Raj. There is no approval workflow, no signoff, no committee. The "process" is therefore a thinking framework for a single developer making a single judgment call:
+
+1. **Imagine another developer reading this code in six months.** Will they understand why the rule was broken here?
+2. **Try to write the EXCEPTION comment.** If you can write a clear, two-sentence rationale that answers that question, the exception is probably legitimate. If you can't — if the comment comes out as "this seemed cleaner" or "the rule felt too strict" — follow the rule.
+3. **If still unsure, follow the rule.** A consistent codebase that occasionally has a less-than-ideal function is easier to maintain than an inconsistent codebase full of justified-feeling deviations. The default is "follow the rule."
+
+There is no escalation path during pilot beyond "talk it over with Raj." For non-trivial deviations (anything affecting security, correctness, or a rule that exists for a serious reason), do that.
+
+---
+
+## How to Decide on Exceptions (Future, Team Phase)
+
+When the template has more than one maintainer and exceptions stop being a one-person decision, the process formalizes. The expected shape:
+
+- **Routine exceptions** (function size, naming, magic values, formatting) — in-code documentation is sufficient. No review needed.
+- **Exceptions to correctness or security rules** (error handling, input validation, auth checks) — peer review required before merge.
+- **Repeated exceptions to the same rule** — escalated as a rule-change proposal via [`contributing.md`](contributing.md) rather than granted again.
+
+This section is forward-looking. None of the above is in force today.
+
+---
+
+## When to Change the Rule Instead
+
+The single most useful signal in this whole guide:
+
+> **If you find yourself granting the same exception three or more times, the rule is probably wrong.**
+
+Three exceptions to the same rule means one of two things: the rule is too strict, or the rule has unstated conditions that should be explicit. Either way, the right move is to fix the rule, not keep stacking exceptions.
+
+Concrete examples of "the rule should change":
+
+- The 40-line function-size limit gets exception-ed repeatedly inside a game-logic module where state machines naturally produce longer functions → either the rule needs a stated exception for state machines, or the limit needs to be relaxed for that domain.
+- A naming convention that fights the language's idioms (e.g., a `camelCase` rule applied to a Python file where `snake_case` is the language standard) → the rule is wrong, not the code.
+- An anti-pattern that turns out to be the canonical pattern in one stack (e.g., "no global state" applied to a Redux codebase where the store *is* the architecture) → the rule needs scoping.
+
+Use [`contributing.md`](contributing.md) to propose the rule change. Don't keep granting exceptions to a broken rule.
+
+---
+
+## Tracking Exceptions
+
+### Today (pilot phase)
+
+Exceptions are not formally tracked. They live in code as `EXCEPTION:` comments, and they are reviewed when (and only when) someone happens across them. This is fine at solo scale; it does not scale to a team.
+
+### Future
+
+When team grows, exceptions become auditable. The simplest mechanism is grep:
+
+```bash
+grep -rn "EXCEPTION:" --include="*.{js,ts,tsx,jsx,py,go,rs}" .
+```
+
+A periodic review of that output catches two things: (a) exceptions whose follow-up plans are now overdue, and (b) rules that are being exception-ed often enough to warrant changing.
+
+Codifying that into a CI step or a quarterly review ritual is a v1.0+ concern.
+
+---
+
+## What NOT to Document as an Exception
+
+Some things look like exceptions but aren't:
+
+- **Things outside the rule's scope.** If the rule doesn't actually cover your case, you're not deviating — you're just operating outside the rule. No comment needed.
+- **Personal style preferences.** "I like spaces around operators in this one file." → Not an exception. Use `CLAUDE.local.md` (see [`customization.md`](customization.md#personal-vs-shared-customizations)).
+- **Bugs.** A function that's 200 lines because nobody factored it isn't an exception, it's a bug. Fix it or file it; don't dignify it with an `EXCEPTION:` comment.
+- **Exploratory hacks.** Code marked "I'm just trying something" belongs behind a `TODO` or `FIXME`, not an `EXCEPTION:`. Reserve `EXCEPTION:` for *intentional, justified* deviations.
+
+The bar for `EXCEPTION:` is: I have considered the rule, I have a specific reason this case is different, and I'd defend that reason in a code review.
+
+---
+
+## Where to Get Help
+
+- **A recurring exception suggests the rule itself is wrong** → [`contributing.md`](contributing.md) for proposing a rule change.
+- **You want to add a rule that fits your specific context** → [`customization.md`](customization.md).
+- **Overall context on what the template is** → [`../README.md`](../README.md).
+- **When in doubt** → message Raj Shah. During pilot phase, that is the entire escalation path.

package/skillhub-registry/docs/installation.md

@@ -0,0 +1,277 @@
+# Installation Guide
+
+**Status:** Pilot — install instructions for the v0.1.0 template
+**Last updated:** 2026-05-06
+**Owner:** Raj Shah
+
+This guide walks you through installing the org's Claude coding template so that Claude Code automatically loads the shared rules, skills, and slash commands on every session. Most developers should follow Method 1 (the install script). Allow about 5 minutes end-to-end.
+
+> **TL;DR:** Clone the template, run `./install.sh`, then start `claude` and type `/help` to confirm the slash commands appear. If they don't, jump to the Troubleshooting section.
+
+---
+
+## Prerequisites
+
+Before running any of the steps below, confirm you have:
+
+| Requirement | How to check | Where to get it |
+|---|---|---|
+| **Claude Code** installed and signed in | `claude --version` returns a version string | See Anthropic's Claude Code docs |
+| **Git** | `git --version` returns a version string | https://git-scm.com/ (or `xcode-select --install` on macOS) |
+| **A terminal** | Terminal.app on macOS, your distro's terminal on Linux, Windows Terminal on Windows | Built into the OS |
+| **An Anthropic API key configured** | `claude` launches without prompting for credentials | Anthropic Console → API Keys |
+
+If any of these are missing, install them first. The rest of this guide assumes all four are working.
+
+---
+
+## Installation Method 1: Install script (recommended)
+
+The fastest path. The script symlinks `CLAUDE.md`, `rules/`, `skills/`, and `domain/` into `~/.claude/`, with smart handling of any files that are already there.
+
+### Step 1 — Clone the template
+
+```bash
+git clone [REPO_URL] ~/.claude-template
+```
+
+**What it does:** Puts the template in `~/.claude-template`. Pick any path you like; this guide assumes `~/.claude-template`.
+**Success looks like:** `ls ~/.claude-template` shows `CLAUDE.md`, `rules/`, `skills/`, `domain/`, `docs/`, `install.sh`, `uninstall.sh`.
+
+> Replace `[REPO_URL]` with your org's actual repo URL. If you don't have one yet, copy the folder manually — Method 3 below covers that.
+
+### Step 2 — Make the script executable
+
+```bash
+cd ~/.claude-template
+chmod +x install.sh
+```
+
+**Why this step:** Git preserves the executable bit when present in the repo, but a fresh clone or a copy through some channels (zip, scp without preserved permissions) may strip it. The script can't make itself executable — that's a one-time chmod.
+
+### Step 3 — Run the installer
+
+```bash
+./install.sh
+```
+
+**What it does:** Verifies the template directory looks right, ensures `~/.claude/` exists, and creates four symlinks. If anything is already at one of those paths, the script tells you what's there and asks before replacing it. Real files and directories are backed up to `<name>.backup-YYYYMMDD-HHMMSS` before the symlink replaces them.
+
+**Success looks like:**
+```
+Summary
+  created:    4
+  replaced:   0
+  backed up:  0
+  unchanged:  0
+  skipped:    0
+```
+
+If the script reports `unchanged: 4`, you'd already installed it — re-running is safe and idempotent.
+
+### Step 4 — Verify the slash commands
+
+Launch Claude Code in interactive mode, then type `/help` inside the session:
+
+```bash
+claude
+```
+
+Once the session is open, type:
+
+```
+/help
+```
+
+**Success looks like:** The `/help` output lists the custom commands defined by this template — `/build`, `/refactor`, `/review`, `/feature-dev`, `/fast`, `/strict`. If you only see Claude Code's built-in commands, the symlinks didn't take — see Troubleshooting.
+
+> Slash commands like `/help` only work inside an interactive Claude Code session — they are not available via non-interactive flags.
+
+---
+
+## Installation Method 2: Manual install (advanced)
+
+The script does nothing magical — these are the same `ln -s` commands it issues. Use this method when you want to understand what's happening, can't execute scripts on a managed machine, or are debugging the script itself.
+
+### Step 1 — Clone the template to a permanent location
+
+```bash
+git clone [REPO_URL] ~/.claude-template
+```
+
+**Success looks like:** `ls ~/.claude-template` shows `CLAUDE.md`, `rules/`, `skills/`, `domain/`, `docs/`.
+
+### Step 2 — Make sure `~/.claude/` exists
+
+```bash
+mkdir -p ~/.claude
+```
+
+### Step 3 — Symlink the four entry points
+
+```bash
+ln -s ~/.claude-template/CLAUDE.md ~/.claude/CLAUDE.md
+ln -s ~/.claude-template/rules    ~/.claude/rules
+ln -s ~/.claude-template/skills   ~/.claude/skills
+ln -s ~/.claude-template/domain   ~/.claude/domain
+```
+
+**Success looks like:** `ls -la ~/.claude` shows four entries with `->` pointing back at `~/.claude-template/...`.
+
+> If `~/.claude/CLAUDE.md` already exists (from a prior setup), back it up first: `mv ~/.claude/CLAUDE.md ~/.claude/CLAUDE.md.bak`. Then re-run the `ln -s` line. The install script handles this for you automatically.
+
+### Step 4 — Verify the slash commands
+
+Same as Method 1, Step 4 — launch `claude` and type `/help`.
+
+---
+
+## Installation Method 3: Direct copy (alternative)
+
+For users who can't use symlinks (some corporate-managed machines disable them) or who prefer a frozen snapshot:
+
+```bash
+cp ~/.claude-template/CLAUDE.md ~/.claude/CLAUDE.md
+cp -r ~/.claude-template/rules   ~/.claude/rules
+cp -r ~/.claude-template/skills  ~/.claude/skills
+cp -r ~/.claude-template/domain  ~/.claude/domain
+```
+
+**Trade-off:** When the template updates, you have to re-run these copies manually. With symlinks (Methods 1 and 2), `cd ~/.claude-template && git pull` is enough.
+
+Verify the same way as Method 1 — launch `claude` and type `/help` inside the session.
+
+---
+
+## Per-Project Installation (advanced)
+
+Claude Code also reads a `CLAUDE.md` from the **project root** (the directory you launched `claude` from). Project-level config layers on top of the global config in `~/.claude/`.
+
+This is useful when:
+- A specific project has its own conventions that override or extend the global rules
+- You want skills that only apply to one codebase
+- You're piloting changes to the template before promoting them globally
+
+To set up a project-specific `CLAUDE.md`:
+
+1. Create `CLAUDE.md` in the project root.
+2. Reference the global rules by `@import` if you want them to still apply (Claude Code resolves `@import` paths relative to the file doing the import).
+3. Add project-specific rules below the imports.
+
+For details on how Claude Code merges global and project config, see https://code.claude.com/docs/en/memory.
+
+---
+
+## Verification
+
+After installing, do a quick smoke test:
+
+1. **Open Claude Code in any project:**
+   ```bash
+   cd ~/some-project && claude
+   ```
+2. **Type `/help`** — confirm `/build`, `/refactor`, `/review`, `/feature-dev`, `/fast`, `/strict` all appear in the list.
+3. **Ask Claude something simple,** e.g.:
+   > "Write a function that sums an array."
+
+   Verify Claude follows the rules in `rules/general.md` — concretely: it asks for clarification if the language isn't obvious, doesn't invent APIs, and doesn't refactor unrelated code.
+4. **Trigger the React skill:**
+   > "Review this React component: `function Foo() { return <div>hi</div>; }`"
+
+   Claude should pick up React-specific guidance (from `skills/react/SKILL.md`) without you having to invoke it explicitly. A quick way to confirm: ask Claude "which skills did you load for that response?" and it should mention `react`.
+
+If all four pass, installation is complete.
+
+---
+
+## Troubleshooting
+
+| Symptom | Likely cause | Fix |
+|---|---|---|
+| **Slash commands don't appear in `/help`** | `~/.claude/skills/` is missing or empty | Confirm `ls ~/.claude/skills/` shows folders (`api`, `build`, `fast`, etc.) each containing a `SKILL.md`. Re-run `./install.sh` if missing. |
+| **Rules don't seem to apply** (Claude ignores conventions) | `~/.claude/CLAUDE.md` missing, or its `@import` lines point to files that don't exist | Confirm `~/.claude/CLAUDE.md` exists (`ls -la ~/.claude/CLAUDE.md`) and contains the three `@rules/...` imports. Confirm `~/.claude/rules/general.md` resolves. |
+| **Claude Code logs `cannot find file referenced by @import`** | `@import` paths are resolved **relative to the file doing the import** | If `CLAUDE.md` lives at `~/.claude/CLAUDE.md`, then `@rules/general.md` resolves to `~/.claude/rules/general.md`. Make sure that file exists (or that the symlink points somewhere real). |
+| **Symlinks broke after I moved the template folder** | `ln -s` stores absolute paths — moving the target leaves dangling links, and `uninstall.sh` will see them as "foreign" because they no longer point at the new location | Manually clear the broken links: `unlink ~/.claude/CLAUDE.md ~/.claude/rules ~/.claude/skills ~/.claude/domain`, then run `./install.sh` from the new template location. |
+
+If none of the above match, message Raj Shah with the output of `ls -la ~/.claude/` and the first line of `~/.claude/CLAUDE.md`.
+
+---
+
+## Updating the Template
+
+### Symlink installs (Methods 1 and 2)
+
+```bash
+cd ~/.claude-template
+git pull
+```
+
+Updates apply automatically — Claude Code reads the new files on the next session. No need to re-run `install.sh` unless the update introduces new top-level entries (the script is safe to re-run; it will report `unchanged` for anything already linked correctly).
+
+### Direct-copy installs (Method 3)
+
+Re-run the `cp` commands from Method 3. Existing `~/.claude/CLAUDE.md` will be overwritten — back it up first if you've made local edits.
+
+### Before updating
+
+Skim [`CHANGELOG.md`](../CHANGELOG.md) at the root of the template. Major version bumps may require re-running install steps; minor and patch versions just apply.
+
+---
+
+## Uninstalling
+
+### From a script-based or manual symlink install (Methods 1 and 2)
+
+```bash
+cd ~/.claude-template
+./uninstall.sh
+```
+
+The uninstaller only removes symlinks that point back into *this* template directory. Real files at `~/.claude/`, symlinks pointing to other templates, and any `*.backup-*` files left by `install.sh` are kept. The script prints a summary so you can see exactly what was removed and what was left.
+
+### From a direct-copy install (Method 3)
+
+The uninstall script won't remove copied directories — it only handles symlinks. Remove them manually:
+
+```bash
+rm ~/.claude/CLAUDE.md
+rm -r ~/.claude/rules ~/.claude/skills ~/.claude/domain
+```
+
+> Confirm each path before running `rm -r`. If you're not sure, list contents first with `ls -la ~/.claude/`.
+
+### Deleting the template folder
+
+If you also want to remove the cloned template itself:
+
+```bash
+rm -rf ~/.claude-template
+```
+
+> Be careful with `rm -rf`. Confirm the path before pressing Enter.
+
+---
+
+## Setup for Claude.ai (web/app) instead of Claude Code
+
+If you use Claude.ai instead of (or alongside) Claude Code, you can get most of the same benefit by setting up a Project:
+
+1. **Create a Project** in Claude.ai (left sidebar → New Project).
+2. **Paste the contents of `CLAUDE.md`** into the Project's "Custom instructions" / "Project instructions" field.
+3. **Upload the rule and skill files as Project Knowledge:**
+   - `rules/general.md`, `rules/code-standards.md`, `rules/anti-patterns.md`
+   - The `SKILL.md` files for any skills you want available
+   - `domain/api.md` if you're working on API code
+4. **Reference them in conversation** — on Claude.ai, skills don't auto-trigger the way they do in Claude Code. You'll need to explicitly say "apply the React skill" or "follow the testing standards" when relevant.
+
+This is a workable fallback but it's a noticeably worse experience than Claude Code: no auto-loading, no slash commands, no on-demand skill detection. If the org standardizes on Claude Code, this section becomes optional.
+
+---
+
+## Where to Get Help
+
+- **Installation problems** → Raj Shah
+- **Cost / token-usage best practices** → [`docs/cost-hygiene.md`](cost-hygiene.md)
+- **Overall context on what this template is and why it exists** → [`README.md`](../README.md)
+- **Proposing changes to rules or skills** → `docs/contributing.md` (when published)
+- **Requesting an exception to a rule** → `docs/exception-process.md` (when published)