@zigrivers/scaffold 2.38.1 → 2.44.3

package/tools/review-pr.md

@@ -0,0 +1,229 @@
+---
+name: review-pr
+description: Run all configured code review channels on a PR (Codex CLI, Gemini CLI, Superpowers code-reviewer)
+phase: null
+order: null
+dependencies: []
+outputs: []
+conditional: null
+stateless: true
+category: tool
+knowledge-base: [multi-model-review-dispatch, automated-review-tooling]
+argument-hint: "<PR number or blank for current branch>"
+---
+
+## Purpose
+
+Run all three code review channels on a pull request and reconcile findings.
+This is the single entry point for PR code review — agents call this once instead
+of remembering three separate review invocations.
+
+The three channels are:
+1. **Codex CLI** — OpenAI's code analysis (implementation correctness, security, API contracts)
+2. **Gemini CLI** — Google's design reasoning (architectural patterns, broad context)
+3. **Superpowers code-reviewer** — Claude subagent review (plan alignment, code quality, testing)
+
+## Inputs
+
+- $ARGUMENTS — PR number (optional; auto-detected from current branch if omitted)
+- docs/review-standards.md (optional) — severity definitions and review criteria
+- docs/coding-standards.md (required) — coding conventions for review context
+- docs/tdd-standards.md (optional) — test coverage expectations
+- AGENTS.md (optional) — reviewer instructions with project-specific rules
+
+## Expected Outputs
+
+- All three review channels executed (or fallback documented)
+- P0/P1/P2 findings fixed before proceeding
+- Review summary with per-channel results and reconciliation
+
+## Instructions
+
+### Step 1: Identify the PR
+
+```bash
+# Use argument if provided, otherwise detect from current branch
+PR_NUMBER="${ARGUMENTS:-$(gh pr view --json number -q .number 2>/dev/null)}"
+```
+
+If no PR is found, stop and tell the user to create a PR first.
+
+### Step 2: Gather Review Context
+
+Collect the PR diff and project standards for review prompts:
+
+```bash
+PR_DIFF=$(gh pr diff "$PR_NUMBER")
+```
+
+Read these files for review context (skip any that don't exist):
+- `docs/coding-standards.md`
+- `docs/tdd-standards.md`
+- `docs/review-standards.md`
+- `AGENTS.md`
+
+### Step 3: Run All Three Review Channels
+
+Run all three channels. Track which ones complete successfully.
+
+#### Channel 1: Codex CLI
+
+**Auth check first** (auth tokens expire — always re-verify):
+
+```bash
+codex login status 2>/dev/null && echo "codex authenticated" || echo "codex NOT authenticated"
+```
+
+If Codex is not installed, skip this channel and note it in the summary.
+If auth fails, tell the user: "Codex auth expired. Run: `! codex login`" — do NOT
+silently fall back. After the user re-authenticates, retry.
+
+**Run the review:**
+
+```bash
+codex exec --skip-git-repo-check -s read-only --ephemeral "REVIEW_PROMPT" 2>/dev/null
+```
+
+The review prompt must include:
+- The PR diff
+- Coding standards from docs/coding-standards.md
+- Review standards from docs/review-standards.md (if exists)
+- Instruction to report P0/P1/P2 findings as JSON with severity, location (file:line), description, and suggestion
+
+#### Channel 2: Gemini CLI
+
+**Auth check first:**
+
+```bash
+GEMINI_AUTH_CHECK=$(NO_BROWSER=true gemini -p "respond with ok" -o json 2>&1)
+GEMINI_EXIT=$?
+if [ "$GEMINI_EXIT" -eq 0 ]; then
+  echo "gemini authenticated"
+elif [ "$GEMINI_EXIT" -eq 41 ]; then
+  echo "gemini NOT authenticated (exit 41: auth error)"
+fi
+```
+
+If Gemini is not installed, skip this channel and note it in the summary.
+If auth fails (exit 41), tell the user: "Gemini auth expired. Run: `! gemini -p \"hello\"`" — do NOT silently fall back. After the user re-authenticates, retry.
+
+**Run the review:**
+
+```bash
+NO_BROWSER=true gemini -p "REVIEW_PROMPT" --output-format json --approval-mode yolo 2>/dev/null
+```
+
+Same review prompt content as Codex. Do NOT share one model's output with the other —
+each reviews independently.
+
+#### Channel 3: Superpowers Code-Reviewer Subagent
+
+Dispatch the `superpowers:code-reviewer` subagent. This channel always runs (it uses
+Claude, which is always available).
+
+```bash
+BASE_SHA=$(gh pr view "$PR_NUMBER" --json baseRefOid -q .baseRefOid)
+HEAD_SHA=$(gh pr view "$PR_NUMBER" --json headRefOid -q .headRefOid)
+```
+
+Dispatch with the Agent tool using `superpowers:code-reviewer` as the subagent type,
+providing:
+- `WHAT_WAS_IMPLEMENTED` — PR title and description
+- `PLAN_OR_REQUIREMENTS` — coding standards and review standards
+- `BASE_SHA` — base commit
+- `HEAD_SHA` — head commit
+- `DESCRIPTION` — PR summary
+
+### Step 4: Reconcile Findings
+
+After all channels complete, reconcile findings:
+
+| Scenario | Confidence | Action |
+|----------|-----------|--------|
+| Multiple channels flag same issue | **High** | Fix immediately |
+| All channels approve (no findings) | **High** | Proceed to merge |
+| One channel flags P0, others approve | **High** | Fix it — P0 is critical from any source |
+| One channel flags P1, others approve | **Medium** | Fix it — P1 findings are mandatory regardless of source count |
+| Channels contradict each other | **Low** | Present to user for adjudication |
+
+### Step 5: Report Results
+
+Output a review summary in this format:
+
+```
+## Code Review Summary — PR #[number]
+
+### Channels Executed
+- [ ] Codex CLI — [completed / skipped (not installed) / skipped (auth failed) / error]
+- [ ] Gemini CLI — [completed / skipped (not installed) / skipped (auth failed) / error]
+- [ ] Superpowers code-reviewer — [completed / error]
+
+### Consensus Findings (High Confidence)
+[Findings flagged by 2+ channels]
+
+### Single-Source Findings
+[Findings from only one channel, with attribution]
+
+### Disagreements
+[Contradictions between channels]
+
+### Verdict
+[All channels approve / Fix required (list P0/P1/P2 items) / User adjudication needed]
+```
+
+### Step 6: Fix P0/P1/P2 Findings
+
+If any P0, P1, or P2 findings exist:
+1. Fix them in the code
+2. Push the fixes: `git push`
+3. Re-run the channels that produced findings to verify fixes
+4. After 3 fix rounds with unresolved P0/P1/P2 findings, stop and ask the user for direction — do NOT merge automatically. Document remaining findings and let the user decide whether to continue fixing, create follow-up issues, or override.
+
+### Step 7: Confirm Completion
+
+After all findings are resolved (or 3 rounds complete), output:
+
+```
+Code review complete. All 3 channels executed. PR #[number] is ready for merge.
+```
+
+Do NOT proceed to the next task or merge until this confirmation is output.
+
+## Fallback Behavior
+
+| Situation | Action |
+|-----------|--------|
+| Neither Codex nor Gemini installed | Run Superpowers code-reviewer only; document as "single-channel review" |
+| One CLI installed, one not | Run available CLI + Superpowers; document missing channel |
+| CLI auth expired | Surface to user with recovery command; do NOT silently skip |
+| Superpowers plugin not installed | Run both CLIs; warn user to install superpowers plugin |
+| All external channels unavailable | Superpowers code-reviewer only; warn user that review coverage is reduced |
+
+## Process Rules
+
+1. **All three channels are mandatory** — skip only when the tool is genuinely unavailable (not installed), never by choice.
+2. **Auth failures are not silent** — always surface to the user with recovery instructions.
+3. **Independence** — never share one channel's output with another. Each reviews the diff independently.
+4. **Fix before proceeding** — P0/P1/P2 findings must be resolved before moving to the next task.
+5. **Document everything** — the review summary must show which channels ran and which were skipped, with reasons.
+
+---
+
+## After This Step
+
+When code review is complete, tell the user:
+
+---
+**Code review complete** — All channels executed for PR #[number].
+
+**Results:**
+- Channels run: [list which of the 3 ran]
+- Findings fixed: [count]
+- Remaining: [none / list]
+
+**Next:** Return to the task execution loop — mark the task complete and pick up
+the next unblocked task with `/scaffold:single-agent-start`.
+
+**Pipeline reference:** `/scaffold:prompt-pipeline`
+
+---

package/tools/session-analyzer.md

@@ -0,0 +1,299 @@
+---
+name: session-analyzer
+description: Analyze session history to find automation opportunities
+phase: null
+order: null
+dependencies: []
+outputs: []
+conditional: null
+stateless: true
+category: tool
+knowledge-base: [session-analysis]
+---
+
+## Purpose
+
+Analyze all Claude Code sessions on this computer and identify repeated tasks,
+workflows, decisions, and patterns across every project — then recommend what
+to automate as skills, plugins, agents, and claude.md rules.
+
+## Inputs
+
+| Flag | Description |
+|------|-------------|
+| `--project <name>` | Focus deep analysis on one project (match against `~/.claude/projects/` directory names) |
+| `--depth shallow` | Use only `history.jsonl` and `stats-cache.json` — fast, skips session sampling |
+| `--depth deep` | Sample session transcripts from all active projects (default when omitted) |
+| `--output <path>` | Save the report as a markdown file at the specified path |
+
+## Expected Outputs
+
+A structured recommendations report containing:
+- Summary statistics (sessions, projects, date range, prompt count)
+- Top 10 skills to build
+- Top 5 plugins/tools to build
+- Top 5 agents to build
+- Most important missing claude.md sections
+- Build-first recommendation with scoring
+- Ranked build-order backlog (top 15 items)
+
+## Instructions
+
+### Phase 1: Data Collection
+
+Use **parallel subagents** to read the data sources below simultaneously. Each subagent handles one or two sources and returns a structured summary — not raw content.
+
+#### 1.1 Prompt History Index
+
+Read `~/.claude/history.jsonl` fully. Each line is a JSON object:
+```json
+{ "display": "<the prompt text>", "timestamp": 1234567890, "project": "/path/to/project" }
+```
+
+Extract:
+- Total prompt count and date range
+- All unique project paths and their prompt counts
+- All prompt text (store as an array for clustering in Phase 2)
+- The 5 most active projects by prompt count
+
+#### 1.2 Activity Statistics
+
+Read `~/.claude/stats-cache.json`. Extract:
+- Daily message counts and session counts
+- Most active days/weeks
+- Overall usage volume
+
+#### 1.3 Project Discovery
+
+List all directories under `~/.claude/projects/`. For each project directory:
+- Count the number of `.jsonl` session files
+- Note the most recently modified session file date
+- Identify if a CLAUDE.md-style file exists in that project's working directory
+
+#### 1.4 Session Transcript Sampling
+
+Skip this step if `--depth shallow` was passed.
+
+For the **5 most active projects** identified in step 1.1:
+- Find the 5 most recently modified `.jsonl` session files in `~/.claude/projects/<project-slug>/`
+- Read the first 80 lines of each session file
+- From each line, extract only entries where `type == "user"` (user messages only, skip assistant and tool responses)
+- Summarize the user messages from each session — do not reproduce raw content
+
+#### 1.5 Plan Title Clustering
+
+List all files in `~/.claude/plans/`. For each `.md` file:
+- Read only the first 3 lines (title + brief context)
+- Note the filename slug (e.g., `calm-fixing-storm.md` — likely a bug-fix plan)
+- Identify recurring themes across plan titles
+
+#### 1.6 Cross-Project CLAUDE.md Patterns
+
+For the 5 most active projects identified in step 1.1:
+- Locate the project's working directory from the path-encoded slug in `~/.claude/projects/`
+- Read its `CLAUDE.md` if it exists
+- Extract: key rules, repeated commands, tool preferences, workflow constraints
+- Note rules that appear in 2+ project CLAUDE.md files (these are likely global preferences)
+
+---
+
+### Phase 2: Pattern Recognition
+
+Using the data collected in Phase 1, identify patterns by category. Focus on **recurrence** — one-off requests are not patterns.
+
+#### 2.1 Prompt Clustering
+
+Group the prompt history by semantic similarity. Look for:
+- Prompts that follow the same template structure (e.g., "Create a PRD for X", "Write tests for Y")
+- Prompts that reference the same type of task across different projects
+- Prompts that start with the same verbs or follow the same format
+
+Flag any prompt pattern that appears **3 or more times** as a candidate for automation.
+
+#### 2.2 Repeated Workflow Sequences
+
+Look for multi-step patterns — sequences of prompts in the same session or across sessions that follow the same order:
+
+Examples to detect:
+- Always: plan then implement then test then commit
+- Always: read file then understand then refactor then verify
+- Always: create task then write code then write tests then PR
+
+#### 2.3 Correction and Preference Patterns
+
+Scan for patterns that indicate stated preferences or corrections:
+- Phrases like "always", "never", "don't", "remember to", "make sure to"
+- Corrections where the user had to re-prompt because the previous response didn't follow a preference
+- Project-agnostic preferences that appear in multiple projects
+
+#### 2.4 Tool and Integration Requests
+
+Look for prompts asking Claude to:
+- Access external services (GitHub, Jira, Slack, Notion, Linear, etc.)
+- Search for information online
+- Read/write files outside the project directory
+- Run scripts or CLI tools in specific ways
+- Transform data between formats (JSON to CSV, screenshot to code, etc.)
+
+#### 2.5 Autonomy and Orchestration Requests
+
+Look for prompts that describe **multi-step workflows** needing minimal supervision:
+- "Do X, then Y, then Z"
+- "Every time I do X, also do Y"
+- "Check Z before you do X"
+- "Run until all tasks are done"
+- Any request for a loop, pipeline, or sequence with conditional steps
+
+---
+
+### Phase 3: Categorization
+
+Sort each identified pattern into exactly one of these 4 buckets. Use the decision criteria below.
+
+#### Bucket A: Skills
+**Definition:** A repeatable thinking or writing task that can be captured as a reusable structured prompt. The output is predictable and follows a consistent format.
+
+**Decision criteria:** Use this bucket if:
+- The same prompt structure was used 3+ times
+- The task produces a document, analysis, or structured artifact
+- The task requires thinking/judgment but follows a known process
+- No external system access required
+
+**Examples:** Code review checklist, PRD creation, git commit message generation, explaining a codebase to a new dev, writing test plans.
+
+#### Bucket B: Plugins / Tools
+**Definition:** A task that requires access to external systems, APIs, web content, databases, or file integrations. The bottleneck is data access, not reasoning.
+
+**Decision criteria:** Use this bucket if:
+- The task requires reading from or writing to an external service
+- The task requires searching the web or scraping data
+- The task requires transforming data between systems
+- The task would be trivially easy if Claude had the data, but currently requires the user to copy-paste
+
+**Examples:** GitHub PR status fetcher, Jira ticket creator, Slack message summarizer, browser automation, CSV data analysis.
+
+#### Bucket C: Agents
+**Definition:** A multi-step autonomous workflow that requires decision-making, orchestration, or running until a condition is met. The value is in the automation of a sequence, not just a single step.
+
+**Decision criteria:** Use this bucket if:
+- The task involves 5+ sequential steps that are always done together
+- The task requires branching logic or conditional decisions
+- The task runs until a condition is met (e.g., "keep trying until tests pass")
+- The task coordinates multiple tools or sessions
+
+**Examples:** End-to-end feature implementation loop, automated code review and fix cycle, CI failure diagnosis and fix agent, multi-file refactor with test verification.
+
+#### Bucket D: claude.md Rules
+**Definition:** A rule, preference, standard, or project context that is currently being stated ad-hoc in prompts instead of being captured once in CLAUDE.md (or a per-project config).
+
+**Decision criteria:** Use this bucket if:
+- The user has stated the same rule 2+ times across sessions
+- The rule could be written once and would apply to all future sessions
+- The rule is about tone, format, process, or project context (not task-specific logic)
+
+**Examples:** "Always use TypeScript strict mode", "Never commit without running tests", "Use kebab-case for file names", "This project uses Postgres not MySQL".
+
+---
+
+### Phase 4: Detailed Analysis
+
+For **every item** identified in Phase 3, produce a structured entry:
+
+```
+### [Bucket] Item Name
+
+**What I keep doing:** [1-2 sentences describing the repeated pattern]
+
+**Why this bucket:** [1 sentence justifying the categorization]
+
+**Frequency:** [Exact count from history, or estimate with reasoning]
+
+**Time saved per use:** [Estimated minutes saved each time this is automated]
+
+**Suggested implementation:**
+[2-4 sentences describing what building this would look like. For skills: describe the prompt structure. For plugins: name the API or integration needed. For agents: describe the steps and decision points. For claude.md: quote the exact rule.]
+
+**Priority:** [High / Medium / Low]
+[Justify: High = frequent + high time savings + easy to build. Low = rare or hard to build.]
+```
+
+---
+
+### Phase 5: Recommendations Report
+
+After completing Phase 4, produce the final report with these sections in order:
+
+#### Summary Stats
+
+```
+Sessions analyzed: [N]
+Projects analyzed: [N]
+Date range: [earliest] to [latest]
+Total prompts reviewed: [N]
+Patterns identified: [N] (Skills: N, Plugins: N, Agents: N, claude.md: N)
+```
+
+#### Top 10 Skills to Build
+
+Ranked by: frequency x time-saved / implementation effort.
+
+For each, include: name, one-line description, estimated weekly time saved, priority.
+
+#### Top 5 Plugins / Tools to Build
+
+Ranked by: how often the user is blocked or doing manual copy-paste that a tool would eliminate.
+
+For each, include: name, what external system it connects to, the core capability needed, priority.
+
+#### Top 5 Agents to Build
+
+Ranked by: how many sequential steps it automates, how often the workflow runs.
+
+For each, include: name, the workflow it automates, estimated steps saved per run, priority.
+
+#### Most Important Missing claude.md Sections
+
+List the top rules/preferences that appeared repeatedly in prompts but are not yet captured in a claude.md. For each:
+- The rule itself (suggested wording)
+- How often it was re-stated in prompts
+- Which projects it applies to (all / specific project)
+
+#### Build-First Recommendation
+
+Recommend the single best thing to build first. Score each item using:
+
+```
+Score = (Impact x 3) + (Frequency x 2) + (Ease x 1)
+```
+
+Where each dimension is rated 1-5:
+- **Impact**: How much friction or time does this eliminate per use?
+- **Frequency**: How often does the pattern occur per week?
+- **Ease**: How quick is it to implement? (5 = under 30 min, 1 = requires significant infrastructure)
+
+Present the top 3 scored items and explain the winner.
+
+#### Recommended Build Order
+
+A ranked backlog of the top 15 items across all 4 buckets, ordered by score. Format as a table:
+
+| Rank | Type | Name | Score | Reason |
+|------|------|------|-------|--------|
+| 1 | Skill | ... | 22 | High frequency, easy to build |
+| 2 | claude.md | ... | 20 | Stated 8x, zero effort to capture |
+| ... | | | | |
+
+---
+
+## Process Rules
+
+1. **Read-only** — never write, modify, or delete any files in `~/.claude/`
+2. **Privacy-aware** — summarize patterns only; do not reproduce raw conversation content, API keys, passwords, or sensitive data
+3. **Subagents for data collection** — use parallel subagents in Phase 1 to read multiple data sources simultaneously; this keeps the main context from filling with raw session data
+4. **Subagents return summaries** — each subagent should return structured summaries, not raw file contents
+5. **Handle sparse data gracefully** — if `history.jsonl` has fewer than 50 entries, note this and proceed with what's available; don't fabricate patterns
+6. **Depth flag controls scope** — `--depth shallow` skips steps 1.4 and 1.6 (no session transcript sampling, no cross-project CLAUDE.md reading)
+7. **Project flag focuses analysis** — if `--project <name>` is passed, steps 1.4 and 1.6 read from that project only; steps 1.1-1.3 still cover all projects for context
+8. **No output file by default** — present the report inline; if `--output <path>` is passed, also save to that path as markdown
+9. **Minimum 3 examples** — don't put an item in Bucket A (Skills) unless you found at least 3 concrete examples; note the exact prompts that support the pattern
+10. **Frequency beats recency** — a pattern that appeared 10 times last year beats one that appeared 3 times this week

package/tools/update.md

@@ -0,0 +1,113 @@
+---
+name: update
+description: Check for and apply scaffold updates
+phase: null
+order: null
+dependencies: []
+outputs: []
+conditional: null
+stateless: true
+category: tool
+knowledge-base: []
+---
+
+## Purpose
+
+Check for and apply updates to the scaffold prompt pipeline. Detects the
+installation method, fetches the latest version, shows what changed, and
+applies the update.
+
+## Instructions
+
+### Step 1 — Detect Installation Method
+
+Check which installation method is in use:
+
+1. Run `ls ~/.claude/commands/.scaffold-version 2>/dev/null` to check for the user-command version marker.
+2. Check if this command was invoked as `/scaffold:update` (plugin install) or `/user:update` (user command install).
+
+Report the detected method to the user.
+
+### Step 2 — Fetch Latest Version
+
+Clone or pull the latest scaffold repo:
+
+```bash
+CACHE_DIR="$HOME/.cache/scaffold"
+if [ -d "$CACHE_DIR/.git" ]; then
+    cd "$CACHE_DIR" && git pull origin main
+else
+    mkdir -p "$(dirname "$CACHE_DIR")"
+    git clone https://github.com/zigrivers/scaffold.git "$CACHE_DIR"
+fi
+```
+
+### Step 3 — Show What Changed
+
+Read `~/.cache/scaffold/CHANGELOG.md` and display the entries to the user so they can see what's new.
+
+If `~/.claude/commands/.scaffold-version` exists, read it to determine the currently installed version and highlight only the newer entries.
+
+### Step 4 — Apply Update
+
+**For user command installs** (files in `~/.claude/commands/`):
+
+Run the install script from the fetched repo to update all command files:
+
+```bash
+bash ~/.cache/scaffold/scripts/install.sh -f
+```
+
+Report the result to the user.
+
+**For plugin installs** (`/scaffold:` prefix):
+
+Update the plugin in-place by pulling the latest code into the marketplace clone:
+
+1. Locate the marketplace clone directory:
+   ```bash
+   PLUGIN_DIR="$HOME/.claude/plugins/marketplaces/zigrivers-scaffold"
+   ```
+
+2. Verify it exists and is a git repo. If the directory doesn't exist or has no `.git`, fall back to telling the user to run `/plugin marketplace update zigrivers-scaffold` and stop here.
+
+3. Record the current state before updating:
+   ```bash
+   cd "$PLUGIN_DIR" && git rev-parse --short HEAD
+   ```
+
+4. Pull the latest changes:
+   ```bash
+   cd "$PLUGIN_DIR" && git pull origin main
+   ```
+
+5. Read the new version from the plugin manifest:
+   ```bash
+   cat "$PLUGIN_DIR/.claude-plugin/plugin.json"
+   ```
+   Extract the `version` field from the JSON.
+
+6. **Best-effort metadata sync** — Update `~/.claude/plugins/installed_plugins.json` to keep Claude Code's metadata in sync. Read the file, find the entry for `scaffold@zigrivers-scaffold`, and update its `version`, `commitSha` (from `git rev-parse HEAD`), and `lastUpdated` (current ISO timestamp) fields. Write the updated JSON back. **Wrap this in error handling** — if reading/writing fails, skip it silently. The update still worked because commands are served directly from the clone.
+
+7. **Best-effort timestamp sync** — Update the `lastUpdated` field for `zigrivers-scaffold` in `~/.claude/plugins/known_marketplaces.json`. Same error handling approach — skip silently on failure.
+
+8. Report the result: old SHA to new SHA, old version to new version.
+
+### Step 5 — Confirm
+
+After updating, tell the user:
+
+---
+**Scaffold updated.** Run `/scaffold:prompt-pipeline` (or `/user:prompt-pipeline`) to verify the commands are working.
+
+Check the changelog above for what's new. If any prompts you've already run were changed, you may want to re-run them.
+
+**Note:** For plugin installs, updated commands take effect immediately for new invocations. If anything seems stale, start a fresh Claude Code session.
+
+---
+
+## Process Rules
+
+1. Run each step in order.
+2. Do NOT skip the changelog display — users need to see what changed.
+3. If any step fails, report the error clearly and suggest running `./scripts/update.sh` from the scaffold repo directory as a fallback.