promptup-plugin 0.2.1 → 0.2.2

package/README.md

@@ -10,36 +10,86 @@ Zero infrastructure. Just SQLite at `~/.promptup/`.
 npx promptup-plugin
 ```
 
-This installs everything: MCP server, skills, hooks, statusline, and default config. Restart Claude Code to activate.
+Installs MCP server, commands, hooks, statusline, and default config. Restart Claude Code to activate.
 
-## What it does
+## How it works
 
-**4 MCP Tools:**
+### Session tracking
+Every Claude Code session is passively tracked via hooks. On session creation, the current git branch is recorded. This links sessions to PRs automatically.
+
+### Evaluation
+`/pup:eval` spawns an independent `claude -p` to analyze your session transcript across 11 dimensions. It extracts developer decisions (steers, rejects, validates, scopes) and generates coaching recommendations with before/after examples from your actual prompts. Falls back to heuristic scoring if Claude is unavailable.
+
+### PR reports
+`/pup:pr-report` matches sessions to the current branch, auto-evaluates unscored sessions, gathers all decisions, and computes a Decision Quality Score (DQS). The session-to-PR link uses `sessions.branch` — set when the session was created. Optionally posts as a GitHub PR comment.
+
+### DQS formula
+```
+DQS = autonomy * 25% + discipline * 25% + validation * 30% + diversity * 20%
+```
+- **Autonomy**: How often you steer, reject, or modify AI output vs accepting
+- **Discipline**: Ratio of modifications to blind accepts
+- **Validation**: How often you verify/test output
+- **Diversity**: How many decision types you use (steer, reject, validate, modify, scope, accept)
+
+## Commands
+
+| Command | What |
+|---------|------|
+| `/pup:eval` | Evaluate session across 11 skill dimensions |
+| `/pup:pr-report` | DQS report for current branch (add `--post` to comment on PR) |
+| `/pup:status` | Sessions tracked, evaluations, decision counts |
+| `/pup:config` | View/modify settings (`/pup:config evaluation.auto_trigger=prompt_count`) |
+| `/pup:update` | Check for and install updates |
+
+## MCP Tools
 
 | Tool | What |
 |------|------|
-| `evaluate_session` | Score a coding session across 11 skill dimensions |
-| `generate_pr_report` | Decision Quality Score (DQS) report for a git branch |
-| `get_status` | Sessions tracked, evaluations, decision counts |
-| `configure` | View/modify all PromptUp settings |
+| `evaluate_session` | Score session, extract decisions, coaching recommendations |
+| `generate_pr_report` | Match sessions to branch, compute DQS, optionally post to GitHub |
+| `get_status` | Tracking status and recent activity |
+| `configure` | Show/modify config (dot-path keys) |
+
+## Statusline
+
+`pupmeter` shows your latest composite score in the Claude Code status bar with a recommendation tip.
+
+## Hooks
+
+| Hook | What | Async |
+|------|------|-------|
+| `PostToolUse` | Logs tool events to `~/.promptup/tool-events.jsonl` | Yes |
+| `Stop` | Captures session end to `~/.promptup/session-end.json` | Yes |
+| `SessionStart` | Background update check against npm | Yes |
+| `UserPromptSubmit` | Auto-eval every N prompts (off by default) | Yes |
+
+## Configuration
 
-**3 Skills:**
-- `/eval` — Run an evaluation
-- `/pr-report` — Generate PR report (optionally post to GitHub)
-- `/status` — Check tracking status
+```bash
+/pup:config                                        # show all settings
+/pup:config evaluation.auto_trigger=prompt_count   # enable auto-eval
+/pup:config evaluation.interval=5                  # eval every 5 prompts
+/pup:config evaluation.weight_profile=bugfix       # scoring profile
+/pup:config decisions.signal_filter=all            # show all decisions
+```
+
+Config file: `~/.promptup/config.json`
 
-**Statusline:** `pupmeter` shows your latest score in the Claude Code status bar.
+## 11 Dimensions
 
-**Hooks:** Passive tracking via PostToolUse + session capture on Stop. Auto-eval on prompt count (configurable). Update check on SessionStart.
+**Base (interaction quality):**
+task decomposition, prompt specificity, output validation, iteration quality, strategic tool usage, context management
+
+**Domain (depth of understanding):**
+architectural awareness, error anticipation, technical vocabulary, dependency reasoning, tradeoff articulation
 
 ## Requirements
 
 - Node.js >= 20
 - Claude Code
 
-## Manual setup (alternative)
-
-If you prefer not to use the installer:
+## Manual setup
 
 ```json
 {
@@ -52,21 +102,6 @@ If you prefer not to use the installer:
 }
 ```
 
-## Configuration
-
-Run `configure` with no args to see all settings:
-
-```
-evaluation.auto_trigger    off | prompt_count | session_end
-evaluation.interval        prompts between auto-evals (default: 10)
-evaluation.weight_profile  balanced | greenfield | bugfix | refactor | security_review
-evaluation.feedback_detail brief | standard | detailed
-decisions.signal_filter    high | high+medium | all
-pr_report.auto_post        true | false
-```
-
-Config file: `~/.promptup/config.json`
-
 ## Uninstall
 
 ```bash

package/dist/index.js

@@ -20,14 +20,14 @@ const server = new McpServer({
     version: '1.0.0',
 });
 // Tool 1: evaluate_session
-server.tool('evaluate_session', 'Evaluate a coding session across 11 skill dimensions. Spawns an independent Claude analysis of the session transcript. Returns composite score, dimension breakdown, trends, and recommendations.', {
+server.tool('evaluate_session', 'Evaluate a coding session across 11 skill dimensions. Spawns an independent Claude analysis of the session transcript. Extracts developer decisions (steers, rejects, validates, scopes). Returns composite score, dimension breakdown, trends, coaching recommendations with before/after examples. Session is tagged with current git branch for PR matching.', {
     session_id: z.string().optional().describe('Session ID to evaluate. If omitted, evaluates the most recent session.'),
 }, async (args) => {
     const result = await handleEvaluateSession(args);
     return { ...result };
 });
 // Tool 2: generate_pr_report
-server.tool('generate_pr_report', 'Generate a Decision Quality Score (DQS) report for a git branch. Matches commits to sessions, analyzes developer decisions, and produces a structured markdown report. Optionally posts as a GitHub PR comment.', {
+server.tool('generate_pr_report', 'Generate a Decision Quality Score (DQS) report for a git branch. Matches sessions to the branch via sessions.branch column (set on session creation). Auto-evaluates unscored sessions, extracts decisions, computes DQS (autonomy + discipline + validation + diversity). Optionally posts as a GitHub PR comment via gh CLI.', {
     branch: z.string().optional().describe('Git branch name. Defaults to current branch.'),
     post: z.boolean().optional().default(false).describe('If true, post the report as a GitHub PR comment via gh CLI.'),
 }, async (args) => {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "promptup-plugin",
-  "version": "0.2.1",
+  "version": "0.2.2",
   "description": "AI coding skill evaluator for Claude Code — 11-dimension scoring, decision intelligence, PR reports",
   "type": "module",
   "main": "./dist/index.js",