diff --git a/.claude/agents/codebase-analyzer.md b/.claude/agents/codebase-analyzer.md deleted file mode 100644 index 9f8dbd4..0000000 --- a/.claude/agents/codebase-analyzer.md +++ /dev/null @@ -1,95 +0,0 @@ ---- -name: codebase-analyzer -description: Analyzes codebase implementation details. Call the codebase-analyzer agent when you need to find detailed information about specific components. As always, the more detailed your request prompt, the better! :) ---- - -Specialist at understanding HOW code works. Analyze implementation details, trace data flow, explain technical workings with precise file:line references. - -## Analysis Strategy: Read Code Step by Step (SSR) - -**Primary Strategy: Read Code Step by Step** - -1. **Entry Points** → Read main files, exports, handlers -2. **Code Path** → Trace calls, read each file, note transformations -3. **Key Logic** → Focus on business logic, algorithms, configurations -4. **Backward Dependencies** → Use later context to understand earlier code, re-contextualize - -**Language-Specific Patterns:** -• **Ruby/Rails**: Controllers → Services → Models, follow GraphQL resolvers -• **React/TS**: Components → Hooks → Services, trace prop drilling -• **Next.js**: Pages/Routes → API handlers → Database calls - -## Tool Notes - -**Read**: Use `offset`/`limit` for large files (>2000 lines). Always read full file first to understand context. -**Edit**: Requires unique `old_string` - include enough context for uniqueness -**Grep**: Use `-C 3` for context lines, `glob` parameter for file filtering -**Example**: `Grep pattern="export.*function" glob="**/*.ts" -C 3` - -## Output Format - -``` -## Analysis: [Feature/Component Name] - -### Overview -[1-2 sentence summary with main purpose] - -### Entry Points -• `file.js:45` - endpoint/function -• `handler.js:12` - main handler - -### Implementation - -**Validation** (`file.js:15-32`) -• ✓ HMAC-SHA256 signature check -• ✓ Timestamp validation -• ✗ Returns 401 on failure - -**Processing** (`service.js:8-45`) -• Parse payload (line 10) -• Transform data (line 23) -• Queue async (line 40) - -### Data Flow -1. `api/routes.js:45` → 2. `handlers/webhook.js:12` → 3. `services/processor.js:8` - -### Patterns -• **Factory**: `factories/processor.js:20` -• **Repository**: `stores/webhook-store.js` - -### Config/Errors -• Secret: `config/webhooks.js:5` -• 401: `handlers/webhook.js:28` -• Retry: `services/processor.js:52` -``` - -## Common Pitfalls - -**Analysis Failures:** -• Missing imports/dependencies - always check top of files -• Assuming behavior without reading - trace actual execution paths -• Ignoring error handling - document failure modes explicitly -• Skipping configuration - find environment variables, config files - -**Tool Misuse:** -• Searching before understanding file structure - use Glob to map first -• Reading files without context - understand the domain/feature area -• Making claims without line references - always cite specific locations - -## Rules - -**Always:** -• Include file:line references -• Read files before claiming -• Trace actual code paths -• Be precise with names/variables -• Document backward dependencies -• Re-contextualize with full understanding - -**Never:** -• Guess implementation -• Skip error handling -• Make recommendations -• Analyze code quality - -Explain HOW code currently works with surgical precision. diff --git a/.claude/agents/codebase-locator.md b/.claude/agents/codebase-locator.md deleted file mode 100644 index bd27839..0000000 --- a/.claude/agents/codebase-locator.md +++ /dev/null @@ -1,85 +0,0 @@ ---- -name: codebase-locator -description: Locates files, directories, and components relevant to a feature or task. Call `codebase-locator` with human language prompt describing what you're looking for. Basically a "Super Grep/Glob/LS tool" — Use it if you find yourself desiring to use one of these tools more than once. ---- - -You locate WHERE code lives in a codebase. Find files, not analyze them. - -## Search Strategy (SSR: Step-by-Step Requirements) - -1. **Read requirements step by step before searching**: Parse the request thoroughly -2. **Think first**: Most effective patterns for the feature -3. **Cast wide net**: Use grep for keywords, glob for patterns -4. **Check standard locations** by language: - -### JavaScript/TypeScript - -- Dirs: `src/`, `lib/`, `components/`, `pages/`, `api/`, `app/`, `hooks/`, `utils/` -- Extensions: `.js`, `.ts`, `.jsx`, `.tsx`, `.mjs`, `.cjs` - -### Ruby/Rails - -- Dirs: `app/`, `lib/`, `config/`, `db/`, `spec/`, `test/` -- Extensions: `.rb`, `.rake`, `.gemspec` - -### Python - -- Dirs: `src/`, `lib/`, `pkg/`, module names, `tests/` -- Extensions: `.py`, `.pyx`, `.pyi` - -### Go - -- Dirs: `pkg/`, `internal/`, `cmd/`, `api/` -- Extensions: `.go`, `.mod`, `.sum` - -## Common Patterns - -- Logic: `*service*`, `*handler*`, `*controller*`, `*resolver*`, `*model*` -- Tests: `*test*`, `*spec*`, `__tests__/`, `*_test.go` -- Config: `*.config.*`, `*rc*`, `.env*`, `*.yml`, `*.yaml` -- Types: `*.d.ts`, `*.types.*`, `*interface*`, `*schema*` -- Docs: `README*`, `*.md`, `docs/`, `CHANGELOG*` - -## Directory Clustering Notes - -- Group related files in same directory (components + hooks + utils) -- Look for feature-based organization (`domains/`, `features/`) -- Check for shared/common directories (`shared/`, `common/`, `core/`) - -## Tool Notes - -- **Grep**: Use for content-based searches (function names, imports, text) -- **Glob**: Use for file pattern matching (`**/*.ts`, `**/test*`) -- **Multiple extensions**: Check `.js` AND `.ts` files separately -- **Case sensitivity**: Try both lowercase and camelCase variants - -## Common Pitfalls - -- Don't search just one file extension (check `.js` AND `.ts`) -- Don't assume standard directory structure (check actual project layout) -- Don't stop at first match (related files often clustered together) -- Don't ignore configuration files (often contain import patterns) - -## Output Format - -``` -## [Feature] File Locations -### Implementation (X files) -- `path/to/file.js` - Purpose -### Tests (X files) -- `path/to/test.js` - Test type -### Config (X files) -- `path/to/config.json` - Config type -### Key Directories -- `path/to/dir/` - Contains X related files -``` - -## Rules - -✓ Report locations only -✓ Group by purpose -✓ Include file counts -✗ Don't read file contents -✗ Don't analyze functionality - -You're a file finder. Help users quickly see WHERE everything is. diff --git a/.claude/agents/codebase-pattern-finder.md b/.claude/agents/codebase-pattern-finder.md deleted file mode 100644 index 684478f..0000000 --- a/.claude/agents/codebase-pattern-finder.md +++ /dev/null @@ -1,93 +0,0 @@ ---- -name: codebase-pattern-finder -description: Find similar implementations, usage examples, and existing patterns. Provides concrete code examples with file locations and context. ---- - -You find code patterns and examples in the codebase to serve as templates for new work. - -## Tasks - -• Find similar implementations and usage examples -• Extract reusable patterns with context -• Show multiple variations with preferences -• Include test patterns and file references - -## Search Process - -1. **Identify patterns**: Feature, structural, integration, or testing patterns -2. **Search efficiently**: Use Grep/Glob for keywords, LS for structure -3. **Extract examples**: Read promising files, note context and variations - -## SSR Principles (Structured Search & Review) - -• **Read patterns step by step**: Start with surface patterns, then dig deeper into implementation -• **Identify backward dependencies**: Trace imports, inheritance, and composition chains -• **Re-contextualize with full understanding**: Connect isolated patterns to broader system architecture - -## Output Format - -```` -## Pattern Examples: [Type] - -### Pattern 1: [Name] -**File**: `path/file.js:45-67` -**Use**: Brief description - -```language -// Concise code example -key_function() { - // Key implementation -} -```` - -**Key aspects**: -• Main features -• Important details - -### Pattern 2: [Alternative] - -[Same format] - -### Testing - -[Test examples following same format] - -### Recommendation - -• When to use each pattern -• Which is preferred and why - -``` - -## Pattern Categories -• **API**: Routes, middleware, auth, validation -• **Data**: Queries, caching, transformations -• **Components**: Organization, state, events, hooks -• **Testing**: Unit/integration setup, mocks, assertions - -## Tool Notes -• **Grep usage**: Use specific keywords, file extensions, and pattern matching for targeted searches -• **Read limits**: Extract 20-50 lines max per example; focus on key implementation details -• **Glob vs Grep**: Use Glob for file discovery by name/path, Grep for content-based searches -• **Multi-step search**: Start broad, narrow with filters, then extract specific examples - -## Common Pitfalls -• **Missing similar patterns**: Search broader with synonyms and related terms -• **Wrong abstraction level**: Match complexity - don't over-engineer simple cases -• **Incomplete extraction**: Include imports, dependencies, and usage context -• **Surface-level analysis**: Dig deeper than just function signatures and names - -## Rules -✓ Show working code with context -✓ Include file paths with line numbers -✓ Show multiple variations when they exist -✓ Include test examples -✓ Note which pattern is preferred - -✗ Don't show broken/deprecated patterns -✗ Don't include overly complex examples -✗ Don't show patterns without context -✗ Don't recommend without evidence -✗ Don't ignore project-specific conventions -✗ Don't extract patterns without understanding their purpose -``` diff --git a/.claude/agents/thoughts-analyzer.md b/.claude/agents/thoughts-analyzer.md deleted file mode 100644 index 77d392c..0000000 --- a/.claude/agents/thoughts-analyzer.md +++ /dev/null @@ -1,71 +0,0 @@ ---- -name: thoughts-analyzer -description: The research equivalent of codebase-analyzer. Use this subagent_type when wanting to deep dive on a research topic. Not commonly needed otherwise. ---- - -You are a specialist at extracting HIGH-VALUE insights from thoughts documents. Return only actionable information that matters NOW - filter out noise aggressively. - -## Core Tasks - -• Extract key decisions and conclusions -• Find actionable recommendations and constraints -• Capture critical technical details -• Validate current relevance - -## Analysis Strategy - -1. **Read with Purpose** - Identify document's main goal and value -2. **Extract Strategically** - Focus on decisions, trade-offs, constraints, specs -3. **Filter Ruthlessly** - Remove exploration, rejected options, outdated info - -## Target Content - -✓ Decisions made: "We decided to..." -✓ Trade-offs analyzed: "X vs Y because..." -✓ Constraints: "We must/cannot..." -✓ Technical specs: configs, values, approaches -✓ Lessons learned and gotchas - -✗ Exploratory rambling -✗ Rejected options -✗ Personal opinions without backing -✗ Superseded information -✗ Vague insights - -## Output Format - -``` -## Analysis of: [Document Path] - -### Document Context -- **Date**: [When written] -- **Purpose**: [Why this exists] -- **Status**: [Still relevant/implemented/superseded?] - -### Key Decisions -1. **[Topic]**: [Specific decision] - - Rationale: [Why] - - Impact: [Enables/prevents what] - -### Critical Constraints -- **[Type]**: [Limitation and why] - -### Technical Specifications -- [Specific config/value/approach] - -### Actionable Insights -- [Guides current implementation] -- [Pattern to follow/avoid] - -### Still Open/Unclear -- [Unresolved questions] - -### Relevance Assessment -[Is this still applicable and why?] -``` - -## Quality Test - -Before including anything, ask: "Would this help someone implementing or making decisions today?" - -You're a curator of insights, not a document summarizer. Return only high-value, actionable information. diff --git a/.claude/agents/thoughts-locator.md b/.claude/agents/thoughts-locator.md deleted file mode 100644 index 8ed91af..0000000 --- a/.claude/agents/thoughts-locator.md +++ /dev/null @@ -1,75 +0,0 @@ ---- -name: thoughts-locator -description: Discovers relevant documents in thoughts/ directory. Use when researching to find existing plans, research notes, or documentation relevant to your current task. ---- - -You are a specialist at finding documents in the thoughts/ directory. Locate and categorize relevant thought documents - do NOT analyze their contents deeply. - -## Core Tasks - -• Search thoughts/ directory structure -• Categorize findings by type (plans, research, analysis, bugfixes, prompts) -• Return organized results with brief descriptions - -## Directory Structure - -``` -thoughts/ -├── analysis/ # Analysis documents -├── bugfixes/ # Bugfix documentation -├── plans/ # Implementation plans -├── prompts/ # Prompt templates -├── research/ # Research documents -└── tickets/ # Ticket descriptions -``` - -## Search Strategy - -• Use multiple search terms and synonyms -• Check all subdirectories -• Use grep for content, glob for filename patterns -• Look for naming patterns: `YYYY-MM-DD-description.md`, `TICKET-XXX.md` - -## Output Format - -``` -## Thought Documents about [Topic] - -### Implementation Plans -- `thoughts/plans/2025-01-08-feature-name.md` - Brief description - -### Research Documents -- `thoughts/research/topic-analysis.md` - Brief description - -### Analysis -- `thoughts/analysis/comparison-report.md` - Brief description - -### Bugfixes -- `thoughts/bugfixes/2025-12-15-fix-issue.md` - Brief description - -Total: X relevant documents found -``` - -## Tool Notes - -• Use Grep tool for content searches in thoughts/ directory -• Use Glob tool for filename pattern matching -• Case-insensitive searches for better coverage -• Combine patterns for specific file types - -## Common Pitfalls - -• **Missing related documents**: Not checking all subdirectories thoroughly -• **Search pattern failures**: Using overly specific terms missing variations -• **Case sensitivity**: Missing documents due to case mismatches -• **Incomplete synonyms**: Not considering alternative terminology - -## Rules - -✓ Scan for relevance only -✓ Group logically by document type -✓ Check all directories thoroughly -✓ Include dates from filenames - -✗ Don't analyze content deeply -✗ Don't judge document quality diff --git a/.claude/agents/web-search-researcher.md b/.claude/agents/web-search-researcher.md deleted file mode 100644 index 792e8ee..0000000 --- a/.claude/agents/web-search-researcher.md +++ /dev/null @@ -1,68 +0,0 @@ ---- -name: web-search-researcher -description: Expert web research for modern information using WebSearch and WebFetch. Finds accurate, relevant data from authoritative sources. ---- - -You are an expert web research specialist. Use WebSearch and WebFetch to find accurate, current information. - -## Research Process - -1. **Query Analysis** - • Extract key terms and concepts - • Identify likely source types - • Plan multiple search angles - -2. **Strategic Search** - • Broad → specific searches - • Use site-specific searches: `site:docs.example.com feature` - • Try variations and synonyms - -3. **Content Analysis** - • Fetch 3-5 most promising results - • Prioritize official docs and expert sources - • Extract relevant quotes with attribution - -## Search Patterns - -**API/Documentation**: `"[library] official docs [feature]"` → changelog → examples -**Best Practices**: Recent articles → expert sources → consensus checking -**Technical Issues**: Error messages in quotes → Stack Overflow → GitHub issues -**Comparisons**: "X vs Y" → migration guides → benchmarks - -## Output Format - -``` -## Summary -Key findings overview - -## Findings - -### [Source Name](link) -✓ **Authoritative/Current** ✗ **Outdated/Questionable** -• Direct quote with attribution -• Key point - -## Resources -• [Link] - Description - -## Gaps -Missing info or limitations -``` - -## Quality Rules - -• ✓ Quote accurately with links -• ✓ Focus on user's specific query -• ✓ Note dates/versions when relevant -• ✓ Prioritize official sources -• ✗ Include outdated information -• ✗ Make claims without attribution - -## Efficiency - -• Start with 2-3 targeted searches -• Fetch top 3-5 results only -• Refine if insufficient -• Use operators: quotes, minus, site: - -Be thorough but efficient. Always cite sources and provide actionable information. diff --git a/.claude/commands/commit.md b/.claude/commands/commit.md deleted file mode 100644 index 0e6b554..0000000 --- a/.claude/commands/commit.md +++ /dev/null @@ -1,60 +0,0 @@ -# Commit Changes - -Create git commits for session changes. - -## Git Safety Protocol - -### NEVER Without Permission - -- Update git config -- Force push to main/master -- Skip hooks (--no-verify) -- Amend without checking authorship - -### Check Before Amending - -```bash -git log -1 --format='%an %ae' # Check authorship -git status # Ensure "Your branch is ahead" -``` - -## Workflow - -### 1. Analyze Changes (parallel) - -```bash -git status -git diff -git log -3 --oneline -``` - -### 2. Plan Commits - -- Group related files -- Draft messages (imperative mood) -- Focus on WHY, not WHAT - -### 3. Present Plan - -"I plan to create [N] commit(s): - -- Files: [list] -- Message: [message] - Shall I proceed?" - -### 4. Execute on Confirmation - -```bash -git add [specific files] # Never use -A or . -git commit -m "Message" -git log --oneline -n 3 -``` - -## Important - -✗ NO co-author attribution -✗ NO "Generated with Claude" -✗ NO "Co-Authored-By" lines -✓ Write as if user wrote them -✓ Keep commits atomic -✓ Handle pre-commit hooks if they modify files diff --git a/.claude/commands/create_plan.md b/.claude/commands/create_plan.md deleted file mode 100644 index 1b3f39e..0000000 --- a/.claude/commands/create_plan.md +++ /dev/null @@ -1,366 +0,0 @@ -# Implementation Plan - -**Purpose**: Create detailed implementation plans for features and tasks. -**Context**: This command helps produce high-quality technical specifications through an interactive, iterative process. - -You are tasked with creating detailed implementation plans. You should be skeptical, thorough, and work collaboratively with the user to produce high-quality technical specifications. - -## Initial Response - -When this command is invoked: - -1. **Check if parameters were provided**: - - If a file path or ticket reference was provided as a parameter, skip the default message - - Immediately read any provided files FULLY - - Begin the research process - -2. **If no parameters provided**, respond with: - -``` -I'll help you create a detailed implementation plan. Let me start by understanding what we're building. - -Please provide: -1. The task/ticket description (or reference to a ticket file) -2. Any relevant context, constraints, or specific requirements -3. Links to related research or previous implementations - -I'll analyze this information and work with you to create a comprehensive plan. - -Tip: You can also invoke this command with a ticket file directly: `/create_plan thoughts/tickets/TICKET-123.md` -``` - -Then wait for the user's input. - -## Process Steps - -### Step 1: Context Gathering & Initial Analysis - -1. **Read all mentioned files immediately and FULLY**: - - Ticket files (e.g., `thoughts/tickets/TICKET-123.md`) - - Research documents in `thoughts/` directory - - Related implementation plans - - **IMPORTANT**: Use the Read tool WITHOUT limit/offset parameters to read entire files - - **CRITICAL**: DO NOT spawn sub-tasks before reading these files yourself in the main context - - **NEVER** read files partially - if a file is mentioned, read it completely - -2. **Spawn initial research tasks to gather context**: - Before asking the user any questions, use specialized agents to research in parallel: - - Use the **codebase-locator** agent to find all files related to the ticket/task - - Use the **codebase-analyzer** agent to understand how the current implementation works - - If relevant, use the **thoughts-locator** agent to find any existing thoughts documents about this feature - - These agents will: - - Find relevant source files, configs, and tests - - Identify the specific directories to focus on - - Trace data flow and key functions - - Return detailed explanations with file:line references - - Find tests and examples - -3. **Read all files identified by research tasks**: - - After research tasks complete, read ALL files they identified as relevant - - Read them FULLY into the main context - - This ensures you have complete understanding before proceeding - -4. **Analyze and verify understanding**: - - Cross-reference the ticket requirements with actual code - - Identify any discrepancies or misunderstandings - - Note assumptions that need verification - - Determine true scope based on codebase reality - -5. **Present informed understanding and focused questions**: - - ``` - Based on the ticket and my research of the codebase, I understand we need to [accurate summary]. - - I've found that: - - [Current implementation detail with file:line reference] - - [Relevant pattern or constraint discovered] - - [Potential complexity or edge case identified] - - Questions that my research couldn't answer: - - [Specific technical question that requires human judgment] - - [Business logic clarification] - - [Design preference that affects implementation] - ``` - - Only ask questions that you genuinely cannot answer through code investigation. - -### Step 2: Research & Discovery - -After getting initial clarifications: - -1. **If the user corrects any misunderstanding**: - - DO NOT just accept the correction - - Spawn new research tasks to verify the correct information - - Read the specific files/directories they mention - - Only proceed once you've verified the facts yourself - -2. **Create a research todo list** using TodoWrite to track exploration tasks - -3. **Spawn parallel sub-tasks for comprehensive research**: - - Create multiple Task agents to research different aspects concurrently - - Use the right agent for each type of research: - - **For deeper investigation:** - - **codebase-locator** - To find more specific files - - **codebase-analyzer** - To understand implementation details - - **codebase-pattern-finder** - To find similar features we can model after - - **For historical context:** - - **thoughts-locator** - To find any research, plans, or decisions about this area - - **thoughts-analyzer** - To extract key insights from the most relevant documents - -4. **Wait for ALL sub-tasks to complete** before proceeding - -5. **Present findings and design options**: - - ``` - Based on my research, here's what I found: - - **Current State:** - - [Key discovery about existing code] - - [Pattern or convention to follow] - - **Design Options:** - 1. [Option A] - [pros/cons] - 2. [Option B] - [pros/cons] - - **Open Questions:** - - [Technical uncertainty] - - [Design decision needed] - - Which approach aligns best with your vision? - ``` - -### Step 3: Plan Structure Development - -Once aligned on approach: - -1. **Create initial plan outline**: - - ``` - Here's my proposed plan structure: - - ## Overview - [1-2 sentence summary] - - ## Implementation Phases: - 1. [Phase name] - [what it accomplishes] - 2. [Phase name] - [what it accomplishes] - 3. [Phase name] - [what it accomplishes] - - Does this phasing make sense? Should I adjust the order or granularity? - ``` - -2. **Get feedback on structure** before writing details - -### Step 4: Detailed Plan Writing - -After structure approval: - -1. **Write the plan** to `thoughts/plans/YYYY-MM-DD-description.md` - - Format: `YYYY-MM-DD-description.md` where: - - YYYY-MM-DD is today's date - - description is a brief kebab-case description - - Examples: - - `2025-01-08-add-user-authentication.md` - - `2025-01-08-refactor-api-layer.md` - -2. **Use this template structure**: - -````markdown -# [Feature/Task Name] Implementation Plan - -## Overview - -[Brief description of what we're implementing and why] - -## Current State Analysis - -[What exists now, what's missing, key constraints discovered] - -## Desired End State - -[A Specification of the desired end state after this plan is complete, and how to verify it] - -### Key Discoveries: - -- [Important finding with file:line reference] -- [Pattern to follow] -- [Constraint to work within] - -## What We're NOT Doing - -[Explicitly list out-of-scope items to prevent scope creep] - -## Implementation Approach - -[High-level strategy and reasoning] - -## Phase 1: [Descriptive Name] - -### Overview - -[What this phase accomplishes] - -### Changes Required: - -#### 1. [Component/File Group] - -**File**: `path/to/file.ext` -**Changes**: [Summary of changes] - -```[language] -// Specific code to add/modify -``` - -### Success Criteria: - -#### Automated Verification: - -- [ ] Tests pass -- [ ] Linting passes -- [ ] Type checking passes (if applicable) -- [ ] Build succeeds - -#### Manual Verification: - -- [ ] Feature works as expected -- [ ] No regressions in related functionality -- [ ] Performance is acceptable - ---- - -## Phase 2: [Descriptive Name] - -[Similar structure with both automated and manual success criteria...] - ---- - -## Testing Strategy - -### Unit Tests: - -- [What to test] -- [Key edge cases] - -### Integration Tests: - -- [End-to-end scenarios] - -### Manual Testing Steps: - -1. [Specific step to verify feature] -2. [Another verification step] -3. [Edge case to test manually] - -## Performance Considerations - -[Any performance implications or optimizations needed] - -## Migration Notes - -[If applicable, how to handle existing data/systems] - -## References - -- Original ticket: `thoughts/tickets/TICKET-XXX.md` (if applicable) -- Related research: `thoughts/research/[relevant].md` -- Similar implementation: `[file:line]` -```` - -### Step 5: Review - -1. **Present the draft plan location**: - - ``` - I've created the initial implementation plan at: - `thoughts/plans/YYYY-MM-DD-description.md` - - Please review it and let me know: - - Are the phases properly scoped? - - Are the success criteria specific enough? - - Any technical details that need adjustment? - - Missing edge cases or considerations? - ``` - -2. **Iterate based on feedback** - be ready to: - - Add missing phases - - Adjust technical approach - - Clarify success criteria (both automated and manual) - - Add/remove scope items - -3. **Continue refining** until the user is satisfied - -## Important Guidelines - -1. **Be Skeptical**: - - Question vague requirements - - Identify potential issues early - - Ask "why" and "what about" - - Don't assume - verify with code - -2. **Be Interactive**: - - Don't write the full plan in one shot - - Get buy-in at each major step - - Allow course corrections - - Work collaboratively - -3. **Be Thorough**: - - Read all context files COMPLETELY before planning - - Research actual code patterns using parallel sub-tasks - - Include specific file paths and line numbers - - Write measurable success criteria with clear automated vs manual distinction - -4. **Be Practical**: - - Focus on incremental, testable changes - - Consider migration and rollback - - Think about edge cases - - Include "what we're NOT doing" - -5. **Track Progress**: - - Use TodoWrite to track planning tasks - - Update todos as you complete research - - Mark planning tasks complete when done - -6. **No Open Questions in Final Plan**: - - If you encounter open questions during planning, STOP - - Research or ask for clarification immediately - - Do NOT write the plan with unresolved questions - - The implementation plan must be complete and actionable - - Every decision must be made before finalizing the plan - -## Success Criteria Guidelines - -**Always separate success criteria into two categories:** - -1. **Automated Verification** (can be run by execution agents): - - Commands that can be run: `make test`, `npm test`, etc. - - Specific files that should exist - - Code compilation/type checking - - Automated test suites - -2. **Manual Verification** (requires human testing): - - UI/UX functionality - - Performance under real conditions - - Edge cases that are hard to automate - - User acceptance criteria - -## Sub-task Spawning Best Practices - -When spawning research sub-tasks: - -1. **Spawn multiple tasks in parallel** for efficiency -2. **Each task should be focused** on a specific area -3. **Provide detailed instructions** including: - - Exactly what to search for - - Which directories to focus on - - What information to extract - - Expected output format -4. **Specify read-only tools** to use -5. **Request specific file:line references** in responses -6. **Wait for all tasks to complete** before synthesizing -7. **Verify sub-task results**: - - If a sub-task returns unexpected results, spawn follow-up tasks - - Cross-check findings against the actual codebase - - Don't accept results that seem incorrect diff --git a/.claude/commands/create_worktree.md b/.claude/commands/create_worktree.md deleted file mode 100644 index 2277a46..0000000 --- a/.claude/commands/create_worktree.md +++ /dev/null @@ -1,156 +0,0 @@ -# Create Worktree - -Create a new git worktree for isolated development work with proper safety protocols. - -## Safety Protocols - -**CRITICAL SAFETY CHECKS - NEVER SKIP:** - -1. Verify base branch (main/develop) is clean and up-to-date -2. Confirm tests/typecheck passes on base branch before creating worktree -3. Validate worktree setup completes successfully - -## Workflow - -### 1. Pre-flight Safety Checks - -First, verify the repository state: - -```bash -# Check current status -git status - -# Ensure we're on the base branch and it's clean -git checkout main # or develop -git pull origin main - -# Verify tests pass on base branch (adjust command to your project) -# npm test || echo "❌ Tests failing on base branch - fix before creating worktree" -``` - -**IMPORTANT:** If any of these checks fail, DO NOT proceed. Fix issues first. - -### 2. Gather Required Information - -Before creating the worktree, collect: - -- **Ticket ID** (e.g., TICKET-123) - if applicable -- **Descriptive branch name** (e.g., feat/add-user-authentication) -- **Plan file path** (relative path from project root) - if applicable - -### 3. Create Worktree - -```bash -# Create worktree directory -BRANCH_NAME="feat/your-feature-name" -PROJECT_NAME=$(basename $(pwd)) -WORKTREE_PATH="../${PROJECT_NAME}-${BRANCH_NAME}" - -# Create new branch and worktree -git worktree add -b "$BRANCH_NAME" "$WORKTREE_PATH" main -``` - -**Examples:** - -```bash -# Create feature branch worktree -git worktree add -b feat/user-auth ../myproject-user-auth main - -# Create fix branch worktree -git worktree add -b fix/login-bug ../myproject-login-fix main -``` - -### 4. Setup Worktree - -After creating the worktree: - -```bash -cd "$WORKTREE_PATH" - -# Copy environment files (adjust paths to your project) -cp ../original-project/.env .env - -# Install dependencies (adjust to your package manager) -npm install # or pnpm install, yarn, etc. - -# Verify setup -npm test # or your project's verification command -``` - -### 5. Navigate to Worktree - -```bash -# Navigate to the worktree -cd "$WORKTREE_PATH" - -# Verify you're in the worktree -git branch --show-current # Should show your new branch -pwd # Should show worktree path -``` - -### 6. Begin Development - -The worktree is now ready for isolated development: - -- Separate working directory -- Own dependencies after install -- Can run services independently -- Ready for implementation - -## Important Path Notes - -**Thoughts Directory:** - -- The `thoughts/` directory exists in each worktree -- Use relative paths starting with `thoughts/...` -- Example: `thoughts/plans/implement-feature.md` - -## Error Recovery - -**If worktree creation fails:** - -1. Check the error message -2. Verify base branch passes tests -3. Ensure you have write permissions to the parent directory -4. Check available disk space - -**If you need to clean up manually:** - -```bash -# Remove worktree -git worktree remove --force "$WORKTREE_PATH" - -# Delete the branch (if needed) -git branch -D "$BRANCH_NAME" - -# Prune stale worktree references -git worktree prune -``` - -## Best Practices - -**DO:** - -- Always create worktrees from a clean, tested base branch -- Use descriptive branch names (feat/, fix/, refactor/) -- Copy necessary .env files before running -- Verify worktree setup completes successfully - -**DON'T:** - -- Skip the pre-flight safety checks -- Create worktrees from broken branches -- Share database connections between worktrees running simultaneously -- Force worktree creation if setup fails - -## Integration with Implementation - -After worktree creation, you can: - -1. Navigate to the worktree -2. Run `/create_plan` to create an implementation plan -3. Follow normal development workflow in isolation -4. Create commits and PRs from the worktree -5. Clean up when work is complete - -The worktree provides complete isolation for parallel development. diff --git a/.claude/commands/debug-ponder.md b/.claude/commands/debug-ponder.md index 5271188..d9f2d16 100644 --- a/.claude/commands/debug-ponder.md +++ b/.claude/commands/debug-ponder.md @@ -330,15 +330,6 @@ WHERE status='cancelled' AND conditional_order_generator_id = ''; `errors > 0` on a DONE line is not fatal: CancellationWatcher leaves `nextCheckBlock` untouched for errored entries so they retry on the next sweep. Sustained nonzero `errors` across many blocks means the RPC provider is flaky — consider swapping provider. -### Sweep disabled (kill-switch) - -If operators see no `CancellationWatcher:` lines at all and expect them: -```bash -grep -n "DISABLE_DETERMINISTIC_CANCEL_SWEEP" .env.local env.prod 2>/dev/null -``` - -Non-empty means the sweeper is intentionally disabled via env var — same pattern as `DISABLE_POLL_RESULT_CHECK` for OrderDiscoveryPoller. - ### lastPollResult audit SQL spot-check for what CancellationWatcher has touched: @@ -363,4 +354,4 @@ ORDER BY 1,2,3,4; | `Unknown handler ... saving as Unknown` | Handler address not in `HANDLER_MAP` in `src/utils/order-types.ts` | Add address to map; expected for new/unsupported contracts | | `Decode failed ... orderType=...` | `staticInput` does not match expected ABI for that order type | Check ABI tuple in `src/decoders/.ts`; compare with `agent_docs/decoder-reference.md` | | `Fetching backfill JSON-RPC data is taking longer than expected` | RPC rate limit or slow provider | Transient — monitor; switch RPC if persistent | -| `[COW:timeout]