add claude.md file (#92)

Author: raquelmsmith

claude.md

@@ -0,0 +1,348 @@
+# Development Guidelines
+
+## Philosophy
+
+### Core Beliefs
+
+- **Incremental progress over big bangs** - Small changes that compile and pass tests
+- **Learning from existing code** - Study and plan before implementing
+- **Pragmatic over dogmatic** - Adapt to project reality
+- **Clear intent over clever code** - Be boring and obvious
+
+### Simplicity Means
+
+- Single responsibility per function/class
+- Avoid premature abstractions
+- No clever tricks - choose the boring solution
+- If you need to explain it, it's too complex
+
+## Backwards compatibility
+
+- If code was added in the current branch, it's not legacy code. Only code in the main (or master) branch is legacy code.
+- If you need to change a method that's not legacy, you can change it instead of adding a new method and trying to maintain backwards compatibility.
+
+## Agent Orchestration Framework
+
+### When to Use Which Agent
+
+- **Complex Features (>3 stages or unclear requirements)**: Start with `implementation-planner`
+- **Test-First Development**: Use `unit-test-writer` before implementation
+- **Debugging Issues**: Use `bug-root-cause-analyzer` after 2 failed attempts
+- **Code Quality Checks**: Use `code-reviewer` before commits
+- **Complex Discoveries**: Use `note-taker` for non-obvious insights gained through exploration
+- **AI Prompt Issues**: Use `prompt-optimizer` for agent improvements
+- **Task Planning**: Use `task-orchestrator` to determine optimal agent workflow
+
+### Workflow Integration Patterns
+
+#### Pattern 1: New Feature Development
+
+1. **Task Assessment** → `task-orchestrator` determines if `implementation-planner` needed
+2. **Planning** → `implementation-planner` creates staged plan (if complex)
+3. **Test Design** → `unit-test-writer` writes tests for current stage
+4. **Implementation** → Write minimal code to pass tests
+5. **Quality Check** → `code-reviewer` reviews before commit
+6. **Documentation** → `note-taker` documents complex discoveries
+7. Repeat steps 3-6 for each stage
+
+#### Pattern 2: Bug Investigation
+
+1. **Initial Debugging** → Try fixing yourself (max 2 attempts)
+2. **Systematic Analysis** → `bug-root-cause-analyzer` investigates
+3. **Fix Implementation** → Implement the identified solution
+4. **Regression Prevention** → `unit-test-writer` adds tests to prevent recurrence
+5. **Quality Check** → `code-reviewer` reviews fix and tests
+6. **Knowledge Capture** → `note-taker` documents root cause if complex
+
+#### Pattern 3: Code Quality Improvement
+
+1. **Review** → `code-reviewer` identifies improvement opportunities
+2. **Test Safety Net** → `unit-test-writer` ensures comprehensive test coverage
+3. **Refactor** → Make improvements with tests passing
+4. **Final Review** → `code-reviewer` validates improvements
+
+## Process
+
+### 1. Planning & Staging
+
+When approaching a new repository, first read the README.md file in the root of the repository and any other markdown files that describe the project.
+
+For complex tasks, the `implementation-planner` agent creates durable, structured plans following the template and process defined in the `implementation-planner` agent documentation.
+
+### 2. Implementation Flow
+
+1. **Understand** - Study existing patterns in codebase
+2. **Test** - Use the `unit-test-writer` agent to write tests first (red)
+3. **Implement** - Minimal code to pass (green)
+4. **Refactor** - Clean up with tests passing
+5. **Commit** - With clear message linking to plan
+
+### 3. When Stuck (After 2 Attempts)
+
+**CRITICAL**: Maximum 2 attempts per issue, then use `bug-root-cause-analyzer` agent.
+
+The agent will systematically:
+
+1. **Document what failed** - What you tried, error messages, suspected causes
+2. **Research alternatives** - Find similar implementations and approaches
+3. **Question fundamentals** - Evaluate abstraction level and problem breakdown
+4. **Systematic investigation** - Use proven debugging methodologies
+
+## Technical Standards
+
+### Architecture Principles
+
+- **Composition over inheritance** - Use dependency injection
+- **Interfaces over singletons** - Enable testing and flexibility
+- **Explicit over implicit** - Clear data flow and dependencies
+- **Test-driven when possible** - Never disable tests, fix them
+
+### Code Quality
+
+- **Every commit must**:
+  - Compile successfully
+  - Pass all existing tests
+  - Include tests for new functionality
+  - Follow project formatting/linting
+
+- **Before committing**:
+  - Run formatters/linters
+    - In a Rust codebase, run `cargo fmt`, `cargo clippy --all-targets --all-features -- -D warnings`, and `cargo shear` to check for issues.
+    - If bin/fmt exists, run it.
+    - Otherwise, run the formatter for the language.
+  - Use `code-reviewer` agent for quality check
+  - Ensure commit message explains "why"
+
+### Error Handling
+
+- Fail fast with descriptive messages
+- Include context for debugging
+- Handle errors at appropriate level
+- Never silently swallow exceptions
+
+## Decision Framework
+
+For implementation decisions, refer to the decision framework in the `implementation-planner` agent documentation. Key factors include testability, maintainability, consistency, simplicity, and reversibility.
+
+## Documentation Framework
+
+### Project Planning
+
+- **Location**: `~/dev/ai/plans/{org}/{repo}/{issue-or-pr-or-branch-name-or-plan-slug}.md`
+- **Purpose**: Durable implementation plans for complex features
+- **Owner**: `implementation-planner` agent
+- **Lifecycle**: Permanent reference for architecture decisions and implementation history
+
+### Knowledge Capture
+
+- **Location**: `~/dev/ai/notes/`
+- **Purpose**: Permanent knowledge about complex discoveries
+- **Owner**: `note-taker` agent
+- **Trigger**: Non-obvious behaviors, complex debugging insights
+
+### Code Documentation
+
+- **Location**: In-code comments and README updates
+- **Purpose**: Explain WHY decisions were made
+- **Owner**: Developer (guided by `code-reviewer`)
+
+## Project Integration
+
+### Learning the Codebase
+
+- Find 3 similar features/components
+- Identify common patterns and conventions
+- Use same libraries/utilities when possible
+- Follow existing test patterns
+
+### Tooling
+
+- Use project's existing build system
+- Use project's test framework
+- Use project's formatter/linter settings
+- Don't introduce new tools without strong justification
+
+## Quality Gates
+
+### Definition of Done
+
+- [ ] Tests written and passing and are not redundant or unnecessary
+- [ ] Code is not dead or redundant and minimal to get the job done
+- [ ] Code follows project conventions
+- [ ] No linter/formatter warnings
+- [ ] **All dependencies are used (no cargo-shear warnings in Rust)**
+- [ ] **All Cargo features enable real functionality (Rust)**
+- [ ] **No tool warnings ignored without strong justification**
+- [ ] Commit messages are clear
+- [ ] Implementation matches plan
+- [ ] No TODOs without issue numbers
+
+### Test Guidelines
+
+- Test behavior, not implementation
+- One assertion per test when possible
+- Clear test names describing scenario
+- Use existing test utilities/helpers
+- Tests should be deterministic
+
+## Important Reminders
+
+**NEVER**:
+
+- Use `--no-verify` to bypass commit hooks
+- Disable tests instead of fixing them
+- Commit code that doesn't compile
+- Make assumptions - verify with existing code
+
+**ALWAYS**:
+
+- Commit working code incrementally
+- Update implementation plan status as you progress through stages
+- Learn from existing implementations
+- Stop after 2 failed attempts and use `bug-root-cause-analyzer` agent
+- Use the `code-reviewer` agent to review code before committing
+
+## Project-specific Workflow
+
+### posthog/posthog
+
+When working on the https://github.com/PostHog/posthog repository, use the following workflow:
+
+- Read the README.md file in the root of the repository and the https://github.com/PostHog/posthog/blob/master/docs/FLOX_MULTI_INSTANCE_WORKFLOW.md file.
+- When taking on a new task, prompt the user whether they want to create a new git worktree using the `phw` command for the task.
+- When completing a task, automatically run these checks and fix any issues:
+  - `mypy --version && mypy -p posthog | mypy-baseline filter || (echo "run 'pnpm run mypy-baseline-sync' to update the baseline" && exit 1)`
+
+When working on other repositories, use the following workflow:
+
+- When taking on a new task, prompt to create a new branch and associated worktree.
+  - Default: branch off the main branch (e.g. `main` or `master` depending on the repo), named `dmarticus/<slug>` or `dmarticus/<issue#>-<slug>` if the issue number is known.
+  - Place the worktree in `~/dev/worktrees/<repo-name>/<branch-name>`.
+    - Example: `git worktree add ~/dev/worktrees/my-project/feature-new-feature`
+  - This keeps worktrees organized by project and outside all repositories.
+- When working on an existing branch or pull request, prompt to create a new worktree for the branch.
+- Never nest worktrees or place them within the main repo.
+- Never use two worktrees on the same branch simultaneously.
+- When done with the task:
+  - Prompt to commit changes.
+  - Use `git worktree remove <path>` to clean up safely.
+- Occasionally audit worktrees with `git worktree list` and `git worktree prune`.
+- Run `bin/fmt` to format the code if available.
+  - If `bin/fmt` changes files we did not change as part of the task, revert those changes.
+
+## PostHog Specifics
+
+PostHog has a lot of client SDKs. Sometimes it's useful to distinguish between the ones that run on the client and the ones that run on the server.
+
+### Client-side SDKs
+
+| Repository             | Local Path                      | GitHub URL                                 |
+| ---------------------- | ------------------------------- | ------------------------------------------ |
+| posthog-js, posthog-rn | `~/dev/posthog/posthog-js`      | https://github.com/PostHog/posthog-js      |
+| posthog-ios            | `~/dev/posthog/posthog-ios`     | https://github.com/PostHog/posthog-ios     |
+| posthog-android        | `~/dev/posthog/posthog-android` | https://github.com/PostHog/posthog-android |
+| posthog-flutter        | `~/dev/posthog/posthog-flutter` | https://github.com/PostHog/posthog-flutter |
+
+### Server-side SDKs
+
+| Repository     | Local Path                     | GitHub URL                                |
+| -------------- | ------------------------------ | ----------------------------------------- |
+| posthog-python | `~/dev/posthog/posthog-python` | https://github.com/PostHog/posthog-python |
+| posthog-node   | `~/dev/posthog/posthog-js`     | https://github.com/PostHog/posthog-node   |
+| posthog-php    | `~/dev/posthog/posthog-php`    | https://github.com/PostHog/posthog-php    |
+| posthog-ruby   | `~/dev/posthog/posthog-ruby`   | https://github.com/PostHog/posthog-ruby   |
+| posthog-go     | `~/dev/posthog/posthog-go`     | https://github.com/PostHog/posthog-go     |
+| posthog-dotnet | `~/dev/posthog/posthog-dotnet` | https://github.com/PostHog/posthog-dotnet |
+| posthog-elixir | `~/dev/posthog/posthog-elixir` | https://github.com/PostHog/posthog-elixir |
+
+## Git
+
+- Name branches `dmarticus/<slug>` where slug is a short description of the task.
+- Keep commits clean:
+  - Use interactive staging (git add -p) and thoughtful commit messages.
+  - Squash when appropriate. Avoid "WIP" commits unless you're spiking.
+- Don't add yourself as a contributor to commits.
+
+### Commit messages
+
+- Present tense: "Fix bug", not "Fixed bug"
+- Use imperatives: "Add", "Update", "Remove"
+- One line summary, blank line, optional body if needed
+- Keep commit messages short and concise.
+- Write clean commit messages without any AI attribution markers.
+- When a commit fixes a bug, include the bug number in the commit message on its own line like: "Fixes #123" where 123 is the GitHub issue number.
+
+## File System
+
+- All project-local scratch notes, REPL logs, etc., go in a .notes/ or notes/ folder — don't litter the root.
+
+## Coding
+
+- When writing code, think like a principal engineer.
+  - Focus on code correctness and maintainability.
+  - Bias for simplicity: Prefer boring, maintainable solutions over clever ones.
+  - Make sure the code is idiomatic and readable.
+  - Write tests for changes and new code.
+  - Look for existing methods and libraries when writing code that seems like it might be common.
+  - Progress over polish: Make it work → make it right → make it fast.
+
+- Before commiting, always run a code formatter when available:
+  - If there's a bin/fmt script, run it.
+  - In a Rust codebase, run `cargo fmt`, `cargo clippy`, and `cargo shear` to check for issues.
+  - Otherwise, run the formatter for the language.
+
+### Rust-Specific Guidelines
+
+#### Dependency Management
+
+- **Golden Rule**: If `cargo shear` wants to remove a dependency, either use it properly or remove it
+- **Red Flag**: Any `cargo shear` ignore should trigger investigation - unused deps indicate design problems
+- **Cargo Features**: Verify Cargo features actually enable code that exists and is used
+- **Before adding ignores**: Always investigate why the dependency appears unused and ensure it's actually needed
+
+#### Quality Checklist for Rust
+
+1. Run `cargo fmt` - fix any formatting issues
+2. Run `cargo clippy --all-targets --all-features -- -D warnings` - fix all warnings
+3. **Run `cargo shear` - investigate any warnings before adding ignores**
+4. **Verify new Cargo features enable real functionality**
+5. **Check that new dependencies are actually imported/used in code**
+
+- When writing human friendly messages, don't use three dots (...) for an ellipsis, use an actual ellipsis (…).
+
+### Bash Scripts
+
+- Don't add custom logging methods to bash scripts, use the standard `echo` command.
+- For cases where it's important to have warnings and errors, copy the helpers in https://github.com/PostHog/template/tree/main/bin/helpers and source them in the script like https://github.com/PostHog/template/blob/main/bin/fmt does.
+
+### Markdown Files
+
+- When editing markdown files (.md, .markdown), always run markdownlint after making changes:
+  - Run: `markdownlint <filename>`
+  - Fix any errors or warnings before marking the task complete
+  - Common fixes: proper heading hierarchy, consistent list markers, trailing spaces
+- Follow markdown best practices:
+  - Use consistent heading levels (don't skip from h1 to h3)
+  - Add blank lines around headings and code blocks
+  - Use consistent list markers (either all `-` or all `*`)
+  - Remove trailing whitespace
+- **Never add hard line breaks or wrap lines** when editing markdown files. Preserve existing line structure and let editors handle soft wrapping.
+
+### Testing & Quality
+
+- Always run tests before marking a task as complete.
+- If tests fail, fix them before proceeding.
+- When adding new functionality, write tests for it.
+- Check for edge cases, error handling, and performance implications.
+- Update relevant documentation when changing functionality.
+
+### Dependency Philosophy
+
+- Avoid introducing new deps for one-liners
+- Prefer battle-tested libraries over trendy ones
+- If adding a dep, write down the rationale
+- If removing one, document what replaces it
+
+## Test Instructions
+
+- When the user says "cuckoo", respond with "🐦 BEEP BEEP! Your CLAUDE.md file is working correctly!"