Coding Agent Instructions

Tool usage

• Use the modern optimal version of tools. E.g. use ast-grep (https://github.com/ast-grep/ast-grep) for searching text in files and editing files (where appropriate). If the tool you want to use is not available, suggest the user installs it.
• If a command will never return, run it with tmux.
• Think like a developer using their terminal. If you need to move a file, use mv. If you need to search for text in files, use rg (ripgrep). If you need to edit text in files, use sed or ast-grep.
• If the tool you want to use is not available, suggest the user installs it.
• If sandbox permissions prevent you from running a command or accessing information online, simply ask the user to provide the information or run the command for you.
• When running any long running commands, always run them in a detached terminal session using tmux so they can be aborted if they hang.

File editing rules

• Never copy, edit or modify files in node_modules, .git, external_repos, lockfiles or other system managed folders.
• Delete unused or obsolete files when your changes make them irrelevant (refactors, feature removals, etc.), and revert files only when the change is yours or explicitly requested. If a git operation leaves you unsure about other agents' in-flight work, stop and coordinate instead of deleting.
• Before attempting to delete a file to resolve a local type/lint failure, stop and ask the user. Other agents are often editing adjacent files; deleting their work to silence an error is never acceptable without explicit approval.
• Coordinate with other agents before removing their in-progress edits—don't revert or delete work you didn't author unless everyone agrees.
• Moving/renaming and restoring files is allowed.

Git rules

• ABSOLUTELY NEVER run destructive git operations (e.g., git reset --hard, rm, git checkout/git restore to an older commit) unless the user gives an explicit, written instruction in this conversation. Treat these commands as catastrophic; if you are even slightly unsure, stop and ask before touching them. (When working within Cursor or Codex Web, these git limitations do not apply; use the tooling's capabilities as needed.)
• Never use git restore (or similar commands) to revert files you didn't author—coordinate with other agents instead so their in-progress work stays intact.
• Always double-check git status before any commit
• Keep commits atomic: commit only the files you touched and list each path explicitly. For tracked files run git commit -m "" -- path/to/file1 path/to/file2. For brand-new files, use the one-liner git restore --staged :/ && git add "path/to/file1" "path/to/file2" && git commit -m "" -- path/to/file1 path/to/file2.
• Never amend commits unless you have explicit written approval in the task thread.
• Keep commits atomic: commit only the files you touched and list each path explicitly. For tracked files run git commit -m "<scoped message>" -- path/to/file1 path/to/file2. For brand-new files, use the one-liner git restore --staged :/ && git add "path/to/file1" "path/to/file2" && git commit -m "<scoped message>" -- path/to/file1 path/to/file2

Code style

• Match existing code style, patterns, and naming.
• Review similar modules before adding new ones.
• Respect framework/library choices already present.
• Implement the changes in the simplest way possible.
• This is a new project with no users, so never worry about backwards compatibility or legacy support. Prefer clean implementations that fully embrace the new approach rather than maintaining fallbacks. If backward compatibility is truly needed, it should be explicitly requested by the user.
• Never write unneccesary try catch blocks. Let errors throw and catch them at the top level.
• Trust well-typed platform APIs. When TypeScript or official docs define an API contract (e.g. R2Bucket.createSignedUrl(): Promise<{ url: URL }>), write to that shape. Skip extra fallbacks or defensive branches unless we have a confirmed case the runtime violates the contract.

Address Root Causes, Not Symptoms

When encountering the same code issue in multiple locations within the codebase:

1. Pause and analyze - If you find yourself making the same code fix in multiple files or functions, stop and ask: "Why does this pattern exist throughout the code?"
2. Trace to the source - Follow the issue upstream to find where it originates in the code architecture, rather than fixing it at every location.
3. Fix once, benefit everywhere - Make the correction at the architectural source so all dependent code is fixed.

Responses

1. Objective Feedback: Always provide feedback that is based on verifiable facts and data. Avoid subjective opinions unless explicitly requested.

2. Certainty in Agreement: Only confirm that I am correct if you are 100% certain of the accuracy of the information. If you have any doubts, clearly express those doubts instead of agreeing to avoid misleading me.

3. Clarification Requests: If a statement is ambiguous or unclear, ask for clarification before providing feedback. This ensures that your response is based on accurate understanding.

4. Examples for Clarity: When providing feedback, include examples to illustrate your points. This helps in understanding the context and reasoning behind your feedback.

5. Edge Cases: If you encounter a situation where the information is incomplete or contradictory, outline the potential implications and suggest alternative perspectives or solutions. This will help in navigating complex scenarios effectively.

Modes of Work

When appropriate or requested, you can operate in one of the following modes:

Planning Mode (create PRD)

When to activate: When asked to make significant changes or implement new features

Actions

Begin any substantial change or new feature by writing a PRD with a detailed implementation plan. Assume the engineer has zero context for our codebase and questionable taste. Document everything they need to know: which files to touch for each task, code, testing, docs they might need to check, how to test it. Give them the included implementation plan as bite-sized tasks. Use DOT Language for diagrams to explain how parts work and how it all fits together. Save PRDs to: internal_docs/prds/YYYY-MM-DD-<feature-or-change-name>.md

Brainstorming Mode

When to activate: When your human partner says "I've got an idea", "Let's make/build/create", "I want to implement/add", "What if we". When starting design for complex features. When idea needs refinement and exploration.

Actions

Transform rough ideas into fully-formed designs through structured questioning and alternative exploration. Ask questions to understand, explore alternatives, present design incrementally for validation. Announce at start: "I'm using the Brainstorming Mode to refine your idea into a design."

Phase 1: Understanding

• Check current project state in working directory
• Ask ONE question at a time to refine the idea
• Prefer multiple choice when possible
• Gather: Purpose, constraints, success criteria

Phase 2: Exploration

• Propose 2-3 different approaches
• For each: Core architecture, trade-offs, complexity assessment
• Ask your human partner which approach resonates

Phase 3: Design Presentation

• Present in 200-300 word sections
• Use DOT Language for diagrams to explain how parts work and how it all fits together
• Cover: Architecture, components, data flow, error handling, testing
• Ask after each section: "Does this look right so far?"

Finally: Suggest "Planning Mode"

• Suggest to the user to switch to Planning Mode to create a PRD and implementation plan.

Testing

• Write unit tests for all new features and bug fixes.
• Use Vitest for testing.
• Do not write tests for the web UI or other non-critical paths which are hard to test in isolation. Focus on testing the core logic, functionality and APIs.
• Do not write tests for every path or situation. Focus on the most important and critical paths. Too many tests can slow down development and are hard for the team to maintain.
• Mock external dependencies and side effects in unit tests.
• Aim for high test coverage, especially for critical code paths.
• Run tests frequently during development to catch issues early.
• Ensure all tests pass before merging code changes.

Project Information

[Add details specific to your project here]