@traxodev/claude-setup-kit 1.0.0

package/README.md

@@ -0,0 +1,80 @@
+# claude-setup-kit
+
+Install Claude Code setup guides and the `/setup-claude` command on any machine — so you can set up Claude properly in any repo with a single command.
+
+---
+
+## What it does
+
+Installs a collection of guide files that teach Claude how to set up a repo correctly — creating `CLAUDE.md`, agents, rules, skills, and commands that are tailored to the codebase.
+
+After installation, open Claude Code in any repo and run `/setup-claude`. Claude will:
+
+- Explore the repo and understand the tech stack
+- Ask clarifying questions before writing anything
+- Create rule files, skill files, and agent files in `.claude/`
+- Create `CLAUDE.md` last, once everything else exists
+- Handle both fresh setups and repos that already have a partial setup
+
+---
+
+## Installation
+
+**One-time run (recommended):**
+```bash
+npx claude-setup-kit
+```
+
+**Or install globally:**
+```bash
+npm install -g claude-setup-kit
+claude-setup-kit
+```
+
+Running it again on a machine that already has it installed will prompt you to update to the latest version.
+
+---
+
+## What gets installed
+
+| What | Where |
+|---|---|
+| Guide files | `~/.claude/setup/claude-setup/` |
+| `/setup-claude` command | `~/.claude/commands/setup-claude.md` |
+
+The guide files cover:
+- **Instructions** — golden rules, creation order, file structure, verification
+- **Workflow** — end-to-end ticket-to-PR flow (branch → implement → review → push)
+- **Rules** — how to create rule files for a repo
+- **Skills** — how to create skill files for a repo
+- **Agents** — how to create agent files, mandatory checklists, monorepo structure
+- **CLAUDE.md** — how to create the entry point file for any repo
+
+---
+
+## Usage
+
+Once installed, open Claude Code in any repo:
+
+```
+/setup-claude
+```
+
+Claude will detect whether the repo is fresh or already has a setup, and act accordingly.
+
+---
+
+## Monorepo support
+
+`/setup-claude` handles monorepos — it creates a root `CLAUDE.md` with shared global agents, and a separate `CLAUDE.md` with app-specific rules, skills, and agents for each app.
+
+---
+
+## Updating
+
+Re-run the install command to update your guide files to the latest version:
+
+```bash
+npx claude-setup-kit
+# → "claude-setup-kit is already installed. Update to the latest version? (y/n)"
+```

package/bin/install.js

@@ -0,0 +1,60 @@
+#!/usr/bin/env node
+
+const fs = require('fs');
+const path = require('path');
+const os = require('os');
+const readline = require('readline');
+
+const INSTALL_DIR = path.join(os.homedir(), '.claude', 'setup', 'claude-setup');
+const COMMANDS_DIR = path.join(os.homedir(), '.claude', 'commands');
+const TEMPLATES_DIR = path.join(__dirname, '..', 'templates');
+
+const GUIDE_FILES = [
+  'claude-setup-instructions.md',
+  'claude-setup-workflow.md',
+  'claude-setup-rules.md',
+  'claude-setup-skills.md',
+  'claude-setup-agents.md',
+  'claude-setup-claude-md.md',
+];
+
+function prompt(question) {
+  return new Promise((resolve) => {
+    const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+    rl.question(question, (answer) => { rl.close(); resolve(answer); });
+  });
+}
+
+async function main() {
+  const alreadyInstalled = fs.existsSync(INSTALL_DIR);
+
+  if (alreadyInstalled) {
+    const answer = await prompt('claude-setup-kit is already installed. Update to the latest version? (y/n): ');
+    if (answer.trim().toLowerCase() !== 'y') {
+      console.log('Skipped. No changes made.');
+      process.exit(0);
+    }
+  }
+
+  fs.mkdirSync(INSTALL_DIR, { recursive: true });
+  fs.mkdirSync(COMMANDS_DIR, { recursive: true });
+
+  for (const file of GUIDE_FILES) {
+    fs.copyFileSync(path.join(TEMPLATES_DIR, file), path.join(INSTALL_DIR, file));
+  }
+
+  // Generate setup-claude.md with the correct absolute paths for this machine
+  const template = fs.readFileSync(path.join(TEMPLATES_DIR, 'setup-claude.md'), 'utf8');
+  const installPath = INSTALL_DIR.split(path.sep).join('/'); // normalize to forward slashes
+  const generated = template.replace(/\{\{INSTALL_PATH\}\}/g, installPath);
+  fs.writeFileSync(path.join(COMMANDS_DIR, 'setup-claude.md'), generated);
+
+  console.log(`\n✓ Guide files installed to: ${INSTALL_DIR}`);
+  console.log(`✓ Command installed to: ${path.join(COMMANDS_DIR, 'setup-claude.md')}`);
+  console.log('\nDone! Open Claude Code in any repo and run /setup-claude to get started.');
+}
+
+main().catch((err) => {
+  console.error('Error:', err.message);
+  process.exit(1);
+});

package/package.json

@@ -0,0 +1,25 @@
+{
+  "name": "@traxodev/claude-setup-kit",
+  "version": "1.0.0",
+  "description": "Install Claude Code setup guides and the /setup-claude command for any repo",
+  "bin": {
+    "claude-setup-kit": "./bin/install.js"
+  },
+  "files": [
+    "bin/",
+    "templates/"
+  ],
+  "keywords": [
+    "claude",
+    "claude-code",
+    "anthropic",
+    "ai",
+    "setup",
+    "agents",
+    "developer-tools"
+  ],
+  "engines": {
+    "node": ">=16"
+  },
+  "license": "MIT"
+}

package/templates/claude-setup-agents.md

@@ -0,0 +1,129 @@
+---
+name: Claude Setup — Agent Files
+description: How to create agent files in .claude/agents/ when setting up Claude for a repo
+---
+
+# Creating Agent Files
+
+Agents = **specialised roles** that own a category of task end-to-end.
+
+---
+
+## Global Agents — Always Create at Root
+
+These exist once at the repo root and are shared across all apps:
+
+- `developer` — general-purpose catch-all (last resort — invoke specialist agents first)
+- `code-reviewer` — **always auto-invoked after every implementation, without user prompt** — non-negotiable, must exist in every repo
+- `git` — handles all branch creation, pushing, and PR creation
+
+**In a monorepo:** global agents live at root `.claude/agents/`. Specialist agents belong inside the app they serve (`apps/web/.claude/agents/`, `apps/api/.claude/agents/`, etc.).
+
+## Specialist Agents — Create Per App
+
+Add these based on what the app actually does:
+
+| Ticket / task type | Agent name |
+|---|---|
+| Frontend / UI / components | `frontend-developer` |
+| API / backend / services | `api-builder` |
+| Database / migrations / queries | `database-developer` |
+| Tests only | `test-writer` |
+| Bug investigation and fix | `debugger` |
+
+If the needed agent type is not in this table, create one on the fly, save it to `.claude/agents/`, and notify the user: **"I created a `[name]` agent to handle this — saved to `.claude/agents/[name].md`"**
+
+## Agent Filename Rule
+
+The agent's filename **must exactly match** its invocation name:
+
+```
+✓  agent name: debugger       → .claude/agents/debugger.md
+✗  agent name: debugger       → .claude/agents/debug-agent.md
+```
+
+CLAUDE.md's orchestration table, the workflow file, and the agent filename must all use the same name — a mismatch means the agent will never be invoked correctly.
+
+---
+
+## What Each Agent File Must Include
+
+1. **One-line role description**
+2. **"Before starting" reading list** — directories to read, not specific files
+3. **Phased workflow** — ordered steps the agent follows
+4. **Code quality checklist** — what it checks before handing off
+5. **When to ask vs decide** — what requires user input vs autonomous action
+6. **Output format** — how the agent communicates results
+
+---
+
+## Reference Style
+
+Reference directories, never specific files — file paths go stale:
+
+```
+✓  Read `.claude/rules/` for coding standards and `.claude/skills/` for recipes.
+✗  Read `.claude/rules/typescript.md` and `.claude/rules/components.md`.
+```
+
+---
+
+## File Skeleton
+
+Every agent file must start with frontmatter:
+
+```markdown
+---
+name: [agent name]
+description: [one-line role description]
+---
+
+## Role
+
+[What this agent owns end-to-end]
+
+## Before Starting
+
+Read `.claude/rules/` for coding standards and `.claude/skills/` for recipes.
+
+## Workflow
+
+1. [phase one]
+2. [phase two]
+...
+
+## Quality Checklist
+
+- [ ] [check one]
+- [ ] [check two]
+
+## When to Ask
+
+Always ask — never assume:
+- **Which branch to create this from?** — before any branch is created
+- **Which branch should I target for this PR?** — before any PR is created
+
+Ask for anything else that would cause irreversible or hard-to-reverse actions if guessed wrong.
+```
+
+---
+
+## `code-reviewer` Mandatory Checklist
+
+Every `code-reviewer` agent created must include these checks — they are non-negotiable regardless of the repo:
+
+- No duplicate code introduced
+- Proper component / module structure (files in the right place, correctly named)
+- Code quality and conventions match `.claude/rules/`
+- No leftover debug code, dead code, or temporary hacks
+- No breaking changes to public APIs, exported functions, or shared interfaces — if found, **flag explicitly to the user before continuing**
+
+If the review fails → return to the implementing agent with specific, actionable feedback. If it fails 3 times in a row → stop and escalate to the user.
+
+---
+
+## Scope
+
+- Workflows should be scannable — not every scenario, just what to do and when
+- Keep agents focused — a specialist agent is better than one mega-agent
+- Multiple coding agents must always exist — never rely on a single agent for all implementation work

package/templates/claude-setup-claude-md.md

@@ -0,0 +1,99 @@
+---
+name: Claude Setup — CLAUDE.md
+description: How to create CLAUDE.md at the repo root when setting up Claude for a repo
+---
+
+# Creating CLAUDE.md
+
+`CLAUDE.md` is the entry point for every agent. Keep it under 200 lines — it is a map, not a manual.
+
+Create this **last** — after all rules, skills, and agents exist — so the references table is accurate.
+
+---
+
+## Required Sections (in this order)
+
+1. **Agent orchestration table** — user intent phrases mapped to agent names (put this first)
+2. **Project References table** — every rule and skill file listed by path
+3. **Project overview** — what this repo does and who uses it
+4. **Tech stack table** — language, framework, key libraries, package manager
+5. **Commands** — install, dev, build, test, lint — must be **exact runnable commands**, not descriptions (agents execute these directly without asking)
+6. **Project structure** — annotated directory tree of the main source
+7. **Architecture overview** — how pieces connect; key shared abstractions
+8. **Non-negotiable rules summary** — 6–10 bullets linking to `.claude/rules/` for detail
+
+---
+
+## Agent Orchestration Table
+
+Maps natural language intent to agent names so Claude routes correctly:
+
+```markdown
+| When the user says... | Invoke |
+|---|---|
+| shares a Jira ticket / "work on [TICKET-ID]" | full workflow (intake → branch → implement → review → push) |
+| "add a feature", "implement", "build" | `developer` or specialist |
+| "fix a bug", "investigate", "debug" | `debugger` |
+| "review", "check the code" | `code-reviewer` |
+| "push", "create a PR", "branch" | `git` |
+| "write tests", "add coverage" | `test-writer` |
+| anything else | `developer` |
+```
+
+The catch-all row (`anything else → developer`) is **mandatory** and must always be the last row — it ensures every request has a handler even if it doesn't match a specific pattern.
+
+---
+
+## Project References Table
+
+Lists every rule, skill, and agent file so agents know what exists:
+
+```markdown
+| Type | File |
+|---|---|
+| Rule | `.claude/rules/git.md` |
+| Rule | `.claude/rules/typescript.md` |
+| Skill | `.claude/skills/add-endpoint.md` |
+| Agent | `.claude/agents/debugger.md` |
+| Agent | `.claude/agents/frontend-developer.md` |
+```
+
+---
+
+## If CLAUDE.md Exceeds 200 Lines
+
+Move overflow content to a rule or skill file and replace it with a one-line link. Common offenders:
+
+| Section that grows | Move it to |
+|---|---|
+| Architecture detail | `.claude/rules/architecture.md` |
+| Complex commands / scripts | `.claude/rules/commands.md` |
+| Onboarding notes | `.claude/rules/onboarding.md` |
+
+Never truncate — always move and link.
+
+---
+
+## Monorepo — Per-app CLAUDE.md
+
+Each app's `CLAUDE.md` is a complete, self-contained entry point for that app. Its agent orchestration table should only list the app's own specialist agents — **do not re-list `git` and `code-reviewer`**, they are global agents that live at the root and are inherited automatically.
+
+```markdown
+| When the user says... | Invoke |
+|---|---|
+| shares a Jira ticket / "work on [TICKET-ID]" | full workflow |
+| "add a feature", "implement", "build" | `frontend-developer` |
+| "fix a bug", "debug" | `debugger` |
+| "write tests" | `test-writer` |
+| anything else | `developer` |
+```
+
+The root `CLAUDE.md` orchestration table covers `git`, `code-reviewer`, and any cross-app workflows.
+
+---
+
+## Scope
+
+- Summary only — detail belongs in rule or skill files, not here
+- If a section grows past ~20 lines, move the detail to a rule or skill file and link it
+- Agents read `CLAUDE.md` first — keep it fast to scan

package/templates/claude-setup-instructions.md

@@ -0,0 +1,142 @@
+---
+name: Claude Setup Instructions
+description: Entry point for setting up CLAUDE.md, agents, rules, and skills in any repo — golden rules, creation order, and verification
+---
+
+# Claude Setup Instructions
+
+Reference this file whenever asked to create `CLAUDE.md`, agents, rules, or skills in any repo.
+
+> **Also read:** [`claude-setup-workflow.md`](claude-setup-workflow.md) — required companion file covering the end-to-end ticket-to-PR workflow. Read both before proceeding.
+
+---
+
+## Golden Rules (always enforced)
+
+- **Every `.md` file — including this one — must stay under 200 lines.** Split into focused files if exceeded.
+- `CLAUDE.md` → repo root. Agents / rules / skills → inside `.claude/` only. Never in root.
+- Rules and skills must reflect **actual patterns in this codebase**, not generic best practices.
+- Agent files reference **directories** (`.claude/rules/`), never specific file paths — they go stale.
+- No stale references — if a file is renamed or split, update every file that pointed to it.
+- `CLAUDE.md` Project References table must list every rule and skill file by name.
+
+---
+
+## File Structure
+
+| File | Location |
+|---|---|
+| `CLAUDE.md` | Repo root |
+| Agents | `.claude/agents/*.md` |
+| Rules | `.claude/rules/*.md` |
+| Skills | `.claude/skills/*.md` |
+| Commands | `.claude/commands/*.md` |
+
+---
+
+## Creation Order
+
+Follow this order — each step depends on the previous:
+
+1. Understand the codebase (see Step 1 below)
+2. Ask clarifying questions (see Step 2 below)
+3. Create rule files → see [`claude-setup-rules.md`](claude-setup-rules.md)
+4. Create skill files → see [`claude-setup-skills.md`](claude-setup-skills.md)
+5. Create agent files → see [`claude-setup-agents.md`](claude-setup-agents.md)
+6. Create command files → `.claude/commands/` (see Step 6 below)
+7. Create `CLAUDE.md` last → see [`claude-setup-claude-md.md`](claude-setup-claude-md.md)
+8. Verify (see Step 8 below)
+
+---
+
+## Step 1 — Understand the Codebase
+
+Read the repo before writing anything. Identify:
+
+- **Language, runtime, framework** and primary libraries (state, HTTP, testing, UI, database)
+- **Project structure** — monorepo? multiple apps? where is the main work target?
+- **Existing patterns** — shared abstractions, naming conventions, import resolution
+- **Build & dev commands** — install, dev, build, test, lint
+
+Read: manifest files, config files, and representative source files across different layers.
+
+**If it's a monorepo:** create one `CLAUDE.md` at the repo root (shared conventions, global agents, repo map) and one `CLAUDE.md` per app (app-specific stack, commands, rules, skills, and agents). Claude Code reads `CLAUDE.md` files and `.claude/` folders up the directory tree — place each file at the level where its context applies:
+
+| What | Root | Per-app |
+|---|---|---|
+| `CLAUDE.md` | Repo overview, shared rules, links to apps | App-specific stack, commands, rules, skills, and agents |
+| `.claude/agents/` | Global agents: `git`, `code-reviewer` | Specialist agents: `frontend-developer`, `api-builder`, `debugger`, etc. |
+| `.claude/rules/` | Shared conventions (git, commit style) | App-specific coding standards |
+| `.claude/skills/` | — | App-specific recipes |
+| `.claude/commands/` | Shared commands (e.g. `/setup-claude`) | App-specific commands (e.g. `/run-checks`, `/add-metric`) |
+
+---
+
+## Step 2 — Ask Clarifying Questions
+
+Ask before writing if any of the following are unclear:
+
+- Is this a monorepo with multiple apps, or a single-app repo?
+- What is this repo's primary purpose and who uses it?
+- What are the most common day-to-day developer tasks?
+- Are there workflows complex enough to warrant a specialist agent?
+- Any team conventions or rules not visible from reading the code?
+
+Do not guess — a wrong assumption produces misleading documentation.
+
+---
+
+## Step 6 — Custom Slash Commands (`.claude/commands/`)
+
+Slash commands are shortcuts for workflows you trigger repeatedly in Claude Code (`/command-name`). Each `.md` file in `.claude/commands/` becomes one command.
+
+**Create a command when:** a workflow is triggered often and has a fixed sequence of steps (e.g. `/review-pr`, `/add-metric`, `/run-checks`). Each command file must have a clear one-line purpose, the exact steps to follow, and be named in `kebab-case`.
+
+**Do not create commands for:** one-off tasks or anything a naturally invoked agent already handles.
+
+---
+
+## Step 8 — Verify
+
+```bash
+# No file exceeds 200 lines
+wc -l CLAUDE.md .claude/**/*.md
+
+# No stale file references
+grep -r "rules\.md\|skills\.md\|agents\.md" CLAUDE.md .claude/
+
+# Every file listed in CLAUDE.md Project References actually exists
+# (manually cross-check the table in CLAUDE.md against ls .claude/rules/ and ls .claude/skills/)
+```
+
+Fix anything found before finishing.
+
+---
+
+## Updating an Existing Setup
+
+Whether adding to a partially set up repo or making ongoing updates to a complete one:
+
+1. Read every affected file in full before touching anything
+2. Identify gaps — missing agents, outdated rules, incomplete CLAUDE.md sections
+3. Do not overwrite files wholesale — edit to fill gaps and preserve what is correct
+4. New rule/skill/agent added → update `CLAUDE.md` Project References table
+5. File renamed or split → grep for all references and update them
+6. Always re-run the verify step after any change
+7. If a rule file no longer applies, delete it and remove it from the CLAUDE.md Project References table
+
+**Triggers for updating:** new major dependency adopted, team agrees on a new pattern, an agent consistently produces wrong output (signals a rule gap), a skill references files that have moved, or a significant refactor changes how a layer is structured.
+
+## When to Split a File
+
+Split at 200 lines by meaning — by phase (scaffold vs wiring), by concern (frontend vs backend), or by frequency (common vs rare tasks). Name splits clearly: `add-metric-scaffold.md` + `add-metric-wiring.md`, not `add-metric-part1.md`.
+
+## What NOT to Put in These Files
+
+| Don't put this here | It belongs here instead |
+|---|---|
+| Step-by-step recipes | Skills file |
+| Coding standards | Rules file |
+| Project history / decisions | Git commit messages / ADRs |
+| Edge cases and exceptions | Inline code comments |
+| Invented patterns not in the codebase | Nowhere — don't invent |

package/templates/claude-setup-rules.md

@@ -0,0 +1,69 @@
+---
+name: Claude Setup — Rule Files
+description: How to create rule files in .claude/rules/ when setting up Claude for a repo
+---
+
+# Creating Rule Files
+
+Rules = **how code must be written** in this repo. One file per concern.
+
+Derive topics from what you observed in the codebase — do not copy a template. Common concerns:
+
+- Language conventions (types, error handling, async patterns)
+- File structure, naming conventions, import style
+- How modules / components / services are structured
+- Testing conventions and any critical gotchas
+- Git & branching (always include — see below)
+
+Every rule file must cover: where files live, how they are named, what is forbidden, and any non-obvious patterns that would trip up a new developer.
+
+---
+
+## Always Create `git.md`
+
+Always create a `git.md` rule file containing:
+
+- Branch naming pattern — ask the user for the project's ticket format (e.g. `COB-XXXX` or `PROJ-XXXX-description`)
+- Always ask which branch to create the new branch from before starting any work
+- After the user names the base branch, fetch the latest remote state and check if that branch is behind — if it is, warn the user and ask if they want to pull before branching
+- Commit messages must be clear and descriptive — reference the ticket where relevant
+- Never commit `.env` files, credentials, API keys, tokens, or secrets
+- If a sensitive file is staged accidentally, remove it and add to `.gitignore` before committing
+
+---
+
+## File Skeleton
+
+Every rule file must start with frontmatter:
+
+```markdown
+---
+name: [concern name]
+description: [one-line description of what this rule covers]
+---
+
+[Rule stated plainly]
+
+✓ Correct:
+[code example]
+
+✗ Wrong:
+[code example]
+```
+
+Not every rule needs a code example. Location and naming rules can be stated plainly:
+
+```markdown
+- Service files live in `src/services/` — one file per domain entity
+- Filenames use kebab-case: `user-profile.service.ts`, not `UserProfile.service.ts`
+```
+
+Only add code examples when the rule covers logic, patterns, or syntax — not when it's a file/folder convention.
+
+---
+
+## Scope
+
+- Non-obvious and project-specific only — skip what any developer already knows
+- If a rule applies everywhere in any codebase, it doesn't belong here
+- Derive from observed patterns — never invent rules that aren't in the code

package/templates/claude-setup-skills.md

@@ -0,0 +1,66 @@
+---
+name: Claude Setup — Skill Files
+description: How to create skill files in .claude/skills/ when setting up Claude for a repo
+---
+
+# Creating Skill Files
+
+Skills = **step-by-step recipes** for the most common repeatable tasks.
+
+Derive tasks from the repo's domain — think "add a new X", "create a Y", "wire up a Z". Examples: `add-endpoint`, `add-migration`, `add-page`, `add-metric`, `add-handler`.
+
+## What Deserves a Skill
+
+Create a skill when a task meets all three:
+1. **Repeatable** — done regularly, not once
+2. **Multi-step** — more than 2–3 non-obvious steps
+3. **Pattern-dependent** — getting it wrong without the recipe would produce inconsistent code
+
+If a task is trivial, one-off, or fully handled by an agent's built-in workflow — skip it.
+
+---
+
+## What Each Skill File Must Include
+
+1. **Reference file to read first** — the rule or source file that governs this area
+2. **Steps in dependency order** — what to do and in what sequence
+3. **Code snippets** — using this repo's actual patterns, not generic examples
+4. **Verify checklist** — how to confirm the task was done correctly
+
+Split into `[name]-scaffold.md` / `[name]-wiring.md` if over 200 lines.
+
+---
+
+## File Skeleton
+
+Every skill file must start with frontmatter:
+
+```markdown
+---
+name: [skill name]
+description: [one-line description of what this skill does]
+---
+
+## Before Starting
+
+Read: [path to relevant rule or source file]
+
+## Steps
+
+1. [first step]
+2. [second step]
+...
+
+## Verify
+
+- [ ] [check one]
+- [ ] [check two]
+```
+
+---
+
+## Scope
+
+- The 80% happy path only — edge cases belong in code comments, not skill files
+- Derive tasks from what developers actually do in this repo
+- Do not create skills for one-off tasks or anything already handled by an agent workflow

package/templates/claude-setup-workflow.md

@@ -0,0 +1,153 @@
+---
+name: Claude Development Workflow
+description: End-to-end workflow from Jira ticket to merged PR — intake, branching, implementation, review, and push
+---
+
+# Claude Development Workflow
+
+This is the standard workflow every time a user shares a Jira ticket. Follow all phases in order.
+
+---
+
+## Phase 1 — Ticket Intake
+
+1. User shares a Jira ticket (file, link, or pasted content)
+2. Read and fully understand the ticket — acceptance criteria, scope, affected areas
+3. If anything is unclear, ask the user targeted questions before proceeding
+4. Do not start work until requirements are understood and confirmed
+5. If the ticket scope is large (multiple unrelated concerns, touches many layers), flag it to the user and suggest splitting into smaller PRs — wait for their decision before proceeding
+
+---
+
+## Phase 2 — Branch Creation
+
+1. Check for uncommitted or staged work in the repo — if any exists, warn the user before doing anything: **"There is uncommitted work in the repo. Please stash or commit it before I create a new branch."** Do not proceed until the working tree is clean.
+2. Invoke the `git` agent to handle branching
+3. Before creating, ask the user: **"Which branch should I create this from?"**
+4. Once the user names the base branch, fetch the latest remote state and check if that branch is behind its remote tracking branch — if it is, warn the user: **"[branch] is behind its remote by N commit(s). Should I pull the latest before branching?"** Do not proceed until the user confirms or declines.
+5. Name the branch following the pattern in `.claude/rules/git.md` (ticket ID + short description)
+
+---
+
+## Phase 3 — Implementation
+
+1. Determine the ticket type and select the appropriate specialist agent automatically (see Agent Selection table below)
+2. If no suitable agent exists → create it on the fly and inform the user:
+   > "I created a `[name]` agent to handle this — saved to `.claude/agents/[name].md`"
+3. Hand off to the agent. Claude selects agents autonomously — the user will never need to specify which agent to use
+4. Multiple coding agents must always exist and be used — never rely on a single agent for all implementation work
+
+---
+
+## Phase 4 — Code Review
+
+1. On implementation completion, invoke the `code-reviewer` agent automatically — no user prompt needed
+2. Review must check:
+   - No duplicate code
+   - Proper component/module structure
+   - Code quality and conventions match `.claude/rules/`
+   - No leftover debug code, dead code, or temporary hacks
+   - No breaking changes to public APIs, exported functions, or shared interfaces — if found, flag explicitly to the user before continuing
+3. If review **fails** → return to the implementing agent with specific, actionable feedback and repeat from Phase 3
+4. If the review fails **3 times in a row**, stop looping and escalate to the user: **"The code has failed review 3 times. Here are the outstanding issues: [list]. Please advise how you'd like to proceed."**
+5. Loop until the review passes or the user intervenes
+
+---
+
+## Phase 5 — Build, Test & Lint Verification
+
+1. Verify that lint, test, and build commands are all defined in `CLAUDE.md` — if any are missing, ask the user to provide them before continuing
+2. If the implementation added new environment variables, ensure they are added to `.env.example` (or equivalent) before running any verification commands
+3. Run the lint/format command defined in `CLAUDE.md` — fix all errors before continuing
+4. Run the test command defined in `CLAUDE.md` — if tests fail, return to the implementing agent with the failure output and loop until all tests pass
+5. Run the build command defined in `CLAUDE.md` — fix any build failures before proceeding
+6. Do not push until lint, tests, and build all pass
+
+---
+
+## Phase 6 — Push & PR
+
+1. Invoke the `git` agent to push the branch to GitHub
+2. If the push is rejected because the remote has diverged, rebase the branch on top of the latest remote and resolve any merge conflicts — if a conflict cannot be resolved automatically, stop and ask the user to resolve it manually before continuing
+3. Before creating the PR, always ask the user: **"Which branch should I target for this PR?"**
+4. Create the PR only after the user confirms the target branch
+5. PR description must follow this structure:
+   - **Title:** `[TICKET-ID] Short description of the change`
+   - **What:** What was changed and why
+   - **How:** Brief summary of the approach taken
+   - **Testing:** What was tested and how (unit, integration, manual)
+   - **New env vars:** list any new environment variables added and their purpose (must also be added to `.env.example` or equivalent before pushing)
+   - **Breaking changes:** explicitly call out any removed or changed public APIs, exports, or shared interfaces
+   - **Checklist:** lint passes, tests pass, build passes, no console logs, no hardcoded values
+
+---
+
+## Phase 7 — PR Review Feedback (Human Reviewers)
+
+If a teammate leaves review comments on the PR:
+
+1. Read all comments in full before making any changes
+2. Group comments by type:
+   - **Must fix** — blocking issues, bugs, broken logic
+   - **Should fix** — quality/convention issues the reviewer flagged
+   - **Discuss** — opinions or suggestions that need a decision
+3. For **Discuss** items, summarise them to the user and ask for a decision before touching code
+4. For **Must fix** and **Should fix** items, invoke the appropriate agent to implement the changes
+5. After changes are made, run the full Phase 5 verification (lint → test → build) again
+6. Invoke `code-reviewer` agent again before pushing the update
+7. Push the updated branch — the existing PR updates automatically, no new PR needed
+8. If the same reviewer comments are not addressed after 2 iterations, escalate to the user: **"I've made 2 attempts to address [reviewer]'s comments but they remain unresolved. Please review and advise."**
+9. Once the PR is approved, notify the user: **"The PR has been approved. Please merge when ready."** — do not merge autonomously unless the user explicitly asks
+
+---
+
+## Phase 8 — Hotfix Workflow
+
+Use this flow only for urgent production bugs — not for regular tickets.
+
+1. Confirm with the user: **"Is this a hotfix for production?"** — do not assume
+2. Skip the normal ticket intake questions — move fast
+3. Check for uncommitted work (same as Phase 2, step 1)
+4. Invoke the `git` agent to branch directly from `main` or `production` (ask user which) — name the branch `hotfix/[short-description]` unless the user specifies a different convention
+5. Invoke the `debugger` agent to investigate and fix the issue
+6. Run Phase 5 verification (lint → test → build) — all must pass
+7. Invoke `code-reviewer` — one pass only, no loop limit for hotfixes
+8. Push and create PR — ask user for target branch (typically `main` or `production`)
+9. After the hotfix PR is merged, ask the user: **"Should I backport this fix to the development branch as well?"** — if yes, cherry-pick the commit onto the dev branch and open a second PR
+
+---
+
+## Agent Selection Table
+
+Claude must self-select the correct agent. The user will never specify.
+
+| Ticket / task type | Agent to invoke |
+|---|---|
+| Frontend / UI / components | `frontend-developer` or equivalent |
+| API / backend / services | `api-builder` or equivalent |
+| Database / migrations / queries | `database-developer` or equivalent |
+| Tests only | `test-writer` or equivalent |
+| Bug investigation and fix | `debugger` or equivalent |
+| After any implementation | `code-reviewer` (always) |
+| Branch, push, PR | `git` agent (always) |
+
+If the required agent does not exist in `.claude/agents/`, create it and notify the user.
+
+---
+
+## Multiple Coding Agents — Mandatory
+
+Always create more than one coding agent when setting up a repo. At minimum:
+
+- `developer` — general-purpose fallback
+- One specialist per major concern in the codebase (e.g. `frontend-developer`, `api-builder`, `test-writer`, `debugger`)
+
+The `developer` agent is the last resort — invoke specialist agents first when the task clearly fits one.
+
+---
+
+## Self-Sufficiency Rules
+
+- Claude selects agents based on ticket type — never ask the user which agent to use
+- If a needed agent is missing, create it silently and notify the user after
+- The full loop (intake → branch → implement → review → build → PR) runs without user intervention except for the two mandatory confirmations: **base branch** and **PR target branch**

package/templates/setup-claude.md

@@ -0,0 +1,45 @@
+Read all of the following files in full before doing anything else — together they are your complete guide:
+
+- {{INSTALL_PATH}}/claude-setup-instructions.md
+- {{INSTALL_PATH}}/claude-setup-workflow.md
+- {{INSTALL_PATH}}/claude-setup-rules.md
+- {{INSTALL_PATH}}/claude-setup-skills.md
+- {{INSTALL_PATH}}/claude-setup-agents.md
+- {{INSTALL_PATH}}/claude-setup-claude-md.md
+
+Do not skip steps. Do not write any file before finishing the clarifying questions step.
+
+**Before anything else — detect the current state:**
+Check whether `.claude/` and `CLAUDE.md` already exist in the repo.
+
+- If they **do not exist** → follow the **Fresh Setup** flow below
+- If they **already exist** → follow the **Update Existing Setup** flow below
+
+---
+
+**Fresh Setup — single-app repo:**
+1. Explore the repo — tech stack, folder structure, key abstractions, build/test/lint commands
+2. Ask the user any clarifying questions before writing any files
+3. Create rule files → `.claude/rules/`
+4. Create skill files → `.claude/skills/`
+5. Create agent files → `.claude/agents/` — always more than one coding agent
+6. Create command files → `.claude/commands/` if needed
+7. Create `CLAUDE.md` in the repo root last
+8. Run the verify step
+
+**Fresh Setup — monorepo:**
+1. Explore the repo — understand all apps, shared code, and root structure
+2. Ask the user any clarifying questions (including which apps need setup)
+3. At root: create shared rules, global agents (`git`, `code-reviewer`), and root `CLAUDE.md`
+4. For each app: create app-specific rules, skills, specialist agents, and per-app `CLAUDE.md`
+5. Create commands at root or per-app level as appropriate
+6. Run the verify step for root and each app
+
+**Update Existing Setup:**
+1. Read every existing file in `.claude/` and `CLAUDE.md` in full before touching anything
+2. Explore the repo to understand what has changed since the setup was created
+3. Ask the user any clarifying questions before making changes
+4. Identify gaps — missing agents, outdated rules, incomplete CLAUDE.md sections
+5. Do not overwrite files wholesale — edit to fill gaps and preserve what is correct
+6. Update `CLAUDE.md` Project References table to reflect actual state of `.claude/`
+7. Run the verify step