{
  "markdown": "# Claude Code Library (Plugin)\n\nA reusable Claude Code **plugin** of skills, agents, hooks, and rules that connects to any project. No file copying needed.\n\n## Why This Exists\n\nSetting up Claude Code effectively requires more than just installing it. You need:\n- **Skills** that enforce consistent workflows (safe refactoring, architecture mapping, code review)\n- **Hooks** that automate quality gates and protect sensitive files\n- **Rules** that teach Claude your project's conventions\n\nThis library provides all of these, extracted from real-world usage patterns documented in the [playbook](playbook/How%20I%20Use%20Claude%20Code.md).\n\n---\n\n## Quick Start\n\n### One-time use\n\nFrom any project, pass the plugin path directly:\n\n```bash\nclaude --plugin-dir /path/to/claude_experiments\n```\n\nSkills are namespaced:\n```\n/claude-library:architecture-arch    # Build mental model of codebase\n/claude-library:meta-project-setup   # Analyze project & get recommendations\n```\n\n### Permanent setup (no `--plugin-dir` needed)\n\nInstead of typing the full `--plugin-dir` path every time, create a shell alias that does it for you. Follow the guide for your OS below.\n\n> **Why not `settings.json`?** Claude Code's `extraKnownMarketplaces` config is for **marketplace directories** (folders containing multiple plugins in subdirectories). A single plugin repo like this one doesn't fit that format. The `--plugin-dir` flag is the intended way to load a single plugin, and a shell alias is the cleanest way to avoid retyping it.\n\n---\n\n#### Windows (PowerShell) — step by step\n\nThis is what most VS Code users on Windows will use.\n\n**Step 1: Check if you already have a PowerShell profile**\n\nOpen a terminal in VS Code (or any PowerShell window) and run:\n\n```powershell\nTest-Path $PROFILE\n```\n\n- If it returns `True` → you already have a profile, skip to Step 3.\n- If it returns `False` → continue to Step 2.\n\n**Step 2: Create the profile file**\n\n```powershell\nNew-Item -Path $PROFILE -Type File -Force\n```\n\n**Step 3: Open the profile in Notepad**\n\n```powershell\nnotepad $PROFILE\n```\n\n**Step 4: Add the alias function**\n\nIn Notepad, add this line (update the path to match where you cloned this repo):\n\n```powershell\nfunction claude-lib { claude --plugin-dir \"C:\\Users\\YOUR_USERNAME\\path\\to\\claude_experiments\" $args }\n```\n\nSave the file and close Notepad.\n\n**Step 5: Reload the profile**\n\nBack in your terminal, run:\n\n```powershell\n. $PROFILE\n```\n\nIf you get a script execution error, run this first, then retry:\n\n```powershell\nSet-ExecutionPolicy -Scope CurrentUser -ExecutionPolicy RemoteSigned\n```\n\n**Step 6: Verify it works**\n\nNavigate to any project and run:\n\n```powershell\nclaude-lib\n```\n\nYou should see Claude Code start with all plugin skills available. Done!\n\n---\n\n#### macOS / Linux (Bash or Zsh) — step by step\n\n**Step 1: Open your shell config**\n\n```bash\n# For Zsh (default on macOS)\nnano ~/.zshrc\n\n# For Bash (default on most Linux)\nnano ~/.bashrc\n```\n\n**Step 2: Add the alias**\n\nAdd this line at the end of the file (update the path to match where you cloned this repo):\n\n```bash\nalias claude-lib='claude --plugin-dir /path/to/claude_experiments'\n```\n\nSave and exit (`Ctrl+O`, `Enter`, `Ctrl+X` in nano).\n\n**Step 3: Reload**\n\n```bash\nsource ~/.zshrc   # or source ~/.bashrc\n```\n\n**Step 4: Verify it works**\n\nNavigate to any project and run:\n\n```bash\nclaude-lib\n```\n\n---\n\n#### What `claude-lib` does\n\n`claude-lib` is identical to `claude` — same features, same flags, same behavior. The only difference is it automatically adds `--plugin-dir` for you.\n\n| You type | What actually runs |\n|---|---|\n| `claude-lib` | `claude --plugin-dir \"/path/to/claude_experiments\"` |\n| `claude-lib --model sonnet` | `claude --plugin-dir \"/path/to/claude_experiments\" --model sonnet` |\n| `claude-lib --resume` | `claude --plugin-dir \"/path/to/claude_experiments\" --resume` |\n\n### Local development (this repo)\n\n```bash\n# Set up local symlinks so skills work without --plugin-dir\nbash setup-local.sh\n\n# Then use skills directly\n/architecture-arch map the codebase\n```\n\n---\n\n## Available Skills\n\nSkills are organized by **development phase** — find the phase you're in, pick the skill you need.\n\n> **Essential** = don't skip this. **If needed** = reach for it when the situation fits.\n\n### 1. Project Setup & Onboarding\n\n*Joining a project, assessing health, understanding what exists.*\n\n|  | Skill | When to use |\n|--|-------|-------------|\n| **Essential** | `/meta-project-setup` | First thing on any new project — audit setup, get recommendations, **generate full layered config**, or **auto-improve** existing setup |\n| **Essential** | `/meta-claude-md-gen` | Generate a context-rich CLAUDE.md through interactive interview — reading lists, guardrails, conventions |\n| **Essential** | `/architecture-arch` | Map the codebase structure before touching anything |\n| *If needed* | `/quality-review` | Want a health score with evidence and priority matrix |\n| *If needed* | `/quality-strategic-advisor` | Research your domain, get ideas for new features and capabilities |\n| *If needed* | `/quality-upgrade-advisor` | Dependencies look outdated, need an upgrade plan |\n| *If needed* | `/learning-codebase-mastery` | Deeply *learn* and retain codebase knowledge (5 modes below) |\n\n> **`/learning-codebase-mastery` has 5 modes** — pick by situation:\n> | Mode | Trigger words | When to use |\n> |------|--------------|-------------|\n> | **Deep Dive** (default) | `deep dive`, `analyze` | Understand a module's architecture before touching it |\n> | **Tutor** | `tutor`, `quiz`, `interactive` | Test yourself on code you've been reading |\n> | **Recent Changes** | `what changed`, `catch up`, `recent changes` | Catch up on git commits — quiz on what changed and why |\n> | **Pre-Commit** | `pre-commit`, `before commit`, `review my changes` | Verify you understand your uncommitted changes before committing |\n> | **Daily Practice** | `daily practice`, `practice today`, `session review` | Fill-in-the-code exercises from today's session — learn by doing |\n\n### 2. Planning & Design\n\n*Turning ideas into a concrete plan before writing code.*\n\n|  | Skill | When to use |\n|--|-------|-------------|\n| **Essential** | `/planning-impl-plan` | Design the implementation approach before coding |\n| *If needed* | `/planning-spec-from-text` | Requirements are vague — turn them into testable specs first |\n\n### 3. Building & Implementing\n\n*Writing new code — features, endpoints, methods.*\n\n|  | Skill | When to use |\n|--|-------|-------------|\n| *If needed* | `/learning-pair-programming` | Want to build a feature together — Claude and you split the work adaptively |\n| *If needed* | `/api-development-api-impl` | Adding API endpoints with consistent patterns |\n\n> **`/learning-pair-programming` collaboration modes** — choose how to split the work:\n> | Mode | Who codes | When to use |\n> |------|-----------|-------------|\n> | **Adaptive** (default) | Claude decides per step | Best of both — maximizes learning AND throughput |\n> | **\"I'll drive\"** | User writes, Claude reviews | Learning a new pattern, want full hands-on |\n> | **\"You drive\"** | Claude writes, user reviews | Boilerplate, scaffolding, familiar patterns |\n>\n> Switch modes mid-session by saying \"I'll take this one\", \"you handle this\", or \"let's go adaptive\".\n\n### 4. Reviewing & Refactoring\n\n*Improving existing code, catching issues, safe changes.*\n\n|  | Skill | When to use |\n|--|-------|-------------|\n| **Essential** | `code-reviewer` agent | After writing or modifying code — review your changes |\n| *If needed* | `/code-diagnosis` | Something smells off in a specific module or file |\n| *If needed* | `/quality-bug-sweep` | Full-project bug scan with severity classification — before releases or periodic health checks |\n| *If needed* | `/safe-changes-impact-check` | About to make a risky change — check the blast radius |\n| *If needed* | `/safe-changes-refactor-safe` | Multi-file refactor — need explicit invariants and checkpoints |\n| *If needed* | `/quality-sync-docs` | After refactoring — fix stale paths, counts, and references in all docs |\n\n### 5. Wrapping Up\n\n*Before committing — sync docs, check tests, commit cleanly.*\n\n|  | Skill | When to use |\n|--|-------|-------------|\n| **Essential** | `/commit-ready` | Update docs, check for bugs in changed code, check test gaps, and commit before switching context |\n\n### 6. Skill Building — standalone practice\n\n*Not tied to a specific project. Practice sessions you can do anytime.*\n\n> All learning skills use the `learning-coach` agent with persistent memory. Your progress, weak areas, and mastery levels carry across sessions automatically.\n\n| Skill | What it does |\n|-------|-------------|\n| `/learning-algo-practice` | Algorithm & interview prep (DSA, SQL, pandas, ML) |\n| `/learning-concept-recall` | Spaced repetition — quiz yourself on what you've studied |\n| `/learning-debug-training` | Systematic debugging training — find bugs methodically |\n| `/learning-code-review-eye` | Train your code review instincts on diffs |\n| `/learning-pair-programming` | Pair program on real tasks — adaptive driver split (you drive core logic, Claude drives boilerplate) |\n\n### 7. Library Maintenance — this plugin only\n\n| Skill | What it does |\n|-------|-------------|\n| `/meta-claude-md-gen` | Generate context-rich CLAUDE.md through interactive interview |\n| `/meta-agent-teams` | Decompose tasks into multi-agent orchestration plans. Ask yourself: *\"Can I split this into 3+ tasks where each agent edits different files?\"* If yes, this skill will save you time. If no, stick with a single agent. |\n| `/meta-discover-claude-features` | Scout official docs + community for new Claude Code features to adopt |\n| `/meta-experiment-feature` | Set up experiments for a specific feature you already know about |\n| `/meta-skill-audit` | Audit library for overlaps and gaps |\n| `/meta-self-learning-skill-gen` | Generator for **self-learning skills**, three dispatch modes: greenfield interview, **`describe <prose>`** (qualify a natural-language problem → adaptive gap-fill → build), and `convert <path>` (retrofit an existing skill). Greenfield/describe skills are adaptive (non-skippable Phase 0.5 run plan: reuse/adapt/skip/create over the baseline); convert stays fixed-sequence. Assembles SKILL.md (audit + ledger inlined) and bootstraps run_history.json from `library/templates/self-learning-skill/`. See `documentation/SELF_LEARNING_SKILLS.md`. |\n| `/meta-research-checkpoint` | Suggestion-only, cadence-based research sweep at two levels — **L1** (the generator + pattern + templates) and **L2** (each self-learning skill, gated by the freshness AND-gate or `--all`). Orchestrates `/meta-discover-claude-features`, `/quality-upgrade-advisor`, `/quality-strategic-advisor`, `/meta-skill-audit`; aggregates findings into `documentation/RESEARCH_CHECKPOINT.md` and resets the freshness counter on researched skills. Never auto-edits. Level 3 (normal skills) out of scope. |\n\n> **Discovery workflow**: `/meta-discover-claude-features` finds what's new → you pick what's relevant → `/meta-experiment-feature` sets up the experiment → `/meta-skill-audit` checks the result fits cleanly. For periodic upkeep of the self-learning machinery, `/meta-research-checkpoint` sweeps L1 + due L2 skills on demand.\n\n---\n\n## Quick Reference: Which Skill When?\n\n```\nI'm in this phase...                  Use this\n────────────────────────────────────────────────────────────────\nPROJECT SETUP & ONBOARDING\n  Audit, generate, or improve setup    /meta-project-setup        [essential]\n  Generate context-rich CLAUDE.md     /meta-claude-md-gen         [essential]\n  Map the codebase                    /architecture-arch          [essential]\n  Assess project health               /quality-review\n  Get strategic feature suggestions    /quality-strategic-advisor\n  Audit stale dependencies            /quality-upgrade-advisor\n  Deeply learn a codebase             /learning-codebase-mastery\n  Catch up on recent git changes      /learning-codebase-mastery what changed\n  Quiz before committing              /learning-codebase-mastery pre-commit\n  Practice today's implementations    /learning-codebase-mastery daily practice\n\nPLANNING & DESIGN\n  Design before coding                /planning-impl-plan         [essential]\n  Clarify vague requirements          /planning-spec-from-text\n\nBUILDING & IMPLEMENTING\n  Implement together (adaptive split)  /learning-pair-programming\n  Add an API endpoint                 /api-development-api-impl\n\nREVIEWING & REFACTORING\n  Review code I just wrote            code-reviewer agent         [essential]\n  Scan specific code for issues       /code-diagnosis\n  Full-project bug scan w/ severity   /quality-bug-sweep\n  Check blast radius                  /safe-changes-impact-check\n  Refactor safely                     /safe-changes-refactor-safe\n  Sync docs after changes             /quality-sync-docs\n\nWRAPPING UP\n  Before committing (docs+bugs+tests) /commit-ready               [essential]\n\nSKILL BUILDING (anytime)\n  Practice algorithms & interviews    /learning-algo-practice\n  Retain concepts (spaced repetition) /learning-concept-recall\n  Train debugging skills              /learning-debug-training\n  Sharpen code review instincts       /learning-code-review-eye\n  Pair program (adaptive driver split) /learning-pair-programming\n\nLIBRARY MAINTENANCE\n  Plan multi-agent orchestration      /meta-agent-teams\n  What's new in Claude Code?          /meta-discover-claude-features\n  Try a specific new feature          /meta-experiment-feature\n  Check for skill overlaps            /meta-skill-audit\n  Generate a self-learning skill      /meta-self-learning-skill-gen\n```\n\n---\n\n## Repository Structure\n\n```\nclaude_experiments/\n├── .claude-plugin/\n│   └── plugin.json              # Plugin manifest (hooks inline)\n├── .github/\n│   └── workflows/\n│       └── weekly-quality-check.yml  # Reusable weekly quality action\n├── skills/                       # Plugin skills (auto-discovered)\n│   ├── architecture-arch/\n│   ├── code-diagnosis/\n│   ├── safe-changes-refactor-safe/\n│   ├── safe-changes-impact-check/\n│   ├── planning-spec-from-text/\n│   ├── planning-impl-plan/\n│   ├── commit-ready/\n│   ├── api-development-api-impl/\n│   ├── quality-bug-sweep/\n│   ├── quality-review/\n│   ├── quality-strategic-advisor/\n│   ├── quality-upgrade-advisor/\n│   ├── learning-codebase-mastery/\n│   ├── learning-algo-practice/\n│   ├── learning-concept-recall/\n│   ├── learning-debug-training/\n│   ├── learning-code-review-eye/\n│   ├── learning-pair-programming/\n│   ├── meta-agent-teams/\n│   ├── meta-claude-md-gen/\n│   ├── meta-discover-claude-features/\n│   ├── meta-experiment-feature/\n│   ├── meta-project-setup/\n│   ├── meta-research-checkpoint/\n│   ├── meta-self-learning-skill-gen/\n│   ├── meta-skill-audit/\n│   └── quality-sync-docs/\n├── agents/                       # Agent definitions\n│   ├── code-reviewer.md\n│   └── learning-coach.md\n├── hooks/                        # Hook reference copy\n│   └── hooks.json\n├── skill-rules.json               # Trigger patterns for skill auto-suggestion\n├── scripts/                      # Automation scripts\n│   ├── skill-activation-hook.py  # UserPromptSubmit hook for auto-suggesting skills\n│   ├── sensitive-file-hook.py    # PreToolUse hook for sensitive file guidance\n│   ├── session-start-hook.py     # SessionStart hook for plugin validation\n│   ├── test_cache.py             # SHA-keyed pytest result cache — CLI helper + shared functions\n│   ├── pytest_test_cache.py      # Pytest plugin: auto-skips already-passed tests, auto-records\n│   └── quality-action/           # Weekly quality check (GitHub Action)\n│       ├── run_analysis.py       # Scan repo → call Azure OpenAI → markdown report\n│       ├── requirements.txt      # Action dependencies\n│       └── example-caller-workflow.yml  # Copy to your repos\n├── appendix/                     # Reference configs (settings.py, etc.)\n├── documentation/                # All generated .md docs\n│   ├── PROBLEM_STATEMENT.md\n│   └── BRAINSTORMING.md\n├── library/                      # Reference material\n│   ├── hooks/                    # Hook examples by category\n│   ├── rules/                    # Reusable rule templates\n│   └── templates/                # CLAUDE.md templates + self-learning-skill scaffold\n├── playbook/                     # Source of truth\n├── test_project/                 # Verification project\n├── tests/                        # Validation scripts\n└── experiments/                  # Feature experiments\n```\n\n---\n\n## Practical Workflow Guide\n\nEach skill recommends next steps in its output, so you rarely need to plan chains yourself. **Start with one skill; go deeper only if needed.**\n\n| Scenario | Start here | Go deeper (optional) |\n|----------|-----------|---------------------|\n| **Onboarding to a new project** | `/meta-project-setup` | `claude-md-gen` + `arch` + `quality-review` |\n| **Planning a new feature** | `/planning-impl-plan` | `spec-from-text` if requirements are vague |\n| **Catching up on changes** | `/learning-codebase-mastery what changed` | `code-diagnosis` if something looks off |\n| **Building with guidance** | `/learning-pair-programming` | `code-reviewer` when done |\n| **Adding an API endpoint** | `/api-development-api-impl` | `impl-plan` + `code-reviewer` |\n| **Investigating suspicious code** | `/code-diagnosis` | `impact-check` + `refactor-safe` |\n| **Full-project bug sweep** | `/quality-bug-sweep` | `code-diagnosis` for deep dives on flagged modules |\n| **Making a risky change** | `/safe-changes-impact-check` | `impl-plan` + `refactor-safe` |\n| **Refactoring existing code** | `/safe-changes-impact-check` | `refactor-safe` + `quality-sync-docs` + `code-reviewer` |\n| **Tackling tech debt** | `/quality-review` | `diagnosis` + `refactor-safe` |\n| **Planning next capabilities** | `/quality-strategic-advisor` | `impl-plan` for chosen suggestions |\n| **Upgrading dependencies** | `/quality-upgrade-advisor` | `impact-check` + `refactor-safe` |\n| **Wrapping up a session** | `/commit-ready` | `code-review-eye` to quiz yourself |\n| **Skill building** | `/learning-concept-recall` daily | Add other learning skills as needed |\n| **Planning multi-agent work** | `/meta-agent-teams` | Use the generated plan to launch agents |\n| **What's new in Claude Code?** | `/meta-discover-claude-features` | `meta-experiment-feature` to try what's relevant |\n| **Weekly maintenance** | `/quality-sync-docs` + `pytest` | `meta-skill-audit` if skills changed |\n\n---\n\n## Skill Decision Guide\n\nNot sure which skill to use? Find your concern below.\n\n### For documentation work\n\n| Goal | Skill |\n|------|-------|\n| Fix stale refs, broken paths, merge overlapping docs | `/quality-sync-docs` |\n| Update docs affected by code changes + commit | `/commit-ready` |\n| Generate CLAUDE.md from scratch | `/meta-claude-md-gen` |\n\n### For test work\n\n| Goal | Skill |\n|------|-------|\n| Find test gaps for uncommitted changes + write tests | `/commit-ready` |\n| Understand what tests would break from a proposed change | `/safe-changes-impact-check` |\n| Score overall test quality as part of health check | `/quality-review` |\n\n### For bug finding\n\n| Goal | Skill |\n|------|-------|\n| Check changed files for bugs before committing | `/commit-ready` (Step 3.5) |\n| Scan a specific file/module for bugs | `/code-diagnosis` |\n| Scan entire project for bugs with severity | `/quality-bug-sweep` |\n| Review recent git changes for issues | `code-reviewer` agent |\n| Broad quality score with prioritized improvements | `/quality-review` |\n\n### For all three combined (full health check)\n\nUse `/meta-agent-teams` to plan parallel execution of docs + tests + bugs agents.\n\n### Recommended Workflow\n\n| Frequency | What to run | What it covers |\n|-----------|-------------|----------------|\n| **Daily** (end of session) | `/commit-ready` | Docs + bugs in changed code + test gaps + commit — one skill |\n| **Periodic** (before release, after big refactors) | `/quality-bug-sweep` | Full-project bug scan with severity classification |\n| **Combined** (large projects, full health check) | `/meta-agent-teams` | Plan parallel agents for docs + tests + bugs simultaneously |\n\n---\n\n## Skill Highlights\n\n### `/meta-project-setup` — Setup Audit + Generation + Auto-Improve\n\nThree modes in one skill:\n\n- **Audit mode** (default): Analyzes any project across 8 dimensions, recommends which existing plugin skills fit, and **detects what skills are missing from the library**. Generates `documentation/CLAUDE_SETUP.md`.\n- **Generate mode** (`generate`, `create`, `set up`): Runs the full audit, then **creates the complete layered config** — path-scoped rules in `.claude/rules/`, hooks in `.claude/settings.json`, child CLAUDE.md for monorepos, `CLAUDE.local.md` template, and delegates to `/meta-claude-md-gen` for the root CLAUDE.md.\n- **Auto-improve mode** (`improve`, `upgrade`, `auto-improve`): Audits an existing setup against a best-practice checklist, **researches latest Claude Code patterns**, and suggests prioritized improvements with diffs before applying.\n\n```\n# Audit mode — fingerprint, recommend, discover gaps\n/meta-project-setup\n\n# Generate mode — create the full layered setup\n/meta-project-setup generate the full layered setup\n\n# Auto-improve mode — upgrade existing config with latest best practices\n/meta-project-setup auto-improve this project's Claude config\n```\n\n**Output**: Project fingerprint, recommended artifacts, **library gaps table**, tailored workflows, staged rollout plan, `documentation/CLAUDE_SETUP.md`. Generate mode also creates all config files. Auto-improve mode generates `documentation/CLAUDE_SETUP_IMPROVEMENTS.md`.\n\n**vs `/meta-skill-audit`**: That skill audits the *plugin itself* for overlaps and redundancies. This skill audits a *target project* to find what the plugin is missing for that project's needs.\n\n### `/meta-claude-md-gen` — Interactive CLAUDE.md Generator\n\nInterviews you about your project to build a CLAUDE.md that emphasizes **what to read first**, **what not to touch**, and **domain conventions** — the things that actually save Claude (and you) time every session.\n\n```\n# Full interactive interview\n/meta-claude-md-gen\n\n# Improve an existing CLAUDE.md\n/meta-claude-md-gen improve my current CLAUDE.md\n```\n\n**Output**: A context-rich CLAUDE.md with tiered reading lists (\"always read\" vs \"read if relevant\"), guardrails, exact commands, and domain conventions. Scores the result against a quality checklist before writing.\n\n**vs `/meta-project-setup`**: That skill audits your Claude Code setup and recommends plugin artifacts. This skill focuses *only* on generating the best possible CLAUDE.md through user interview — it doesn't recommend skills, hooks, or rules.\n\n### `/quality-review` — Quality Assessment + Prioritization\n\nGet calibrated, evidence-based project assessment with prioritized action plan:\n\n```\n/quality-review run tests if possible; focus on test quality\n```\n\n**Output**: Score (0-100), category breakdown, evidence with file paths, priority matrix (Do Now / Plan Soon / Monitor / Accept), next 3 PR-sized actions.\n\n### `/architecture-arch` — Architecture Mapping\n\nBefore touching unfamiliar code, map it first:\n\n```\n/architecture-arch focus on:\n- how requests flow from API to database\n- where authentication is enforced\n- what the main execution paths are\n```\n\n**Output**: 10-line overview, component map, execution paths, critical files, risks.\n\n### `/quality-strategic-advisor` — Strategic Feature Discovery\n\nResearch your project's domain and get actionable suggestions for new capabilities:\n\n```\n/quality-strategic-advisor\nThis is an LLM evaluation framework. We want to know:\n- What libraries and techniques exist for multi-agent scoring?\n- What's the state of the art in process reward models?\n- What similar tools do that we don't?\n```\n\n**Output**: Project understanding card, prioritized recommendations (Implement Next / Plan Later / Watch / Skip), implementation sketches, strategic sequence. Findings should be migrated to `documentation/IMPLEMENTATION.md`.\n\n**vs `/quality-upgrade-advisor`**: That skill checks if your existing dependencies are up to date. This skill finds new libraries, techniques, and features you're not using yet.\n\n### `/quality-upgrade-advisor` — Ecosystem Currency Check\n\nAudit dependencies against official docs and produce an upgrade roadmap:\n\n```\n# Full ecosystem audit\n/quality-upgrade-advisor\n\n# With vision context\n/quality-upgrade-advisor\nWe want to move toward async-first architecture.\nOnly recommend upgrades that help with that goal.\n```\n\n**Output**: Project Identity Card, tiered recommendations (Critical / Recommended / Consider / Skip), batched upgrade sequence with exact commands, `documentation/UPGRADE_ROADMAP.md`.\n\n---\n\n## Hook Examples\n\nHooks are inlined in `.claude-plugin/plugin.json`. Reference copies in `hooks/hooks.json`.\n\n### Auto-suggest skills based on user prompt\n\nA `UserPromptSubmit` hook matches your prompt against trigger patterns in `skill-rules.json` and suggests relevant skills automatically — no slash command needed. For example, typing \"help me refactor safely\" will suggest `/safe-changes-refactor-safe`.\n\n```json\n{\n  \"hooks\": [{\n    \"type\": \"command\",\n    \"command\": \"python \\\"${CLAUDE_PLUGIN_ROOT}/scripts/skill-activation-hook.py\\\"\"\n  }]\n}\n```\n\nCustomize triggers by editing `skill-rules.json` at the plugin root.\n\n### Block edits to protected paths\n\n```json\n{\n  \"matcher\": \"Edit|Write\",\n  \"hooks\": [{\n    \"type\": \"command\",\n    \"command\": \"if echo \\\"$CLAUDE_FILE_PATH\\\" | grep -qE '^(protected/|migrations/|.env)'; then echo 'BLOCKED' && exit 2; fi\"\n  }]\n}\n```\n\n### Sensitive file guidance (PreToolUse additionalContext)\n\nInjects context-aware guidance *before* Claude edits sensitive files (auth, config, migration, secrets, security). Uses `additionalContext` to make Claude behave like a cautious colleague.\n\n```json\n{\n  \"matcher\": \"Edit|Write\",\n  \"hooks\": [{\n    \"type\": \"command\",\n    \"command\": \"python \\\"${CLAUDE_PLUGIN_ROOT}/scripts/sensitive-file-hook.py\\\"\"\n  }]\n}\n```\n\n### Plugin validation on session start\n\nShows skill count and catches broken skills when a new session starts.\n\n```json\n{\n  \"matcher\": \"startup\",\n  \"hooks\": [{\n    \"type\": \"command\",\n    \"command\": \"python \\\"${CLAUDE_PLUGIN_ROOT}/scripts/session-start-hook.py\\\"\",\n    \"timeout\": 10\n  }]\n}\n```\n\n### Auto-lint Python files\n\n```json\n{\n  \"matcher\": \"Edit|Write\",\n  \"hooks\": [{\n    \"type\": \"command\",\n    \"command\": \"if echo \\\"$CLAUDE_FILE_PATH\\\" | grep -q '\\\\.py$'; then ruff check \\\"$CLAUDE_FILE_PATH\\\"; fi\"\n  }]\n}\n```\n\nSee `library/hooks/*/README.md` for more examples.\n\n---\n\n## Setting Up Rules\n\nRules are `.md` files in `.claude/rules/` that Claude reads automatically on every conversation. They teach Claude your project's conventions so you don't repeat yourself.\n\n**Rules vs `CLAUDE.md`**: `CLAUDE.md` is the project overview (the \"what\"). Rules are behavioral constraints Claude must follow (the \"how\").\n\n### Where rules live\n\n```\nyour-project/\n└── .claude/\n    └── rules/\n        ├── style.md       # Naming, formatting, imports\n        ├── testing.md      # Test conventions and coverage\n        ├── security.md     # Secrets, validation, auth\n        └── api.md          # Endpoint patterns (if applicable)\n```\n\n### Minimum rules for any project\n\nYou need at least **two rules** to get meaningful value. These cover the most common sources of \"Claude did something I wouldn't do.\"\n\n**1. `style.md`** (required) — prevents Claude from using wrong naming, skipping type hints, or misorganizing imports:\n\n```markdown\n# Style Rules\n\n## Naming Conventions\n- Functions/variables: `snake_case`\n- Classes: `PascalCase`\n- Constants: `UPPER_SNAKE_CASE`\n\n## Type Hints\n- Required for function signatures\n- Use `Optional[]` for nullable\n\n## Imports\n- Standard library first, third-party second, local third\n- Sorted alphabetically within groups\n\n## Formatting\n- Use project formatter (ruff/black)\n- Line length: 88-100 characters\n```\n\n**2. `testing.md`** (required) — ensures tests go in the right place with the right patterns:\n\n```markdown\n# Testing Rules\n\n## Structure\n- Unit tests in `tests/unit/`, integration in `tests/integration/`\n- Files named `test_*.py`\n\n## Conventions\n- One assertion concept per test\n- Names: `test_[what]_[condition]_[expected]`\n- Use fixtures for common setup\n- Mock external dependencies\n\n## Coverage\n- Critical paths: 90%+\n- Happy + error paths: covered\n```\n\n### Additional rules (add as needed)\n\n| Rule | When to add | What it prevents |\n|------|-------------|-----------------|\n| `security.md` | Projects with user input, auth, or secrets | Hardcoded secrets, skipped validation, careless auth changes |\n| `api.md` | Projects with API endpoints | Inconsistent error formats, wrong status codes, missing docs |\n| `project.md` | Projects with unique workflows | Claude ignoring your team's specific conventions |\n\nReady-to-copy templates are in `library/rules/`. Or run `/meta-project-setup` to get recommendations tailored to your project.\n\n### Rule writing tips\n\n- **Be specific** — \"Functions: `snake_case`\" is actionable. \"Write clean code\" is not.\n- **One topic per file** — Don't mix style and security in the same file.\n- **Include commands** — If the rule relates to running something, include the exact command.\n- **List sensitive paths** — Tell Claude which directories need extra caution.\n\n---\n\n## Automated Weekly Quality Checks (GitHub Action)\n\nThis plugin includes a **reusable GitHub Action** that runs upgrade and strategic analysis automatically on a weekly schedule. It uses **Azure OpenAI** to analyze your repos and creates a GitHub issue with prioritized findings.\n\n### How it works\n\n```\nEvery Monday 9am UTC (configurable)\n  │\n  └─ 1 job: Scan repo → call Azure OpenAI → create/update GitHub Issue\n```\n\nThe action scans dependency files, source code, README, and CLAUDE.md, then produces a markdown issue with findings organized as: Do Now > Plan Soon > Monitor > Accept. No PRs, no auto-merge — you review and action findings yourself.\n\n### Prerequisites\n\nYou need **Azure OpenAI** access with a model deployed (e.g., GPT-5.2), and secrets stored in **Azure Key Vault**.\n\n### Setup (5 minutes)\n\n**Step 1: Add 4 secrets to your GitHub repo**\n\nGo to your repo → Settings → Secrets and variables → Actions → New repository secret:\n\n| Secret name | Value | Where to find it |\n|-------------|-------|-------------------|\n| `AZURE_CLIENT_ID` | Service principal client ID | Azure Portal → App registrations |\n| `AZURE_TENANT_ID` | Your Azure tenant ID | Azure Portal → Microsoft Entra ID |\n| `AZURE_CLIENT_SECRET` | Service principal secret | Azure Portal → App registrations → Certificates & secrets |\n| `KEY_VAULT_ENDPOINT` | `https://your-keyvault.vault.azure.net/` | Azure Portal → Key Vault → Overview |\n\nThe action authenticates to Key Vault, which provides the Azure OpenAI API key at runtime.\n\n**Step 2: Copy the caller workflow to your repo**\n\nCreate `.github/workflows/weekly-quality.yml` in your target repo:\n\n```yaml\nname: Weekly Quality Check\n\non:\n  schedule:\n    - cron: \"0 9 * * 1\"  # Every Monday 9am UTC\n  workflow_dispatch:\n    inputs:\n      analysis_mode:\n        description: \"Analysis mode\"\n        type: choice\n        options: [\"upgrade\", \"strategic\", \"both\"]\n        default: \"both\"\n\npermissions:\n  contents: read\n  issues: write\n\njobs:\n  quality:\n    uses: tabers77/claude_experiments/.github/workflows/weekly-quality-check.yml@master\n    with:\n      analysis_mode: ${{ github.event.inputs.analysis_mode || 'both' }}\n      model: \"gpt-5.2\"\n    secrets:\n      AZURE_CLIENT_ID: ${{ secrets.AZURE_CLIENT_ID }}\n      AZURE_TENANT_ID: ${{ secrets.AZURE_TENANT_ID }}\n      AZURE_CLIENT_SECRET: ${{ secrets.AZURE_CLIENT_SECRET }}\n      KEY_VAULT_ENDPOINT: ${{ secrets.KEY_VAULT_ENDPOINT }}\n```\n\nThe full template is also available at `scripts/quality-action/example-caller-workflow.yml`.\n\n**Step 3: Done.** The action will run every Monday, or trigger it manually from Actions → Weekly Quality Check → Run workflow.\n\n### Configuration options\n\n| Input | Default | Description |\n|-------|---------|-------------|\n| `analysis_mode` | `both` | `upgrade`, `strategic`, or `both` |\n| `model` | `gpt-5.2` | Azure OpenAI model |\n\n### What it analyzes\n\n**Upgrade analysis** — scans dependency files and identifies outdated dependencies, deprecated patterns, security vulnerabilities, and available upgrades with risk assessment.\n\n**Strategic analysis** — analyzes project architecture, goals, and tech stack to suggest new features, libraries, methods, or patterns aligned with the project's vision.\n\n---\n\n## The Philosophy\n\n> **Claude is a junior engineer + reviewer + tutor — never an autopilot.**\n\nKey patterns:\n- **Plan before code**: Use `/planning-impl-plan` and `/safe-changes-refactor-safe` to think first\n- **Explicit invariants**: Always state what must not change\n- **Small checkpoints**: Verify after each step, not at the end\n- **Evidence-based**: Scores without file paths and confidence levels are ignored\n\nRead the full philosophy: [playbook/How I Use Claude Code.md](playbook/How%20I%20Use%20Claude%20Code.md)\n\n---\n\n## License\n\nMIT\n",
  "bytes": 33182,
  "sha": "7a905d26850254c4891febaa5516a559113f16eb86c0b0568e6280d7e427f382",
  "repo_slug": "tabers77/claude_experiments",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/plg_tabers77_claude_experiments_claude_libra_5595142a/readme"
}