cc-proficiency 0.1.0

package/.claude-plugin/plugin.json

@@ -0,0 +1,11 @@
+{
+  "name": "cc-proficiency",
+  "version": "0.1.0",
+  "description": "Claude Code proficiency badge generator — analyze usage patterns across 5 domains aligned with Claude Certified Architect",
+  "author": {
+    "name": "Z-M-Huang"
+  },
+  "license": "MIT",
+  "keywords": ["proficiency", "badge", "analytics", "certification"],
+  "skills": "./skills/"
+}

package/LICENSE

@@ -0,0 +1,201 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/README.md

@@ -0,0 +1,345 @@
+<p align="center">
+  <img src="https://img.shields.io/badge/Claude_Code-Proficiency_Badge-7c3aed?style=for-the-badge&logo=data:image/svg+xml;base64,PHN2ZyB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciIHZpZXdCb3g9IjAgMCAyNCAyNCIgZmlsbD0id2hpdGUiPjxwYXRoIGQ9Ik0xMiAyTDIgN2wxMCA1IDEwLTV6Ii8+PHBhdGggZD0iTTIgMTdsMTAgNSAxMC01Ii8+PHBhdGggZD0iTTIgMTJsMTAgNSAxMC01Ii8+PC9zdmc+" alt="cc-proficiency" />
+</p>
+
+<p align="center">
+  <strong>Generate a proficiency badge for your Claude Code usage, aligned with the 5 Claude Certified Architect exam domains.</strong>
+</p>
+
+<p align="center">
+  <a href="https://www.npmjs.com/package/cc-proficiency"><img src="https://img.shields.io/npm/v/cc-proficiency?style=flat-square&color=cb3837&logo=npm" alt="npm version" /></a>
+  <a href="https://www.npmjs.com/package/cc-proficiency"><img src="https://img.shields.io/npm/dm/cc-proficiency?style=flat-square&color=cb3837&logo=npm" alt="npm downloads" /></a>
+  <a href="https://github.com/Z-M-Huang/cc-proficiency"><img src="https://img.shields.io/github/stars/Z-M-Huang/cc-proficiency?style=flat-square&logo=github" alt="GitHub stars" /></a>
+  <a href="https://github.com/Z-M-Huang/cc-proficiency/issues"><img src="https://img.shields.io/github/issues/Z-M-Huang/cc-proficiency?style=flat-square&logo=github" alt="GitHub issues" /></a>
+  <a href="https://github.com/Z-M-Huang/cc-proficiency/blob/main/LICENSE"><img src="https://img.shields.io/github/license/Z-M-Huang/cc-proficiency?style=flat-square" alt="License" /></a>
+</p>
+
+<p align="center">
+  <img src="https://img.shields.io/badge/node-%3E%3D18.0.0-339933?style=flat-square&logo=node.js&logoColor=white" alt="Node.js" />
+  <img src="https://img.shields.io/badge/TypeScript-5.7+-3178c6?style=flat-square&logo=typescript&logoColor=white" alt="TypeScript" />
+  <img src="https://img.shields.io/badge/zero-runtime_deps-22c55e?style=flat-square" alt="Zero Runtime Dependencies" />
+  <img src="https://img.shields.io/badge/coverage-96%25-brightgreen?style=flat-square" alt="Test Coverage" />
+  <a href="https://visitcount.itsvg.in"><img src="https://visitcount.itsvg.in/api?id=cc-proficiency&label=Visitors&color=6&icon=5&pretty=true" alt="Visitors" /></a>
+</p>
+
+<p align="center">
+  <a href="#install">Install</a> &nbsp;·&nbsp;
+  <a href="#usage">Usage</a> &nbsp;·&nbsp;
+  <a href="#embed-in-your-readme">Embed</a> &nbsp;·&nbsp;
+  <a href="#how-scoring-works">Scoring</a> &nbsp;·&nbsp;
+  <a href="#privacy">Privacy</a> &nbsp;·&nbsp;
+  <a href="./README.zh-CN.md">中文</a>
+</p>
+
+---
+
+## What it does
+
+Uses a **rule-based engine** to analyze your Claude Code session transcripts **locally**, scoring usage patterns across 5 domains:
+
+| Domain | Weight | What it measures |
+|--------|--------|-----------------|
+| **CC Mastery** | 20% | CLAUDE.md, hooks, plugins, plan mode, skills, rules |
+| **Tool & MCP** | 20% | Tool chains, MCP servers, LSP, selective edits |
+| **Agentic** | 20% | Subagents, parallel execution, worktrees, task management |
+| **Prompt Craft** | 20% | Structured prompts, code blocks, error traces, refinement |
+| **Context Mgmt** | 20% | Cross-session memory, CLAUDE.md updates, sustained projects |
+
+Plus **8 feature mini-bars** (Hooks, Plugins, Skills, MCP, Agents, Plan, Memory, Rules) showing per-feature adoption as a heatmap.
+
+<details>
+<summary><strong>Example output</strong></summary>
+
+```
+  Claude Code Proficiency — @username
+  ────────────────────────────────────────
+  CC Mastery     ███████████████░░░░░   77  ●
+  Tool & MCP     ███████████████████░   96  ◐
+  Agentic        ██████████████░░░░░░   69  ◐
+  Prompt Craft   ████████████████░░░░   81  ◐
+  Context Mgmt   ████████████████████  100  ●
+  ────────────────────────────────────────
+  [Hooks 100][Plugins 50][Skills 67][MCP 100]
+  [Agents 71][Plan 100][Memory 100][Rules  0]
+  ────────────────────────────────────────
+  139 sessions · 4 projects
+```
+
+</details>
+
+> **Disclaimer:** This is an unofficial usage estimate, not an actual Anthropic certification score. Not affiliated with or endorsed by Anthropic.
+
+## Install
+
+```bash
+npm install -g cc-proficiency
+cc-proficiency init
+```
+
+`init` will:
+1. Detect your GitHub username (via `gh` CLI)
+2. Inject a Stop hook into `~/.claude/settings.json`
+3. Create a private GitHub Gist for your badge (if `gh` is authenticated)
+
+If `gh` is not installed or not authenticated, the badge is saved locally to `~/.cc-proficiency/cc-proficiency.svg`.
+
+## Usage
+
+### First-time setup
+
+```bash
+$ cc-proficiency init
+
+Initializing cc-proficiency...
+
+  GitHub user: @yourname
+  Creating private Gist...
+  Gist created: a1b2c3d4e5f6
+
+  Add to your README:
+  ![CC Proficiency](https://gist.githubusercontent.com/yourname/a1b2c3d4e5f6/raw/cc-proficiency.svg)
+
+  ✓ Configuration saved to /home/you/.cc-proficiency
+  ✓ Hook injected into ~/.claude/settings.json
+
+  Run 'cc-proficiency analyze' to compute your first scores.
+```
+
+### Analyze your proficiency
+
+```bash
+$ cc-proficiency analyze --full
+
+Running full analysis...
+  Claude Code Proficiency — @yourname
+  ────────────────────────────────────────
+  CC Mastery     ███████████████░░░░░   77  ●
+  Tool & MCP     ███████████████████░   96  ◐
+  Agentic        ██████████████░░░░░░   69  ◐
+  Prompt Craft   ████████████████░░░░   81  ◐
+  Context Mgmt   ████████████████████  100  ●
+  ────────────────────────────────────────
+  Hooks   Edit (1411x), Bash (928x), Write (542x) +5
+  Skills  dev-buddy-once (5x), chatroom (2x) +5
+  Tools   Read 2046 · Bash 1045 · Write 379 · Edit 367 (+12 more)
+  ────────────────────────────────────────
+  139 sessions · 4 projects
+```
+
+### Get improvement tips
+
+```bash
+$ cc-proficiency explain
+
+  Claude Code Proficiency — @yourname
+
+  Strengths:
+    Context Mgmt   100/100
+    Tool & MCP      96/100
+    Prompt Craft    81/100
+    CC Mastery      77/100
+    Agentic         69/100
+
+  Areas to Improve:
+    Agentic (69/100)
+       → Try more CC features: subagents, MCP servers, skills,
+         plan mode, worktrees
+    CC Mastery (77/100)
+       → Enhance CLAUDE.md with imports, add hooks with matchers,
+         create rules files
+
+  Feature Usage:
+    Hooks:  Edit (1411x), Bash (928x), Write (542x) +5
+    Skills: dev-buddy-once (5x), chatroom (2x) +5
+    Tools:  Read (2046), Bash (1045), Write (379) +12 more
+    Flags:  ✓ Plan  ✓ Memory  ✗ Rules
+
+  139 sessions · 4 projects
+```
+
+### Generate and push your badge
+
+```bash
+# Save badge locally
+$ cc-proficiency badge --output my-badge.svg
+Badge written to my-badge.svg
+
+# Or push directly to your Gist
+$ cc-proficiency push
+✓ Badge pushed to Gist
+  https://gist.githubusercontent.com/yourname/a1b2c3d4e5f6/raw/cc-proficiency.svg
+```
+
+### Automatic updates (zero effort)
+
+After `init`, a Stop hook runs automatically after every Claude Code session:
+
+```
+You use Claude Code normally
+  → Session ends
+  → Hook queues the session (<1s, invisible to you)
+  → Background process analyzes + updates your badge
+  → Your README badge reflects your latest scores
+```
+
+No manual steps needed after setup.
+
+### Without GitHub CLI
+
+If you don't have `gh` installed or prefer local-only mode:
+
+```bash
+$ cc-proficiency init
+
+  ⚠ GitHub CLI not authenticated.
+  Badge will be saved locally to: ~/.cc-proficiency/cc-proficiency.svg
+  To enable auto-upload: gh auth login && cc-proficiency init
+
+$ cc-proficiency analyze --full
+$ cc-proficiency badge --output badge.svg
+```
+
+## Embed in your README
+
+After running `cc-proficiency init`, add this to your README:
+
+```markdown
+![Claude Code Proficiency](https://gist.githubusercontent.com/<username>/<gist-id>/raw/cc-proficiency.svg)
+```
+
+The badge updates automatically after each Claude Code session (via the Stop hook).
+
+## Progressive Badge
+
+The badge adapts based on how much data is available:
+
+| Phase | Sessions | What's shown |
+|-------|----------|-------------|
+| **Calibrating** | 0–2 | Setup checklist + progress toward first scoring |
+| **Early Results** | 3–9 | 5 domain bars + 8 feature mini-bars (low-confidence indicators ○) |
+| **Full Badge** | 10+ | Full domain bars, feature heatmap, confidence dots (● ◐ ○) |
+
+## How scoring works
+
+### Rule-based engine, not counting
+
+Instead of counting tool usage, cc-proficiency uses a **pattern-matching rule engine** with ~53 rules across 5 domains. Each rule detects a specific behavior pattern and awards points by tier:
+
+| Tier | Points | Example Rule |
+|------|--------|-------------|
+| **Beginner** | 5 pts | Has global CLAUDE.md |
+| **Intermediate** | 10–15 pts | Investigation chain: Grep → Read → Edit |
+| **Advanced** | 15–25 pts | Parallel agents with different subagent types |
+| **Anti-pattern** | -5 to -10 pts | 5+ parallel tools with >50% error rate |
+
+### 5 Domain Bars
+
+| Domain | What it measures |
+|--------|-----------------|
+| **CC Mastery** | CLAUDE.md structure, hooks with matchers, plugins, plan mode, skills, rules files |
+| **Tool & MCP** | Investigation chains, Read-before-Edit, tool variety, MCP server usage, LSP, selective edits |
+| **Agentic** | Subagent type variety, parallel agents, background runs, worktrees, task management |
+| **Prompt Craft** | Structured requests, code blocks, error traces, file references, iterative refinement |
+| **Context Mgmt** | Active memory files, CLAUDE.md updates, sustained projects, session depth |
+
+### 8 Feature Mini-Bars
+
+Below the domain bars, a heatmap row shows adoption per feature:
+
+`Hooks · Plugins · Skills · MCP · Agents · Plan · Memory · Rules`
+
+Each mini-bar derives its score from the same rules — a rule tagged with `"hooks"` contributes to both its domain bar and the Hooks mini-bar.
+
+### Bucket aggregation with caps
+
+Scores are not raw sums. Each domain has capped buckets:
+
+| Bucket | Max Points | Source |
+|--------|-----------|--------|
+| **Config** | 25 pts | Config-based rules (CLAUDE.md, hooks, plugins — available immediately) |
+| **Behavior** | 75 pts | Behavior-based rules (transcript patterns — grow over time) |
+| **Penalty** | -15 pts max | Anti-pattern deductions |
+
+This means:
+- **Fresh installs** can score up to ~25 per domain from config alone (no transcripts needed)
+- **No domain exceeds 35 without transcript evidence** — config alone can't fake proficiency
+- **Anti-patterns are capped** — a few bad sessions don't destroy your score
+
+### Phase-aware weighting
+
+Config evidence is weighted more heavily during calibration, less as transcripts accumulate:
+
+| Phase | Sessions | Config scale | Behavior scale |
+|-------|----------|-------------|---------------|
+| Calibrating | 0–2 | 2.0× | 0.8× |
+| Early | 3–9 | 1.5× | 1.0× |
+| Full | 10+ | 1.0× | 1.15× |
+
+### Anti-gaming
+
+- Rules fire **per-session with caps** — repeating the same tool 100x doesn't help
+- **Anti-pattern rules** deduct points for bad habits (shotgun parallel calls, unstructured walls of text)
+- Each rule has `maxPerSession` — investigation chains cap at 3 per session
+- Config scores are **capped at 25** — you can't max a domain by just installing plugins
+
+## Privacy
+
+| Concern | How it's handled |
+|---------|-----------------|
+| **Data location** | All analysis happens **locally** on your machine |
+| **What's stored** | Only aggregate counts, ratios, and boolean flags — no file paths, code, or prompts |
+| **Gist visibility** | **Private by default** (secret URL, not listed on your profile) |
+| **Offline mode** | Works fully offline without `gh` CLI (local-only mode) |
+| **CI/CD** | Non-interactive sessions are automatically detected and excluded |
+
+## Commands
+
+| Command | Description |
+|---------|-------------|
+| `cc-proficiency init` | Set up hooks and Gist |
+| `cc-proficiency analyze [--full]` | Parse sessions and compute scores |
+| `cc-proficiency process` | Process queued sessions from hook |
+| `cc-proficiency badge [--output <file>]` | Generate SVG badge |
+| `cc-proficiency push` | Upload badge to Gist |
+| `cc-proficiency explain` | Show score drivers and tips |
+| `cc-proficiency config [key] [value]` | View/set configuration |
+| `cc-proficiency uninstall` | Remove hooks and clean up |
+
+## Architecture
+
+```
+Stop hook fires (< 1s)
+  → Writes session path to ~/.cc-proficiency/queue.jsonl
+  → Spawns `cc-proficiency process` as detached child
+
+cc-proficiency process
+  → Acquires queue.lock (stale >60s → break)
+  → Deduplicates by session_id
+  → Parses transcripts (streaming JSONL, per-line error handling)
+  → Extracts signals → computes scores → renders SVG
+  → Pushes to Gist (if configured) or saves locally
+  → Atomically rotates queue
+```
+
+## Contributing
+
+Contributions welcome! Please open an issue first to discuss what you'd like to change.
+
+```bash
+git clone https://github.com/Z-M-Huang/cc-proficiency.git
+cd cc-proficiency
+npm install
+npm test              # 146 tests
+npm run build         # compile to dist/
+npm run typecheck     # tsc --noEmit
+```
+
+## License
+
+[Apache 2.0](LICENSE)
+
+---
+
+<p align="center">
+  <sub>Built with Claude Code. Not affiliated with or endorsed by Anthropic.</sub>
+</p>