From e6d5615becf05be537245a0fd6414f8e89356c43 Mon Sep 17 00:00:00 2001 From: Wojtek Majewski Date: Sun, 16 Nov 2025 11:00:05 +0100 Subject: [PATCH] chore: extract .claude to separate repo --- .claude/.gitkeep | 0 .claude/agents/researcher.md | 41 -- .claude/commands/audit-doc.md | 183 -------- .claude/commands/audit-note.md | 60 --- .claude/commands/create-changeset.md | 99 ----- .claude/commands/create-doc.md | 168 ------- .claude/commands/create-news-article.md | 305 ------------- .claude/commands/create-note.md | 39 -- .claude/commands/edit-doc.md | 224 ---------- .claude/commands/find-notes.md | 47 -- .claude/commands/fix-doc-style.md | 103 ----- .claude/commands/fix-sql-tests.md | 17 - .claude/commands/help-review.md | 9 - .claude/commands/move-doc.md | 221 ---------- .claude/commands/rate.md | 71 --- .claude/commands/read-note.md | 23 - .claude/commands/research.md | 8 - .claude/commands/simplify-doc.md | 169 ------- .claude/commands/split-doc.md | 393 ----------------- .claude/commands/test-first-sql.md | 40 -- .claude/commands/update-note.md | 45 -- .claude/commands/wt-branch.md | 89 ---- .claude/core/build_test_commands.md | 12 - .claude/core/character_guidelines.md | 10 - .claude/core/code_style.md | 11 - .claude/core/codebase.md | 60 --- .claude/core/diataxis.md | 22 - .claude/core/finding_answers.md | 164 ------- .claude/core/mvp_status.md | 12 - .claude/core/naming_convention.md | 12 - .claude/core/packages.md | 9 - .claude/core/testing_guidelines.md | 3 - .../external-contributor-pr-takeover.md | 268 ------------ .claude/guides/writing-good-claude-skills.md | 316 ------------- .claude/reference/tool_examples.md | 290 ------------ .claude/reference/tool_usage_tests.md | 254 ----------- .claude/settings.json | 95 ---- .../skills/_shared/notes/echo-notes-dir.sh | 44 -- .claude/skills/_shared/notes/list-titles.sh | 140 ------ .claude/skills/_shared/notes/list-topics.sh | 36 -- .claude/skills/_shared/notes/notes-layout.md | 41 -- .claude/skills/_shared/notes/search-notes.sh | 57 --- .../skills/_shared/notes/summarize-notes.sh | 77 ---- .claude/skills/_shared/notes/topics.md | 3 - .claude/skills/migration-management/SKILL.md | 237 ---------- .claude/skills/note-capture/SKILL.md | 55 --- .claude/skills/note-find/SKILL.md | 78 ---- .claude/skills/note-list/SKILL.md | 43 -- .claude/skills/note-organize/SKILL.md | 66 --- .claude/skills/note-overview/SKILL.md | 82 ---- .claude/skills/note-refine/SKILL.md | 91 ---- .claude/skills/note-review/SKILL.md | 239 ---------- .claude/skills/notes-sync/SKILL.md | 46 -- .claude/skills/pgtap-testing/SKILL.md | 282 ------------ .claude/skills/pgtap-testing/helpers.md | 289 ------------ .claude/skills/restack/SKILL.md | 67 --- .claude/skills/restack/complex-conflict.md | 80 ---- .claude/skills/restack/lockfile-conflict.md | 43 -- .claude/skills/restack/troubleshooting.md | 37 -- .claude/skills/schema-dev/SKILL.md | 175 -------- .claude/skills/schema-dev/sql_style.md | 67 --- .claude/skills/unblock/SKILL.md | 99 ----- .claude/skills/unblock/patterns.md | 19 - .claude/skills/unblock/prescriptions.md | 45 -- .gitignore | 5 + CLAUDE.md | 86 ---- pkgs/cli/CLAUDE.md | 68 --- pkgs/client/CLAUDE.md | 59 --- pkgs/edge-worker/CLAUDE.md | 152 ------- pkgs/website/CLAUDE.md | 414 ------------------ 70 files changed, 5 insertions(+), 7209 deletions(-) create mode 100644 .claude/.gitkeep delete mode 100644 .claude/agents/researcher.md delete mode 100644 .claude/commands/audit-doc.md delete mode 100644 .claude/commands/audit-note.md delete mode 100644 .claude/commands/create-changeset.md delete mode 100644 .claude/commands/create-doc.md delete mode 100644 .claude/commands/create-news-article.md delete mode 100644 .claude/commands/create-note.md delete mode 100644 .claude/commands/edit-doc.md delete mode 100644 .claude/commands/find-notes.md delete mode 100644 .claude/commands/fix-doc-style.md delete mode 100644 .claude/commands/fix-sql-tests.md delete mode 100644 .claude/commands/help-review.md delete mode 100644 .claude/commands/move-doc.md delete mode 100644 .claude/commands/rate.md delete mode 100644 .claude/commands/read-note.md delete mode 100644 .claude/commands/research.md delete mode 100644 .claude/commands/simplify-doc.md delete mode 100644 .claude/commands/split-doc.md delete mode 100644 .claude/commands/test-first-sql.md delete mode 100644 .claude/commands/update-note.md delete mode 100644 .claude/commands/wt-branch.md delete mode 100644 .claude/core/build_test_commands.md delete mode 100644 .claude/core/character_guidelines.md delete mode 100644 .claude/core/code_style.md delete mode 100644 .claude/core/codebase.md delete mode 100644 .claude/core/diataxis.md delete mode 100644 .claude/core/finding_answers.md delete mode 100644 .claude/core/mvp_status.md delete mode 100644 .claude/core/naming_convention.md delete mode 100644 .claude/core/packages.md delete mode 100644 .claude/core/testing_guidelines.md delete mode 100644 .claude/guides/external-contributor-pr-takeover.md delete mode 100644 .claude/guides/writing-good-claude-skills.md delete mode 100644 .claude/reference/tool_examples.md delete mode 100644 .claude/reference/tool_usage_tests.md delete mode 100644 .claude/settings.json delete mode 100755 .claude/skills/_shared/notes/echo-notes-dir.sh delete mode 100755 .claude/skills/_shared/notes/list-titles.sh delete mode 100755 .claude/skills/_shared/notes/list-topics.sh delete mode 100644 .claude/skills/_shared/notes/notes-layout.md delete mode 100755 .claude/skills/_shared/notes/search-notes.sh delete mode 100755 .claude/skills/_shared/notes/summarize-notes.sh delete mode 100644 .claude/skills/_shared/notes/topics.md delete mode 100644 .claude/skills/migration-management/SKILL.md delete mode 100644 .claude/skills/note-capture/SKILL.md delete mode 100644 .claude/skills/note-find/SKILL.md delete mode 100644 .claude/skills/note-list/SKILL.md delete mode 100644 .claude/skills/note-organize/SKILL.md delete mode 100644 .claude/skills/note-overview/SKILL.md delete mode 100644 .claude/skills/note-refine/SKILL.md delete mode 100644 .claude/skills/note-review/SKILL.md delete mode 100644 .claude/skills/notes-sync/SKILL.md delete mode 100644 .claude/skills/pgtap-testing/SKILL.md delete mode 100644 .claude/skills/pgtap-testing/helpers.md delete mode 100644 .claude/skills/restack/SKILL.md delete mode 100644 .claude/skills/restack/complex-conflict.md delete mode 100644 .claude/skills/restack/lockfile-conflict.md delete mode 100644 .claude/skills/restack/troubleshooting.md delete mode 100644 .claude/skills/schema-dev/SKILL.md delete mode 100644 .claude/skills/schema-dev/sql_style.md delete mode 100644 .claude/skills/unblock/SKILL.md delete mode 100644 .claude/skills/unblock/patterns.md delete mode 100644 .claude/skills/unblock/prescriptions.md delete mode 100644 CLAUDE.md delete mode 100644 pkgs/cli/CLAUDE.md delete mode 100644 pkgs/client/CLAUDE.md delete mode 100644 pkgs/edge-worker/CLAUDE.md delete mode 100644 pkgs/website/CLAUDE.md diff --git a/.claude/.gitkeep b/.claude/.gitkeep new file mode 100644 index 000000000..e69de29bb diff --git a/.claude/agents/researcher.md b/.claude/agents/researcher.md deleted file mode 100644 index 4ec3614a0..000000000 --- a/.claude/agents/researcher.md +++ /dev/null @@ -1,41 +0,0 @@ ---- -name: researcher -description: Deep research specialist that synthesizes information from multiple sources -tools: mcp__perplexity__perplexity_search, mcp__perplexity__perplexity_ask, mcp__crawl4ai-sse__md, mcp__context7__resolve-library-id, mcp__context7__get-library-docs -model: sonnet ---- - -You are a research specialist focused on finding comprehensive, accurate information by consulting multiple sources. - -## Research Process - -1. **Search Phase**: Use perplexity_search (max_results: 5, max_tokens_per_page: 1024) to find relevant sources -2. **Deep Dive**: Use crawl4ai to read promising URLs and perplexity_ask for specific questions -3. **Library Docs**: For library/framework questions, use context7 tools first -4. **Synthesis**: Compare sources, identify consensus and conflicts - -## Output Format - -### Sources Review -List each source with: -- Source type (Perplexity search result, crawled URL, Context7 docs, etc.) -- Key findings -- Reliability assessment - -### Source Comparison -- Points of agreement across sources -- Conflicting information -- Gaps in coverage - -### Final Answer -Provide a definitive, synthesized answer based on all sources. - -### Confidence Score -Rate 1-10 based on: -- 9-10: Strong consensus across authoritative sources -- 7-8: Good agreement with minor variations -- 5-6: Mixed information, moderate confidence -- 3-4: Conflicting sources, low confidence -- 1-2: Insufficient or contradictory information - -Be thorough but concise. Focus on accuracy over speed. diff --git a/.claude/commands/audit-doc.md b/.claude/commands/audit-doc.md deleted file mode 100644 index 70c79f49d..000000000 --- a/.claude/commands/audit-doc.md +++ /dev/null @@ -1,183 +0,0 @@ ---- -allowed-tools: Read, Grep, Bash(ls:*), Bash(tree:*), Bash(wc -l:*) -description: Audit documentation files for compliance with pgflow guidelines and Diataxis -argument-hint: ---- - -You are tasked with auditing documentation for compliance with pgflow guidelines, Diataxis framework, and identifying quality issues. - -## Context - -Documentation root: `pkgs/website/src/content/docs/` - -User request: - -$ARGUMENTS - - -## Multi-Step Process - -### Step 1: Validate Target - -**Target must be a single .mdx file path.** - -If no argument or directory provided: -- Search for matching files using Grep/tree -- Present options to user -- WAIT for confirmation - -If path provided, verify file exists: -```bash -ls -la pkgs/website/src/content/docs/[file-path] -``` - -Present target: -```markdown -## Audit Target - -**File:** pkgs/website/src/content/docs/[path] -**Lines:** [count] -``` - -WAIT for user confirmation. - -### Step 2: Read Guide Files - -Read all guide files to understand standards: - -```bash -# Read guides in parallel -``` - -Files to read: -1. `NOMENCLATURE_GUIDE.md` - Terminology standards -2. `ARCHITECTURE_GUIDE.md` - Architecture concepts -3. `DOCS_GUIDE.md` - Documentation standards -4. `.claude/core/character_guidelines.md` - Character rules -5. `.claude/core/diataxis.md` - Content type definitions -6. `.claude/core/naming_convention.md` - Naming rules - -### Step 3: Read Target File - -Read the target documentation file completely. - -### Step 4: Analyze Against Standards - -**BE PRAGMATIC**: Only flag issues that significantly impact readers or correctness. Don't be nitpicky about things that mostly work. - -**Critical Issues - Must fix:** -- Broken links (internal/external) -- Wrong/broken code examples -- Incorrect architecture/terminology -- Character violations (curly quotes, em-dashes, etc.) -- Incorrect naming (pgFlow, PgFlow, etc.) - -**Important Issues - Should fix:** -- Missing trailing slashes on internal links -- Missing or incorrect frontmatter -- Wrong H1 usage (multiple H1s in content) -- Significantly unclear explanations - -**Only if valuable to readers:** -- Suggest Diataxis improvements ONLY if doc is clearly misclassified -- Suggest reorganization ONLY if current structure causes confusion -- Suggest cross-references ONLY if missing links hurt understanding - -**DO NOT flag:** -- Minor style inconsistencies -- Content type mixing if it serves users (brief install in how-to is fine) -- Small docs (<400 lines) -- Missing "What You'll Learn" sections -- Platform notes when only one platform exists - -### Step 5: Generate Report - -Create a structured report with specific examples: - -```markdown -# Audit Report: [filename] - -**Location:** pkgs/website/src/content/docs/[path] -**Type:** [Tutorial/How-to/Explanation/Reference] -**Lines:** [count] - -## Critical Issues - -[If none: "None found"] -[If found: List with line numbers and examples] - -1. [Issue] (line [X]) - - Found: `[actual text]` - - Fix: `[suggested text]` - -2. [Issue] (lines [X-Y]) - - Problem: [description] - - Suggestion: [fix] - -## Important Issues - -[Similar format] - -## Suggestions - -[Only significant improvements that add real value] - -## Summary - -**Assessment:** [Excellent/Good/Needs Work/Major Issues] -**Critical:** [count] | **Important:** [count] | **Suggestions:** [count] -**Estimated fix time:** [5min/15min/30min/1hr] - -**Next steps:** -1. [Most important fix] -2. [Second priority] -3. [Third priority if any] -``` - -### Step 6: Present Findings - -Show the report to the user with actionable next steps: - -```markdown -## Audit Complete - -[Show the report] - -**Next steps:** -- Fix critical issues first -- You can say "fix issue 1 and 3" to address specific items -- Run `/audit-doc [file]` again after fixes to verify -``` - -## Common Issues Reference - -**Critical (always fix):** -- `pgFlow`/`PgFlow` → `pgflow` -- `/path/to/doc` → `/path/to/doc/` (trailing slash) -- Curly quotes "" → Straight quotes "" -- Em-dash — → Hyphen - -- Broken code examples - -**Important (fix if found):** -- Multiple H1s → Only one H1 in frontmatter title -- Missing `draft: false` in frontmatter -- Code blocks without language -- Relative links `../other` → Absolute `/other/` - -**Suggestions (only if valuable):** -- Missing cross-references that would help understanding -- Structure issues causing real confusion -- Diataxis misclassification (e.g., tutorial written as reference) - -## Error Handling - -- **File not found:** Ask user to verify path -- **Not .mdx file:** Only audit .mdx files -- **Too large (>1000 lines):** Warn and suggest splitting first - -## Special Cases - -- **index.mdx:** Check for proper overview structure -- **Tutorial:** Verify step-by-step progression -- **Reference:** Check completeness and accuracy -- **How-to:** Verify problem-solving focus diff --git a/.claude/commands/audit-note.md b/.claude/commands/audit-note.md deleted file mode 100644 index 6130fa3df..000000000 --- a/.claude/commands/audit-note.md +++ /dev/null @@ -1,60 +0,0 @@ -You are tasked with auditing a single note file from "notes" folder. -The folder path is: !`realpath $notes` - -Available files: - - -!`ls $notes/` - - -You must find the file that most closely matches this user query: "$ARGUMENTS". - -If there are multiple files matching, present user with a/b/c choice and wait for confirmation. -If you are certain there is only one file that strongly matches, proceed with audit. - -## Two-Phase Audit Process - -### Phase 1: Quick Heuristics (try this first) - -1. Read the note file -2. Extract key terms, features, file paths, or function names mentioned -3. Run simple checks: - - Grep for key terms in the codebase - - Glob for mentioned file paths - - Check if described features/patterns exist -4. Based on results, determine: - - **IMPLEMENTED** - Key terms/files/patterns found in codebase - - **INVALID** - Note contradicts current code or mentions non-existent paths - - **UNCLEAR** - Heuristics inconclusive, need deeper analysis - -### Phase 2: Deep Audit (only if Phase 1 returns UNCLEAR) - -If heuristics fail, spawn a Task agent with this prompt: - -``` -Read {filepath} and deeply analyze against the codebase. - -Determine if the note is: -- IMPLEMENTED: Feature/plan already exists in code -- INVALID: Outdated, contradicts current implementation, or not applicable -- VALID: Still relevant and could be worked on - -Return: -STATUS: [IMPLEMENTED|INVALID|VALID] -EXPLANATION: [1-2 sentences why] -``` - -## Output Format - -Present results clearly: - -``` -# Audit: {filename} - -Status: [IMPLEMENTED|INVALID|VALID|UNCLEAR] - -Explanation: [Brief explanation based on findings] - -[If heuristics were used, show what was searched/found] -[If deep audit was needed, show agent's analysis] -``` diff --git a/.claude/commands/create-changeset.md b/.claude/commands/create-changeset.md deleted file mode 100644 index 95e16743d..000000000 --- a/.claude/commands/create-changeset.md +++ /dev/null @@ -1,99 +0,0 @@ -You are tasked with creating a changeset file for the pgflow monorepo. - -## Context - -User description: - -$ARGUMENTS - - -## Available Packages - -- pgflow -- @pgflow/client -- @pgflow/core -- @pgflow/dsl -- @pgflow/edge-worker -- @pgflow/example-flows -- @pgflow/website - -## Versioning Scheme (Pre-1.0) - -- **patch** (0.5.1 → 0.5.2): Bug fixes and small backward-compatible features -- **minor** (0.5.0 → 0.6.0): Breaking changes and major updates - -## Process - -### Step 1: Detect Repo State and Analyze Changes - -First, check if the repository is clean or dirty: - - -!`git status --short` - - -Based on the repo status above, run the appropriate git commands: - -**If repo is CLEAN (no output above):** -- Run `git log -1 --pretty=format:'%s'` to get the commit message -- Run `git show HEAD --stat --pretty=format:''` to see changed files in HEAD - -**If repo is DIRTY (has output above):** -- Run `git diff HEAD --stat` to see all staged and unstaged changes - -Map changed files to affected packages based on the `pkgs/` directory structure: -- `pkgs/cli/` → pgflow -- `pkgs/client/` → @pgflow/client -- `pkgs/core/` → @pgflow/core -- `pkgs/dsl/` → @pgflow/dsl -- `pkgs/edge-worker/` → @pgflow/edge-worker -- `pkgs/example-flows/` → @pgflow/example-flows -- `pkgs/website/` → @pgflow/website - -**IMPORTANT**: Only changes in `pkgs/` directories should trigger changeset creation. Root file changes should be ignored. - -### Step 2: Determine Bump Type - -Based on the changes and user description, determine if this is: -- **patch**: Bug fix or small backward-compatible improvement -- **minor**: Breaking change or major update - -Present your analysis to the user and ask for confirmation of the bump type. - -### Step 3: Generate Filename - -Create a unique 3-word slug for the filename using: -- Simple, descriptive words related to the change -- Lowercase with hyphens -- Example: `tame-shoes-yell.md`, `brave-lions-run.md` - -### Step 4: Create Changeset - -Write the changeset file to `.changeset/.md` with this format: - -``` ---- -'': -'': ---- - - -``` - -**Requirements:** -- List all affected packages in the frontmatter -- Use single quotes around package names -- Keep description concise (1-2 lines) -- No fancy characters (straight quotes, hyphens only) - -## Example - -For a bug fix in @pgflow/client: - -``` ---- -'@pgflow/client': patch ---- - -Fix connection timeout handling in worker pool -``` diff --git a/.claude/commands/create-doc.md b/.claude/commands/create-doc.md deleted file mode 100644 index e7b3221b6..000000000 --- a/.claude/commands/create-doc.md +++ /dev/null @@ -1,168 +0,0 @@ -You are tasked with creating new documentation following pgflow's guidelines, Diataxis framework, and style conventions. - -## Context - -Project documentation location: `pkgs/website/src/content/docs/` - -Current directory structure: - -!`tree pkgs/website/src/content/docs/ -L 2 -d` - - -User request: - -$ARGUMENTS - - -## Process - -### Step 1: Determine Content Type (Diataxis) - -Analyze the user's request and determine which Diataxis category this document belongs to: - -**TUTORIALS** (Learning-oriented) - get-started/, tutorials/ -- First-time learning experience -- Step-by-step with expected outcomes -- Complete working examples -- "Create your first X" - -**HOW-TO GUIDES** (Problem-oriented) - develop/, operate/ -- Solving specific problems -- Assumes basic knowledge -- Practical, real-world scenarios -- "How to do X" - -**EXPLANATIONS** (Understanding-oriented) - concepts/, comparisons/ -- Building mental models -- Why and how it works -- Design decisions and tradeoffs -- No step-by-step instructions - -**REFERENCE** (Information-oriented) - reference/ -- Dry, factual specifications -- API signatures, options, types -- Tables and lists -- No explanations or examples - -Present your analysis to the user: -``` -Content Type: [CATEGORY] -Reasoning: [Why this category] -Suggested Location: pkgs/website/src/content/docs/[path]/[filename].mdx -``` - -**WAIT for user confirmation or correction.** - -### Step 2: Preview Document Structure - -Based on the confirmed content type, show the user which template structure will be used: - -**For TUTORIALS:** -```markdown -- Frontmatter with title/description -- Brief introduction (1-2 sentences) -- Prerequisites in :::caution block -- Sequential steps using component -- Code examples with frame="none" for bash -- Next Steps section with LinkCards -``` - -**For HOW-TO GUIDES:** -```markdown -- Frontmatter with title/description -- Problem statement opening -- Direct solution sections -- Multiple pattern examples -- Learn More section with LinkCards -``` - -**For EXPLANATIONS:** -```markdown -- Frontmatter with title/description -- Conceptual overview -- Progressive narrative (simple → complex) -- Mental models and "why" sections -- Cross-references to related concepts -``` - -**For REFERENCE:** -```markdown -- Frontmatter with title/description -- Minimal introduction -- Tables for parameters/options -- Type definitions -- Terse descriptions (no elaboration) -``` - -Present structure overview and confirm with user before proceeding. - -### Step 3: Create Document with Task Agent - -**Launch a general-purpose task agent to create the document.** - -Present the task summary to the user before launching: - -```markdown -## Task Agent Instructions - -I'm launching a task agent to create the documentation with these instructions: - -**Context:** -- Content type: [TUTORIAL/HOW-TO/EXPLANATION/REFERENCE] -- File location: pkgs/website/src/content/docs/[path]/[filename].mdx -- User request: [original request] - -**Agent will:** -1. Read NOMENCLATURE_GUIDE.md for terminology standards -2. Read ARCHITECTURE_GUIDE.md for architectural accuracy -3. Read DOCS_GUIDE.md for all formatting, style, and component patterns -4. Create complete document following the [content type] template -5. Apply all style guidelines (characters, naming, voice, links) -6. Ensure Diataxis compliance for [content type] -7. Use appropriate components (:::note syntax, LinkCards, Steps, etc.) -8. Present draft for review - -**Critical requirements:** -- Follow DOCS_GUIDE.md patterns exactly -- Use :::note[Title] syntax (not