refactor: simplify notes skill scripts with standardized output format (#316)

Refactored note management scripts to use a consistent header-first output
format and added AI summarization capability for quick note overviews.

Key changes:

1. Standardized script output format:
   - All scripts (search-notes.sh, list-titles.sh) now output header first
   - Data rows follow (empty if no results)
   - Removed verbose "Found N notes" messages for cleaner piping
   - Header-only output clearly indicates no results

2. Added summarize-notes.sh:
   - Pipes into search/list commands to add AI summaries
   - Uses GNU parallel + aichat for fast parallel processing
   - Adds SUMMARY column to help identify notes without reading full content
   - Detects header line (line 1) and appends "| SUMMARY" column
   - Processes data rows (line 2+) with AI model to generate summaries

3. Reorganized skill structure:
   - Moved shared scripts to .claude/skills/_shared/notes/
   - Split monolithic idea-refine into focused skills:
     * note-capture: Save conversation context to topic notes
     * note-find: Search for notes with optional AI summaries
     * note-list: List topics or notes with optional AI summaries
     * note-organize: Archive/refine notes with confirmation prompts
     * note-overview: Summarize all notes in a topic
     * note-refine: Iteratively edit and improve notes
   - Added shared documentation (notes-layout.md, topics.md)

4. Updated skill documentation:
   - All note-* skills now mention summarize-notes.sh capability
   - Added tips on when to use summarization (multiple unclear results)
   - Consistent patterns using AskUserQuestion for confirmations
   - Clear examples of piping: `list-titles.sh topic/ | summarize-notes.sh`

Benefits:
- Cleaner script output for reliable piping
- Fast AI summaries help disambiguate similar notes
- Modular skills with clear responsibilities
- Better UX with confirmation prompts before bulk operations

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>

Author: jumski

.claude/skills/notes/scripts/echo-notes-dir.sh renamed to .claude/skills/_shared/notes/echo-notes-dir.sh

@@ -104,11 +104,6 @@ extract_title() {
   fi
 }
 
-# Print header if with_dates
-if [ "$with_dates" = true ]; then
-  echo "# PATH | TITLE | MODIFIED | CREATED"
-fi
-
 # Collect all output
 output=$(
   for arg in "${args[@]}"; do
@@ -129,10 +124,17 @@ output=$(
   done
 )
 
+# Always output header first
 if [ "$with_dates" = true ]; then
-  # Sort by modification time (oldest first), then format output
-  echo "$output" | sort -t'|' -k1 -n | cut -d'|' -f2- | awk -F'|' '{printf "%s | %s | %s | %s\n", $1, $2, $3, $4}'
+  echo "PATH | TITLE | MODIFIED | CREATED"
+  # Output sorted results (if any)
+  if [ -n "$output" ]; then
+    echo "$output" | sort -t'|' -k1 -n | cut -d'|' -f2- | awk -F'|' '{printf "%s | %s | %s | %s\n", $1, $2, $3, $4}'
+  fi
 else
-  # Just output as-is
-  echo "$output"
+  echo "PATH | TITLE"
+  # Output results (if any)
+  if [ -n "$output" ]; then
+    echo "$output"
+  fi
 fi

.claude/skills/notes/scripts/list-titles renamed to .claude/skills/_shared/notes/list-titles.sh

@@ -0,0 +1,36 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+# list-topics - List all topic directories (non-underscore top-level folders)
+# Usage: list-topics
+# Output: One topic name per line
+
+# Get the directory where this script is located
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+
+# Validate and get notes directory
+NOTES_DIR=$("$SCRIPT_DIR/echo-notes-dir.sh")
+
+# Find all top-level directories that don't start with underscore
+# -maxdepth 1: only top level
+# -type d: directories only
+# -not -name '_*': exclude underscore-prefixed
+# -not -name '.': exclude current dir
+# -not -name '.*': exclude hidden dirs
+# Note: Trailing slash needed for symlink support
+topics=$(find "$NOTES_DIR/" -maxdepth 1 -type d \
+  -not -name '_*' \
+  -not -name '.' \
+  -not -name '.*' \
+  -printf '%f\n' | sort)
+
+# Count and output with summary
+count=$(echo "$topics" | grep -c '^' || echo "0")
+
+if [ "$count" -eq 0 ]; then
+  echo "No topics found."
+else
+  echo "Found $count topic(s):"
+  echo ""
+  echo "$topics"
+fi

.claude/skills/_shared/notes/list-topics.sh

@@ -0,0 +1,41 @@
+# Notes Directory Layout
+
+**Notes directory:** !`./.claude/skills/_shared/notes/echo-notes-dir.sh`
+
+## Folder Structure
+
+```
+./.notes/
+├── [topic]/              # Topic-based folders (e.g., pgflow-demo, ci-optimization)
+│   ├── WIP-*.md         # Work in progress (quick captures, drafts)
+│   └── *.md             # Refined notes (ready to use)
+│
+├── _archive/            # Archived/completed work
+│   └── [topic]/         # Organized by original topic
+│
+├── _reference/          # Knowledge base (optional)
+│   └── *.md             # Reference docs, guides, non-actionable info
+│
+└── roadmap.md           # (optional) Project roadmap
+```
+
+## File Naming
+
+- **WIP prefix**: `WIP-descriptive-name.md` for work in progress
+- **No prefix**: `descriptive-name.md` for refined notes
+- **Kebab-case**: Use hyphens, lowercase, no spaces
+- **Extension**: Always `.md`
+
+## Workflow
+
+1. **Capture**: Create `[topic]/WIP-note.md` (note-capture skill)
+2. **Refine**: Edit and improve over time (note-refine skill)
+3. **Finalize**: Remove WIP prefix when ready (note-organize skill)
+4. **Archive**: Move to `_archive/[topic]/` when done (note-organize skill)
+
+## Important Notes
+
+- Always use `./.notes/` (relative to repo root)
+- Working directory (`$PWD`) must be repository root
+- Use relative paths for scripts: `./.claude/skills/_shared/notes/`
+- Topics are inferred from folder names (use `list-topics.sh` script)

.claude/skills/_shared/notes/notes-layout.md

@@ -35,7 +35,7 @@ else
 fi
 
 # Use ripgrep to find files matching pattern (case-insensitive, list files only)
-"${rg_cmd[@]}" 2>/dev/null | while IFS= read -r file; do
+results=$("${rg_cmd[@]}" 2>/dev/null | while IFS= read -r file; do
   # Extract H1 title from first line
   title=$(head -1 "$file" 2>/dev/null | sed 's/^# //' || echo "")
 
@@ -46,4 +46,12 @@ fi
 
   # Output: path | title
   echo "$file | $title"
-done
+done || true)
+
+# Always output header first
+echo "PATH | TITLE"
+
+# Output results (if any)
+if [ -n "$results" ]; then
+  echo "$results"
+fi

.claude/skills/notes/scripts/search renamed to .claude/skills/_shared/notes/search-notes.sh

@@ -0,0 +1,77 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+# summarize-notes - Add AI summaries to note listings
+# Usage: list-titles.sh scratch/ | summarize-notes.sh
+#    or: search-notes.sh "pattern" | summarize-notes.sh
+#
+# Expected input format:
+#   Line 1: Header (e.g., "PATH | TITLE")
+#   Line 2+: Data rows (e.g., ".notes/foo.md | My Note")
+#   If only header exists (no data rows), means no notes found
+#
+# Adds SUMMARY column with fast AI-generated summaries (parallel processing)
+
+# Model and prompt
+MODEL="groq:meta-llama/llama-4-scout-17b-16e-instruct"
+PROMPT="summarize this file in two sentences, only output summary"
+
+# Check if 'parallel' is available
+if ! command -v parallel &> /dev/null; then
+  echo "Error: GNU parallel not installed. Install with: sudo pacman -S parallel" >&2
+  exit 1
+fi
+
+# Check if 'aichat' command is available
+if ! command -v aichat &> /dev/null; then
+  echo "Error: 'aichat' command not found. Make sure it's installed and in PATH." >&2
+  exit 1
+fi
+
+# Process a single line
+process_line() {
+  local line="$1"
+  local line_number="$2"
+  # Use exported MODEL and PROMPT environment variables
+
+  # First line is always the header - append SUMMARY column
+  if [ "$line_number" -eq 1 ]; then
+    echo "$line | SUMMARY"
+    return
+  fi
+
+  # Extract path (everything before first |)
+  local path="${line%%|*}"
+  # Trim whitespace (bash parameter expansion)
+  path="${path#"${path%%[![:space:]]*}"}"
+  path="${path%"${path##*[![:space:]]}"}"
+
+  # Skip if file doesn't exist
+  if [ ! -f "$path" ]; then
+    return # Skip failed files silently
+  fi
+
+  # Get summary (pass prompt as separate words, not quoted)
+  local summary
+  summary=$(aichat --model "$MODEL" -f "$path" $PROMPT 2>/dev/null || echo "")
+
+  # Skip if summary failed
+  if [ -z "$summary" ]; then
+    return
+  fi
+
+  # Collapse multiline to single line (replace newlines with spaces, collapse multiple spaces)
+  summary=$(echo "$summary" | tr '\n' ' ' | sed 's/  */ /g')
+  # Trim whitespace (bash parameter expansion)
+  summary="${summary#"${summary%%[![:space:]]*}"}"
+  summary="${summary%"${summary##*[![:space:]]}"}"
+
+  # Append summary
+  echo "$line | $summary"
+}
+
+export -f process_line
+export MODEL PROMPT
+
+# Read stdin, number lines, and process in parallel (16 jobs)
+cat -n | parallel -j 16 --keep-order --colsep '\t' process_line {2} {1}

.claude/skills/_shared/notes/summarize-notes.sh

@@ -0,0 +1,3 @@
+## Available Topics
+
+!`./.claude/skills/_shared/notes/list-topics.sh`

.claude/skills/_shared/notes/topics.md

@@ -0,0 +1,55 @@
+---
+name: note-capture
+description: Save conversation context to topic notes. Use when user says "capture note [about X]", "save to notes", "create note [in topic]", "note this [for topic]", "add note to [topic]". IMPORTANT - User must say "note" or "notes" explicitly.
+allowed-tools: Write, Bash, AskUserQuestion
+---
+
+# Note Capture
+
+Save conversation context to `.notes/[topic]/WIP-[name].md`
+
+@../_shared/notes/topics.md
+
+<critical>
+- ALWAYS use AskUserQuestion for topic selection
+- User MUST say "note" or "notes" (not just "save this")
+</critical>
+
+## Workflow
+
+**1. Determine topic:**
+
+If user specified topic explicitly → use it
+
+Otherwise use AskUserQuestion to select from available topics above.
+
+**2. Create file:**
+- Filename: `WIP-[descriptive-name].md` (kebab-case)
+- Location: `.notes/[topic]/WIP-[name].md`
+- Format: H1 title on first line
+
+**3. Confirm:**
+- Tell user where saved
+- Suggest `notes-sync` skill to commit
+
+## File Format
+
+```markdown
+# [Descriptive title]
+
+[Content from conversation]
+```
+
+H1 can be informal: questions, TODOs, context notes.
+
+## Examples
+
+**With explicit topic:**
+- "capture note about deployment in pgflow-demo"
+- "add note to ci-optimization about parallel jobs"
+
+**Inferred topic:**
+- "capture note about this CI discussion" → Ask: which topic?
+- "note this for later" → Ask: which topic + what to capture?
+
+@../_shared/notes/notes-layout.md