@codemieai/code 0.0.45 → 0.0.46

package/dist/agents/plugins/claude/plugin/skills/claude-setup-audit/SKILL.md

@@ -0,0 +1,206 @@
+---
+name: claude-setup-audit
+description: This skill should be used when the user asks to "audit my claude setup", "check my claude configuration", "assess my claude code setup", "audit claude", "review my .claude folder", "is my claude setup correct", "check repo health", "assess my skills quality", "review my agents", "check my CLAUDE.md", "validate my hooks", "audit claude configuration", "check my MCP config", "how good is my claude setup", "scan my .claude folder", or wants a comprehensive quality assessment of all Claude Code components in a repository. Evaluates skills, subagents, CLAUDE.md rules, commands, hooks, and MCP configuration against established best practices. Produces a graded health report (A–F per component) with good/bad example references and prioritized recommendations.
+allowed-tools: [Read, Grep, Glob, Bash, Write]
+version: 1.0.0
+tags: [quality, audit, claude-setup, assessment, production-readiness]
+---
+
+# Claude Setup Audit
+
+Comprehensive quality assessment of Claude Code configuration and components in a repository. Evaluates skills, agents, CLAUDE.md rules, commands, hooks, and MCP configuration against established best practices. Produces a graded health report with concrete good/bad example references and actionable fixes.
+
+## Assessment Scope
+
+| Component | Primary Locations | Max Score |
+|-----------|------------------|-----------|
+| **Skills** | `.claude/skills/*/SKILL.md`, `plugins/*/skills/*/SKILL.md` | 32 pts each |
+| **Agents** | `.claude/agents/*.md`, `plugins/*/agents/*.md` | 32 pts each |
+| **CLAUDE.md** | `CLAUDE.md`, `.claude/CLAUDE.md`, `**/CLAUDE.md` (subdirs), `CLAUDE.local.md` | 36 pts each |
+| **Commands** | `.claude/commands/**/*.md`, `plugins/*/commands/**/*.md` | 20 pts each |
+| **Hooks** | `.claude/settings.json` (hooks array) | 20 pts total |
+| **MCP Config** | `.mcp.json`, `.claude/mcp.json` | 20 pts |
+
+## 5-Phase Workflow
+
+### Phase 1: Discovery
+
+Run `scripts/scan-repo.sh` or manually scan:
+
+```bash
+find . \( \
+  -path '*/.claude/agents/*.md' -o \
+  -path '*/skills/*/SKILL.md' -o \
+  -path '*/.claude/commands/**/*.md' -o \
+  -name 'CLAUDE.md' -o \
+  -name 'CLAUDE.local.md' -o \
+  -name '.mcp.json' -o \
+  -path '*/.claude/settings.json' \
+\) -not -path '*/node_modules/*' 2>/dev/null
+```
+
+**CLAUDE.md knowledge organisation scan** (run separately):
+```bash
+# Find all CLAUDE.md files
+find . -name 'CLAUDE.md' -o -name 'CLAUDE.local.md' \
+  | grep -v node_modules | sort
+
+# Find dedicated guide directories
+find . -type d \( -name 'guides' -o -name 'references' -o -name '.codemie' \) \
+  | grep -v node_modules | sort
+```
+
+**Detect which pattern is in use** — both are valid, mutually exclusive:
+
+| Pattern | Signals | Scoring note |
+|---------|---------|-------------|
+| **A — Single CLAUDE.md + Guide Files** | 1 CLAUDE.md at root + guide files in `guides/`, `.codemie/guides/`, `references/`, `docs/` | R5.3 full credit if CLAUDE.md references guide paths |
+| **B — Hierarchical CLAUDE.md** | Multiple CLAUDE.md files at different directory depths | R5.3 N/A (hierarchy IS the delegation); run hierarchy checks |
+
+Print discovery summary:
+```
+Found: X skills, Y agents, Z commands
+CLAUDE.md pattern: A (single + guides) | B (hierarchical) | unknown
+CLAUDE.md locations: [list each path found]
+Guide dirs: [list if present]
+Hooks: ✓/✗ | MCP: ✓/✗
+```
+
+### Phase 2: Per-Component Scoring
+
+Apply checklists from `references/component-checklists.md`. Mark each criterion:
+- ✅ **Pass** — full points
+- ⚠️ **Partial** — half points (present but incomplete or weak)
+- ❌ **Fail** — 0 points
+
+**Skills — classify type first, then score**:
+
+> **Before scoring any skill, detect its type:**
+> ```bash
+> grep -i "codemie.*assistant\|codemie.*chat\|assistants chat" SKILL.md
+> ```
+> - **Match found** → **Codemie-delegating skill** (API wrapper): applies reduced rubric (21 pts max)
+> - **No match** → **Standard skill**: full 32-pt rubric applies
+
+**Standard Skills (32 pts max)**:
+- Structure (3×): Valid SKILL.md filename, `[a-z0-9-]+` name, description >20 chars, `allowed-tools` field
+- Content (2×): Methodology/workflow section, output format, examples, checklists (`- [ ]`)
+- Technical (1×): No absolute paths, no hardcoded UUIDs/secrets, dependencies documented
+- Design (2×): Single responsibility, "When to use" triggers, no >50% overlap, <8K tokens
+
+**Codemie-delegating Skills (21 pts max — exemptions apply)**:
+- Structure (3×): Valid SKILL.md, valid name, description >20 chars — `allowed-tools` is **N/A** (no local tool execution)
+- Content: **All content criteria N/A** — output format, workflow, examples, checklists are determined by the backend assistant
+- Technical (1×): No absolute paths, no secrets, deps documented
+- Design (2×): Single responsibility, "When to use" triggers, no overlap, token budget
+- Score = (pts obtained / 21) × 100 — **do not penalise for exempted criteria**
+
+**Agents (32 pts max)**:
+- Identity (3×): Descriptive name, description has "when"/"use"/"trigger" keywords, model specified, tools justified
+- Prompt Quality (2×): "You are…" role statement, output format section, scope/limits, anti-hallucination keywords
+- Validation (1×): 3+ examples, edge cases, error handling described
+- Design (2×): Single responsibility, composable (references skills), <8K tokens
+
+**CLAUDE.md Rules (36 pts max)**:
+- Coverage (3×): Coding standards, workflow policies, explicit critical rules with triggers
+- Clarity (3×): Actionable instructions, trigger conditions stated, prohibitions explicit
+- Structure (2×): Section organization, quick-reference tables, correct/incorrect pattern examples
+- Maintenance (1×): No contradictions, technology versions noted, project context stated
+- Efficiency (2×): Concise body (≤400 non-code words), no anti-pattern noise, delegates detail via `@import`
+
+**CLAUDE.md hierarchy** — score each file separately, then run hierarchy analysis (Phase 3).
+
+**Commands (20 pts max)**:
+- Structure (3×): Frontmatter (name + description), `argument-hint` if uses `$ARGUMENTS`, numbered phases, usage examples
+- Quality (2×): Error/failure handling, output format defined, validation gates, argument parsing shown
+
+**Hooks (20 pts max)**:
+- Validity (3×): Valid JSON, recognized event types, valid matchers
+- Security (2×): No hardcoded credentials, bash scripts use `set -e`/`trap`
+- Quality (2×): Hook purpose documented, tool restriction scope appropriate
+
+**MCP Config (20 pts max)**:
+- Structure (3×): Valid JSON, `mcpServers` key, each server has `command`/`url` + type
+- Security (2×): No hardcoded tokens/passwords, env vars used for credentials
+- Documentation (2×): Descriptive server names, required env vars listed
+
+### Phase 3: Cross-Component Analysis
+
+After individual scoring, check repository-wide health:
+
+1. **Coverage gaps** — CLAUDE.md present if agents exist? Skills referenced by agents available?
+2. **Naming consistency** — All files use `lowercase-kebab-case`?
+3. **Duplication** — Any agents/skills with >50% description keyword overlap?
+4. **Security sweep** — Grep all `.claude/` content for `/Users/`, `/home/`, `password=`, `api_key`, `token=`
+5. **Integration** — Agents reference the skills they use? Commands invoke relevant agents?
+6. **CLAUDE.md knowledge organisation analysis** — see checklist in `references/component-checklists.md` (Pattern A and B checks are separate)
+
+### Phase 4: Grading
+
+```
+Component Score = (Points Obtained / Max Points) × 100
+Overall Score   = Average of all component scores
+```
+
+| Grade | Range | Label |
+|-------|-------|-------|
+| A | 90–100% | Production-ready |
+| B | 80–89% | Good — meets production threshold |
+| C | 70–79% | Needs improvement |
+| D | 60–69% | Significant gaps |
+| F | <60% | Critical issues — rewrite needed |
+
+**Production threshold**: Grade B (≥80%) required per component.
+
+### Phase 5: Report Generation
+
+Generate a report following `examples/sample-report.md` structure.
+
+For each failed criterion, cite the relevant example:
+```
+❌ No role statement ("You are...") found
+   → See examples/bad-agent.md (line 10) vs examples/good-agent.md (line 8)
+```
+
+Prioritize findings:
+- 🔴 **Critical** (fix immediately): Security issues OR grade F
+- 🟡 **Important** (fix soon): Grade D–C OR missing key structural elements
+- 🔵 **Minor** (polish): Grade B OR optional improvements
+
+## Quick Wins (High-Impact, Low-Effort Fixes)
+
+| Issue | Score Impact | Fix Effort |
+|-------|-------------|------------|
+| Missing `model:` in agent | +3 pts | 1 line |
+| No `allowed-tools` in standard skill | +3 pts | 1 line |
+
+| No "When to use" trigger section | +2–3 pts | 1 paragraph |
+| Hardcoded `/Users/` path | +1 pt + removes security risk | Find + replace |
+| No `argument-hint` for command with args | +3 pts | 1 line |
+| Missing "You are…" role statement in agent | +2 pts | 1 sentence |
+| No output format section | +2 pts | 1 short section |
+| Description uses second person ("Use this...") | +1–2 pts | Rephrase |
+| CLAUDE.md >400 non-code words | +2 pts + reduces instruction loss | Prune noise |
+| `CLAUDE.local.md` not in `.gitignore` | removes security risk | 1 line in .gitignore |
+| Pattern A: guides exist but not referenced by path | +2 pts | Add guide paths to CLAUDE.md |
+| Pattern B: subdir CLAUDE.md duplicates root | +2 pts | Remove duplication, scope to module only |
+
+## Reference Files
+
+### Scoring Details
+- **`references/component-checklists.md`** — Full rubric: all criteria, point values, detection patterns
+- **`references/best-practices.md`** — Rationale per criterion, anti-patterns to avoid, quick-fix examples
+
+### Examples
+
+| Component | Good Example | Bad Example |
+|-----------|-------------|-------------|
+| Skill | `examples/good-skill.md` | `examples/bad-skill.md` |
+| Agent | `examples/good-agent.md` | `examples/bad-agent.md` |
+| CLAUDE.md | `examples/good-claude-md-snippet.md` | `examples/bad-claude-md-snippet.md` |
+| Command | `examples/good-command.md` | `examples/bad-command.md` |
+| Hooks config | `examples/good-hooks.json` | `examples/bad-hooks.json` |
+| Full report | `examples/sample-report.md` | — |
+
+### Utilities
+- **`scripts/scan-repo.sh`** — Discover and inventory all Claude Code components

package/dist/agents/plugins/claude/plugin/skills/claude-setup-audit/examples/bad-agent.md

@@ -0,0 +1,45 @@
+---
+# ❌ BAD AGENT EXAMPLE
+# Score: ~7/32 pts (Grade F)
+# What's wrong: See inline comments marked ❌
+#
+# ❌ A1.1: Generic name "reviewer" — not descriptive
+# ❌ A1.2: Description has no trigger context, wrong person
+# ❌ A1.3: No model specified
+# ❌ A1.4: Bash in tools with no justification; overly broad tool set
+# ❌ A2.1: No "You are..." role statement
+# ❌ A2.2: No output format defined
+# ❌ A2.3: No scope, no "When NOT to use"
+# ❌ A2.4: No anti-hallucination measures
+# ❌ A3.1: No examples
+# ❌ A3.2: No edge cases
+# ❌ A3.3: No error handling
+# ❌ A4.1: Multi-purpose (code + architecture + docs + CI/CD + DB)
+# ❌ A4.3: No skill references
+---
+name: reviewer
+description: Use this agent to review things and provide feedback on code
+  and other project artifacts.
+tools: [Read, Grep, Glob, Bash, Write, WebFetch, WebSearch]
+
+---
+
+# Code Review Agent
+
+This agent will review your code and tell you if there are any issues. It can
+handle many different types of reviews and will help you improve your code
+quality across all aspects of your project.
+
+Review the code and provide feedback:
+- Check for bugs
+- Check for security issues
+- Check for style issues
+- Check for performance issues
+- Check for test coverage
+- Review architecture decisions
+- Suggest improvements to documentation
+- Help with CI/CD configuration
+- Review database schemas
+- Check API design
+
+Provide thorough feedback on everything you find. Be comprehensive.

package/dist/agents/plugins/claude/plugin/skills/claude-setup-audit/examples/bad-claude-md-snippet.md

@@ -0,0 +1,40 @@
+# ❌ BAD CLAUDE.md SNIPPET EXAMPLE
+# Score: ~6/30 pts (Grade F)
+#
+# ❌ R1.1: No coding standards defined
+# ❌ R1.2: Workflow policies are vague ("try to follow")
+# ❌ R1.3: No MANDATORY/NEVER/ALWAYS directives
+# ❌ R2.1: Not actionable — uses "try", "be careful", "consider"
+# ❌ R2.2: No trigger conditions specified
+# ❌ R2.3: No explicit prohibitions
+# ❌ R3.1: Wall of text, no section organization
+# ❌ R3.2: No quick-reference tables
+# ❌ R3.3: No ✅/❌ examples
+# ❌ R4.1: Contradictions — "always write tests" vs later "only write tests when asked"
+# ❌ R4.2: No version requirements mentioned
+# ❌ R4.3: No project context
+
+---
+
+This project uses TypeScript and Node.js. When working on it, try to follow
+good coding practices and be careful with the code you write. Make sure to
+use modern JavaScript features when possible.
+
+For git operations, try to use descriptive commit messages and be careful
+with what you commit. Remember to test your changes before committing and
+try to follow the team's conventions.
+
+Testing is important. Always write tests for your code to make sure everything
+works. Make sure tests pass before finishing.
+
+Only write tests when the user explicitly asks for them.
+
+When using imports, be careful with the paths and make sure they work.
+Consider using TypeScript properly.
+
+For builds, run the build command when you're done. Be careful about
+environment variables and make sure you're not leaking any sensitive
+information. Try to follow security best practices in general.
+
+If something isn't working, check the logs and try to figure out what's
+wrong. Usually errors have helpful messages. Consider using the debugger.

package/dist/agents/plugins/claude/plugin/skills/claude-setup-audit/examples/bad-command.md

@@ -0,0 +1,30 @@
+---
+# ❌ BAD COMMAND EXAMPLE
+# Score: ~4/20 pts (Grade F)
+#
+# ❌ C1.1: Frontmatter missing description field
+# ❌ C1.2: Uses $ARGUMENTS in body but no argument-hint in frontmatter
+# ❌ C1.3: No phases or structured workflow — just a list of bullets
+# ❌ C1.4: No usage examples section
+# ❌ C2.1: No error handling for failures
+# ❌ C2.2: No output format defined
+# ❌ C2.3: No validation gates or confirmation step
+# ❌ C2.4: $ARGUMENTS used but no parsing logic shown
+name: jira
+---
+
+# Jira Ticket Creator
+
+Create a jira ticket using this command. Just describe what you want and
+the ticket will be created in Jira.
+
+The command will figure out the type and priority automatically based on
+what you write.
+
+Make sure JIRA_TOKEN is set before using this.
+
+Steps:
+- Figure out what kind of ticket $ARGUMENTS is asking for
+- Write a description
+- Create the ticket
+- Tell the user the ticket ID

package/dist/agents/plugins/claude/plugin/skills/claude-setup-audit/examples/bad-hooks.json

@@ -0,0 +1,23 @@
+{
+  "_comment": "❌ BAD HOOKS EXAMPLE — Score: ~3/20 pts (Grade F)",
+  "_notes": {
+    "H1.1": "✅ Valid JSON (only thing that passes)",
+    "H1.2": "❌ 'PreToolCall' is not a valid event type — should be 'PreToolUse'",
+    "H2.1": "❌ Hardcoded API key 'sk-abc123def456' in command string",
+    "H2.2": "❌ No set -e or trap — script will silently fail",
+    "H3.1": "❌ Matcher '.*' matches ALL tool uses — runs on every single action",
+    "H3.2": "❌ No description field — no way to know what this hook is for"
+  },
+  "hooks": [
+    {
+      "event": "PreToolCall",
+      "matcher": ".*",
+      "hooks": [
+        {
+          "type": "command",
+          "command": "bash -c 'curl https://api.mycompany.com/audit -d \"tool=$CLAUDE_TOOL_NAME&session=$CLAUDE_SESSION_ID\" -H \"Authorization: Bearer sk-abc123def456\" -H \"Content-Type: application/json\"'"
+        }
+      ]
+    }
+  ]
+}

package/dist/agents/plugins/claude/plugin/skills/claude-setup-audit/examples/bad-skill.md

@@ -0,0 +1,48 @@
+---
+# ❌ BAD SKILL EXAMPLE
+# Score: ~8/32 pts (Grade F)
+# What's wrong: See inline comments marked ❌
+#
+# ❌ S1.2: Name "Git Helper" has uppercase and space (should be git-helper)
+# ❌ S1.3: Description uses second person ("Use this skill"), vague, no trigger phrases
+# ❌ S1.4: No allowed-tools field — no tool restriction
+# ❌ S2.1: No methodology or structured workflow
+# ❌ S2.2: No output format defined
+# ❌ S2.3: No concrete examples
+# ❌ S2.4: No actionable checklists
+# ❌ S3.1: Hardcoded absolute path /Users/developer/projects
+# ❌ S4.1: Multi-purpose (commits AND branches AND rebasing AND PRs)
+# ❌ S4.2: No "When to use" or trigger conditions
+# ❌ Writing style: second person throughout ("you can", "you should")
+---
+name: Git Helper
+description: Use this skill when you need to do git things like commits and
+  pushing code and other git operations.
+
+---
+
+# Git Helper Skill
+
+This skill helps you with git. You can use it for commits, pushes, branches,
+and various git operations when working on your projects.
+
+When you need to do git things, this skill will help you do them correctly.
+It works with any git repository on your machine.
+
+Instructions:
+- Do git status first to see what files you have
+- Then you should stage the files you want to commit
+- Try to write a good commit message
+- Be careful with the commit message format
+- You should also check what files are staged
+- Make sure everything looks good before committing
+- Don't forget to push when you're done
+
+For branches: you can create new branches when needed. Try to use descriptive
+names. You should merge or rebase depending on the situation.
+
+Working directory note: this skill assumes you're working in
+/Users/developer/projects as the base path for all repositories.
+
+Note: This skill also handles pull requests, rebasing, cherry-picking,
+stash management, and GitHub integration.

package/dist/agents/plugins/claude/plugin/skills/claude-setup-audit/examples/good-agent.md

@@ -0,0 +1,145 @@
+---
+# ✅ GOOD AGENT EXAMPLE
+# Score: ~30/32 pts (Grade A)
+# What makes it good: See inline comments marked ✅
+#
+# ✅ A1.1: Descriptive, domain-specific name
+# ✅ A1.2: Description has "when" and "use" trigger context
+# ✅ A1.3: Model explicitly specified
+# ✅ A1.4: Bash justified with inline comment
+# ✅ A2.1: "You are..." role statement
+# ✅ A2.2: Output format section defined
+# ✅ A2.3: Scope + "When NOT to use"
+# ✅ A2.4: Anti-hallucination section
+# ✅ A3.1: 3+ usage examples
+# ✅ A3.2: Edge cases documented
+# ✅ A3.3: Error handling described
+# ✅ A4.1: Single responsibility (code review only)
+# ✅ A4.3: References related skills/agents
+#
+# ⚠️ Minor gap: A3.4 — integration docs could be more explicit
+---
+name: code-reviewer
+description: This agent should be used when the user asks to "review my code",
+  "check code quality", "review this PR", "look for bugs", "security review",
+  or "give feedback on my implementation". Reviews staged or committed changes
+  for quality, security, and correctness issues.
+model: claude-sonnet-4-6
+tools: [Read, Grep, Glob, Bash]
+# Bash required for: git diff, git log, running lint checks
+
+---
+
+# Code Reviewer Agent
+
+Reviews code changes for quality, security, and correctness. Provides structured
+feedback with severity levels and concrete improvement suggestions.
+
+## Role
+
+You are a senior code reviewer with expertise in security vulnerabilities,
+performance patterns, and maintainability. Your job is to identify real issues
+that would cause problems in production — not stylistic preferences or micro-
+optimizations. Focus on bugs, security vulnerabilities, logic errors, and
+maintainability problems.
+
+## Scope
+
+**Review**: Staged changes (`git diff --cached`), committed changes (`git diff HEAD~1`),
+or specific files provided by the user.
+
+**Do NOT review**: Generated files, `node_modules/`, `dist/`, `*.lock` files,
+binary files.
+
+**When NOT to use this agent**:
+- Architecture decisions → use `solution-architect` agent
+- Writing tests → use `test-writer` agent
+- Performance profiling → run profiler first, then use this agent on hotspots
+
+## Methodology
+
+1. Identify changed files: `git diff --name-only` or user-provided files
+2. For each file: read with context (surrounding code, not just diff)
+3. Evaluate against criteria below
+4. Generate structured report
+
+### Review Criteria
+
+**Security** (Critical — block production):
+- SQL injection, XSS, command injection vectors
+- Hardcoded credentials or secrets in code
+- Unvalidated input at system boundaries (user input, API responses, file reads)
+- Overly permissive CORS, auth bypass patterns
+
+**Correctness** (High — likely causes bugs):
+- Off-by-one errors, logic inversions
+- Unhandled exceptions or null/undefined dereferences
+- Race conditions in async code
+- Incorrect error propagation (swallowing errors)
+
+**Performance** (Medium — degrades at scale):
+- N+1 query patterns
+- Synchronous I/O in async contexts
+- Unbounded loops or missing pagination
+
+**Maintainability** (Low — increases tech debt):
+- Functions >40 lines without clear justification
+- Missing error context in catch blocks
+- Unclear naming in non-trivial logic
+
+## Output Format
+
+```markdown
+## Code Review: [file or PR title]
+
+**Summary**: [1–2 sentence overall assessment]
+**Verdict**: APPROVE / REQUEST CHANGES / BLOCKING
+
+### 🔴 Critical (must fix before merge)
+- **[File:Line]** [Issue]
+  - Impact: [what goes wrong in production]
+  - Fix: [concrete actionable suggestion]
+
+### 🟡 Important (should fix)
+- **[File:Line]** [Issue]
+  - Fix: [suggestion]
+
+### 🔵 Minor (optional polish)
+...
+
+### ✅ Positives
+[2–3 specific things done well — required, not optional]
+```
+
+## Source Verification
+
+- Base all feedback on actual code seen in the diff — never assume patterns not shown
+- If uncertain whether something is a bug: "This may cause issues if [condition]…"
+- Never invent API signatures, library behaviors, or version requirements
+- Do not cite performance numbers without measurement evidence
+
+## Examples
+
+1. "Review my changes before commit" → run `git diff --cached`, review staged changes
+2. "Review the auth PR" → run `git diff main...HEAD`, review branch changes
+3. "Check this file for security issues" → review specified file for security criteria only
+4. "Quick review" → focus on Critical and High issues only, skip Low
+
+## Edge Cases
+
+- **Empty diff**: Warn "No staged/changed files found" and exit
+- **Binary files**: Skip with note "Binary file skipped (not reviewable)"
+- **Very large diffs (>200 files)**: Ask user to scope to specific directories
+- **Generated code** (e.g., `*.generated.ts`): Skip automatically
+
+## Error Handling
+
+- If `git` is not available: switch to direct file analysis
+- If file cannot be read: note in report and continue with other files
+- If user provides invalid path: report "File not found: [path]"
+
+## Works With
+
+- After review: use `commit-helper` skill for conventional commit message
+- For test gaps found: mention `test-writer` agent for coverage
+- For architecture concerns: escalate to `solution-architect` agent

package/dist/agents/plugins/claude/plugin/skills/claude-setup-audit/examples/good-claude-md-snippet.md

@@ -0,0 +1,126 @@
+# ✅ GOOD CLAUDE.md SNIPPET EXAMPLE
+# Score: ~27/30 pts (Grade A)
+#
+# ✅ R1.1: Coding standards defined (TypeScript section)
+# ✅ R1.2: Workflow policies explicit (Git, Testing)
+# ✅ R1.3: Critical rules with MANDATORY/NEVER + triggers
+# ✅ R2.1: Actionable — starts with verbs (Use, Run, Add, Never)
+# ✅ R2.2: Trigger conditions stated ("when user says", "for TypeScript files")
+# ✅ R2.3: Explicit prohibitions with examples
+# ✅ R3.1: Organized H2 sections
+# ✅ R3.2: Quick-reference table
+# ✅ R3.3: ✅/❌ pattern examples
+# ✅ R4.2: Technology versions mentioned
+# ✅ R4.3: Project context stated
+#
+# ⚠️ Minor gap: R4.1 — one minor contradiction possible (needs manual check)
+
+---
+# CLAUDE.md — Acme API Service
+
+**Project**: REST API backend for Acme platform (Node.js 22, TypeScript 5.4)
+**Team**: Platform Engineering
+
+---
+
+## ⚡ Task Classifier (Scan First)
+
+| Keywords in request | Apply policy |
+|--------------------|-------------|
+| "commit", "push", "branch", "PR" | → Git Policy below |
+| "test", "spec", "vitest" | → Testing Policy below |
+| TypeScript, imports, types | → TypeScript Standards below |
+| "deploy", "release", "build" | → Build Policy below |
+
+---
+
+## 🚨 Critical Rules (MANDATORY)
+
+🚨 **NEVER commit to `main` directly.** Always use feature branches.
+
+🚨 **NEVER use `--no-verify` on git hooks.** If a hook fails, fix the underlying issue first.
+
+🚨 **NEVER write tests unless user explicitly asks.** Wait for "write tests", "add coverage", "create specs".
+
+🚨 **ALWAYS use `.js` extensions in TypeScript imports.** TypeScript compiles to ESM. Missing extension = runtime crash.
+
+---
+
+## TypeScript Standards
+
+**Imports** — ES modules only:
+```typescript
+✅ import { foo } from './utils.js'
+✅ import type { Bar } from './types.js'
+❌ import { foo } from './utils'          // missing .js extension
+❌ const { foo } = require('./utils')     // CommonJS not allowed
+```
+
+**Types** — strict mode, no `any` shortcuts:
+```typescript
+✅ function process(input: unknown): Result { ... }
+✅ const value = data as UserProfile       // explicit assertion
+❌ function process(input: any) { ... }    // defeats type safety
+```
+
+**Async patterns**:
+```typescript
+✅ const result = await Promise.all([a(), b()])  // parallel where possible
+❌ const r1 = await a()                           // sequential bottleneck
+❌ const r2 = await b()
+```
+
+---
+
+## Git Policy
+
+**Branch naming**: `<type>/<description>` — e.g., `feat/add-oauth`, `fix/token-refresh`
+
+**Commit format**: Conventional Commits:
+```
+feat(auth): add token refresh on 401 response
+fix(api): handle null user in profile endpoint
+chore: update eslint to v9
+```
+
+**PR requirements**:
+- [ ] Branch is up to date with `main`
+- [ ] All CI checks pass
+- [ ] No `console.log` or debug code
+
+**Never do**:
+- ❌ `git push --force` to `main` (destructive, permanently loses history)
+- ❌ `git commit --amend` on published commits (breaks teammates' history)
+
+---
+
+## Testing Policy
+
+**MANDATORY**: Write tests ONLY when user explicitly says "write tests", "add coverage", "create unit tests".
+
+**Never proactively write or suggest tests.**
+
+Test commands:
+```bash
+npm test              # all tests
+npm run test:unit     # unit only
+npm run test:coverage # with coverage report
+```
+
+Framework: Vitest 4.x. All tests use dynamic imports for mocking (not static).
+
+---
+
+## Build Policy
+
+**Node.js**: >= 22.0.0 required (`node --version`)
+**npm**: bundled with Node — no yarn or pnpm
+**Build output**: `dist/` (gitignored)
+
+```bash
+npm run build    # TypeScript → dist/
+npm run lint     # ESLint (zero warnings required)
+npm run ci       # Full pipeline: lint + build + test
+```
+
+**Before deploying**: All CI checks must pass. No bypassing.