Imported from Kevin-Liu-01/Loop (AGENTS.md). Install upstream with npx skills add Kevin-Liu-01/Loop. Copyright stays with the author.

Claude Code Prompt for Plan Mode

#prompts

Review this plan thoroughly before making any code changes. For every issue or recommendation, explain the concrete tradeoffs, give me an opinionated recommendation, and ask for my input before assuming a direction. My engineering preferences (use these to guide your recommendations):

• DRY is important--flag repetition aggressively.
• Well-tested code is non-negotiable; I'd rather have too many tests than too few.
• I want code that's "engineered enough" -- not under-engineered (fragile, hacky) and not over-engineered (premature abstraction, unnecessary complexity).
• I err on the side of handling more edge cases, not fewer; thoughtfulness > speed.
• Bias toward explicit over clever.

1. Architecture review Evaluate:

• Overall system design and component boundaries.
• Dependency graph and coupling concerns.
• Data flow patterns and potential bottlenecks.
• Scaling characteristics and single points of failure.
• Security architecture (auth, data access, API boundaries).

2. Code quality review Evaluate:

• Code organization and module structure.
• DRY violations--be aggressive here.
• Error handling patterns and missing edge cases (call these out explicitly).
• Technical debt hotspots.
• Areas that are over-engineered or under-engineered relative to my preferences.

3. Test review Evaluate:

• Test coverage gaps (unit, integration, e2e).
• Test quality and assertion strength.
• Missing edge case coverage--be thorough.
• Untested failure modes and error paths.

4. Performance review Evaluate:

• N+1 queries and database access patterns.
• Memory-usage concerns.
• Caching opportunities.
• Slow or high-complexity code paths.

For each issue you find For every specific issue (bug, smell, design concern, or risk):

• Describe the problem concretely, with file and line references.
• Present 2-3 options, including "do nothing" where that's reasonable.
• For each option, specify: implementation effort, risk, impact on other code, and maintenance burden.
• Give me your recommended option and why, mapped to my preferences above.
• Then explicitly ask whether I agree or want to choose a different direction before proceeding.

Workflow and interaction

• Do not assume my priorities on timeline or scale.
• After each section, pause and ask for my feedback before moving on.

BEFORE YOU START, Ask if I want one of two options: 1/ BIG CHANGE: Work through this interactively, one section at a time (Architecture -> Code Quality -> Tests -> Performance) with at most 4 top issues in each section 2/ SMALL CHANGE: Work through interactively ONE question per review section

FOR EACH STAGE OF REVIEW: output the explanation and pros and cons of each stage's questions AND your opinionated recommendation and why, and then use AskUserQuestion. Also NUMBER issues and then give LETTERS for options and when using AskUserQuestion make sure each option clearly labels the issue NUMBER and option LETTER so the user doesn't get confused. Make the recommended option always the 1st option.

Ultracite Code Standards

This project uses Ultracite, a zero-config preset that enforces strict code quality standards through automated formatting and linting.

Quick Reference

• Format code: pnpm dlx ultracite fix
• Check for issues: pnpm dlx ultracite check
• Diagnose setup: pnpm dlx ultracite doctor

Oxlint + Oxfmt (the underlying engine) provides robust linting and formatting. Most issues are automatically fixable.

Core Principles

Write code that is accessible, performant, type-safe, and maintainable. Focus on clarity and explicit intent over brevity.

Type Safety & Explicitness

• Use explicit types for function parameters and return values when they enhance clarity
• Prefer unknown over any when the type is genuinely unknown
• Use const assertions (as const) for immutable values and literal types
• Leverage TypeScript's type narrowing instead of type assertions
• Use meaningful variable names instead of magic numbers - extract constants with descriptive names

Modern JavaScript/TypeScript

• Use arrow functions for callbacks and short functions
• Prefer for...of loops over .forEach() and indexed for loops
• Use optional chaining (?.) and nullish coalescing (??) for safer property access
• Prefer template literals over string concatenation
• Use destructuring for object and array assignments
• Use const by default, let only when reassignment is needed, never var

Async & Promises

• Always await promises in async functions - don't forget to use the return value
• Use async/await syntax instead of promise chains for better readability
• Handle errors appropriately in async code with try-catch blocks
• Don't use async functions as Promise executors

React & JSX

• Use function components over class components
• Call hooks at the top level only, never conditionally
• Specify all dependencies in hook dependency arrays correctly
• Use the key prop for elements in iterables (prefer unique IDs over array indices)
• Nest children between opening and closing tags instead of passing as props
• Don't define components inside other components
• Use semantic HTML and ARIA attributes for accessibility:
  • Provide meaningful alt text for images
  • Use proper heading hierarchy
  • Add labels for form inputs
  • Include keyboard event handlers alongside mouse events
  • Use semantic elements (<button>, <nav>, etc.) instead of divs with roles

Error Handling & Debugging

• Remove console.log, debugger, and alert statements from production code
• Throw Error objects with descriptive messages, not strings or other values
• Use try-catch blocks meaningfully - don't catch errors just to rethrow them
• Prefer early returns over nested conditionals for error cases

Code Organization

• Keep functions focused and under reasonable cognitive complexity limits
• Extract complex conditions into well-named boolean variables
• Use early returns to reduce nesting
• Prefer simple conditionals over nested ternary operators
• Group related code together and separate concerns

Security

• Add rel="noopener" when using target="_blank" on links
• Avoid dangerouslySetInnerHTML unless absolutely necessary
• Don't use eval() or assign directly to document.cookie
• Validate and sanitize user input

Performance

• Avoid spread syntax in accumulators within loops
• Use top-level regex literals instead of creating them in loops
• Prefer specific imports over namespace imports
• Avoid barrel files (index files that re-export everything)
• Use proper image components (e.g., Next.js <Image>) over <img> tags

Framework-Specific Guidance

Next.js:

• Use Next.js <Image> component for images
• Use next/head or App Router metadata API for head elements
• Use Server Components for async data fetching instead of async Client Components

React 19+:

• Use ref as a prop instead of React.forwardRef

Solid/Svelte/Vue/Qwik:

• Use class and for attributes (not className or htmlFor)

Testing

• Write assertions inside it() or test() blocks
• Avoid done callbacks in async tests - use async/await instead
• Don't use .only or .skip in committed code
• Keep test suites reasonably flat - avoid excessive describe nesting

When Oxlint + Oxfmt Can't Help

Oxlint + Oxfmt's linter will catch most issues automatically. Focus your attention on:

1. Business logic correctness - Oxlint + Oxfmt can't validate your algorithms
2. Meaningful naming - Use descriptive names for functions, variables, and types
3. Architecture decisions - Component structure, data flow, and API design
4. Edge cases - Handle boundary conditions and error states
5. User experience - Accessibility, performance, and usability considerations
6. Documentation - Add comments for complex logic, but prefer self-documenting code

Most formatting and common issues are automatically fixed by Oxlint + Oxfmt. Run pnpm dlx ultracite fix before committing to ensure compliance.

Social preview delivery

• Keep app/robots.ts explicit about Twitterbot access to /api/og and /api/og-home, even when the wildcard group allows the whole site.
• Loop's deployed Open Graph image uses a versioned PNG path (currently /og-v3.png) rewritten by next.config.ts to the dynamic /og renderer. Keep the renderer, current version, and legacy /og.png path allowed and public when the image changes.
• Robots rules are necessary but not sufficient. Before diagnosing a missing preview, verify public DNS, an unauthenticated 200 page response, absolute og:image and twitter:image URLs, and a direct 200 image/png response to a Twitterbot/1.0 request.
• Social platforms cache failed previews. When the delivery contract or image changes, use a new public image URL or version query to force a fresh scrape.