diff --git a/.claude/.gitignore b/.claude/.gitignore index d9e7211..9011ab2 100644 --- a/.claude/.gitignore +++ b/.claude/.gitignore @@ -1,32 +1,25 @@ -# macOS -.DS_Store - +# Build artifacts # Editor/IDE -*.swp -*.local.json - +# Logs +# Node.js (for testing/examples) # Python (for testing/examples) +# Temporary files +# macOS +*.local.json +*.log *.pyc -__pycache__/ +*.swp +*.temp +*.tmp +.DS_Store +.created-prompts/ +.pnpm-store/ .pytest_cache/ -.venv/ .ruff_cache/ - -# Node.js (for testing/examples) -node_modules/ -.pnpm-store/ - -# Build artifacts +.venv/ +__pycache__/ bin/ -lib/ -dist/ build/ - -# Logs -*.log - -# Temporary files -*.tmp -*.temp - -.created-prompts/ +dist/ +lib/ +node_modules/ diff --git a/.claude/commands/ai-coding-config.md b/.claude/commands/ai-coding-config.md index 66619f9..99d1e20 100644 --- a/.claude/commands/ai-coding-config.md +++ b/.claude/commands/ai-coding-config.md @@ -5,7 +5,9 @@ argument-hint: [update | add] # AI Coding Configuration -Manages reusable AI configurations across machines and projects. The system lives in `~/.ai_coding_config` and contains Cursor rules, Claude commands, agents, skills, personalities, and GitHub workflows. +Manages reusable AI configurations across machines and projects. The system lives in +`~/.ai_coding_config` and contains Cursor rules, Claude commands, agents, skills, +personalities, and GitHub workflows. ## Usage @@ -15,7 +17,10 @@ Manages reusable AI configurations across machines and projects. The system live ## Interaction Guidelines -Use AskUserQuestion when presenting discrete choices that save the user time (selecting a personality, choosing update strategy, handling file conflicts). This lets users quickly click options while still allowing free-form text via "Other". Only use when it genuinely speeds up the interaction. +Use AskUserQuestion when presenting discrete choices that save the user time (selecting +a personality, choosing update strategy, handling file conflicts). This lets users +quickly click options while still allowing free-form text via "Other". Only use when it +genuinely speeds up the interaction. --- @@ -34,11 +39,13 @@ Detect project type and framework specifics. Django differs from FastAPI. React Show available configurations that match this project. Group by relevance - framework-specific first, then universal. For each option, read description from frontmatter to explain what it does. Available configurations: + - Rules (`.cursor/rules/` subdirectories and files) - Personalities (one or none, common-personality always included) - Agents (specialized AI assistants, default to all) - Skills (modular packages, default to all) -- Commands (always copy all, create in `.claude/commands/` with symlinks in `.cursor/commands/`) +- Commands (always copy all, create in `.claude/commands/` with symlinks in + `.cursor/commands/`) - Standard configs (VSCode settings, Prettier, GitHub workflows) Use AskUserQuestion to present personality options as quick-select. @@ -47,32 +54,37 @@ Use AskUserQuestion to present personality options as quick-select. Copy selected configurations intelligently, respecting existing customizations. Compare files with diff when they exist. For conflicts, use AskUserQuestion to offer choices (overwrite, skip, show diff, or custom action). Never silently overwrite. -Installation mapping: Rules → `.cursor/rules/` (preserve subdirectory structure), Commands → `.claude/commands/` with symlinks in `.cursor/commands/`, Context → `.claude/context.md`, Agents → `.claude/agents/`, Skills → `.skills/` (entire directories), Personalities → `.cursor/rules/personalities/` (common always, additional with `alwaysApply: true`), VSCode → `.vscode/`, Prettier → `.prettierrc`, GitHub workflows → `.github/workflows/`, Gitignore → `.cursor/.gitignore` and `.claude/.gitignore`. +Installation mapping: Rules → `.cursor/rules/` (preserve subdirectory structure), +Commands → `.claude/commands/` with symlinks in `.cursor/commands/`, Context → +`.claude/context.md`, Agents → `.claude/agents/`, Skills → `.skills/` (entire +directories), Personalities → `.cursor/rules/personalities/` (common always, additional +with `alwaysApply: true`), VSCode → `.vscode/`, Prettier → `.prettierrc`, GitHub +workflows → `.github/workflows/`, Gitignore → `.cursor/.gitignore` and +`.claude/.gitignore`. -Report what was copied, skipped, and how conflicts were handled. - +Report what was copied, skipped, and how conflicts were handled. Confirm files are in expected locations. List installed rules (framework-specific, then universal), commands, agents, skills. Confirm symlinks point correctly. Verify personality selection and `alwaysApply` setting. Confirm VSCode settings, Prettier config, GitHub workflows, and gitignore files. -Provide clear summary without deep validation. - +Provide clear summary without deep validation. After successful installation, provide actionable next steps. Always recommend: + 1. Generate AGENTS.md if missing at project root (run /generate-AGENTS-file) -2. List available commands (/load-cursor-rules, /personality-change, /create-prompt, /troubleshoot, /setup-environment, /handoff-context, /product-intel) +2. List available commands (/load-cursor-rules, /personality-change, /create-prompt, + /troubleshoot, /setup-environment, /handoff-context, /product-intel) Conditional recommendations: + - Git worktrees → suggest /setup-environment - Error monitoring detected → mention /troubleshoot - Competitive product → suggest /product-intel -Show only genuinely useful recommendations. - - +Show only genuinely useful recommendations. --- @@ -90,11 +102,12 @@ Compare this command file with repo version. If repo version is newer or differe Use diff to compare each config file. Categorize changes as trivial (typos, comments) or significant. List files in repo but not in project. List files in project but not in repo (possible local customizations). -Explain what changed and why updates matter. Use AskUserQuestion for update strategy: "Update all", "Update none", "Pick individually", or custom instructions. Handle customized files carefully. +Explain what changed and why updates matter. Use AskUserQuestion for update strategy: +"Update all", "Update none", "Pick individually", or custom instructions. Handle +customized files carefully. Copy selected files. Never silently overwrite. Verify and highlight changes. - - + --- @@ -112,42 +125,50 @@ Fetch latest Claude Code documentation for the mechanism you're implementing (co Decision framework: -Trigger: User manually → Command, Claude autonomously → Skill, Claude delegates focused work → Agent, Bundling multiple mechanisms → Plugin +Trigger: User manually → Command, Claude autonomously → Skill, Claude delegates focused +work → Agent, Bundling multiple mechanisms → Plugin Context: Needs isolation → Agent, Uses main conversation → Command or Skill -Compatibility: Commands work in both Claude Code and Cursor, Skills are Claude Code only (create companion Command for Cursor if needed), Agents work in Claude Code (Cursor can @ mention paths), Plugins are Claude Code only +Compatibility: Commands work in both Claude Code and Cursor, Skills are Claude Code only +(create companion Command for Cursor if needed), Agents work in Claude Code (Cursor can +@ mention paths), Plugins are Claude Code only Clarifying questions: + 1. Who triggers this - user manually or Claude autonomously? 2. Needs isolated context window or uses main conversation? 3. Must work in Cursor or Claude Code only acceptable? -4. Single capability or bundling multiple features? - +4. Single capability or bundling multiple features? Commands: Create `.claude/commands/command-name.md` with frontmatter including description. -Skills: Create `.claude/skills/skill-name/SKILL.md` with frontmatter (name, description). Description is critical - Claude uses it to decide when to activate. Add supporting files as needed. Create companion Command for Cursor if needed. +Skills: Create `.claude/skills/skill-name/SKILL.md` with frontmatter (name, +description). Description is critical - Claude uses it to decide when to activate. Add +supporting files as needed. Create companion Command for Cursor if needed. -Agents: Determine plugin location (or create new plugin). Create `plugins/plugin-name/agents/agent-name.md` with frontmatter (name, description, tools, model). Agents live in plugins. +Agents: Determine plugin location (or create new plugin). Create +`plugins/plugin-name/agents/agent-name.md` with frontmatter (name, description, tools, +model). Agents live in plugins. -Plugins: Create `plugins/plugin-name/` directory structure with `.claude-plugin/plugin.json` manifest. Bundle commands (via symlinks), skills, agents, hooks, MCP servers. Add README.md. Update `.claude-plugin/marketplace.json`. +Plugins: Create `plugins/plugin-name/` directory structure with +`.claude-plugin/plugin.json` manifest. Bundle commands (via symlinks), skills, agents, +hooks, MCP servers. Add README.md. Update `.claude-plugin/marketplace.json`. Verify files are in correct locations, frontmatter includes required fields, skill descriptions clearly define activation criteria, commands work when invoked, plugins are properly structured. -Explain what was created and how to test it. - - +Explain what was created and how to test it. --- Work conversationally, not robotically. Focus on outcomes. Determine best approach for each situation. Show file paths when copying. Let users make all choices. Verify everything works before finishing. -Respect existing files - always check before overwriting. Use diff to understand differences, then decide intelligently or ask. Better to be thoughtful than fast. +Respect existing files - always check before overwriting. Use diff to understand +differences, then decide intelligently or ask. Better to be thoughtful than fast. -Explain choices helpfully. Don't just list files - explain what they do and why someone might want them. - +Explain choices helpfully. Don't just list files - explain what they do and why someone +might want them. diff --git a/.claude/commands/autotask.md b/.claude/commands/autotask.md index ec0ff93..8b7ebe9 100644 --- a/.claude/commands/autotask.md +++ b/.claude/commands/autotask.md @@ -38,36 +38,48 @@ Create isolated development environment using /setup-environment. The command au Implement the solution following project patterns and standards. Available agents: -- Dixon (.claude/agents/dev-agents/debugger.md): Root cause analysis, reproduces issues, identifies underlying problems -- Ada (.claude/agents/dev-agents/autonomous-developer.md): Implementation work, writes tests -- Phil (.claude/agents/dev-agents/ux-designer.md): Reviews user-facing text, validates accessibility, ensures UX consistency -- Rivera (.claude/agents/code-review/code-reviewer.md): Architecture review, validates design patterns, checks security -- Petra (.claude/agents/dev-agents/prompt-engineer.md): Prompt optimization and refinement +- Dixon (.claude/agents/dev-agents/debugger.md): Root cause analysis, reproduces issues, + identifies underlying problems +- Ada (.claude/agents/dev-agents/autonomous-developer.md): Implementation work, writes + tests +- Phil (.claude/agents/dev-agents/ux-designer.md): Reviews user-facing text, validates + accessibility, ensures UX consistency +- Rivera (.claude/agents/code-review/code-reviewer.md): Architecture review, validates + design patterns, checks security +- Petra (.claude/agents/dev-agents/prompt-engineer.md): Prompt optimization and + refinement - Explore (general-purpose): Investigation, research, evaluates trade-offs -Build an execution plan based on task type. Use /load-cursor-rules to load relevant project standards. Execute agents in parallel when possible, sequentially when they depend on each other. +Build an execution plan based on task type. Use /load-cursor-rules to load relevant +project standards. Execute agents in parallel when possible, sequentially when they +depend on each other. -Provide targeted context when launching agents: task requirements, implementation decisions, relevant standards, and specific focus area. Tailor context to agent type. +Provide targeted context when launching agents: task requirements, implementation +decisions, relevant standards, and specific focus area. Tailor context to agent type. -Maintain context throughout the workflow. Decisions and clarifications from earlier phases inform later ones. - +Maintain context throughout the workflow. Decisions and clarifications from earlier +phases inform later ones. Pause only for deal-killers: security risks, data loss potential, or fundamentally unclear requirements. For everything else, make a reasonable choice and document it. -Document design decisions in the PR with rationale and alternatives considered. The executing model knows when to ask vs when to decide and document. +Document design decisions in the PR with rationale and alternatives considered. The +executing model knows when to ask vs when to decide and document. Adapt validation intensity to task risk: -Default (trust git hooks): Make changes, commit, let hooks validate, fix only if hooks fail. +Default (trust git hooks): Make changes, commit, let hooks validate, fix only if hooks +fail. -Targeted validation: Run specific tests for changed code, use Rivera for architecture review if patterns change. +Targeted validation: Run specific tests for changed code, use Rivera for architecture +review if patterns change. Full validation: Comprehensive test suite, multiple agent reviews, security scanning. -Principle: Validation intensity should match task risk. Git hooks handle formatting, linting, and tests. Add extra validation only when risk justifies it. +Principle: Validation intensity should match task risk. Git hooks handle formatting, +linting, and tests. Add extra validation only when risk justifies it. @@ -76,54 +88,62 @@ Deliver a well-documented pull request with commits following .cursor/rules/git- PR description must include: Summary: + - What was implemented and why - How it addresses the requirements Design Decisions (if any were made): + - Each significant decision with rationale - Alternatives considered and trade-offs - Why each approach was chosen Obstacles Encountered (if any): + - Challenges faced - How they were resolved or worked around Testing: + - What validation was performed -- Edge cases considered - +- Edge cases considered Autonomously address valuable bot feedback, reject what's not applicable, and deliver a PR ready for human review with all critical issues resolved. -After creating the PR, wait for AI code review bots to complete initial analysis. You have context bots lack: project standards, implementation rationale, trade-offs considered, and user requirements. Evaluate feedback against this context. +After creating the PR, wait for AI code review bots to complete initial analysis. You +have context bots lack: project standards, implementation rationale, trade-offs +considered, and user requirements. Evaluate feedback against this context. -Fix what's valuable (security issues, real bugs, good suggestions). Reject what's not (use WONTFIX with brief explanation for context-missing or incorrect feedback). Trust your judgment on what matters. +Fix what's valuable (security issues, real bugs, good suggestions). Reject what's not +(use WONTFIX with brief explanation for context-missing or incorrect feedback). Trust +your judgment on what matters. -Iterate on bot feedback until critical issues are resolved. - +Iterate on bot feedback until critical issues are resolved. Provide a summary scaled to task complexity: What was accomplished: + - Core functionality delivered - Design decisions made autonomously - Obstacles overcome without user intervention Key highlights: + - Elegant solutions or optimizations - Significant issues found and fixed - Bot feedback addressed -Include the PR URL and worktree location. If design decisions were made autonomously, note they're documented in the PR for review. - +Include the PR URL and worktree location. If design decisions were made autonomously, +note they're documented in the PR for review. Recover gracefully from failures when possible. Capture decision-enabling context: what was attempted, what state preceded the failure, what the error indicates about root cause, and whether you have enough information to fix it autonomously. -Attempt fixes when you can. For issues you can't resolve autonomously, inform the user with clear options and context. - +Attempt fixes when you can. For issues you can't resolve autonomously, inform the user +with clear options and context. ## Key Principles @@ -145,6 +165,7 @@ Attempt fixes when you can. For issues you can't resolve autonomously, inform th ## Configuration The command adapts to your project structure: + - Detects git hooks (husky, pre-commit) - Detects test runners (jest, mocha, vitest, etc.) - Finds linting configs (eslint, prettier, etc.) diff --git a/.claude/commands/create-prompt.md b/.claude/commands/create-prompt.md index 7d228fa..5f93ceb 100644 --- a/.claude/commands/create-prompt.md +++ b/.claude/commands/create-prompt.md @@ -28,10 +28,10 @@ Structure the prompt using XML tags for clarity: Ensure .created-prompts/ directory exists and is in .gitignore. Save with descriptive Title-Case-With-Hyphens name: + - Implement-User-Authentication.md - Fix-Database-Connection-Bug.md -- Add-Dashboard-Analytics.md - +- Add-Dashboard-Analytics.md After saving, offer to execute the prompt immediately using the Task tool (subagent_type: "general-purpose"). diff --git a/.claude/commands/generate-AGENTS-file.md b/.claude/commands/generate-AGENTS-file.md index d4278ed..8bf0cba 100644 --- a/.claude/commands/generate-AGENTS-file.md +++ b/.claude/commands/generate-AGENTS-file.md @@ -1,10 +1,12 @@ --- -description: Generate or update AGENTS.md with essential project context for AI coding assistants +description: + Generate or update AGENTS.md with essential project context for AI coding assistants --- # Generate AGENTS.md -Creates or updates `AGENTS.md` - a universal project context file for AI coding assistants (Claude Code, Cursor, GitHub Copilot, etc.). +Creates or updates `AGENTS.md` - a universal project context file for AI coding +assistants (Claude Code, Cursor, GitHub Copilot, etc.). AGENTS.md should be: @@ -13,8 +15,7 @@ AGENTS.md should be: - Actionable - Specific commands, conventions, and constraints - Valuable - Only include what genuinely improves AI output -Think: "What do I keep repeating to the AI that would prevent mistakes?" - +Think: "What do I keep repeating to the AI that would prevent mistakes?" @@ -31,38 +32,41 @@ Add an "Always Apply Rules" section at the top with @ references: Core project rules that apply to all tasks: -@.cursor/rules/personalities/unity.mdc -@.cursor/rules/git-interaction.mdc +@.cursor/rules/personalities/unity.mdc @.cursor/rules/git-interaction.mdc @.cursor/rules/typescript-coding-standards.mdc ``` Why use @ references instead of extraction: + - AI coding assistants load the full rule when they see `@path/to/rule.mdc` - Ensures rules stay up-to-date without AGENTS.md edits - No token overhead from duplicating rule content - Single source of truth for all conventions When to still extract (rare): + - Only if a rule has a specific command or constraint worth highlighting elsewhere - Don't duplicate - reference in "Always Apply Rules" section instead - + Read these sources for essential project-specific context: From README.md: + - Project tech stack and versions (be specific: "Next.js 14" not just "Next.js") - Key commands (dev, build, test) - Skip: Project description, installation steps for end users, contributing guides From .claude/context.md (if exists): + - Identity or personality instructions (if project uses custom personality) - Any project-specific AI behavior guidelines From recent git commits (last 10): + - Observe commit message style and conventions -- Identify patterns (emoji usage, conventional commits, etc.) - +- Identify patterns (emoji usage, conventional commits, etc.) Create a structured file with these sections (omit sections with no valuable content): @@ -93,9 +97,11 @@ Brief 1-2 sentence description of what this project is. ## Commands -List only project-specific commands. Skip generic commands like `git status` or `npm install`. +List only project-specific commands. Skip generic commands like `git status` or +`npm install`. Good examples: + - `pnpm dev` - Start dev server (use pnpm not npm) - `pytest tests/unit` - Run only unit tests (integration tests are slow) - `/load-cursor-rules` - Load relevant rules for current task @@ -103,11 +109,13 @@ Good examples: ## Code Conventions DO: + - Specific patterns to follow - Required practices unique to this project - Non-obvious constraints that prevent mistakes DON'T: + - Specific anti-patterns to avoid - Project-specific constraints - Explicitly forbidden practices (like --no-verify if that's a rule) @@ -126,6 +134,7 @@ DON'T: - Dependencies between systems - Unique aspects of this project that AI must understand ``` + @@ -138,7 +147,8 @@ After generating content, review and optimize: 5. Cut generic commands: Remove `git status`, `git diff`, basic npm/pip commands 6. Skip emoji lists: One example format is enough, don't list all possible emojis 7. Remove meta-commentary: Cut self-referential notes about token usage or file purpose -8. Question each bullet: Ask "Would removing this cause AI to make a mistake?" If no, cut it. +8. Question each bullet: Ask "Would removing this cause AI to make a mistake?" If no, + cut it. Target: 2-3KB for most projects (500-750 tokens per interaction). 4KB maximum. @@ -150,8 +160,8 @@ Create a symlink from `CLAUDE.md` to `AGENTS.md`: ln -sf AGENTS.md CLAUDE.md ``` -This ensures both filenames work while maintaining a single source of truth without any token overhead. - +This ensures both filenames work while maintaining a single source of truth without any +token overhead. Show the user: @@ -173,17 +183,19 @@ When `AGENTS.md` already exists: 4. Show diff of proposed changes 5. Let user approve before updating -Never silently overwrite - always show what's changing and why. - +Never silently overwrite - always show what's changing and why. Be surgical, not comprehensive: Extract only what AI needs that isn't obvious. Skip generic best practices. -Prioritize always-apply rules: These are gold - they represent project-critical conventions. +Prioritize always-apply rules: These are gold - they represent project-critical +conventions. -Token economics matter: A 10KB file costs 2500 tokens/interaction. Over 100 messages, that's 250K tokens. Be ruthless about value-per-byte. +Token economics matter: A 10KB file costs 2500 tokens/interaction. Over 100 messages, +that's 250K tokens. Be ruthless about value-per-byte. -Test the hypothesis: Ask yourself "Would this prevent a mistake I've seen AI make?" If no, cut it. +Test the hypothesis: Ask yourself "Would this prevent a mistake I've seen AI make?" If +no, cut it. Avoid restating README: If README explains it well, don't duplicate it here. diff --git a/.claude/commands/generate-llms-txt.md b/.claude/commands/generate-llms-txt.md index 61a4db8..e44d095 100644 --- a/.claude/commands/generate-llms-txt.md +++ b/.claude/commands/generate-llms-txt.md @@ -1,10 +1,12 @@ --- -description: Generate or update llms.txt file to help LLMs understand and navigate your site +description: + Generate or update llms.txt file to help LLMs understand and navigate your site --- # Generate llms.txt -Creates or updates llms.txt - a standardized file that helps Large Language Models understand and navigate your website or documentation at inference time. +Creates or updates llms.txt - a standardized file that helps Large Language Models +understand and navigate your website or documentation at inference time. llms.txt provides LLM-friendly navigation and context for websites and documentation. It should be: @@ -26,8 +28,8 @@ Determine the appropriate location: - static/ directory for Django, Flask, Hugo - Repository root as fallback -Choose the location that makes the file accessible at /llms.txt when the site is deployed. - +Choose the location that makes the file accessible at /llms.txt when the site is +deployed. Follow the llmstxt.org standard format: @@ -35,9 +37,12 @@ Follow the llmstxt.org standard format: ```markdown # Project Name -> Brief 1-2 sentence description of what this project/site is and what it helps users accomplish. +> Brief 1-2 sentence description of what this project/site is and what it helps users +> accomplish. -Additional context paragraph (optional): More detailed information about the project's purpose, key features, or important background that helps LLMs understand how to use the site effectively. +Additional context paragraph (optional): More detailed information about the project's +purpose, key features, or important background that helps LLMs understand how to use the +site effectively. ## Documentation @@ -63,6 +68,7 @@ Additional context paragraph (optional): More detailed information about the pro ``` Structure requirements: + - H1 title with project name - Blockquote summary for quick context - H2 sections organizing documentation by category @@ -70,10 +76,10 @@ Structure requirements: - "Optional" section for less critical resources Link format: + - Use relative paths for internal documentation - Use absolute URLs for external resources -- Prioritize most important links first within each section - +- Prioritize most important links first within each section Identify documentation and resources to include: @@ -86,14 +92,14 @@ Identify documentation and resources to include: - Specialized agents from .claude/agents/ Organize by importance: + 1. Getting started and quickstart guides 2. Core concepts and tutorials 3. API reference and technical documentation 4. Advanced topics and edge cases 5. Contributing and community resources -Target file size: Under 2KB for focused navigation. - +Target file size: Under 2KB for focused navigation. When llms.txt already exists: @@ -109,9 +115,11 @@ Next.js project with comprehensive docs: ```markdown # AI Coding Config -> Plugin marketplace for Claude Code and Cursor providing reusable coding standards, workflows, and AI agents. +> Plugin marketplace for Claude Code and Cursor providing reusable coding standards, +> workflows, and AI agents. -Provides a marketplace of plugins that bundle coding rules, slash commands, and specialized agents. Plugins maintain single source of truth through symlinks. +Provides a marketplace of plugins that bundle coding rules, slash commands, and +specialized agents. Plugins maintain single source of truth through symlinks. ## Documentation @@ -144,7 +152,8 @@ Django API project: > RESTful API for processing payments across multiple providers with unified interface. -Supports Stripe, PayPal, and Square with automatic failover and transaction reconciliation. +Supports Stripe, PayPal, and Square with automatic failover and transaction +reconciliation. ## Documentation @@ -169,6 +178,7 @@ Supports Stripe, PayPal, and Square with automatic failover and transaction reco - [Architecture](docs/architecture.md): System design - [Contributing](CONTRIBUTING.md): Development setup ``` + diff --git a/.claude/commands/handoff-context.md b/.claude/commands/handoff-context.md index aea51d4..6baafe0 100644 --- a/.claude/commands/handoff-context.md +++ b/.claude/commands/handoff-context.md @@ -12,22 +12,22 @@ Generate a comprehensive context handoff for the current conversation that can b Create handoff following the XML-structured format, save to timestamped temp file, copy to clipboard automatically. Show brief confirmation: `📋 Copied to clipboard` -Do not ask for permission - execute immediately. - +Do not ask for permission - execute immediately. ```markdown # Context Handoff - - [State the original, specific request or task] - [List everything successfully accomplished with file paths and line numbers] - [Detail work that still needs to be done with priorities] - [Document approaches that didn't work and why] - [Preserve essential technical, project, and business context] + [State the original, specific request or task] + [List everything successfully accomplished with file +paths and line numbers] [Detail work that still needs +to be done with priorities] [Document +approaches that didn't work and why] +[Preserve essential technical, project, and business context] [Describe exact state of deliverables and system] [Provide actionable next steps in priority order] + ``` @@ -46,3 +46,4 @@ For comprehensive documentation: Include file paths with line numbers, document Handoff should be immediately pasteable into new Claude conversation. New Claude instance should be able to continue work without additional context. +``` diff --git a/.claude/commands/personality-change.md b/.claude/commands/personality-change.md index 11552ad..672945b 100644 --- a/.claude/commands/personality-change.md +++ b/.claude/commands/personality-change.md @@ -22,14 +22,21 @@ Change the active AI personality to create consistent behavior across Claude Cod If no personality name provided, show available personalities and ask which to activate. -Validate that `.cursor/rules/personalities/.mdc` exists. If `none` requested, remove personality. +Validate that `.cursor/rules/personalities/.mdc` exists. If `none` requested, +remove personality. -For Claude Code: Read or create `.claude/context.md`. Check for existing `## Active Personality` section with `` comment. If personality exists and matches requested, confirm already active and stop. If different, remove entire section. If not removing (name != "none"), read personality file, strip frontmatter, append to `.claude/context.md` with HTML comments marking boundaries. +For Claude Code: Read or create `.claude/context.md`. Check for existing +`## Active Personality` section with `` comment. If +personality exists and matches requested, confirm already active and stop. If different, +remove entire section. If not removing (name != "none"), read personality file, strip +frontmatter, append to `.claude/context.md` with HTML comments marking boundaries. -For Cursor: Find all personality files in `.cursor/rules/personalities/` (except `common-personality.mdc`). For each file, update frontmatter: set `alwaysApply: true` for selected personality, set `alwaysApply: false` for all others. +For Cursor: Find all personality files in `.cursor/rules/personalities/` (except +`common-personality.mdc`). For each file, update frontmatter: set `alwaysApply: true` +for selected personality, set `alwaysApply: false` for all others. -Report results clearly showing what changed in both Claude Code and Cursor configurations. - +Report results clearly showing what changed in both Claude Code and Cursor +configurations. /personality-change samantha diff --git a/.claude/commands/product-intel.md b/.claude/commands/product-intel.md index 9cde80f..06d3702 100644 --- a/.claude/commands/product-intel.md +++ b/.claude/commands/product-intel.md @@ -1,11 +1,13 @@ --- -description: Run comprehensive product intelligence research on competitors and industry trends +description: + Run comprehensive product intelligence research on competitors and industry trends argument-hint: [competitor name | topic | "all"] --- # Product Intelligence Research -Run comprehensive product intelligence research on competitors, industry trends, and opportunities. +Run comprehensive product intelligence research on competitors, industry trends, and +opportunities. $ARGUMENTS @@ -22,24 +24,24 @@ Track competitor features, launches, and positioning. Monitor relevant technolog Quality over quantity: Five meaningful insights beat fifty links. -Actionability first: Every finding should answer "so what?" If it doesn't inform a decision, it doesn't belong. +Actionability first: Every finding should answer "so what?" If it doesn't inform a +decision, it doesn't belong. Recency matters: Focus on the last 30-60 days. Archive older news. Trust but verify: Cross-reference claims. Official sources over rumors. -Stay objective: Report what you find, not what you hope to find. - +Stay objective: Report what you find, not what you hope to find. Product intelligence lives in `/product-intel/` with research settings, competitors and topics in their own directories, and opportunities for actionable insights. Each competitor and topic gets its own markdown file following standard templates. When creating this structure for the first time, create: + - `/product-intel/research-settings.md` (with frontmatter for settings) - `/product-intel/competitors/` (will be populated during discovery) - `/product-intel/topics/` (will be populated during discovery) -- `/product-intel/opportunities/` (for tracking insights) - +- `/product-intel/opportunities/` (for tracking insights) Competitor files (`/product-intel/competitors/[slug].md`): @@ -47,9 +49,7 @@ Competitor files (`/product-intel/competitors/[slug].md`): ```markdown # [Company Name] -**Last Checked**: YYYY-MM-DD -**Website**: [url] -**Positioning**: One-sentence value prop +**Last Checked**: YYYY-MM-DD **Website**: [url] **Positioning**: One-sentence value prop ## Overview @@ -65,9 +65,9 @@ Brief description of what they do and how they compete. ## Feature Comparison -| Feature | Them | Us | Notes | -|---------|------|-----|-------| -| ... | ✅ | ❌ | ... | +| Feature | Them | Us | Notes | +| ------- | ---- | --- | ----- | +| ... | ✅ | ❌ | ... | ## Strengths @@ -87,8 +87,7 @@ Topic files (`/product-intel/topics/[topic-slug].md`): ```markdown # [Topic Name] -**Last Checked**: YYYY-MM-DD -**Relevance**: Why this matters to the project +**Last Checked**: YYYY-MM-DD **Relevance**: Why this matters to the project ## Recent Developments @@ -107,61 +106,102 @@ Topic files (`/product-intel/topics/[topic-slug].md`): - [ ] Things we should consider based on these developments ``` + Discovery Process: -Understanding the product means extracting its essence from repository files. Read README, package.json, and project documentation to grasp what problem this solves, who it's for, and what technologies it uses. This context shapes everything else. +Understanding the product means extracting its essence from repository files. Read +README, package.json, and project documentation to grasp what problem this solves, who +it's for, and what technologies it uses. This context shapes everything else. -Finding competitors requires thinking like a product manager. Search for alternatives to the value proposition, comparison articles, and community discussions about similar tools. Prioritize companies with funding, active development, and real market presence. Create files for the top 5-8 most relevant competitors. +Finding competitors requires thinking like a product manager. Search for alternatives to +the value proposition, comparison articles, and community discussions about similar +tools. Prioritize companies with funding, active development, and real market presence. +Create files for the top 5-8 most relevant competitors. -Discovering topics means identifying what technologies and trends matter to this product. Look at dependencies, protocols mentioned in docs, and industry-specific developments. Focus on 3-5 core topics that directly impact the product's strategy or technical direction. +Discovering topics means identifying what technologies and trends matter to this +product. Look at dependencies, protocols mentioned in docs, and industry-specific +developments. Focus on 3-5 core topics that directly impact the product's strategy or +technical direction. Maintaining Intelligence: -Competitor research should uncover what they've shipped, how they're positioning themselves, and where they're strong or weak. Use official sources first (changelogs, blogs, docs), then community signals, then news. Look for changes that create opportunities or threats. Update files with dated, sourced findings that answer "so what?" +Competitor research should uncover what they've shipped, how they're positioning +themselves, and where they're strong or weak. Use official sources first (changelogs, +blogs, docs), then community signals, then news. Look for changes that create +opportunities or threats. Update files with dated, sourced findings that answer "so +what?" -Topic research tracks how the underlying technologies and industry trends are evolving. Monitor official specifications, community adoption signals, and major announcements. The goal is identifying when changes require action—a breaking protocol update, a security advisory, a shift in best practices. +Topic research tracks how the underlying technologies and industry trends are evolving. +Monitor official specifications, community adoption signals, and major announcements. +The goal is identifying when changes require action—a breaking protocol update, a +security advisory, a shift in best practices. Research Approach: -Use targeted searches to find high-signal information. For competitors, search for their launches, announcements, and changelog pages directly. Check HackerNews and GitHub for community sentiment. For technologies, look for specification updates, official documentation changes, and adoption signals in the developer ecosystem. For integration opportunities, search for API updates, trending tools in the category, and community demand signals. - +Use targeted searches to find high-signal information. For competitors, search for their +launches, announcements, and changelog pages directly. Check HackerNews and GitHub for +community sentiment. For technologies, look for specification updates, official +documentation changes, and adoption signals in the developer ecosystem. For integration +opportunities, search for API updates, trending tools in the category, and community +demand signals. Bootstrap (first time ever): -When `/product-intel/` directory doesn't exist at all, guide the user through setup. Welcome them: "I'll set up product intelligence tracking for this repo. This will automatically discover competitors and industry topics by analyzing your codebase, then keep that intelligence up to date." +When `/product-intel/` directory doesn't exist at all, guide the user through setup. +Welcome them: "I'll set up product intelligence tracking for this repo. This will +automatically discover competitors and industry topics by analyzing your codebase, then +keep that intelligence up to date." -Explain what happens: "I'll create a `/product-intel/` directory with research settings and tracking files. The settings control things like how often to check for updates (monthly by default) and what sources to prioritize." +Explain what happens: "I'll create a `/product-intel/` directory with research settings +and tracking files. The settings control things like how often to check for updates +(monthly by default) and what sources to prioritize." -Offer customization or defaults: "Would you like to customize research settings now, or use sensible defaults? (Defaults: check monthly, focus on last 60 days, prioritize official sources over news)" +Offer customization or defaults: "Would you like to customize research settings now, or +use sensible defaults? (Defaults: check monthly, focus on last 60 days, prioritize +official sources over news)" -If they want defaults, create the directory structure with `research-settings.md` using default values. If they want to customize, walk through key settings interactively. +If they want defaults, create the directory structure with `research-settings.md` using +default values. If they want to customize, walk through key settings interactively. Then proceed to understanding the product and discovery. First Run (discovery phase): -When `/product-intel/` exists but has no competitor or topic files yet, you need to understand this product and establish initial tracking. Read the repository's key files (README, package.json, CLAUDE.md) to extract the product's name, value proposition, technology stack, target audience, and industry domain. +When `/product-intel/` exists but has no competitor or topic files yet, you need to +understand this product and establish initial tracking. Read the repository's key files +(README, package.json, CLAUDE.md) to extract the product's name, value proposition, +technology stack, target audience, and industry domain. -Use this understanding to discover 5-8 relevant competitors through targeted searches for alternatives, comparison articles, and community discussions. Look for funded companies, projects with momentum, and active development. Create initial files for each with baseline information. +Use this understanding to discover 5-8 relevant competitors through targeted searches +for alternatives, comparison articles, and community discussions. Look for funded +companies, projects with momentum, and active development. Create initial files for each +with baseline information. -Similarly, identify 3-5 key topics by extracting technologies from the codebase, noting protocols or standards mentioned, and determining relevant industry trends. Create topic files with foundational context. +Similarly, identify 3-5 key topics by extracting technologies from the codebase, noting +protocols or standards mentioned, and determining relevant industry trends. Create topic +files with foundational context. -Read `research-settings.md` for any manual includes/excludes, then conduct initial research to populate all files with real intelligence. +Read `research-settings.md` for any manual includes/excludes, then conduct initial +research to populate all files with real intelligence. Subsequent Runs (maintenance phase): -When competitor and topic files already exist, scan them to see what needs updating. Prioritize files with stale `last_checked` dates. Read `research-settings.md` to understand focus windows and source priorities. +When competitor and topic files already exist, scan them to see what needs updating. +Prioritize files with stale `last_checked` dates. Read `research-settings.md` to +understand focus windows and source priorities. -Plan your research tasks, execute systematic updates for each tracked entity, edit files with new findings, and surface opportunities. The goal is keeping intelligence current and actionable, not just collecting links. +Plan your research tasks, execute systematic updates for each tracked entity, edit files +with new findings, and surface opportunities. The goal is keeping intelligence current +and actionable, not just collecting links. Targeted Research: -When asked about a specific competitor or topic, find that file and do a comprehensive deep-dive. Update just that entity with thorough findings. - +When asked about a specific competitor or topic, find that file and do a comprehensive +deep-dive. Update just that entity with thorough findings. Before completing any research task: @@ -182,4 +222,5 @@ Professional: Clear writing, consistent formatting Evidence-based: Always cite sources -You are a trusted intelligence analyst. Your research informs product strategy, so accuracy and relevance are paramount. +You are a trusted intelligence analyst. Your research informs product strategy, so +accuracy and relevance are paramount. diff --git a/.claude/commands/setup-environment.md b/.claude/commands/setup-environment.md index 9a5fed5..be16296 100644 --- a/.claude/commands/setup-environment.md +++ b/.claude/commands/setup-environment.md @@ -15,7 +15,8 @@ Detect whether this is a git worktree or new machine setup: - Neither? → new machine setup For worktrees: Minimal setup (install dependencies, copy environment files, smoke test). -For new machines: Full setup (install and verify dependencies, set up git hooks, run build, execute tests). +For new machines: Full setup (install and verify dependencies, set up git hooks, run +build, execute tests). Trust main repo validation for worktrees. Comprehensive verification for new machines. @@ -23,10 +24,12 @@ Trust main repo validation for worktrees. Comprehensive verification for new mac Identify project type and package manager by examining project files. -Project types: Node.js (package.json), Python (requirements.txt or Pipfile), Ruby (Gemfile), Go (go.mod), Rust (Cargo.toml), Java (pom.xml or build.gradle), .NET (.csproj). +Project types: Node.js (package.json), Python (requirements.txt or Pipfile), Ruby +(Gemfile), Go (go.mod), Rust (Cargo.toml), Java (pom.xml or build.gradle), .NET +(.csproj). -Node.js package managers: pnpm (pnpm-lock.yaml), yarn (yarn.lock), bun (bun.lockb), npm (default). - +Node.js package managers: pnpm (pnpm-lock.yaml), yarn (yarn.lock), bun (bun.lockb), npm +(default). Install project dependencies using the appropriate package manager. Use frozen/locked versions to ensure consistency with the main repository. @@ -35,14 +38,12 @@ Install project dependencies using the appropriate package manager. Use frozen/l For git worktrees, copy environment files from main repository: .env and variants (.env.local, .env.development, .env.test), local configuration files, and secret files needed for development. -Find main repository path using git worktree list. - +Find main repository path using git worktree list. Set up git hooks based on what the project uses: Husky (run husky install if .husky exists), Pre-commit (run pre-commit install if .pre-commit-config.yaml exists), custom hooks (copy from main repository's .git/hooks). -For worktrees, find main repository path using git worktree list. - +For worktrees, find main repository path using git worktree list. Run necessary code generation steps: Prisma (generate client if @prisma/client in dependencies), GraphQL (run codegen if configuration exists), TypeScript (generate declarations if configured), package prepare scripts (run if defined in package.json). @@ -51,8 +52,9 @@ Run necessary code generation steps: Prisma (generate client if @prisma/client i For worktrees: Confirm dependencies installed, run quick compilation check if applicable, trust main repository validation. -For new machines: Verify development tools available and working, run build process, execute test suite, test git hooks function correctly, check required command-line tools installed. - +For new machines: Verify development tools available and working, run build process, +execute test suite, test git hooks function correctly, check required command-line tools +installed. When encountering failures, identify root cause and attempt automatic resolution where possible. For issues requiring manual intervention, provide clear guidance. Continue with other setup steps when safe to do so without the failed component. @@ -61,7 +63,7 @@ When encountering failures, identify root cause and attempt automatic resolution Worktrees: Dependencies installed, smoke test passes, development environment ready. -New machines: All dependencies and tools functioning, build and test processes verified, git hooks operational, complete development environment validated. +New machines: All dependencies and tools functioning, build and test processes verified, +git hooks operational, complete development environment validated. -Goal: Right-sized verification matching context. - +Goal: Right-sized verification matching context. diff --git a/.claude/commands/troubleshoot.md b/.claude/commands/troubleshoot.md index 75d085b..57d8b9e 100644 --- a/.claude/commands/troubleshoot.md +++ b/.claude/commands/troubleshoot.md @@ -17,8 +17,7 @@ You are an autonomous error resolution agent. Your goal is to eliminate producti - /troubleshoot watch - Monitor and auto-fix critical errors as they occur - /troubleshoot analyze - Pattern analysis without fixes - /troubleshoot 3 - Fix the 3rd error in priority order -- /troubleshoot csrf token - Find and fix error matching keywords - +- /troubleshoot csrf token - Find and fix error matching keywords Check which error monitoring tools are available (Sentry, HoneyBadger, or others). If available, fetch unresolved errors, analyze for patterns and root causes, then begin autonomous fixing. Create worktrees for each fix, write tests, and submit PRs. @@ -29,47 +28,73 @@ If no monitoring service available, explain what's needed and how to connect one Intelligent Prioritization: Trust Sentry/HoneyBadger's default sorting. Recognize when multiple errors share a root cause and prioritize those clusters. -Parallel Execution: Work on multiple independent bugs simultaneously in separate git worktrees. Typically 3-5 concurrent worktrees is optimal. +Parallel Execution: Work on multiple independent bugs simultaneously in separate git +worktrees. Typically 3-5 concurrent worktrees is optimal. -Root Cause Over Symptoms: Investigate why errors happen. Review recent commits, check for related errors, understand data flow. Find the actual problem, not just where it manifested. +Root Cause Over Symptoms: Investigate why errors happen. Review recent commits, check +for related errors, understand data flow. Find the actual problem, not just where it +manifested. -Pattern Recognition: Identify common causes across multiple files or components. One strategic fix can prevent many future errors. +Pattern Recognition: Identify common causes across multiple files or components. One +strategic fix can prevent many future errors. -Know When Not to Fix: Skip errors that aren't worth fixing: rate limiting (429 errors), external service failures, user-caused errors, flaky/intermittent issues, deprecated code paths, low-value cosmetic issues, monitoring noise. Mark these as ignored in the monitoring service with brief explanation. +Know When Not to Fix: Skip errors that aren't worth fixing: rate limiting (429 errors), +external service failures, user-caused errors, flaky/intermittent issues, deprecated +code paths, low-value cosmetic issues, monitoring noise. Mark these as ignored in the +monitoring service with brief explanation. -Autonomous Decision Making: Create worktree, debug, write fix, add tests, submit PR. Use your judgment on what to fix and what to ignore. Follow project cursor rules, run validation, invoke code review agents if available. +Autonomous Decision Making: Create worktree, debug, write fix, add tests, submit PR. Use +your judgment on what to fix and what to ignore. Follow project cursor rules, run +validation, invoke code review agents if available. -Learning System: After fixes deploy, check if error rate dropped. Adjust approach based on outcomes. +Learning System: After fixes deploy, check if error rate dropped. Adjust approach based +on outcomes. -Trust the executing model's intelligence - you can determine the best approach for each situation. - +Trust the executing model's intelligence - you can determine the best approach for each +situation. Autonomous Continuous (default): Fix highest priority error. While PR is in CI, start next one in parallel worktree. Continue until all critical errors resolved. -Parallel Batch (auto N): Identify top N independent errors and fix simultaneously in separate worktrees. Submit all PRs at once. +Parallel Batch (auto N): Identify top N independent errors and fix simultaneously in +separate worktrees. Submit all PRs at once. -Watch Mode: Monitor for new critical errors (priority score >85). Auto-create worktree, fix, submit PR tagged [HOTFIX]. Queue non-critical errors for batch processing. +Watch Mode: Monitor for new critical errors (priority score >85). Auto-create worktree, +fix, submit PR tagged [HOTFIX]. Queue non-critical errors for batch processing. -Analysis Mode: Fetch last 500 errors (including resolved), identify patterns and common root causes, generate insights about error-prone areas, suggest preventive refactorings. +Analysis Mode: Fetch last 500 errors (including resolved), identify patterns and common +root causes, generate insights about error-prone areas, suggest preventive refactorings. -Keyword Search: Search errors for matches in messages, types, file paths, stack traces, function names. Use fuzzy matching. If multiple matches, show ranked by relevance. If one clear match, fix immediately. - +Keyword Search: Search errors for matches in messages, types, file paths, stack traces, +function names. Use fuzzy matching. If multiple matches, show ranked by relevance. If +one clear match, fix immediately. Service Detection: Identify available error monitoring tools. If multiple, ask user preference. -Error Intelligence: Fetch unresolved errors in default sort order. Identify clusters sharing root causes. Triage aggressively - skip external failures, rate limiting, user mistakes, rare flukes. Mark ignored errors in monitoring service with explanation. +Error Intelligence: Fetch unresolved errors in default sort order. Identify clusters +sharing root causes. Triage aggressively - skip external failures, rate limiting, user +mistakes, rare flukes. Mark ignored errors in monitoring service with explanation. -Root Cause Analysis: Review git history for affected files, examine code context, look for related errors, check deployment timelines. Generate hypotheses about actual problems. +Root Cause Analysis: Review git history for affected files, examine code context, look +for related errors, check deployment timelines. Generate hypotheses about actual +problems. -Git Worktree Workflow: Each bug fix in isolated worktree. Read .cursor/rules/git-worktree-task.mdc for full workflow. Clean up worktrees after PRs merge. +Git Worktree Workflow: Each bug fix in isolated worktree. Read +.cursor/rules/git-worktree-task.mdc for full workflow. Clean up worktrees after PRs +merge. -Fixing Process: Gather full context from error monitoring (stack traces, request data, timelines). Read failing code and context. Identify root cause. Implement fix handling edge cases with improved error messages. Add tests when appropriate. Run validation. Use code review agents if available. Create descriptive commits. Submit PRs with error links, occurrence counts, root cause analysis, monitoring plans. +Fixing Process: Gather full context from error monitoring (stack traces, request data, +timelines). Read failing code and context. Identify root cause. Implement fix handling +edge cases with improved error messages. Add tests when appropriate. Run validation. Use +code review agents if available. Create descriptive commits. Submit PRs with error +links, occurrence counts, root cause analysis, monitoring plans. -Verification: After PR deploys, check if error rates dropped. Mark errors as resolved once confirmed. If errors persist, create follow-up fix. +Verification: After PR deploys, check if error rates dropped. Mark errors as resolved +once confirmed. If errors persist, create follow-up fix. -Preventive Work: Notice patterns (missing error boundaries, inadequate input validation). Suggest broader refactorings. Create optional PRs for improvements. +Preventive Work: Notice patterns (missing error boundaries, inadequate input +validation). Suggest broader refactorings. Create optional PRs for improvements. @@ -98,13 +123,13 @@ Show clear summaries when starting: Starting with auth cluster... ``` -For keyword search, show matches ranked by relevance or fix immediately if one clear match. +For keyword search, show matches ranked by relevance or fix immediately if one clear +match. -Provide updates as you complete each fix. - +Provide updates as you complete each fix. Production error count decreases over time. Errors don't recur after fixes. Related errors fixed together through root cause analysis. Preventive refactorings reduce new error introduction. Tests prevent regressions. No new errors introduced by changes. Low-value errors intelligently triaged and ignored. -Track outcomes and adjust approach based on what works. Good triage (knowing what NOT to fix) is as valuable as good fixes. - +Track outcomes and adjust approach based on what works. Good triage (knowing what NOT to +fix) is as valuable as good fixes. diff --git a/.claude/skills/brainstorming/SKILL.md b/.claude/skills/brainstorming/SKILL.md index e3e59fd..b246ee8 100644 --- a/.claude/skills/brainstorming/SKILL.md +++ b/.claude/skills/brainstorming/SKILL.md @@ -8,79 +8,102 @@ description: Turn rough ideas into fully-formed designs through natural collaborative dialogue. Understand the context, explore alternatives, validate incrementally. -Core principle: Ask questions to understand, present options to explore, validate sections to refine. - +Core principle: Ask questions to understand, present options to explore, validate +sections to refine. Use brainstorming when you have a rough idea but unclear implementation, multiple approaches exist and you need to choose, requirements are fuzzy or incomplete, or design decisions need validation before coding. -Skip for clear mechanical tasks with obvious solutions, well-defined requirements with standard implementations, or simple bug fixes. - +Skip for clear mechanical tasks with obvious solutions, well-defined requirements with +standard implementations, or simple bug fixes. Explore the current project state. Check existing files, documentation, recent commits. Understand what's already built. -Ask questions one at a time to refine the idea. Use multiple choice when possible - easier to answer than open-ended. Focus on understanding purpose (what problem does this solve?), constraints (what limits the solution?), and success criteria (how do we know it works?). +Ask questions one at a time to refine the idea. Use multiple choice when possible - +easier to answer than open-ended. Focus on understanding purpose (what problem does this +solve?), constraints (what limits the solution?), and success criteria (how do we know +it works?). -One question per message. If a topic needs more exploration, break it into multiple questions. Don't overwhelm with a list of questions. - +One question per message. If a topic needs more exploration, break it into multiple +questions. Don't overwhelm with a list of questions. Propose different approaches with their tradeoffs. Present conversationally, showing all options first before making a recommendation. -Example pattern: -"I see three main approaches: +Example pattern: "I see three main approaches: -1. Direct integration - Fast to implement but creates coupling. Good if this is temporary. +1. Direct integration - Fast to implement but creates coupling. Good if this is + temporary. -2. Event-driven - More flexible, better separation, but adds complexity. Worth it if we'll extend this. +2. Event-driven - More flexible, better separation, but adds complexity. Worth it if + we'll extend this. -3. Separate service - Maximum isolation, easier to scale, but operational overhead. Overkill unless we need independent scaling. +3. Separate service - Maximum isolation, easier to scale, but operational overhead. + Overkill unless we need independent scaling. -I'd recommend #2 (event-driven) because the requirements suggest we'll add features here, and the loose coupling will make that easier. What do you think?" +I'd recommend #2 (event-driven) because the requirements suggest we'll add features +here, and the loose coupling will make that easier. What do you think?" -Present options before recommendation. LLMs process information sequentially - showing options first lets them fully consider each alternative before being influenced by a recommendation. The recommendation comes after all options have been presented. +Present options before recommendation. LLMs process information sequentially - showing +options first lets them fully consider each alternative before being influenced by a +recommendation. The recommendation comes after all options have been presented. -Make a clear recommendation - pick one approach and explain why it fits best. Don't hedge or suggest combining approaches. +Make a clear recommendation - pick one approach and explain why it fits best. Don't +hedge or suggest combining approaches. -Avoid defaulting to hybrid approaches. Hybrid solutions are rarely the right answer. They often combine the complexity of multiple approaches without clear benefits. Only suggest a hybrid if there's a specific, compelling reason why a pure approach won't work. +Avoid defaulting to hybrid approaches. Hybrid solutions are rarely the right answer. +They often combine the complexity of multiple approaches without clear benefits. Only +suggest a hybrid if there's a specific, compelling reason why a pure approach won't +work. -Structure alternatives clearly - each option should be distinct with clear tradeoffs. If options are too similar, you haven't explored the design space enough. +Structure alternatives clearly - each option should be distinct with clear tradeoffs. If +options are too similar, you haven't explored the design space enough. -Explain the choice criteria - make explicit what factors led to your recommendation (simplicity, performance, maintainability, etc.). This helps validate whether the recommendation aligns with priorities. +Explain the choice criteria - make explicit what factors led to your recommendation +(simplicity, performance, maintainability, etc.). This helps validate whether the +recommendation aligns with priorities. -Let the human partner react after your recommendation. They may have constraints or priorities you didn't consider. - +Let the human partner react after your recommendation. They may have constraints or +priorities you didn't consider. Once you understand what you're building, present the design in small, manageable sections covering architecture and component structure, data flow and state management, error handling and edge cases, and testing approach. -Ask after each section whether it looks right. Be ready to go back and clarify if something doesn't make sense. +Ask after each section whether it looks right. Be ready to go back and clarify if +something doesn't make sense. -This incremental validation catches misunderstandings early before you've written a complete design document. - +This incremental validation catches misunderstandings early before you've written a +complete design document. Write the validated design to docs/plans/[topic]-design.md. Keep it concise and focused on decisions and rationale, not implementation details. Commit the design document to git so it's tracked with the project. -If continuing to implementation, ask whether to proceed. Set up an isolated workspace for development (git worktree or feature branch). Create a detailed implementation plan breaking the design into concrete tasks. - +If continuing to implementation, ask whether to proceed. Set up an isolated workspace +for development (git worktree or feature branch). Create a detailed implementation plan +breaking the design into concrete tasks. One question at a time. Don't list multiple questions. Ask one, get an answer, ask the next. -Multiple choice preferred. "Should we use events or direct calls?" is easier than "How should components communicate?" +Multiple choice preferred. "Should we use events or direct calls?" is easier than "How +should components communicate?" -YAGNI ruthlessly. Remove unnecessary features from designs. Build what's needed, not what might be needed someday. +YAGNI ruthlessly. Remove unnecessary features from designs. Build what's needed, not +what might be needed someday. -Explore alternatives always. Present multiple approaches before settling on one. This surfaces tradeoffs. Choose one clear recommendation - avoid defaulting to hybrid approaches which rarely solve the problem well. +Explore alternatives always. Present multiple approaches before settling on one. This +surfaces tradeoffs. Choose one clear recommendation - avoid defaulting to hybrid +approaches which rarely solve the problem well. -Incremental validation. Present design in sections, validate each before continuing. Don't write a complete design then ask for feedback - you might be heading the wrong direction. +Incremental validation. Present design in sections, validate each before continuing. +Don't write a complete design then ask for feedback - you might be heading the wrong +direction. -Be flexible. When something doesn't make sense to your partner, go back and clarify. Don't defend the design, refine it. - +Be flexible. When something doesn't make sense to your partner, go back and clarify. +Don't defend the design, refine it. Don't ask many questions at once. Don't present a complete design without incremental validation. Don't skip exploring alternatives. Don't add features beyond stated requirements. Don't continue with a design that confuses your partner - go back and clarify first. diff --git a/.claude/skills/research/SKILL.md b/.claude/skills/research/SKILL.md index be09f1e..3cf0a0a 100644 --- a/.claude/skills/research/SKILL.md +++ b/.claude/skills/research/SKILL.md @@ -22,18 +22,22 @@ Clear signals that research is needed: When: Mid-flow verification Time: Under a minute -Examples: "Is useEffect still the way to handle this in React 18?", "Did Stripe change their webhook payload?", "What's the current Node LTS version?" +Examples: "Is useEffect still the way to handle this in React 18?", "Did Stripe change +their webhook payload?", "What's the current Node LTS version?" -Just search, grab the answer, keep coding. No storage, no ceremony, no permission needed. - +Just search, grab the answer, keep coding. No storage, no ceremony, no permission +needed. When: The decision really matters Time: 5-15 minutes -Examples: Choosing between competing technologies, understanding a new architectural pattern, debugging something that doesn't match documentation. +Examples: Choosing between competing technologies, understanding a new architectural +pattern, debugging something that doesn't match documentation. -Always ask first: "This needs deeper research (5-15 min). Should I dig into this now?" Let the user decide if they want to pause for research or continue with existing knowledge. +Always ask first: "This needs deeper research (5-15 min). Should I dig into this now?" +Let the user decide if they want to pause for research or continue with existing +knowledge. Research thoroughly, save findings in research/[topic].md for team reference. @@ -42,21 +46,24 @@ Research thoroughly, save findings in research/[topic].md for team reference. Always use the best available web search. Priority order: MCP servers (preferred when available): + - Tavily MCP server - Exa MCP server - Other specialized search MCP servers Built-in tools (fallback): + - Cursor: web_search tool - Claude Code: Built-in web search Tell the user which you're using: + - "Using Tavily MCP server for enhanced search capabilities" - "Using Exa MCP server for code-focused research" - "Using built-in web search (no MCP servers configured)" -This transparency helps users understand tool selection and configure MCP servers if desired. - +This transparency helps users understand tool selection and configure MCP servers if +desired. Start with official sources - docs, changelogs, GitHub releases. Then expand to community discussions if needed. @@ -72,23 +79,25 @@ Good pattern: Breaking change: redirectToCheckout() removed in v4 New pattern: + - Use Payment Element (unified UI) - Or Checkout Sessions API (hosted page) Migration: [Specific code example] -Source: Stripe docs v2024.11.15 - +Source: Stripe docs v2024.11.15 Recognize patterns: When you see version-specific errors, deprecated methods, or post-2023 technologies, that signals research is needed. -Be transparent: Say "I should verify this" or "Let me check current best practices" rather than guessing. +Be transparent: Say "I should verify this" or "Let me check current best practices" +rather than guessing. -Speed over perfection: For quick checks, first good answer wins. For deep dives, thoroughness matters. +Speed over perfection: For quick checks, first good answer wins. For deep dives, +thoroughness matters. -No unnecessary storage: Quick research lives in the conversation. Only save deep research that others might reference. - +No unnecessary storage: Quick research lives in the conversation. Only save deep +research that others might reference. Don't research everything. If your React knowledge from 2023 still works and the user isn't hitting issues, just build. Research is a tool, not a crutch. diff --git a/.claude/skills/skill-creator/SKILL.md b/.claude/skills/skill-creator/SKILL.md index 2057023..3c5cc83 100644 --- a/.claude/skills/skill-creator/SKILL.md +++ b/.claude/skills/skill-creator/SKILL.md @@ -9,14 +9,14 @@ description: Skills are reusable reference guides for proven techniques, patterns, and tools. Write them as intelligent companions would read them - focused on goals and outcomes, not rigid procedures. -Core principle: Trust the LLM's intelligence. Describe what needs to happen and why, not step-by-step how. - +Core principle: Trust the LLM's intelligence. Describe what needs to happen and why, not +step-by-step how. Create skills for techniques that weren't intuitively obvious to you, patterns you'd reference across projects, or broadly applicable approaches (not project-specific). -Skip skills for one-off solutions, well-documented standard practices, or project-specific conventions (use CLAUDE.md instead). - +Skip skills for one-off solutions, well-documented standard practices, or +project-specific conventions (use CLAUDE.md instead). Every skill has YAML frontmatter and markdown content: @@ -48,17 +48,21 @@ What goes wrong and how to avoid it. Frontmatter requirements: -name: Letters, numbers, hyphens only. Use verb-first active voice (e.g., creating-skills not skill-creation). +name: Letters, numbers, hyphens only. Use verb-first active voice (e.g., creating-skills +not skill-creation). -description: Third-person, under 500 characters. Start with "Use when..." to describe triggering conditions, then explain what it does. Include concrete symptoms and situations, not just abstract concepts. +description: Third-person, under 500 characters. Start with "Use when..." to describe +triggering conditions, then explain what it does. Include concrete symptoms and +situations, not just abstract concepts. -Good: "Use when tests have race conditions or pass/fail inconsistently - replaces arbitrary timeouts with condition polling for reliable async tests" - +Good: "Use when tests have race conditions or pass/fail inconsistently - replaces +arbitrary timeouts with condition polling for reliable async tests" Show, don't tell (pattern reinforcement): LLMs encode patterns from what you show them. Demonstrate desired approaches with 5+ examples. Describe undesired alternatives in prose without code. Good pattern: + ```typescript // Use condition-based waiting for reliable async tests await waitFor(() => element.textContent === "loaded"); @@ -66,20 +70,24 @@ await waitFor(() => user.isAuthenticated === true); await waitFor(() => data.length > 0); ``` -Then in prose: "Avoid arbitrary timeouts like setTimeout() which make tests brittle and slow." +Then in prose: "Avoid arbitrary timeouts like setTimeout() which make tests brittle and +slow." -Focus on goals, not process: Describe outcomes and constraints. Let the LLM figure out how to achieve them. +Focus on goals, not process: Describe outcomes and constraints. Let the LLM figure out +how to achieve them. -Good: "Ensure each test has a clear failure mode that identifies what's wrong. Tests should verify behavior, not implementation details." +Good: "Ensure each test has a clear failure mode that identifies what's wrong. Tests +should verify behavior, not implementation details." Positive framing: Frame as "do this" not "avoid that." Focus on what success looks like. Good: "Write minimal code to pass the test. Add features only when tests require them." -Trust intelligence: Assume the LLM can handle edge cases and variations. Specify boundaries, not decision trees. +Trust intelligence: Assume the LLM can handle edge cases and variations. Specify +boundaries, not decision trees. -Good: "Check if files exist before copying. If they differ, show changes and ask the user what to do." - +Good: "Check if files exist before copying. If they differ, show changes and ask the +user what to do." Self-contained (preferred): @@ -89,6 +97,7 @@ skill-name/ ``` With supporting files (when needed): + ``` skill-name/ SKILL.md # Overview + patterns @@ -96,7 +105,8 @@ skill-name/ tool-example.ts # Reusable code to adapt ``` -Only separate files for heavy reference material (comprehensive API docs) or reusable tools (actual code to copy/adapt). +Only separate files for heavy reference material (comprehensive API docs) or reusable +tools (actual code to copy/adapt). Keep inline: Principles and concepts, code patterns under 50 lines, everything else. @@ -123,6 +133,7 @@ Structure: - Examples showing desired patterns (5+ for main approach) Content: + - Goals and outcomes, not rigid procedures - Positive framing (show what to do) - Trust LLM intelligence (avoid over-prescription) @@ -130,19 +141,22 @@ Content: - Common pitfalls addressed Organization: + - Self-contained in SKILL.md when possible - Supporting files only when truly needed -- Under 500 words unless it's reference material - +- Under 500 words unless it's reference material Over-prescription: Writing detailed step-by-step procedures for things the LLM can figure out. Describe the goal, not the algorithm. -Showing anti-patterns: Demonstrating "wrong" code teaches that pattern. Describe alternatives in prose instead. +Showing anti-patterns: Demonstrating "wrong" code teaches that pattern. Describe +alternatives in prose instead. -Vague triggers: "Use when debugging" is too broad. "Use when encountering test failures with unclear root causes" is specific. +Vague triggers: "Use when debugging" is too broad. "Use when encountering test failures +with unclear root causes" is specific. -First person: Skills inject into system prompts. Write "Use when..." not "I can help when..." +First person: Skills inject into system prompts. Write "Use when..." not "I can help +when..." -Missing keywords: Future Claude searches for skills by symptoms and errors. Include the terms someone would actually search for. - +Missing keywords: Future Claude searches for skills by symptoms and errors. Include the +terms someone would actually search for. diff --git a/.claude/skills/skill-creator/scripts/init_skill.py b/.claude/skills/skill-creator/scripts/init_skill.py index 329ad4e..0c45329 100755 --- a/.claude/skills/skill-creator/scripts/init_skill.py +++ b/.claude/skills/skill-creator/scripts/init_skill.py @@ -188,7 +188,7 @@ def main(): def title_case_skill_name(skill_name): """Convert hyphenated skill name to Title Case for display.""" - return ' '.join(word.capitalize() for word in skill_name.split('-')) + return " ".join(word.capitalize() for word in skill_name.split("-")) def init_skill(skill_name, path): @@ -221,11 +221,10 @@ def init_skill(skill_name, path): # Create SKILL.md from template skill_title = title_case_skill_name(skill_name) skill_content = SKILL_TEMPLATE.format( - skill_name=skill_name, - skill_title=skill_title + skill_name=skill_name, skill_title=skill_title ) - skill_md_path = skill_dir / 'SKILL.md' + skill_md_path = skill_dir / "SKILL.md" try: skill_md_path.write_text(skill_content) print("✅ Created SKILL.md") @@ -236,24 +235,24 @@ def init_skill(skill_name, path): # Create resource directories with example files try: # Create scripts/ directory with example script - scripts_dir = skill_dir / 'scripts' + scripts_dir = skill_dir / "scripts" scripts_dir.mkdir(exist_ok=True) - example_script = scripts_dir / 'example.py' + example_script = scripts_dir / "example.py" example_script.write_text(EXAMPLE_SCRIPT.format(skill_name=skill_name)) example_script.chmod(0o755) print("✅ Created scripts/example.py") # Create references/ directory with example reference doc - references_dir = skill_dir / 'references' + references_dir = skill_dir / "references" references_dir.mkdir(exist_ok=True) - example_reference = references_dir / 'api_reference.md' + example_reference = references_dir / "api_reference.md" example_reference.write_text(EXAMPLE_REFERENCE.format(skill_title=skill_title)) print("✅ Created references/api_reference.md") # Create assets/ directory with example asset placeholder - assets_dir = skill_dir / 'assets' + assets_dir = skill_dir / "assets" assets_dir.mkdir(exist_ok=True) - example_asset = assets_dir / 'example_asset.txt' + example_asset = assets_dir / "example_asset.txt" example_asset.write_text(EXAMPLE_ASSET) print("✅ Created assets/example_asset.txt") except Exception as e: @@ -264,14 +263,16 @@ def init_skill(skill_name, path): print(f"\n✅ Skill '{skill_name}' initialized successfully at {skill_dir}") print("\nNext steps:") print("1. Edit SKILL.md to complete the TODO items and update the description") - print("2. Customize or delete the example files in scripts/, references/, and assets/") + print( + "2. Customize or delete the example files in scripts/, references/, and assets/" + ) print("3. Run the validator when ready to check the skill structure") return skill_dir def main(): - if len(sys.argv) < 4 or sys.argv[2] != '--path': + if len(sys.argv) < 4 or sys.argv[2] != "--path": print("Usage: init_skill.py --path ") print("\nSkill name requirements:") print(" - Hyphen-case identifier (e.g., 'data-analyzer')") diff --git a/.claude/skills/skill-creator/scripts/package_skill.py b/.claude/skills/skill-creator/scripts/package_skill.py index 3ee8e8e..8eebdc1 100755 --- a/.claude/skills/skill-creator/scripts/package_skill.py +++ b/.claude/skills/skill-creator/scripts/package_skill.py @@ -65,9 +65,9 @@ def package_skill(skill_path, output_dir=None): # Create the zip file try: - with zipfile.ZipFile(zip_filename, 'w', zipfile.ZIP_DEFLATED) as zipf: + with zipfile.ZipFile(zip_filename, "w", zipfile.ZIP_DEFLATED) as zipf: # Walk through the skill directory - for file_path in skill_path.rglob('*'): + for file_path in skill_path.rglob("*"): if file_path.is_file(): # Calculate the relative path within the zip arcname = file_path.relative_to(skill_path.parent) @@ -84,7 +84,9 @@ def package_skill(skill_path, output_dir=None): def main(): if len(sys.argv) < 2: - print("Usage: python utils/package_skill.py [output-directory]") + print( + "Usage: python utils/package_skill.py [output-directory]" + ) print("\nExample:") print(" python utils/package_skill.py skills/public/my-skill") print(" python utils/package_skill.py skills/public/my-skill ./dist") diff --git a/.claude/skills/skill-creator/scripts/quick_validate.py b/.claude/skills/skill-creator/scripts/quick_validate.py index 6fa6c63..f6dcaab 100755 --- a/.claude/skills/skill-creator/scripts/quick_validate.py +++ b/.claude/skills/skill-creator/scripts/quick_validate.py @@ -8,58 +8,66 @@ import re from pathlib import Path + def validate_skill(skill_path): """Basic validation of a skill""" skill_path = Path(skill_path) - + # Check SKILL.md exists - skill_md = skill_path / 'SKILL.md' + skill_md = skill_path / "SKILL.md" if not skill_md.exists(): return False, "SKILL.md not found" - + # Read and validate frontmatter content = skill_md.read_text() - if not content.startswith('---'): + if not content.startswith("---"): return False, "No YAML frontmatter found" - + # Extract frontmatter - match = re.match(r'^---\n(.*?)\n---', content, re.DOTALL) + match = re.match(r"^---\n(.*?)\n---", content, re.DOTALL) if not match: return False, "Invalid frontmatter format" - + frontmatter = match.group(1) - + # Check required fields - if 'name:' not in frontmatter: + if "name:" not in frontmatter: return False, "Missing 'name' in frontmatter" - if 'description:' not in frontmatter: + if "description:" not in frontmatter: return False, "Missing 'description' in frontmatter" - + # Extract name for validation - name_match = re.search(r'name:\s*(.+)', frontmatter) + name_match = re.search(r"name:\s*(.+)", frontmatter) if name_match: name = name_match.group(1).strip() # Check naming convention (hyphen-case: lowercase with hyphens) - if not re.match(r'^[a-z0-9-]+$', name): - return False, f"Name '{name}' should be hyphen-case (lowercase letters, digits, and hyphens only)" - if name.startswith('-') or name.endswith('-') or '--' in name: - return False, f"Name '{name}' cannot start/end with hyphen or contain consecutive hyphens" + if not re.match(r"^[a-z0-9-]+$", name): + return ( + False, + f"Name '{name}' should be hyphen-case (lowercase letters, digits, and hyphens only)", + ) + if name.startswith("-") or name.endswith("-") or "--" in name: + return ( + False, + f"Name '{name}' cannot start/end with hyphen or contain consecutive hyphens", + ) # Extract and validate description - desc_match = re.search(r'description:\s*(.+)', frontmatter) + desc_match = re.search(r"description:\s*(.+)", frontmatter) if desc_match: description = desc_match.group(1).strip() # Check for angle brackets - if '<' in description or '>' in description: + if "<" in description or ">" in description: return False, "Description cannot contain angle brackets (< or >)" return True, "Skill is valid!" + if __name__ == "__main__": if len(sys.argv) != 2: print("Usage: python quick_validate.py ") sys.exit(1) - + valid, message = validate_skill(sys.argv[1]) print(message) - sys.exit(0 if valid else 1) \ No newline at end of file + sys.exit(0 if valid else 1) diff --git a/.claude/skills/systematic-debugging/SKILL.md b/.claude/skills/systematic-debugging/SKILL.md index 60760c0..750332c 100644 --- a/.claude/skills/systematic-debugging/SKILL.md +++ b/.claude/skills/systematic-debugging/SKILL.md @@ -8,8 +8,8 @@ description: Find the root cause before writing fixes. Understanding why something breaks leads to correct fixes. Guessing wastes time and creates new problems. -Core principle: If you can't explain WHY it's broken, you're not ready to fix it. Every fix must address a specific, understood root cause. - +Core principle: If you can't explain WHY it's broken, you're not ready to fix it. Every +fix must address a specific, understood root cause. Use for any technical issue: test failures, build errors, bugs, unexpected behavior, performance problems. Especially valuable when previous attempts haven't worked or when tempted to try a "quick fix." @@ -18,36 +18,39 @@ Use for any technical issue: test failures, build errors, bugs, unexpected behav Read error messages completely. Stack traces, line numbers, and error codes contain valuable information. The error message often points directly to the problem. -Work to reproduce the issue reliably. If you can't trigger it consistently, gather more data before proposing solutions. Document the exact steps that trigger the failure. +Work to reproduce the issue reliably. If you can't trigger it consistently, gather more +data before proposing solutions. Document the exact steps that trigger the failure. -Check what changed recently. Review commits, new dependencies, configuration changes, environmental differences. Most bugs correlate with recent changes. +Check what changed recently. Review commits, new dependencies, configuration changes, +environmental differences. Most bugs correlate with recent changes. Follow the data flow backward from the error. Where does the bad value originate? Work through the call stack until you find the source. Understanding the complete path from source to symptom reveals the true problem. -When multiple components interact, add diagnostic output at each boundary to identify which component fails. This narrows the investigation to the specific failing layer. +When multiple components interact, add diagnostic output at each boundary to identify +which component fails. This narrows the investigation to the specific failing layer. Find similar code that works correctly. Compare the working and broken versions systematically. Every difference matters until proven otherwise. -When implementing a pattern, read reference implementations thoroughly. Understand their dependencies, settings, and environmental requirements. - +When implementing a pattern, read reference implementations thoroughly. Understand their +dependencies, settings, and environmental requirements. Form a clear hypothesis: "X causes the problem because Y." Test with the smallest possible change. Change one variable at a time to isolate the cause. -When a hypothesis proves wrong, form a new one based on what you learned. Don't layer fixes on top of failed attempts. - +When a hypothesis proves wrong, form a new one based on what you learned. Don't layer +fixes on top of failed attempts. Create a test that reproduces the issue before fixing it. This ensures you understand the problem and can verify the fix works. -Apply a single, focused fix that addresses the root cause. Resist bundling other improvements or refactoring. +Apply a single, focused fix that addresses the root cause. Resist bundling other +improvements or refactoring. -Verify the fix resolves the issue without breaking other functionality. - +Verify the fix resolves the issue without breaking other functionality. When multiple fix attempts fail in different ways, the architecture might be the problem. Signs include: @@ -55,8 +58,8 @@ When multiple fix attempts fail in different ways, the architecture might be the - Fixes require extensive refactoring to work properly - Each attempted fix creates new symptoms elsewhere -These patterns suggest reconsidering the fundamental approach rather than continuing to patch symptoms. - +These patterns suggest reconsidering the fundamental approach rather than continuing to +patch symptoms. Stop and investigate properly when thinking: @@ -71,5 +74,5 @@ These thoughts signal you're guessing rather than debugging systematically. If you don't understand something, say so clearly. Ask for help or research more. Understanding the problem before attempting fixes saves time and prevents introducing new bugs. -Systematic debugging finds and fixes the real problem. Random attempts waste time and create new issues. - +Systematic debugging finds and fixes the real problem. Random attempts waste time and +create new issues. diff --git a/.claude/skills/youtube-transcript-analyzer/SKILL.md b/.claude/skills/youtube-transcript-analyzer/SKILL.md index 1e84721..360b5ff 100644 --- a/.claude/skills/youtube-transcript-analyzer/SKILL.md +++ b/.claude/skills/youtube-transcript-analyzer/SKILL.md @@ -27,6 +27,7 @@ brew install yt-dlp # Verify installation yt-dlp --version ``` + @@ -38,7 +39,8 @@ ANALYSIS_DIR=$(mktemp -d) echo "Using temporary directory: $ANALYSIS_DIR" ``` -Download transcript using yt-dlp to extract subtitles/transcripts to the temporary directory: +Download transcript using yt-dlp to extract subtitles/transcripts to the temporary +directory: ```bash # Download transcript only (no video) @@ -51,14 +53,15 @@ yt-dlp --skip-download --write-sub --sub-lang en --sub-format vtt --output "$ANA yt-dlp --skip-download --print-json URL > "$ANALYSIS_DIR/metadata.json" ``` -Handle long transcripts - For transcripts exceeding 8,000 tokens (roughly 6,000 words or 45+ minutes): +Handle long transcripts - For transcripts exceeding 8,000 tokens (roughly 6,000 words or +45+ minutes): + 1. Split into logical chunks based on timestamp or topic breaks 2. Generate a summary for each chunk focusing on key concepts 3. Create an overall synthesis connecting themes to the user's question 4. Reference specific timestamps for detailed sections -For shorter transcripts, analyze directly without chunking. - +For shorter transcripts, analyze directly without chunking. When analyzing with respect to a project or question: @@ -71,40 +74,47 @@ When analyzing with respect to a project or question: Provide analysis in this format: Video Overview: + - Title, author, duration - Main topic and key themes Key Insights: + - Concept 1 with timestamp - Concept 2 with timestamp - Technical approaches explained Relevance to Your Project: + - Direct applications - Differences from current approach - Potential improvements or learnings Specific Recommendations: + - Actionable items based on video content -- Code patterns or techniques to consider - +- Code patterns or techniques to consider No transcript available: Some videos lack auto-generated or manual captions. Inform user and offer alternative approaches (video description, comments). -Multiple languages: Prefer English transcripts using --sub-lang en. If unavailable, check available languages with --list-subs. +Multiple languages: Prefer English transcripts using --sub-lang en. If unavailable, +check available languages with --list-subs. -Long processing time: Set expectations for videos over 2 hours. Offer to focus on specific sections if timestamps provided. - +Long processing time: Set expectations for videos over 2 hours. Offer to focus on +specific sections if timestamps provided. Focus analysis on practical application rather than comprehensive summaries. Users want to know "how does this help me" not "what did they say for 90 minutes." -Extract concrete examples and code patterns when available. Reference specific timestamps so users can jump to relevant sections. +Extract concrete examples and code patterns when available. Reference specific +timestamps so users can jump to relevant sections. -When comparing with project code, be specific about similarities and differences. Vague comparisons like "similar approach" don't add value. +When comparing with project code, be specific about similarities and differences. Vague +comparisons like "similar approach" don't add value. -For technical content, identify the underlying patterns and principles rather than surface-level implementation details. Help users understand transferable concepts. +For technical content, identify the underlying patterns and principles rather than +surface-level implementation details. Help users understand transferable concepts. diff --git a/.cursor/.gitignore b/.cursor/.gitignore index d9e7211..9011ab2 100644 --- a/.cursor/.gitignore +++ b/.cursor/.gitignore @@ -1,32 +1,25 @@ -# macOS -.DS_Store - +# Build artifacts # Editor/IDE -*.swp -*.local.json - +# Logs +# Node.js (for testing/examples) # Python (for testing/examples) +# Temporary files +# macOS +*.local.json +*.log *.pyc -__pycache__/ +*.swp +*.temp +*.tmp +.DS_Store +.created-prompts/ +.pnpm-store/ .pytest_cache/ -.venv/ .ruff_cache/ - -# Node.js (for testing/examples) -node_modules/ -.pnpm-store/ - -# Build artifacts +.venv/ +__pycache__/ bin/ -lib/ -dist/ build/ - -# Logs -*.log - -# Temporary files -*.tmp -*.temp - -.created-prompts/ +dist/ +lib/ +node_modules/ diff --git a/.github/workflows/build.yml b/.github/workflows/build.yml index 27b9c38..2496fda 100644 --- a/.github/workflows/build.yml +++ b/.github/workflows/build.yml @@ -12,7 +12,7 @@ jobs: steps: - name: Checkout Code - uses: actions/checkout@v5 + uses: actions/checkout@v6 - name: Run pre-commit uses: pre-commit/action@v3.0.1 @@ -27,7 +27,7 @@ jobs: steps: - name: Checkout Code - uses: actions/checkout@v5 + uses: actions/checkout@v6 - name: Setup Python uses: actions/setup-python@v6 diff --git a/.github/workflows/claude-code-review.yml b/.github/workflows/claude-code-review.yml index 07f89ea..c452652 100644 --- a/.github/workflows/claude-code-review.yml +++ b/.github/workflows/claude-code-review.yml @@ -27,7 +27,7 @@ jobs: steps: - name: Checkout repository - uses: actions/checkout@v5 + uses: actions/checkout@v6 with: fetch-depth: 1 diff --git a/.github/workflows/claude.yml b/.github/workflows/claude.yml index d1eb962..97eefe9 100644 --- a/.github/workflows/claude.yml +++ b/.github/workflows/claude.yml @@ -26,7 +26,7 @@ jobs: actions: read # Required for Claude to read CI results on PRs steps: - name: Checkout repository - uses: actions/checkout@v5 + uses: actions/checkout@v6 with: fetch-depth: 1 diff --git a/pyproject.toml b/pyproject.toml index 2407ff9..185e910 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -83,3 +83,4 @@ docstring-code-format = true [tool.ruff.lint.per-file-ignores] "test_*.py" = ["PLR0915", "ARG001", "ARG005", "SLF001", "F841"] "**/conftest.py" = ["ARG001"] +".claude/skills/*/scripts/*.py" = ["E501", "F401", "PLR0911", "T201", "TRY300"]