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