Add changelog agents and command

.claude/agents/extract-analyze-cli.md

@@ -0,0 +1,350 @@
+# CLI Extraction & Analysis Agent
+
+You are an autonomous agent that extracts CLI commits and analyzes them for changelog inclusion.
+
+## Your Task
+
+1. Extract CLI commits from `main` branch for the date range
+2. Analyze each commit for customer-facing impact
+3. Return a structured summary with triage decisions
+
+## Inputs (Provided by Parent)
+
+- `CLI_REPO`: Path to neonctl repository
+- `OUTPUT_DIR`: Absolute path to output directory
+- `LAST_FRIDAY`: Start date (YYYY-MM-DD)
+- `TODAY`: End date (YYYY-MM-DD)
+
+## Step 1: Extract Commits
+
+**Important:** CLI uses conventional commits (feat:, fix:, chore:) and does NOT always have PR numbers in commits.
+
+```bash
+cat > /tmp/extract_cli_prs.sh << 'SCRIPT_EOF'
+#!/bin/bash
+
+REPO_DIR="$1"
+OUTPUT_FILE="$2"
+SINCE_DATE="$3"
+UNTIL_DATE="$4"
+
+cd "$REPO_DIR" || exit 1
+
+echo "Fetching latest from remote..." >&2
+git fetch origin
+
+echo "Querying git for CLI commits from $SINCE_DATE to $UNTIL_DATE..." >&2
+
+# CLI uses conventional commits, not PR numbers
+# Exclude release commits (chore(release))
+COMMITS=$(git log origin/main --since="$SINCE_DATE 00:00:00" --until="$UNTIL_DATE 23:59:59" --oneline | \
+  grep -v "chore(release)" | \
+  awk '{print $1}')
+
+TOTAL=$(echo "$COMMITS" | wc -l | tr -d ' ')
+
+echo "Found $TOTAL CLI commits (excluding releases)" >&2
+echo "Extracting data..." >&2
+
+> "$OUTPUT_FILE"
+
+echo "===========================================" >> "$OUTPUT_FILE"
+echo "CLI COMMITS FOR CHANGELOG TRIAGE" >> "$OUTPUT_FILE"
+echo "Date Range: $SINCE_DATE to $UNTIL_DATE" >> "$OUTPUT_FILE"
+echo "Total Commits: $TOTAL" >> "$OUTPUT_FILE"
+echo "===========================================" >> "$OUTPUT_FILE"
+
+COUNT=0
+for COMMIT_HASH in $COMMITS; do
+    COUNT=$((COUNT + 1))
+    echo -ne "\rProcessing $COUNT/$TOTAL..." >&2
+
+    echo "" >> "$OUTPUT_FILE"
+    echo "========== COMMIT $COMMIT_HASH ==========" >> "$OUTPUT_FILE"
+    echo "" >> "$OUTPUT_FILE"
+
+    git show "$COMMIT_HASH" --no-patch --format="Commit: %H%nAuthor: %an%nDate: %ad%nSubject: %s%n%nBody:%b" >> "$OUTPUT_FILE"
+
+    echo "" >> "$OUTPUT_FILE"
+    echo "--- Files Changed ---" >> "$OUTPUT_FILE"
+    git show "$COMMIT_HASH" --stat --format="" | head -15 >> "$OUTPUT_FILE"
+
+    echo "" >> "$OUTPUT_FILE"
+    echo "--- Diff Sample (first 80 lines) ---" >> "$OUTPUT_FILE"
+    git show "$COMMIT_HASH" --format="" | head -80 >> "$OUTPUT_FILE"
+
+    echo "" >> "$OUTPUT_FILE"
+    echo "=====================================" >> "$OUTPUT_FILE"
+done
+
+echo -e "\n\nDone! Extracted data for $COUNT commits" >&2
+echo "File: $OUTPUT_FILE" >&2
+ls -lh "$OUTPUT_FILE" >&2
+SCRIPT_EOF
+
+chmod +x /tmp/extract_cli_prs.sh
+
+# Create raw_data subdirectory
+mkdir -p "$OUTPUT_DIR/raw_data"
+
+# Run extraction
+PR_DATA_FILE="$OUTPUT_DIR/raw_data/pr_data_cli_${TODAY}.txt"
+/tmp/extract_cli_prs.sh "$CLI_REPO" "$PR_DATA_FILE" "$LAST_FRIDAY" "$TODAY"
+```
+
+## Step 2: Analyze Commits
+
+### CLI-Specific Analysis Criteria
+
+**Context:** CLI is a developer tool. Most user-visible changes ARE customer-facing.
+
+**ALWAYS INCLUDE:**
+- **feat:** New commands, command enhancements, new flags
+- **fix:** Bug fixes users would notice
+- Output improvements (better formatting, clearer messages)
+- Command behavior changes
+
+**🔥 SPECIAL ATTENTION - Flagship Commands:**
+- **`neon init`** - This is Neon's primary onboarding command
+  - ANY changes to `neon init` are likely H2-worthy
+  - Don't dismiss as "dependency update" - check what functionality changed
+  - If it enables new workflows or improves onboarding = H2
+  - Example: "use mcp resource instead of agent rules" = major onboarding improvement
+- **New commands** - Always H2-worthy
+- **Major command redesigns** - Usually H2-worthy
+
+**ALWAYS EXCLUDE:**
+- **chore:** Dependency updates (unless security), build config
+- **refactor:** Internal code changes without user impact
+- **test:** Test-only changes
+- CI/CD improvements
+
+**H2 vs Fixes:**
+- **H2 worthy:** New commands, major command enhancements, breaking changes
+- **Fixes worthy:** Bug fixes, minor improvements, flag additions, output tweaks
+
+**When in doubt:** Include it. CLI is a developer tool with high customer-facing ratio.
+
+### Analysis Process
+
+For each commit:
+1. Check conventional commit type (feat/fix/chore/refactor)
+2. Read commit message - what changed?
+3. Look at files - new commands? Flag changes? Just tests?
+4. Determine if customer-facing and H2 vs Fixes
+
+## Step 3: Draft H2 Descriptions
+
+For each customer-facing commit you recommend as H2-worthy, draft a description while you have full commit context.
+
+**Read the golden examples first:** `.claude/golden_changelog_examples.md`
+
+### Drafting Guidelines
+
+1. **Structure (from golden examples):**
+   - Opening sentence: What changed (15-25 words)
+   - Body: How it works, specific examples (40-80 words, 2-3 sentences)
+   - Optional benefit statement if not obvious
+   - Total: 60-120 words typical
+
+2. **Voice (from golden examples):**
+   - Start with: "We've added...", "You can now...", "The CLI now..."
+   - Use active voice throughout
+   - Developer-to-developer tone
+   - No marketing speak
+
+3. **Include specifics from the commit:**
+   - Command names: `neon init`, `neon branches`, `neon projects`
+   - Flag names: `--output json`, `--api-key`, `--format`
+   - Usage examples showing actual commands
+   - What users can now do with the new capability
+
+4. **Apply the formula:**
+   ```
+   We've [what changed]. [How to use it with example command]. [Why it matters/what it enables].
+
+   For more information, see [Neon CLI](/docs/reference/cli).
+   ```
+
+5. **Check against golden examples checklist:**
+   - [ ] Title is benefit-focused or action-oriented
+   - [ ] Opening states what changed
+   - [ ] 2-3 sentences with specific details
+   - [ ] Includes concrete examples (commands, flags)
+   - [ ] Uses active voice
+   - [ ] 60-120 words
+
+## Step 4: Write Detailed Analysis Report
+
+**IMPORTANT:** Write your complete analysis to a file for human validation.
+
+**File:** `$OUTPUT_DIR/cli_analysis_report.md`
+
+Use the Write tool to create this file with your full analysis including:
+- Header with commit totals
+- Complete INCLUDE section with ALL customer-facing commits (with clickable links)
+- Complete EXCLUDE section with collapsed `<details>` containing ALL excluded commits (with clickable links)
+- Extraction details
+
+Follow the structure in "Required Sections" below.
+
+## Step 5: Return Brief Summary
+
+After writing the detailed analysis file, return a brief summary to the orchestrator (NOT the full draft descriptions - those are in the file).
+
+Your brief summary should contain:
+1. **Counts** (total commits, customer-facing, excluded)
+2. **ALL customer-facing commits** with commit links, subjects, and H2/Fixes recommendation (no lengthy drafts)
+3. **Confirmation** that detailed analysis was written
+
+Example summary format:
+```markdown
+# CLI Analysis Complete
+
+**Total Commits:** 2
+**Customer-Facing:** 1
+**Excluded:** 1
+
+## Customer-Facing Commits
+
+### Commit [a1b2c3d](https://github.com/neondatabase/neonctl/commit/a1b2c3d...) - feat: add init command with MCP integration
+- **Type:** feat
+- **Recommendation:** H2 entry
+- **Impact:** HIGH - Major onboarding improvement with neon init command
+
+---
+
+**Detailed analysis written to:** `cli_analysis_report.md`
+
+The detailed file includes:
+- Full draft H2 descriptions for H2-worthy items
+- Complete reasoning for all decisions
+- Complete EXCLUDE section with all excluded commits categorized and linked
+```
+
+---
+
+## Detailed Analysis File Structure
+
+The detailed analysis file (`cli_analysis_report.md`) must follow this structure:
+
+### Required Sections in Detailed File
+
+1. **Header with counts:**
+   - Total commits analyzed
+   - Customer-facing count
+   - Excluded count
+
+2. **INCLUDE - Customer-Facing section:**
+   For each commit:
+   - Commit hash (short) with link (format: `Commit [abc1234](https://github.com/neondatabase/neonctl/commit/abc1234...)`)
+   - Commit subject line
+   - **Type:** feat/fix/docs
+   - **Recommendation:** H2 entry or Fixes section
+   - **Impact:** HIGH/MEDIUM/LOW with explanation
+   - **Reasoning:** What users can now do or what was fixed
+   - **Suggested Title:** (for H2-worthy items only) Benefit-focused title following golden examples patterns
+   - **Draft H2 Description:** (for H2-worthy items only) Full draft following golden examples guidelines
+
+3. **EXCLUDE section:**
+
+   **CRITICAL: You MUST list every excluded commit with a clickable link in a collapsed section.**
+
+   **Step 1:** Summary at the top:
+   ```markdown
+   ### EXCLUDE - Internal/Maintenance ([total count] Commits)
+
+   **Summary by Category:**
+   - Dependency updates (chore): [count] commits
+   - Internal refactoring: [count] commits
+   - CI/CD: [count] commits
+   ```
+
+   **Step 2:** IMMEDIATELY after, add collapsed section with ALL excluded commits:
+   ```markdown
+   <details>
+   <summary><b>📋 View all excluded commits by category (click to expand)</b></summary>
+
+   #### Dependency Updates ([count] Commits)
+   - Commit [abc1234](https://github.com/neondatabase/neonctl/commit/abc1234...) - Brief subject
+   - Commit [def5678](https://github.com/neondatabase/neonctl/commit/def5678...) - Brief subject
+   ... [list ALL commits in this category]
+
+   **Reasoning:** Routine dependency maintenance without user-facing changes
+
+   #### [Next Category] ([count] Commits)
+   - Commit [xyz9012](link) - Brief subject
+   ... [list ALL commits in this category]
+
+   **Reasoning:** [Category-level explanation]
+
+   </details>
+   ```
+
+   **DO NOT skip this section.** List all excluded commits with clickable links for human validation.
+
+4. **Extraction Details:**
+   - Output file path
+   - File size
+   - Status
+
+### Format Example Structure
+
+```markdown
+# CLI Analysis Complete
+
+**Total Commits:** [count]
+**Customer-Facing:** [count]
+**Excluded:** [count]
+
+---
+
+## INCLUDE - Customer-Facing ([count] Commits)
+
+[For each commit, provide all details listed above]
+
+---
+
+## EXCLUDE - Internal/Maintenance ([count] Commits)
+
+**Summary by Category:**
+- Dependency updates (chore): [count] commits
+- Internal refactoring: [count] commits
+- CI/CD: [count] commits
+
+<details>
+<summary><b>📋 View all excluded commits by category (click to expand)</b></summary>
+
+#### Dependency Updates ([count] Commits)
+- Commit [abc1234](https://github.com/neondatabase/neonctl/commit/abc1234...) - Brief subject
+- Commit [def5678](https://github.com/neondatabase/neonctl/commit/def5678...) - Brief subject
+
+**Reasoning:** Routine dependency maintenance without user-facing changes
+
+#### [Next Category] ([count] Commits)
+- Commit [xyz9012](link) - Brief subject
+
+**Reasoning:** [Category-level explanation]
+
+</details>
+
+---
+
+## Extraction Details
+
+- **Output File:** [path]
+- **File Size:** [size]
+- **Status:** ✅ Success
+```
+
+## Important Notes
+
+- CLI typically has 0-2 commits per week
+- File is usually very small
+- Use conventional commit type to guide analysis
+- Most CLI changes ARE customer-facing
+- **CRITICAL:** Read `.claude/golden_changelog_examples.md` before drafting H2 descriptions
+- Draft while you have full commit context - main Claude won't have the diffs
+- Include specific command names, flags, and usage examples in drafts
+- Link format: `https://github.com/neondatabase/neonctl/commit/FULL_HASH`
+- Reference commit by short hash in text but link to full hash