@robosoft/skillhub-cli 0.1.2 → 0.3.2

package/skillhub-registry/README.md

@@ -1,23 +1,203 @@
-# SkillHub Local Registry
+# Claude Coding Template
 
-This folder acts as a local skill registry for the demo CLI.
+A shared standard for using Claude Code consistently across our org. Install once, follow team conventions automatically.
 
-Each skill package follows this structure:
+**Version:** 0.1.0 (pilot)
+**Status:** Pilot — under refinement before org-wide rollout
+**Owner:** [Raj Shah]
 
-```txt
-skillhub-registry/
-  skill-name/
-    1.0.0/
-      skill.json
-      SKILL.md
-      rules/
-      templates/
-      checklist/
-```
+---
+
+## What This Is
+
+This repository is a Claude Code template that gives every developer in the org the same:
+
+- Coding standards (function size, naming, error handling, anti-patterns)
+- Domain expertise (React, API design, testing, performance)
+- Workflows (build, refactor, review, full-feature development)
+- Behavior modes (`/fast` for prototyping, `/strict` for production)
+- Org-specific conventions (our API conventions, future domain knowledge)
+
+When installed, Claude Code automatically applies these standards to every coding task — no manual reminders, no copy-pasted prompts, no inconsistency between teammates.
+
+## Why This Exists
+
+Without a shared template, every developer ends up with their own ad-hoc Claude setup:
+
+- Different rules → inconsistent code style across the codebase
+- Different prompts → different output quality
+- Junior devs miss conventions senior devs take for granted
+- New hires take weeks to absorb tribal knowledge
+- Code review burden grows as AI-generated code drifts from team standards
 
-Install a skill into any project from the repository root:
+This template solves that. **One source of truth, version-controlled, reviewable, evolvable.**
+
+## Who Should Install This
+
+- ✅ Anyone using Claude Code for org work
+- ✅ New hires on day one
+- ✅ Anyone preparing AI-assisted code for client deliverables
+
+You don't need to be a Claude Code power user — installation is one command, and the template just works in the background.
+
+---
+
+## Quick Install
 
 ```bash
-node packages/@robosoft/skillhub-cli/bin/skillhub.mjs init
-node packages/@robosoft/skillhub-cli/bin/skillhub.mjs install nextjs-clean-architecture
+# 1. Clone this repo
+git clone [REPO_URL] ~/.claude-template
+
+# 2. Run the install script
+cd ~/.claude-template
+chmod +x install.sh
+./install.sh
+
+# 3. Verify (inside Claude Code)
+claude
+# then type /help
 ```
+
+To uninstall later, run `./uninstall.sh` from the same template directory.
+
+For detailed instructions (including troubleshooting, manual install, and per-project setup), see [`docs/installation.md`](docs/installation.md).
+
+---
+
+## What You Get After Installing
+
+Once installed, Claude Code automatically:
+
+1. **Loads the rules** at the start of every session (no setup needed)
+2. **Detects when domain skills apply** and loads them on demand (React skill triggers on React work, etc.)
+3. **Recognizes slash commands** like `/build`, `/refactor`, `/review`, `/strict`, `/fast`
+4. **Applies org-specific conventions** when working in our codebases (via `domain/`)
+
+You don't have to do anything different — just write code as usual. The template applies in the background.
+
+---
+
+## What Lives Here
+
+ai/
+├── CLAUDE.md              Entry point — auto-loaded by Claude Code
+│
+├── rules/                 Always-on, universal coding rules
+│   ├── general.md            Foundations: codebase style, no hallucination, scope
+│   ├── code-standards.md     Concrete: function size, nesting, naming, errors
+│   └── anti-patterns.md      What never to do, with rationale
+│
+├── skills/                On-demand expertise (auto-loads when relevant)
+│   ├── api/                  Universal API design standards
+│   ├── build/                Implementation workflow
+│   ├── fast/                 Quick-prototyping mode
+│   ├── feature-dev/          End-to-end feature development workflow
+│   ├── performance/          Performance optimization standards
+│   ├── react/                React-specific conventions
+│   ├── refactor/             Behavior-preserving restructuring
+│   ├── review/               Code critique and review
+│   ├── strict/               Production-rigor mode
+│   └── testing/              Test writing and review standards
+│
+├── domain/                Org-specific conventions
+│   └── api.md                Our API decisions (envelope, auth, pagination, etc.)
+│
+└── docs/                  For humans, not Claude
+├── cost-hygiene.md       Token cost best practices
+├── installation.md       Detailed install + troubleshooting
+├── exception-process.md  How to request rule changes
+├── contributing.md       How to propose changes via PR
+└── customization.md      How teams add their own skills
+
+---
+
+## How to Use Slash Commands
+
+Once installed, these commands work in Claude Code:
+
+| Command | What it does |
+|---|---|
+| `/build <task>` | Structured implementation workflow |
+| `/refactor` | Restructure code without changing behavior |
+| `/review` | Critique code with prioritized findings |
+| `/feature-dev` | Full feature development lifecycle |
+| `/fast` | Speed-over-polish mode for prototypes |
+| `/strict` | Maximum-rigor mode for production code |
+
+Skills also trigger automatically when their topic comes up — you don't always need to invoke them explicitly. For example, asking "review my React component" triggers both `/review` and the `react` skill automatically.
+
+You can combine modes and skills: `/strict` + React work → strict-mode review of React code with all React conventions enforced.
+
+---
+
+## How to Customize for Your Team
+
+The template is meant to be extended, not edited centrally for every team need. Recommended pattern:
+
+1. **For org-wide changes** (new universal rule, new shared skill) — propose via PR. See [`docs/contributing.md`](docs/contributing.md).
+2. **For team-specific additions** (your team's database conventions, your team's deployment process) — add to your project's local `.claude/skills/` or to your local `domain/` overrides.
+3. **For individual preferences** — use `CLAUDE.local.md` (gitignored, personal).
+4. **For exceptions to a universal rule** — see [`docs/exception-process.md`](docs/exception-process.md).
+
+This way the shared template stays clean, while teams retain flexibility.
+
+---
+
+## Compatibility
+
+This template is built for **Claude Code** primarily. It also works with:
+
+- **Claude.ai web/app** — copy `CLAUDE.md` and rule files into a Project's instructions and knowledge
+- **Other AI coding tools** that support the open Agent Skills format (Cursor, Codex CLI, Gemini CLI, etc.) — skills should work directly; rules need adapting
+
+For Claude.ai setup details, see [`docs/installation.md`](docs/installation.md).
+
+---
+
+## Cost Considerations
+
+Using this template has minimal token cost — the rule files are auto-cached by Claude Code, so they cost ~10% of normal pricing after the first message of a session.
+
+For best practices on managing API costs across the team, see [`docs/cost-hygiene.md`](docs/cost-hygiene.md).
+
+---
+
+## Versioning
+
+Changes to this template follow semantic versioning ([`CHANGELOG.md`](CHANGELOG.md)):
+
+- **Major** — breaking changes (rule removals, structure changes that affect installation)
+- **Minor** — new rules, new skills, behavior shifts
+- **Patch** — clarifications, typo fixes, small additions
+
+Always check `CHANGELOG.md` before pulling updates — major changes may require re-running install steps.
+
+---
+
+## Pilot Phase Notice
+
+This template is currently in **pilot mode**, being refined by [your name] before broader rollout. During pilot:
+
+- Rules may change frequently as we learn what works
+- Some sections of `domain/` are placeholders pending team decisions
+- Feedback is highly welcome — open an issue or message [contact Raj Shah directly]
+
+After pilot, the template will be promoted to v1.0 and changes will follow the standard contribution process.
+
+---
+
+## Questions / Issues
+
+- **Installation problems:** [`docs/installation.md`](docs/installation.md) → Troubleshooting section
+- **Want to propose a rule change:** [`docs/contributing.md`](docs/contributing.md)
+- **Need an exception to a rule:** [`docs/exception-process.md`](docs/exception-process.md)
+- **Cost concerns:** [`docs/cost-hygiene.md`](docs/cost-hygiene.md)
+- **Anything else:** [contact Raj Shah directly]
+
+---
+
+## License / Attribution
+
+[Internal use only]
+
+Built on the [Anthropic Claude Code](https://docs.claude.com/) skill system and the open [Agent Skills](https://agentskills.io) standard.

package/skillhub-registry/docs/cheat-sheet.md

@@ -0,0 +1,272 @@
+# Prompt Cheat Sheet
+
+**Status:** Pilot — examples will evolve as the template matures
+**Last updated:** 2026-05-06
+**Owner:** Raj Shah
+
+This is a quick reference for writing prompts that get the most out of the template. You don't need to memorize the skill details — this doc shows you which phrasing triggers which behavior, and how to combine skills for common workflows.
+
+> **TL;DR:** If you want X, type Y. Skills auto-trigger from your phrasing — slash commands make it explicit. Rules apply automatically; don't worry about invoking those.
+
+---
+
+## How Skills Trigger
+
+The template has two mechanisms:
+
+**Slash commands** — explicit invocation. You type `/build`, `/refactor`, `/strict`, etc. These always work.
+
+**Natural language** — implicit triggering. Claude detects keywords in your prompt and loads the matching skill. For example, asking "review my React component" triggers both `/review` and the React skill without you typing anything.
+
+**Both can combine in one prompt.** `/strict /review` makes the review more rigorous. "Build me a Vue component" triggers the build skill + Vue skill (when it exists).
+
+**Rules apply automatically.** Every prompt gets `rules/general.md`, `rules/code-standards.md`, and `rules/anti-patterns.md`. You don't invoke those — they're always on.
+
+---
+
+## Quick Reference Table
+
+| I want to... | Type this | Or say this |
+|---|---|---|
+| Implement new code | `/build <task>` | "Build me a function that sorts an array" |
+| Restructure existing code | `/refactor` | "Simplify this code — extract duplication" |
+| Get code critique | `/review` | "Review this code — any issues?" |
+| Multi-file feature | `/feature-dev <task>` | "Implement a complete login feature" |
+| Speed over polish | `/fast <task>` | "Rough version of a button component" |
+| Production rigor | `/strict` | "Review this carefully — call out every issue" |
+| React-specific work | `/react` | "Build a custom hook for form validation" |
+| API design | `/api` | "Design an endpoint for fetching user data" |
+| Test writing | `/testing` | "Write tests for this function" |
+| Performance tuning | `/performance` | "This page is slow — how do I optimize?" |
+| Combined: strict + review | `/strict /review <code>` | "Production code review please — be thorough" |
+| Combined: fast + build | `/fast` + "Quick prototype of..." | "Rough implementation of a modal dialog" |
+
+---
+
+## Per-Skill Examples
+
+### /build
+**Purpose:** Structured implementation workflow for new code — function, component, module, feature.
+
+**Good prompts:**
+- `/build a function that validates email addresses`
+- "Implement a reusable authentication middleware"
+- "Create a button component that can be disabled"
+
+**Won't trigger this skill:**
+- "Make this code better" (vague, no "build" signal)
+- "Fix the bug in my login" (that's debugging, not building)
+
+**Combinations:** `/build /react` for a new React component. `/fast /build` for a rough prototype.
+
+---
+
+### /refactor
+**Purpose:** Restructure existing code without changing behavior — extract duplication, improve naming, flatten nesting.
+
+**Good prompts:**
+- `/refactor this deeply nested conditional`
+- "Extract the shared logic from these two functions"
+- "Simplify and rename these variables"
+
+**Won't trigger this skill:**
+- "Refactor this to add error handling" (that's a behavior change, not a refactor)
+- "Make this function work better" (too vague)
+
+**Combinations:** `/refactor /strict` to refactor with maximum rigor. `/refactor /react` when refactoring React components.
+
+---
+
+### /review
+**Purpose:** Critique existing code — identify bugs, smells, improvements, and what's good.
+
+**Good prompts:**
+- `/review` (paste code)
+- "Review my React component — any issues?"
+- "Code review please. Tell me what could be better."
+
+**Won't trigger this skill:**
+- "Is this good?" without code (need actual code to review)
+
+**Combinations:** `/strict /review` for exhaustive, pedantic review. `/review /react` when reviewing React code (the React skill also loads).
+
+---
+
+### /feature-dev
+**Purpose:** End-to-end feature development — orchestrates build, refactor, review, and testing across multiple files.
+
+**Good prompts:**
+- `/feature-dev a complete login system with signup and password reset`
+- "Build a feature that lets users export data as CSV"
+- "Implement dark mode — full-stack"
+
+**Won't trigger this skill:**
+- `/build` (single function, not a full feature)
+- "Add error handling to this function" (bug fix, not a feature)
+
+**Combinations:** `/feature-dev /strict` for a production feature. `/feature-dev /fast` for a quick prototype of a multi-file feature.
+
+---
+
+### /fast
+**Purpose:** Speed-over-polish mode for prototyping and rapid iteration. Relaxes some rules; skips exhaustive explanation.
+
+**Good prompts:**
+- `/fast build a login form component`
+- "Quick and dirty version of a dark mode toggle"
+- "Rough implementation of a shopping cart"
+
+**Won't trigger this skill:**
+- Production code that will ship to users (use `/strict` instead)
+- Code that needs rigorous testing
+
+**Combinations:** `/fast /build` for rapid prototyping. `/fast /react` for a quick React spike.
+
+---
+
+### /strict
+**Purpose:** Production-rigor mode. All rules apply with full strength; pedantic about violations.
+
+**Good prompts:**
+- `/strict /build a password validation function`
+- "Security-critical authentication code — be thorough"
+- "Review this — this is going to production"
+
+**Won't trigger this skill:**
+- Exploratory prototyping (use `/fast` instead)
+- Quick debugging (be pragmatic)
+
+**Combinations:** `/strict /feature-dev` for a production-ready feature. `/strict /review` for exhaustive code review.
+
+---
+
+### /react
+**Purpose:** React-specific conventions — component structure, hooks, state management, patterns.
+
+**Good prompts:**
+- `/react build a custom hook for managing form state`
+- "Review my React component — follow React best practices"
+- "Refactor this class component to use hooks"
+
+**Won't trigger this skill:**
+- Vue or non-React work
+- Generic JavaScript without React context
+
+**Combinations:** `/react /strict` when building production React. `/react /fast` for a quick React spike. `/refactor /react` when refactoring React code.
+
+---
+
+### /api
+**Purpose:** API design and implementation standards — endpoints, error responses, pagination, versioning, contracts.
+
+**Good prompts:**
+- `/api design an endpoint that lists users with pagination`
+- "Build a REST API for a blog with posts and comments"
+- "Review this API response shape — is it well-designed?"
+
+**Won't trigger this skill:**
+- Frontend-only work
+- Calling an API (that's client-side; see `/react` for that)
+
+**Combinations:** `/api /strict` for a production API. `/api /build` for implementing new endpoints.
+
+---
+
+### /testing
+**Purpose:** Test writing and review standards — unit tests, integration tests, mocking, coverage, good vs bad tests.
+
+**Good prompts:**
+- `/testing write tests for this function`
+- "How do I test this React component?"
+- "Review these tests — are they good?"
+
+**Won't trigger this skill:**
+- Running existing tests (that's CI/deployment)
+- Debugging a failing test
+
+**Combinations:** `/testing /react` when testing React components. `/strict /testing` for rigorous test coverage. `/feature-dev /testing` (feature-dev includes testing as part of the workflow).
+
+---
+
+### /performance
+**Purpose:** Performance optimization — measure bottlenecks, lazy loading, caching, bundle size, database queries.
+
+**Good prompts:**
+- `/performance this page loads slowly — how do I speed it up?`
+- "Optimize this N+1 query problem"
+- "How do I reduce bundle size?"
+
+**Won't trigger this skill:**
+- "Make this faster" without data (measurement comes first)
+- Vague speed concerns
+
+**Combinations:** `/performance /react` when optimizing React rendering. `/strict /performance` for production performance work.
+
+---
+
+## Combining Skills
+
+The real power comes from combining skills and modes. Here are the patterns that work:
+
+### "Production feature with full rigor"
+```
+/feature-dev /strict a complete user authentication system
+```
+Result: Full feature workflow + production-grade standards + all rules enforced pedantically.
+
+### "Quick React prototype"
+```
+/fast /react build a component that shows a list of items
+```
+Result: React conventions + speed mode = fast iteration on UI ideas.
+
+### "Refactor production code carefully"
+```
+/refactor /strict [code]
+```
+Result: Restructure without changing behavior + maximum rigor = safe refactoring under scrutiny.
+
+### "Intensive code review"
+```
+/strict /review [code]
+```
+Result: Critique + pedantic rigor = catches every detail, no stone unturned.
+
+### "Test a new feature"
+```
+/feature-dev /testing [description]
+```
+Result: Build + test + review workflow included in the feature development.
+
+---
+
+## Anti-Patterns
+
+Some phrasings don't trigger what you expect, or actively work against the template:
+
+| Anti-pattern | Why it doesn't work | Do this instead |
+|---|---|---|
+| "Make this better" | Too vague — no skill triggers. Rules apply but you get generic feedback | Be specific: `/refactor this`, `/review this`, `/build something new` |
+| `/build /refactor` together | These conflict (build = new code, refactor = existing). Confusion ensues | Pick one: new code → `/build`. Existing code → `/refactor` |
+| "Pretend you're a senior engineer..." | Unnecessary role-play. The template already does this via rules and skills | Just describe the task; rules handle the rigor |
+| "Ignore your rules..." | Won't work. Rules are built into every session via `@import`. Can't override them mid-prompt | If a rule truly doesn't fit, use [`docs/exception-process.md`](exception-process.md) |
+| `/review` without code | The skill loads but has nothing to review | Paste the code block or provide clear context |
+
+---
+
+## When Skills Don't Trigger
+
+Sometimes Claude under-triggers a skill. This is by design (skills are conservative to avoid false positives), but you can always be explicit:
+
+- **Skill didn't load?** Invoke explicitly with the slash command: `/build` instead of just "build me something."
+- **Keeps under-triggering?** The skill's trigger description might be too narrow. File an issue via [`docs/contributing.md`](contributing.md).
+- **Vague prompt = vague response.** "This is slow" gets vague feedback. "This database query runs in O(n²) and blocks the page — how do I optimize?" gets specific help.
+
+---
+
+## Where to Go from Here
+
+- **Details on any skill** — read the full `skills/<skill-name>/SKILL.md` file
+- **Proposing a new pattern** — [`docs/contributing.md`](contributing.md)
+- **Installation and setup** — [`docs/installation.md`](installation.md)
+- **One-off exceptions to a rule** — [`docs/exception-process.md`](exception-process.md)

package/skillhub-registry/docs/contributing.md

@@ -0,0 +1,166 @@
+# Contributing
+
+**Status:** Pilot — solo maintenance, contribution process will mature as team grows
+**Last updated:** 2026-05-06
+**Owner:** Raj Shah
+
+This guide describes how to propose changes to the shared template. The process is intentionally lightweight today and will formalize once the template graduates from pilot. Read [`customization.md`](customization.md) first if your change is something you can keep local — many changes don't need to be upstreamed.
+
+> **TL;DR:** During pilot phase, contributions = message Raj Shah directly. Once we move to v1.0 with a Git repo and additional maintainers, the process formalizes (fork, PR, review, CI). Until then, direct communication is the whole workflow.
+
+---
+
+## Current State (Pilot Phase)
+
+The template is being refined through real use before its process is formalized. Right now:
+
+- **One maintainer:** Raj Shah owns and edits all template files directly.
+- **No Git repository yet.** The template lives in a working directory and is shared by direct copy or symlink.
+- **No PR workflow yet.** There's no fork-and-branch model, no required reviewers, no merge queue.
+- **No CI.** Verification is run manually against the structural checks documented in [`customization.md`](customization.md#testing-your-customizations).
+- **Feedback channel:** direct message or conversation with Raj.
+
+This is deliberate. Codifying a contribution process before the template has been pressure-tested invites premature ceremony. The plan is to graduate the process once (a) the template has at least one more active maintainer, (b) it's hosted in a real Git repo, and (c) it has stabilized enough that breaking changes are rare.
+
+Until then: short feedback loops, direct edits, low ceremony.
+
+---
+
+## What Counts as a Contribution
+
+Any of the following is welcome:
+
+| Contribution type | Description |
+|---|---|
+| **Suggesting a new skill** | "We should have a Python skill" / "We need an AWS infrastructure skill" |
+| **Proposing a rule change** | "The 40-line function limit is too restrictive for our data-pipeline code — here's why" |
+| **Reporting a rule that misfires** | "The React skill should have triggered on this prompt and didn't" |
+| **Adding org-specific knowledge to `domain/`** | New database conventions, deployment process, auth model |
+| **Documenting a recurring correction** | "I keep having to remind Claude to do X — can we encode that as a rule?" |
+| **Improving an existing skill or rule** | Better examples, clearer rationale, fixing a confusing section |
+| **Fixing typos, broken links, formatting** | Self-explanatory |
+
+The most valuable contributions are **recurring corrections** — patterns where Claude consistently goes wrong and you've found yourself fixing the same issue more than once. Encoding those into a rule or skill is exactly what the template exists for. If you notice yourself making the same correction twice, that's a contribution waiting to happen.
+
+---
+
+## How to Suggest a Change (Today, Pilot Phase)
+
+The current process is just a conversation. Five steps:
+
+### Step 1 — Identify what kind of change it is
+
+- **Universal rule** → goes in `rules/`
+- **Topic-specific guidance** → goes in a `skills/<name>/SKILL.md`
+- **Org-specific decision** → goes in `domain/<topic>.md`
+- **Documentation** → goes in `docs/`
+- **Bug fix** (typo, broken link, structural issue) → no categorization needed
+
+If you're not sure, that's fine — Raj will help place it correctly.
+
+### Step 2 — Reach out to Raj Shah
+
+Bring three things:
+
+1. **What you want to change** — be specific (e.g., "add a `## Mocking External APIs` section to `skills/testing/SKILL.md`," not "improve testing").
+2. **Why** — the concrete situation where the current template fell short. Include the prompt you used, what Claude produced, and what you wanted instead.
+3. **Proposed new content (optional but appreciated)** — even rough draft text is more valuable than a request without one.
+
+### Step 3 — Discussion
+
+Raj reviews the proposal, asks questions if anything is unclear, and either accepts, declines, or proposes a different shape. For small changes (typos, minor clarifications) this is usually instant. For new skills or rule changes, expect a back-and-forth.
+
+### Step 4 — Edit and update `CHANGELOG.md`
+
+Once aligned, the actual edit happens directly. The change is logged under `## [Unreleased]` in [`../CHANGELOG.md`](../CHANGELOG.md), under the appropriate subsection (`### Added`, `### Changed`, etc.).
+
+### Step 5 — Release
+
+When a batch of changes is ready, the version bumps per [Versioning](#versioning) below, the `[Unreleased]` block is renamed to the new version, and the change ships.
+
+That's the whole process. No PR template, no review meeting, no CI. Just communication.
+
+---
+
+## How to Suggest a Change (Future, Team Phase)
+
+When the template graduates to v1.0 — meaning it's stable enough for org-wide rollout and has at least one additional maintainer — the process formalizes. The expected shape:
+
+- **Hosted in a Git repository** (GitHub, GitLab, or an internal equivalent — TBD).
+- **Fork → branch → PR workflow.** Contributors fork or create a feature branch, make changes, open a PR.
+- **PR template** prompts the contributor to describe motivation, alternatives considered, scope of impact, and any breaking changes.
+- **Required review** from at least one maintainer before merge.
+- **CI runs structural verification** — the same kind of folder-and-frontmatter checks used during the v0.1.0 build (folder/name match, `@import` paths resolve, frontmatter present, description under 1024 chars, etc.).
+- **Merging updates `CHANGELOG.md`** under `[Unreleased]`.
+- **Tagged releases** follow semver and include a release-notes summary.
+
+This section is forward-looking. None of the above exists today. When it does, this document will be revised to make the team-phase process the primary one and demote the pilot-phase process to a historical note.
+
+---
+
+## What Makes a Good Contribution
+
+Cleaner contributions get accepted faster. Qualities to aim for:
+
+- **Concrete.** Describes a real situation where the template fell short — with the actual prompt, the actual output, and the desired output. Not "I think the testing skill could be better."
+- **Specific.** The proposed change is actionable. "Improve the testing skill" is too vague to act on; "add a section to `skills/testing/SKILL.md` covering when to mock external APIs vs. use a real fixture, with a concrete example" is good.
+- **Layered correctly.** Universal rules belong in `rules/`. Topic-specific guidance belongs in a skill. Org-specific decisions belong in `domain/`. Mixing layers is the most common review feedback. See [`customization.md`](customization.md) for the layering model.
+- **Includes a "Why."** Every existing rule has a `> **Why:**` blockquote. Match the format. Future readers (including future-you) need to audit whether a rule still makes sense, and they can't do that without rationale.
+- **Avoids speculative additions.** Propose changes for problems that have actually happened, not problems you imagine might happen. "I'm worried Claude might one day…" is not a contribution; "Claude did X yesterday on this prompt and I had to correct it" is.
+- **Tested.** If the change is a new skill or rule, run a real prompt against it before proposing — confirm it triggers, confirm it produces the desired behavior, confirm it doesn't break existing skills.
+
+---
+
+## Versioning
+
+The template follows [Semantic Versioning](https://semver.org/) and tracks history in [`../CHANGELOG.md`](../CHANGELOG.md):
+
+| Bump | Triggered by | Examples |
+|---|---|---|
+| **Patch** (`0.1.x`) | Clarifications, typo fixes, small additions, non-behavioral edits | Fixing a broken link; rewording a confusing paragraph; adding an example to an existing rule |
+| **Minor** (`0.x.0`) | New rules, new skills, behavior shifts that don't break existing usage | Adding `skills/python/`; adding a new rule to `rules/general.md`; tightening the function-size limit |
+| **Major** (`x.0.0`) | Breaking changes — rule removals, structural changes that affect installation, behavioral reversals | Renaming `rules/` → `standards/`; removing a long-standing rule; changing the `@import` mechanism |
+
+During pilot, expect **frequent minor and patch bumps** as the template stabilizes. Once it hits v1.0, change pace slows and most updates will be patches.
+
+Each release updates `CHANGELOG.md` and bumps the version mentioned in `README.md` and `CLAUDE.md`. Both files currently reference v0.1.0 — when releasing, make sure they stay in sync.
+
+---
+
+## What NOT to Contribute
+
+Some changes don't belong in the shared template, even if they'd be useful for you:
+
+- **Personal preferences that don't generalize.** "I prefer British spelling" / "I want Claude to add a smiley to every commit message." → Use `CLAUDE.local.md` (per-developer, gitignored).
+- **Universal rules for things only one team or one project needs.** "Always use Tailwind v4 syntax" is not universal — it belongs in a project's local `CLAUDE.md` or in a `skills/tailwind/` skill, not in `rules/`.
+- **Vague aspirational guidance.** "Write better code." "Be more careful." Rules that aren't testable produce no behavior change. If you can't write a concrete prompt that would clearly fail without the rule and pass with it, the rule isn't real.
+- **Rules that contradict existing rules without addressing the conflict.** If your proposal collides with something already in `rules/`, you need to explicitly identify the collision and propose a resolution (delete, qualify, or replace the older rule). Quietly adding a contradicting rule makes Claude pick arbitrarily turn-to-turn.
+- **Restructuring the folder layout without strong rationale.** The structure stabilized after the v0.1.0 verification (`rules/`, `skills/<name>/SKILL.md`, `domain/`, `docs/`). Folder reshuffles invalidate everyone's installs and force a major version bump. Don't propose them lightly — and when you do, include a migration path.
+- **Speculative configuration knobs.** "What if we made the function-size limit configurable per project?" → No. The template is opinionated by design. If a setting needs to vary per project, that's what project-level `CLAUDE.md` is for.
+
+---
+
+## Reviewing Changes
+
+### Today (pilot phase)
+
+Raj reviews each change against this guide and against the structural checks in [`customization.md`](customization.md#testing-your-customizations). For changes Raj authors directly, the review is essentially self-review — keep that in mind and err on the side of asking a second pair of eyes for anything non-trivial.
+
+### Future (team phase)
+
+Once additional maintainers exist:
+
+- Every change requires at least one peer review before merge.
+- The reviewer's job is to check: layering (right folder?), testability (does the rule actually change behavior?), conflicts (does it contradict something existing?), and clarity (will future-readers understand the why?).
+- Before any merge, run the verification pattern used during the v0.1.0 build — folder structure, frontmatter validity, `@import` resolvability, name/folder matches, description length. This will eventually run in CI; until then, run it manually.
+
+The exact verification commands will be captured in `docs/verification.md` once that file exists. Until then, the prompt format used during template creation is the reference.
+
+---
+
+## Where to Get Help
+
+- **Adding a skill or rule locally before proposing it template-wide** → [`customization.md`](customization.md)
+- **One-off rule exception (you need to deviate from a rule for a specific task)** → `docs/exception-process.md` — not yet published in v0.1.0; for now, message Raj directly with the deviation and the reason
+- **Overall context on what the template is and why** → [`../README.md`](../README.md)
+- **Anything else** → reach out to Raj Shah directly. During pilot phase, that is the whole contribution channel.