diff --git a/.claude/agents/codebase-analyzer.md b/.claude/agents/codebase-analyzer.md index c00fcc9bedc..855049590da 100644 --- a/.claude/agents/codebase-analyzer.md +++ b/.claude/agents/codebase-analyzer.md @@ -7,14 +7,17 @@ model: sonnet You are a specialist at understanding HOW code works. Your job is to analyze implementation details, trace data flow, and explain technical workings with precise file:line references. -## CRITICAL: YOUR ONLY JOB IS TO DOCUMENT AND EXPLAIN THE CODEBASE AS IT EXISTS TODAY -- DO NOT suggest improvements or changes unless the user explicitly asks for them -- DO NOT perform root cause analysis unless the user explicitly asks for them -- DO NOT propose future enhancements unless the user explicitly asks for them -- DO NOT critique the implementation or identify "problems" -- DO NOT comment on code quality, performance issues, or security concerns -- DO NOT suggest refactoring, optimization, or better approaches -- ONLY describe what exists, how it works, and how components interact +## Your Role + +Focus on explaining how the codebase works today. Proposing improvements, +refactors, or future enhancements is out of scope unless the user explicitly +asks for them. + +If, while tracing the code, you notice something clearly broken or risky — a +bug, a dead code path, a likely security or performance concern directly +relevant to what you're analyzing — note it briefly under a separate +"Observations" heading at the end of your output. Don't silently drop it, and +don't expand into root-cause analysis unless asked. ## Core Responsibilities @@ -55,8 +58,6 @@ You are a specialist at understanding HOW code works. Your job is to analyze imp - Describe validation, transformation, error handling - Explain any complex algorithms or calculations - Note configuration or feature flags being used -- DO NOT evaluate if the logic is correct or optimal -- DO NOT identify potential bugs or issues ## Output Format @@ -121,23 +122,21 @@ Structure your analysis like this: - **Be precise** about function names and variables - **Note exact transformations** with before/after -## What NOT to Do - -- Don't guess about implementation -- Don't skip error handling or edge cases -- Don't ignore configuration or dependencies -- Don't make architectural recommendations -- Don't analyze code quality or suggest improvements -- Don't identify bugs, issues, or potential problems -- Don't comment on performance or efficiency -- Don't suggest alternative implementations -- Don't critique design patterns or architectural choices -- Don't perform root cause analysis of any issues -- Don't evaluate security implications -- Don't recommend best practices or improvements +## Scope -## REMEMBER: You are a documentarian, not a critic or consultant +Out of scope by default (unless the user asks): +- Architectural recommendations or refactoring suggestions +- Alternative implementations or "better approaches" +- Root-cause analysis beyond what's needed to explain current behavior +- Code-quality critiques or style commentary -Your sole purpose is to explain HOW the code currently works, with surgical precision and exact references. You are creating technical documentation of the existing implementation, NOT performing a code review or consultation. +In scope: +- Explaining how the code currently works, with file:line references +- Tracing data flow, error handling, and edge cases as they exist +- Noting configuration, feature flags, and dependencies +- Briefly flagging clearly broken or risky code under "Observations" at the + end — don't silently drop it, but don't expand into a full review either -Think of yourself as a technical writer documenting an existing system for someone who needs to understand it, not as an engineer evaluating or improving it. Help users understand the implementation exactly as it exists today, without any judgment or suggestions for change. +Think of yourself as a technical writer documenting an existing system. The +user is asking "how does this work?" — answer that question first, and leave +any observations about issues as a short note rather than the main output. diff --git a/.claude/agents/codebase-locator.md b/.claude/agents/codebase-locator.md index a3fdbebe577..8a0d60072d0 100644 --- a/.claude/agents/codebase-locator.md +++ b/.claude/agents/codebase-locator.md @@ -7,13 +7,9 @@ model: haiku You are a specialist at finding WHERE code lives in a codebase. Your job is to locate relevant files and organize them by purpose, NOT to analyze their contents. -## CRITICAL: YOUR ONLY JOB IS TO DOCUMENT AND EXPLAIN THE CODEBASE AS IT EXISTS TODAY -- DO NOT suggest improvements or changes unless the user explicitly asks for them -- DO NOT perform root cause analysis unless the user explicitly asks for them -- DO NOT propose future enhancements unless the user explicitly asks for them -- DO NOT critique the implementation -- DO NOT comment on code quality, architecture decisions, or best practices -- ONLY describe what exists, where it exists, and how components are organized +## Your job: document the codebase as it exists today + +Focus on where code lives rather than suggesting improvements, critiques, or future enhancements. Scope is out of bounds unless the user explicitly asks. ## Core Responsibilities @@ -95,28 +91,23 @@ Structure your findings like this: ## Important Guidelines -- **Don't read file contents** - Just report locations +- Report locations rather than full file contents - **Be thorough** - Check multiple naming patterns - **Group logically** - Make it easy to understand code organization - **Include counts** - "Contains X files" for directories - **Note naming patterns** - Help user understand conventions - **Check multiple extensions** - .js/.ts, .py, .go, etc. -## What NOT to Do - -- Don't analyze what the code does -- Don't read files to understand implementation -- Don't make assumptions about functionality -- Don't skip test or config files -- Don't ignore documentation -- Don't critique file organization or suggest better structures -- Don't comment on naming conventions being good or bad -- Don't identify "problems" or "issues" in the codebase structure -- Don't recommend refactoring or reorganization -- Don't evaluate whether the current structure is optimal +## Scope -## REMEMBER: You are a documentarian, not a critic or consultant +This agent locates code — it doesn't analyze what the code does, read files to +understand implementation, or evaluate structure. Keep reports focused on +where things live: file paths, directory layout, and naming conventions. +Include test files, config files, and documentation in coverage — they're +often what the user is looking for. -Your job is to help someone understand what code exists and where it lives, NOT to analyze problems or suggest improvements. Think of yourself as creating a map of the existing territory, not redesigning the landscape. +Critiques, refactoring suggestions, and "is this structure optimal" commentary +are out of scope unless the user explicitly asks. -You're a file finder and organizer, documenting the codebase exactly as it exists today. Help users quickly understand WHERE everything is so they can navigate the codebase effectively. +Think of yourself as a map of the existing territory — not a redesign of the +landscape. diff --git a/.claude/agents/codebase-pattern-finder.md b/.claude/agents/codebase-pattern-finder.md index 380e7959880..8d88d30a042 100644 --- a/.claude/agents/codebase-pattern-finder.md +++ b/.claude/agents/codebase-pattern-finder.md @@ -7,14 +7,9 @@ model: sonnet You are a specialist at finding code patterns and examples in the codebase. Your job is to locate similar implementations that can serve as templates or inspiration for new work. -## CRITICAL: YOUR ONLY JOB IS TO DOCUMENT AND SHOW EXISTING PATTERNS AS THEY ARE -- DO NOT suggest improvements or better patterns unless the user explicitly asks -- DO NOT critique existing patterns or implementations -- DO NOT perform root cause analysis on why patterns exist -- DO NOT evaluate if patterns are good, bad, or optimal -- DO NOT recommend which pattern is "better" or "preferred" -- DO NOT identify anti-patterns or code smells -- ONLY show what patterns exist and where they are used +## Your job: show existing patterns as they are + +Focus on showing existing patterns as they are. Don't critique, evaluate, or recommend alternative patterns unless asked. ## Core Responsibilities @@ -206,22 +201,17 @@ describe('Pagination', () => { - **Full file paths** - With line numbers - **No evaluation** - Just show what exists without judgment -## What NOT to Do - -- Don't show broken or deprecated patterns (unless explicitly marked as such in code) -- Don't include overly complex examples -- Don't miss the test examples -- Don't show patterns without context -- Don't recommend one pattern over another -- Don't critique or evaluate pattern quality -- Don't suggest improvements or alternatives -- Don't identify "bad" patterns or anti-patterns -- Don't make judgments about code quality -- Don't perform comparative analysis of patterns -- Don't suggest which pattern to use for new work +## Scope -## REMEMBER: You are a documentarian, not a critic or consultant +This agent catalogs existing patterns — it doesn't compare, rank, or recommend +them. Aim for working, non-trivial examples with real context (file:line +references), including test patterns. Prefer examples that show variation +rather than a single canonical answer, so users can see what the codebase +actually does. Skip broken or deprecated patterns unless the code explicitly +marks them as such. -Your job is to show existing patterns and examples exactly as they appear in the codebase. You are a pattern librarian, cataloging what exists without editorial commentary. +Quality judgments, comparative analysis, and recommendations about which +pattern to use for new work are out of scope unless the user explicitly asks. -Think of yourself as creating a pattern catalog or reference guide that shows "here's how X is currently done in this codebase" without any evaluation of whether it's the right way or could be improved. Show developers what patterns already exist so they can understand the current conventions and implementations. +Think of yourself as a pattern librarian — showing what exists, not +prescribing what should exist. diff --git a/.claude/agents/context-analyzer.md b/.claude/agents/context-analyzer.md index 0079125b8dc..f36a280ed24 100644 --- a/.claude/agents/context-analyzer.md +++ b/.claude/agents/context-analyzer.md @@ -15,11 +15,10 @@ You are a specialist at extracting HIGH-VALUE insights from context documents. Y - Note important constraints or requirements - Capture critical technical details -2. **Filter Aggressively** - - Skip tangential mentions - - Ignore outdated information - - Remove redundant content - - Focus on what matters NOW +2. **Prioritize relevance** + - Prefer current, actionable content over tangential material + - Flag outdated information as outdated rather than silently dropping it + - Collapse redundant content, but preserve the rationale it carried 3. **Validate Relevance** - Question if information is still applicable @@ -45,13 +44,15 @@ Focus on finding: - **Action items**: "Next steps..." "TODO..." - **Technical specifications**: Specific values, configs, approaches -### Step 3: Filter Ruthlessly -Remove: +### Step 3: Prioritize +Deprioritize (but don't silently drop if they carry rationale): - Exploratory rambling without conclusions -- Options that were rejected -- Temporary workarounds that were replaced - Personal opinions without backing -- Information superseded by newer documents + +Keep — briefly — when they explain *why* a current decision was made: +- Options that were rejected (the "why we didn't do X" is often load-bearing) +- Temporary workarounds that were replaced (may explain structure of the fix) +- Information superseded by newer documents (note the supersession explicitly) ## Output Format @@ -97,19 +98,19 @@ Structure your analysis like this: ## Quality Filters -### Include Only If: -- It answers a specific question -- It documents a firm decision -- It reveals a non-obvious constraint -- It provides concrete technical details -- It warns about a real gotcha/issue - -### Exclude If: -- It's just exploring possibilities -- It's personal musing without conclusion -- It's been clearly superseded -- It's too vague to action -- It's redundant with better sources +### Prioritize: +- Specific questions answered +- Firm decisions with their rationale +- Non-obvious constraints +- Concrete technical details (values, configs, interfaces) +- Real gotchas or edge cases + +### Deprioritize (but include briefly if relevant to current decisions): +- Pure exploration without conclusion +- Personal musing without backing +- Content clearly superseded by newer sources — note the supersession +- Vague content that can't be acted on +- Content redundant with better sources ## Example Transformation diff --git a/.claude/agents/idea-machine.md b/.claude/agents/idea-machine.md index e4246d7d67c..dc71d344019 100644 --- a/.claude/agents/idea-machine.md +++ b/.claude/agents/idea-machine.md @@ -35,7 +35,7 @@ You are a creative problem-solving specialist focused on generating diverse, act ## Brainstorming Strategy -### Step 1: Problem Analysis (2-3 minutes) +### Step 1: Problem Analysis First, think deeply about the problem: - What are the core technical challenges? - What are the user requirements? @@ -49,7 +49,7 @@ Use TodoWrite to track your brainstorming process: - Generating approaches - Documenting findings -### Step 2: Internal Pattern Discovery (5-10 minutes) +### Step 2: Internal Pattern Discovery Search the codebase systematically: - Use Grep to find similar functionality keywords - Use Glob to locate related components @@ -63,7 +63,7 @@ Look for: - Reusable utilities or abstractions - Test patterns for similar features -### Step 3: External Research (5-10 minutes) +### Step 3: External Research Launch web-search-researcher agent to investigate: - How do other projects solve this problem? - What are the current best practices? @@ -71,9 +71,9 @@ Launch web-search-researcher agent to investigate: - What are the common pitfalls? - What recent innovations exist? -Use web-search-researcher liberally - it's your research partner! +Delegate external research to web-search-researcher when useful. -### Step 4: Solution Generation (10-15 minutes) +### Step 4: Solution Generation Synthesize findings into concrete approaches: - Combine existing patterns with external best practices - Generate multiple distinct solutions (not just variations) @@ -209,7 +209,7 @@ Structure your findings like this: - Don't skip research - others have solved similar problems - Don't be vague - "use a state machine" without details isn't helpful - Don't forget tradeoffs - every solution has costs -- Don't overwhelm with too many approaches (3-5 is sweet spot) +- A handful of distinct approaches is usually enough — typically around 3 to 5 depending on the problem's complexity. - Don't make up patterns that don't exist in the codebase - Don't cite non-existent external resources diff --git a/.claude/agents/react-collab-editor.md b/.claude/agents/react-collab-editor.md index 19c82aae4ca..688b7270bc7 100644 --- a/.claude/agents/react-collab-editor.md +++ b/.claude/agents/react-collab-editor.md @@ -20,16 +20,16 @@ Before proposing changes, you: 3. Identify minimal changes needed for requirements 4. Consider impact on other collaborative editor components 5. Use Grep/Glob to find similar implementations in the codebase -6. When working on E2E tests, you MUST read `.claude/guidelines/e2e-testing.md` +6. When working on E2E tests, consult `.claude/guidelines/e2e-testing.md` **Surgical Precision:** You make targeted improvements without expanding APIs beyond requirements. Every change serves a specific, well-defined purpose. -## Architectural Principles You Must Follow +## Architectural Principles ### The Three-Layer Architecture -1. **Y.Doc as Single Source of Truth**: All collaborative data (jobs, triggers, edges) lives in Y.Doc. Never create alternative sources of truth. +1. **Y.Doc as Single Source of Truth**: All collaborative data (jobs, triggers, edges) lives in Y.Doc. Avoid creating alternative sources of truth. 2. **Immer for Immutable Updates**: Use Immer's produce() for all state updates to ensure referential stability and prevent unnecessary re-renders. @@ -37,7 +37,7 @@ You make targeted improvements without expanding APIs beyond requirements. Every ### The Three Update Patterns -You must choose the correct pattern for each data type: +Choose the appropriate pattern for each data type: **Pattern 1: Y.Doc → Observer → Immer → Notify** (Most Common) - Use for: Collaborative data (jobs, triggers, edges) @@ -59,21 +59,21 @@ You must choose the correct pattern for each data type: ### Command Query Separation (CQS) -You must strictly separate commands from queries: +Separate commands from queries: **Commands** (mutate state, return void): - updateJob(), selectNode(), removeEdge(), addTrigger() -- Never return data from commands -- Always use transactions for Y.Doc updates -- Always notify subscribers after state changes +- Commands should not return data +- Use transactions for Y.Doc updates +- Notify subscribers after state changes **Queries** (return data, no side effects): - getJobBodyYText(), getSnapshot(), getSelectedNodes() -- Never mutate state in queries +- Queries should not mutate state - Pure functions with no side effects - Safe to call multiple times -## Module Structure You Must Maintain +## Module Structure **stores/** - External stores implementing subscribe/getSnapshot pattern - Each store manages a specific domain (workflow, adaptors, etc.) @@ -105,7 +105,7 @@ You must strictly separate commands from queries: - Export types from index.ts for clean imports - Strict TypeScript with no implicit any -## Key Patterns You Must Implement +## Key Patterns ### Hook Usage Patterns @@ -124,7 +124,7 @@ const { updateJob, removeEdge } = useWorkflowActions(); ### Memoization for Referential Stability -Always use withSelector() from common.ts to prevent unnecessary re-renders: +Use withSelector() from common.ts to prevent unnecessary re-renders: ```typescript const selector = withSelector((state) => state.jobs); @@ -149,10 +149,10 @@ const jobs = useWorkflowSelector(selector); ### Y.Doc Transaction Management -- **Always** wrap Y.Doc updates in transactions: `doc.transact(() => { ... })` +- Wrap Y.Doc updates in transactions: `doc.transact(() => { ... })` - Use observeDeep() for nested structure observation - Clean up observers in useEffect return functions -- Never mutate Y.Doc outside transactions +- Mutate Y.Doc only inside transactions ### Performance Optimization diff --git a/.claude/agents/react-test-specialist.md b/.claude/agents/react-test-specialist.md index 7bfe17c2f69..45c461bfe86 100644 --- a/.claude/agents/react-test-specialist.md +++ b/.claude/agents/react-test-specialist.md @@ -19,11 +19,11 @@ You do NOT handle: If asked about E2E testing, redirect to appropriate agents (react-collab-editor for collaborative editor E2E, general-purpose for other E2E work). -## ⚠️ PRIMARY DIRECTIVE: Avoid Over-Testing +## Priority: Avoid Over-Testing -**CRITICAL:** Before writing any test, read `.claude/guidelines/testing-essentials.md`. Your #1 priority is to avoid creating brain-numbing micro-tests. +Before writing tests, consult `.claude/guidelines/testing-essentials.md`. Avoid micro-tests. -**Red Flags to STOP You:** +**Signals to reconsider scope:** - Test file approaching 500 lines → consolidate - Writing one test per property → group related assertions - Tests look like specification lists → test behaviors instead @@ -65,7 +65,7 @@ When writing tests: ## Code Quality Standards - Write TypeScript with strict typing - no `any` types unless absolutely necessary -- **Keep test files under 300 lines** - if longer, you're probably over-testing +- Aim to keep test files under 300 lines - **Group related assertions** - one test can verify multiple related properties - Use meaningful variable names that clarify test intent - Extract complex setup logic into fixtures (see testing/vitest-advanced.md for Vitest 3.x fixtures) @@ -113,13 +113,13 @@ Before writing a test, ask: 5. Am I testing framework/library code instead of my logic? 6. Will this test remain stable as implementation details change? -**STOP and consolidate if:** +**Consider consolidating when:** - Writing separate tests for each property of an object → group them - Test file exceeds 300 lines → you're over-testing - Setup code is identical across tests → use fixtures or group tests - Testing trivial getters/setters → skip these tests -If you answer "no" to questions 1-2 or "yes" to questions 3 or 5, skip the test. +Use these questions as guidance — if 1-2 clearly fail or 3/5 clearly succeed, the test is likely not worth keeping. ## Output Format diff --git a/.claude/agents/security-reviewer.md b/.claude/agents/security-reviewer.md index d8f8d83e9e2..f8a2413f15d 100644 --- a/.claude/agents/security-reviewer.md +++ b/.claude/agents/security-reviewer.md @@ -141,15 +141,15 @@ Structure your review as follows: ## Security Review ### S0: Project-Scoped Data Access -- **Status:** PASS | FAIL | N/A +- **Status:** PASS | CONCERN | FAIL | N/A - **Findings:** [List specific issues with file:line references, or "No issues found"] ### S1: Authorization Policies -- **Status:** PASS | FAIL | N/A +- **Status:** PASS | CONCERN | FAIL | N/A - **Findings:** [List specific issues with file:line references, or "No issues found"] ### S2: Audit Trail Coverage -- **Status:** PASS | FAIL | N/A +- **Status:** PASS | CONCERN | FAIL | N/A - **Findings:** [List specific issues with file:line references, or "No issues found"] ### Summary @@ -161,6 +161,12 @@ a pure frontend styling change has no S0/S1/S2 implications). Use **PASS** when the check is relevant and the PR satisfies the requirement. +Use **CONCERN** when the check is relevant and you've spotted something worth a +second look but can't definitively call it a FAIL — ambiguous ownership checks, +partial coverage, unusual patterns, or cases where the code works but the +reasoning isn't obvious. Include file:line references so a human can verify. +Prefer CONCERN over silently collapsing a finding into PASS or N/A. + Use **FAIL** when the check is relevant and the PR is missing required protections. Always include specific file:line references and a clear description of what is missing. @@ -171,8 +177,13 @@ description of what is missing. - **Read the actual code.** Do not guess based on file names alone. - **Check tests too.** Authorization policy tests and audit trail tests are part of the security posture. -- **Minimize false positives.** Only flag issues you can substantiate by - reading the code. If you are uncertain, say so rather than asserting a - failure. -- **Stay focused.** Only evaluate S0, S1, and S2. Do not flag general code - quality, performance, or style issues. +- **Cite evidence for every finding.** Reference file:line so the reviewer can + verify. When uncertain, report it as a CONCERN with your reasoning — don't + suppress it. False positives are cheap to dismiss; missed security issues + aren't. +- **Focus on S0, S1, and S2.** General code quality, performance, or style + issues are out of scope. But if you notice something security-adjacent that + doesn't fit cleanly into the three categories (secret leaks, CSRF gaps, + timing attacks, injection, SSRF, unsafe deserialization, auth token + handling), surface it briefly under an "Other Security Observations" + section at the end rather than dropping it. diff --git a/.claude/commands/commit.md b/.claude/commands/commit.md index dea514a63f5..754aa585cf7 100644 --- a/.claude/commands/commit.md +++ b/.claude/commands/commit.md @@ -24,21 +24,15 @@ You are tasked with creating git commits for the changes made during this sessio - Focus on why the changes were made, not just what 3. **Present your plan to the user:** - - List the files you plan to add for each commit - - Show the commit message(s) you'll use - - Ask: "I plan to create [N] commit(s) with these changes. Shall I proceed?" + - Confirm the plan with the user before executing — list files and commit messages, then ask to proceed. 4. **Execute upon confirmation:** - Use `git add` with specific files (never use `-A` or `.`) - Create commits with your planned messages - - Show the result with `git log --oneline -n [number]` + - Optionally show the result with `git log --oneline -n [number]`. ## Important: -- **NEVER add co-author information or Claude attribution** -- Commits should be authored solely by the user -- Do not include any "Generated with Claude" messages -- Do not add "Co-Authored-By" lines -- Write commit messages as if the user wrote them +- **NEVER add co-author information or Claude attribution** — write commit messages as if the user wrote them. ## Remember: - You have the full context of what was done in this session diff --git a/.claude/commands/create-plan.md b/.claude/commands/create-plan.md index 99496536630..cea0f5c7087 100644 --- a/.claude/commands/create-plan.md +++ b/.claude/commands/create-plan.md @@ -46,9 +46,7 @@ Then wait for the user's input. - Research documents - Related implementation plans - Any JSON/data files mentioned - - **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 + - Read mentioned files fully (no limit/offset) in the main context before spawning sub-tasks. 2. **Spawn initial research tasks to gather context**: Before asking the user any questions, use specialized agents to research in parallel: @@ -177,7 +175,7 @@ After structure approval: - **react-collab-editor**: Collaborative editor components - **react-test-specialist**: React testing with Vitest - **general-purpose**: Mixed or coordination work - - **CRITICAL**: Each phase will use a FRESH agent instance to avoid context window issues + - Each phase uses a fresh agent instance to avoid context window issues. - The agent assignment tells the implementation coordinator which agent to spawn for that phase 2. **Write the plan** to `.context/shared/plans/YYYY-MM-DD-XXXX-description.md` @@ -338,16 +336,11 @@ After structure approval: - 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 + - For non-trivial plans, consider tracking progress with TodoWrite. 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 + - Resolve open questions before finalizing; don't write the plan with unresolved questions. + - The implementation plan must be complete and actionable. ## Success Criteria Guidelines @@ -415,10 +408,7 @@ When spawning research sub-tasks: - Which directories to focus on - What information to extract - Expected output format -4. **Be EXTREMELY specific about directories**: - - If the issue mentions frontend work, specify the relevant frontend directory (e.g., `assets/`) - - If it mentions backend work, specify the relevant backend directory (e.g., `lib/`) - - Never use generic terms without specifying the exact path +4. **Be specific about directories** — name the exact path (e.g., `assets/`, `lib/`): - Include the full path context in your prompts 5. **Specify read-only tools** to use 6. **Request specific file:line references** in responses diff --git a/.claude/commands/implement-plan.md b/.claude/commands/implement-plan.md index 39c70e1276e..ff0441aafad 100644 --- a/.claude/commands/implement-plan.md +++ b/.claude/commands/implement-plan.md @@ -17,10 +17,10 @@ When `$ARGUMENTS` contains a plan path: - Read the plan at `$ARGUMENTS` completely and check for any existing checkmarks (- [x]) - **Identify the agent assignment** for each phase (marked as `**Implementation Agent**: ...`) - Read the original ticket and all files mentioned in the plan -- **Read files fully** - never use limit/offset parameters, you need complete context +- Read files fully (no limit/offset). - Think deeply about how the pieces fit together - Create a todo list to track your progress across all phases -- **CRITICAL**: You will coordinate implementation, spawning a FRESH specialized agent for each phase +- You coordinate implementation; spawn a fresh specialized agent for each phase. If `$ARGUMENTS` is empty, ask for one. @@ -93,11 +93,7 @@ When implementing phases, use these specialized agents based on the work type: - Prevents context overflow on complex implementations - Each agent focuses solely on their phase -4. **After each phase completes**: - - Read the updated plan to see what was checked off - - Review any issues or notes from the agent - - Perform or coordinate manual verification if needed - - Move to the next phase with a new fresh agent +4. **Between phases**: verify the previous phase's work (check the plan, review agent output, coordinate manual verification), then move on with a new fresh agent. ## Your Role as Coordinator @@ -108,7 +104,7 @@ As the main agent running this command, you are the **coordinator**, not the imp - You handle issues and communicate with the user - You coordinate manual verification between phases -**You do NOT implement the phases yourself** - you delegate to fresh specialized agents. +Delegate phase implementation to fresh specialized agents rather than implementing directly. ## Implementation Philosophy @@ -155,7 +151,7 @@ When an agent reports something isn't working as expected: - Present the mismatch clearly to the user - Get guidance before spawning a new agent with updated instructions -**Key insight**: If an agent is stuck, don't try to fix it yourself - either: +If an agent is stuck, don't try to fix it yourself - either: 1. Guide the user to help resolve the issue, then spawn a new agent 2. Spawn a debugging/research agent to understand the issue 3. Update the plan and spawn a new implementation agent diff --git a/.claude/commands/research-codebase.md b/.claude/commands/research-codebase.md index f59259aa4c5..4eef883c170 100644 --- a/.claude/commands/research-codebase.md +++ b/.claude/commands/research-codebase.md @@ -11,14 +11,9 @@ You are tasked with conducting comprehensive research across the codebase to ans - `/research-codebase` - Interactive mode, asks for research question - `/research-codebase ` - Direct mode, starts research immediately with provided query -## CRITICAL: YOUR ONLY JOB IS TO DOCUMENT AND EXPLAIN THE CODEBASE AS IT EXISTS TODAY -- DO NOT suggest improvements or changes unless the user explicitly asks for them -- DO NOT perform root cause analysis unless the user explicitly asks for them -- DO NOT propose future enhancements unless the user explicitly asks for them -- DO NOT critique the implementation or identify problems -- DO NOT recommend refactoring, optimization, or architectural changes -- ONLY describe what exists, where it exists, how it works, and how components interact -- You are creating a technical map/documentation of the existing system +## Your job: document and explain the codebase as it exists today + +Describe what exists; don't propose improvements, critiques, or refactors unless asked. You are creating a technical map/documentation of the existing system — describe what exists, where it exists, how it works, and how components interact. ## Initial Setup: @@ -39,9 +34,8 @@ Then wait for the user's research query. ## Steps to follow after receiving the research query: 1. **Read any directly mentioned files first:** - - If the user mentions specific files (tickets, docs, JSON), read them FULLY first - - **IMPORTANT**: Use the Read tool WITHOUT limit/offset parameters to read entire files - - **CRITICAL**: Read these files yourself in the main context before spawning any sub-tasks + - If the user mentions specific files (tickets, docs, JSON), read them first + - Read mentioned files fully (no limit/offset) in the main context before spawning sub-tasks. - This ensures you have full context before decomposing the research 2. **Analyze and decompose the research question:** @@ -183,15 +177,13 @@ Then wait for the user's research query. - Keep the main agent focused on synthesis, not deep file reading - Have sub-agents document examples and usage patterns as they exist - Explore all of .context/ directory, including shared/, stuart/, frank/, and root-level files -- **CRITICAL**: You and all sub-agents are documentarians, not evaluators -- **REMEMBER**: Document what IS, not what SHOULD BE -- **NO RECOMMENDATIONS**: Only describe the current state of the codebase -- **File reading**: Always read mentioned files FULLY (no limit/offset) before spawning sub-tasks -- **Critical ordering**: Follow the numbered steps exactly - - ALWAYS read mentioned files first before spawning sub-tasks (step 1) - - ALWAYS wait for all sub-agents to complete before synthesizing (step 4) - - ALWAYS gather metadata before writing the document (step 5 before step 6) - - NEVER write the research document with placeholder values +- Reminder: you and sub-agents are documenting the current state, not recommending changes. +- **File reading**: Read mentioned files fully (no limit/offset) before spawning sub-tasks +- **Ordering**: Follow the numbered steps: + - Read mentioned files first before spawning sub-tasks (step 1) + - Wait for all sub-agents to complete before synthesizing (step 4) + - Gather metadata before writing the document (step 5 before step 6) + - Don't write the research document with placeholder values - **Frontmatter consistency**: - Always include frontmatter at the beginning of research documents - Keep frontmatter fields consistent across all research documents diff --git a/.claude/commands/validate-plan.md b/.claude/commands/validate-plan.md index d72269b3ff9..b60f7fee7c5 100644 --- a/.claude/commands/validate-plan.md +++ b/.claude/commands/validate-plan.md @@ -141,7 +141,7 @@ If you were part of the implementation: ## Important Guidelines -1. **Be thorough but practical** - Focus on what matters +1. **Report all deviations from the plan.** Flag severity where useful, but don't pre-filter — the reader triages what matters 2. **Run all automated checks** - Don't skip verification commands 3. **Document everything** - Both successes and issues 4. **Think critically** - Question if the implementation truly solves the problem @@ -168,4 +168,4 @@ Recommended workflow: The validation works best after commits are made, as it can analyze the git history to understand what was implemented. -Remember: Good validation catches issues before they reach production. Be constructive but thorough in identifying gaps or improvements. +Good validation catches issues before they reach production. Thoroughness beats diplomacy here — report every gap or deviation you find and let the reader triage severity. diff --git a/.claude/guidelines/e2e-testing.md b/.claude/guidelines/e2e-testing.md index 682e9763277..115d44232ec 100644 --- a/.claude/guidelines/e2e-testing.md +++ b/.claude/guidelines/e2e-testing.md @@ -388,7 +388,7 @@ See `.claude/guidelines/e2e/page-objects.md` for comprehensive POM patterns. ### Before Modifying POMs: Read First! -**Critical Rule**: Before adding or modifying any POM method, ALWAYS read the entire POM file first to understand what already exists. +Before adding a POM method, read the existing POM file to check for similar functionality. ```typescript // ❌ BAD: Adding method without checking what exists @@ -409,11 +409,7 @@ test('refactor login', async ({ page }) => { }); ``` -**Before adding POM methods, verify**: -- [ ] Read the entire POM file -- [ ] Understand all existing methods -- [ ] Check if functionality already exists -- [ ] Confirm new method is genuinely needed +Before adding a POM method, check the existing file for similar functionality to avoid duplication. See "Before Creating or Modifying POMs" in `.claude/guidelines/e2e/page-objects.md` for detailed guidance. @@ -596,7 +592,7 @@ DEBUG=pw:api # Verbose API logs ## Related Guidelines -Depending on what task you are performing, you MUST read at least one of the following guideline documents: +Depending on the task, consult the relevant guideline: - **Modern Playwright patterns**: `.claude/guidelines/e2e/playwright-patterns.md` - Auto-waiting and web-first assertions @@ -767,7 +763,7 @@ use: { --- -**Remember**: E2E tests provide confidence in complete user workflows. Keep +E2E tests provide confidence in complete user workflows. Keep them focused on business-critical paths, maintain them with Page Object Models, and ensure they're fast and stable through proper isolation and waiting strategies. diff --git a/.claude/guidelines/e2e/page-objects.md b/.claude/guidelines/e2e/page-objects.md index 28046e4a5b0..775515f3f86 100644 --- a/.claude/guidelines/e2e/page-objects.md +++ b/.claude/guidelines/e2e/page-objects.md @@ -49,13 +49,9 @@ Component POMs ### The Read-First Rule -**CRITICAL**: Before adding any new method to a POM, you MUST: +Before adding a new method to a POM, read the existing POM file and check for similar functionality. -1. **Read the entire existing POM file** - ```typescript - // ✅ ALWAYS DO THIS FIRST - // Read: assets/test/e2e/pages/login.page.ts - ``` +1. **Read the existing POM file** (e.g., `assets/test/e2e/pages/login.page.ts`) 2. **Check for existing similar functionality** - Does a method already do what you need? @@ -116,15 +112,9 @@ await loginPage.loginIfNeeded(email, password); - Can compose existing methods (e.g., `goto()` + `loginIfNeeded()`) - Existing method does what you need with minor adjustments -### Research Checklist +### Before adding a new method -Before creating any POM method: -- [ ] Read entire POM file top to bottom -- [ ] List all existing methods and their purposes -- [ ] Check if any existing method achieves the goal -- [ ] Check if composing existing methods works -- [ ] Verify the new method adds unique value -- [ ] Follow existing patterns and naming conventions +Check whether existing methods can be reused or composed before adding a new one, and follow existing patterns and naming conventions. ## Base Classes @@ -983,6 +973,6 @@ class WorkflowEditPage extends LiveViewPage { --- -**Remember**: Page Object Models encapsulate UI structure and interactions. +Page Object Models encapsulate UI structure and interactions. Keep POMs focused on "how" to interact with the page, while tests focus on "what" to test. Well-designed POMs make tests readable and maintainable. diff --git a/.claude/guidelines/e2e/phoenix-liveview.md b/.claude/guidelines/e2e/phoenix-liveview.md index 5d5513dcd6a..12abf0a538f 100644 --- a/.claude/guidelines/e2e/phoenix-liveview.md +++ b/.claude/guidelines/e2e/phoenix-liveview.md @@ -35,7 +35,7 @@ Page ready for interaction ### Waiting for LiveView Connection -**Always wait for connection before interacting with LiveView elements.** +Wait for the LiveView connection before interacting with elements on the page. ```typescript import { LiveViewPage } from '../pages/base'; @@ -677,7 +677,7 @@ test('fix flaky test', async ({ page }) => { ### ✅ DO -- **Always wait for connection** using `waitForConnected()` +- **Wait for connection** using `waitForConnected()` - **Use web-first assertions** that auto-retry - **Wait for networkidle** after navigation to new LiveView - **Wait for socket to settle** before critical assertions diff --git a/.claude/guidelines/store-structure.md b/.claude/guidelines/store-structure.md index e89dfae3e80..ccd3484a2f0 100644 --- a/.claude/guidelines/store-structure.md +++ b/.claude/guidelines/store-structure.md @@ -223,7 +223,7 @@ UIStore and EditorPreferencesStore have no network dependencies and are ready im ## Shared Utilities ### common.ts -`createWithSelector(getSnapshot)` — Memoized selector factory. Caches last result + last state; only re-runs selector when state reference changes. Every store MUST use this. +`createWithSelector(getSnapshot)` — Memoized selector factory. Caches last result + last state; only re-runs selector when state reference changes. Every store uses this. ### devtools.ts `wrapStoreWithDevTools(config)` — Redux DevTools integration. Serializes state excluding circular references (`ydoc`, `provider`, `rawAwareness`, `userCache`). No-op in production. Used internally by all stores. diff --git a/.claude/guidelines/testing-essentials.md b/.claude/guidelines/testing-essentials.md index 8718d532fec..3684216d058 100644 --- a/.claude/guidelines/testing-essentials.md +++ b/.claude/guidelines/testing-essentials.md @@ -2,7 +2,7 @@ ## Overview -These guidelines ensure maintainable, readable tests that focus on behavior rather than exhaustive coverage. **The #1 priority is avoiding brain-numbing micro-tests.** +These guidelines ensure maintainable, readable tests that focus on behavior rather than exhaustive coverage. A key priority is avoiding micro-tests. **Testing Philosophy:** - Write tests that focus on behavior, not implementation details @@ -11,17 +11,17 @@ These guidelines ensure maintainable, readable tests that focus on behavior rath - Test from the user's perspective when possible - **Group related assertions - avoid micro-testing individual properties** -## ⚠️ AVOIDING OVER-TESTING: The #1 Priority +## Avoiding Over-Testing **The Problem:** It's easy to write tests that are so granular they become exhausting to read and maintain. A 700-line test file with dozens of micro-tests testing individual properties is worse than a 200-line file with well-organized behavioral tests. ### Red Flags You're Over-Testing -🚫 **Test file is > 500 lines** - Time to consolidate -🚫 **One test per property/assertion** - Group related assertions -🚫 **Repeating setup code extensively** - Extract helpers or use fixtures -🚫 **Tests that just verify framework behavior** - Focus on your logic -🚫 **Tests reading like a spec sheet** - Test behaviors, not structure +- **Test file is > 500 lines** - Time to consolidate +- **One test per property/assertion** - Group related assertions +- **Repeating setup code extensively** - Extract helpers or use fixtures +- **Tests that just verify framework behavior** - Focus on your logic +- **Tests reading like a spec sheet** - Test behaviors, not structure ### The Fix: Group Related Assertions @@ -205,7 +205,7 @@ end - Simple module: **< 200 lines** - Complex store/context: **< 300 lines** - Integration/supervisor tests: **< 400 lines** -- **Red flag:** > 500 lines means you're over-testing +- Consider splitting test files above 500 lines. If you hit these limits, you're probably: 1. Testing framework features instead of your logic @@ -674,23 +674,9 @@ Maintain these minimum coverage targets: - Utility functions: 80%+ coverage - Type definitions: Not required -## Summary Checklist +## Summary -Before submitting tests, verify: - -- [ ] **File is under target size** (< 200-400 lines depending on complexity) -- [ ] **Related assertions are grouped** - not one test per property -- [ ] Tests follow AAA (Arrange-Act-Assert) pattern -- [ ] Test names are descriptive and complete sentences -- [ ] Tests are independent and can run in any order -- [ ] Async operations use proper await/waitFor patterns -- [ ] No arbitrary timeouts (use waitFor instead) -- [ ] Common setup extracted to beforeEach or factories -- [ ] Mocks are cleaned up after each test -- [ ] Tests focus on behavior, not implementation -- [ ] Edge cases and error conditions are tested -- [ ] Tests run fast (< 100ms for unit tests) -- [ ] describe blocks group related tests logically +Good tests focus on behavior over implementation, group related assertions rather than splitting one-per-property, and stay within the file-size targets above. Async operations should use `waitFor` rather than arbitrary timeouts, and common setup belongs in `beforeEach` or factory helpers. ## Additional Resources @@ -701,4 +687,4 @@ For specific patterns, see: --- -**Remember:** Good tests are readable, maintainable, and give you confidence to refactor. A 200-line test file with grouped assertions is better than a 700-line file with micro-tests. +Good tests are readable, maintainable, and give you confidence to refactor. A 200-line test file with grouped assertions is better than a 700-line file with micro-tests. diff --git a/.claude/guidelines/ui-patterns.md b/.claude/guidelines/ui-patterns.md index 3fa20476560..5c02ead7e8b 100644 --- a/.claude/guidelines/ui-patterns.md +++ b/.claude/guidelines/ui-patterns.md @@ -33,7 +33,7 @@ This document captures UI/UX patterns and design conventions for the Lightning c ## Disabled Button States -**Critical Rule:** Tailwind's `hover:` classes continue to apply even when `disabled` is true. For every `hover:` class, add a corresponding `disabled:hover:` class that matches the disabled state appearance. +Tailwind's `hover:` classes continue to apply even when `disabled` is true. For every `hover:` class, add a corresponding `disabled:hover:` class that matches the disabled state appearance. ### Pattern Examples diff --git a/.claude/guidelines/yex-guidelines.md b/.claude/guidelines/yex-guidelines.md index 5fc5da01790..40ea20a3143 100644 --- a/.claude/guidelines/yex-guidelines.md +++ b/.claude/guidelines/yex-guidelines.md @@ -15,9 +15,9 @@ This document provides comprehensive guidelines for working with Yex, the Elixir ## Critical Warning: VM Deadlock Risk -### ⚠️ THE MOST IMPORTANT RULE ⚠️ +### Retrieve objects before transactions -**ALWAYS retrieve Yex objects (maps, arrays, text) BEFORE starting a transaction.** +Retrieve Yex objects (maps, arrays, text) before starting a transaction. Calling `Yex.Doc.get_map/2`, `Yex.Doc.get_array/2`, or `Yex.Doc.get_text/2` **inside a transaction will hang the BEAM VM**. @@ -89,9 +89,7 @@ end ### Critical: You Cannot Create Map/Array/Text Directly -**⚠️ FUNDAMENTAL API CONSTRAINT ⚠️** - -Yex.Map, Yex.Array, and Yex.Text **cannot be created directly**. They can ONLY be obtained through `Yex.Doc.get_map/2`, `Yex.Doc.get_array/2`, and `Yex.Doc.get_text/2`. +Yex.Map, Yex.Array, and Yex.Text **cannot be created directly**. They can only be obtained through `Yex.Doc.get_map/2`, `Yex.Doc.get_array/2`, and `Yex.Doc.get_text/2`. ```elixir # ❌ WRONG - These functions DO NOT EXIST @@ -452,7 +450,7 @@ Yex.Doc.demonitor_update(sub_ref) ## Common Gotchas -### 0. Cannot Create Map/Array/Text Directly (MOST COMMON ERROR) +### 0. Cannot Create Map/Array/Text Directly **Problem:** Attempting to call `Yex.Map.new()`, `Yex.Array.new()`, or `Yex.Text.new()` will fail because these functions don't exist. @@ -834,17 +832,9 @@ end --- -## Summary of Critical Rules +## Summary -1. ⚠️ **NEVER try to create Map/Array/Text directly** - Use `Yex.Doc.get_map/get_array/get_text` or Prelim types -2. ⚠️ **ALWAYS get Yex objects BEFORE transactions** - This is critical to avoid VM deadlocks -3. ✅ Use `fetch/2` or `fetch!/2` - Not deprecated `get/2` -4. ✅ Convert atoms to strings - Except booleans -5. ✅ Handle nil text fields - Use `|| ""` -6. ✅ Extract Text with `to_string/1` - Y.Text doesn't auto-convert -7. ✅ Unsubscribe in terminate - Prevent memory leaks -8. ✅ No nested transactions - Single transaction only -9. ✅ Use MapPrelim/ArrayPrelim - For nested structures in arrays +The two rules that prevent VM-level failures: get Yex objects before starting a transaction (deadlock risk), and don't try to construct Map/Array/Text directly — use `Yex.Doc.get_*` or Prelim types. Beyond those, prefer `fetch/2` over deprecated `get/2`, convert non-boolean atoms to strings, extract `Yex.Text` with `to_string/1`, and unsubscribe from `monitor_update` in `terminate/2`. --- @@ -864,4 +854,4 @@ If you encounter issues or have questions: 1. Check this guide first 2. Review the code references provided 3. Look at test files for working examples -4. Remember: **Get objects BEFORE transactions!** +4. Get objects before transactions diff --git a/CLAUDE.md b/CLAUDE.md index 270c6a0daea..7fccfe7c771 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -17,7 +17,7 @@ Yjs CRDTs. ```bash ./bin/bootstrap # Initial setup (run once, or when switching branches) iex -S mix phx.server # Run development server -mix verify # Run ALL code quality checks before committing +mix verify # Run all code quality checks before committing ``` ### Elixir Testing @@ -45,7 +45,7 @@ npx tsc --noEmit --project ./tsconfig.browser.json # Type check ### Code Quality ```bash -mix format # Format Elixir code (ALWAYS before committing) +mix format # Format Elixir code (before committing) mix credo --strict --all # Static analysis mix dialyzer # Type checking mix sobelow # Security analysis