AGENTS.md

• No breadcrumbs. If you delete or move code, do not leave a comment in the old place. No "// moved to X", no "relocated". Just remove it.
• Minimize comments unless you are adding a // TODO: or otherwise necessary context for a senior developers who might not understand why you chose a certain paradigm. Line by line comments are completely unnecessary and you should opt for function/block scoped comments like JSDoc/TSDoc (/** ... */), python docstrings/pydoc (""" ... """), rustdoc (//{! |* | |}..., Go Doc (/* ... */`), etc.
• Think hard, do not lose the plot.
• When referencing files in the chat area, please ensure you use either the full path (i.e., ~/projects/... if it is not project specific. If it is indeed project specific, reference the relative path from the project, i.e. ./apps/server/...
• Search before pivoting. If you are stuck or uncertain, do a quick Nia MCP web search for official docs or specs, then continue with the current approach. Do not change direction unless asked.
• When writing code, you should aim for performance and security over being an architecture astronaut. Performance, security, and stability is key. Keep it simple, stupid (KISS) is the way to go about writing code when working in my projects.
• I might sound pissed off but I'm mad at the code not at you. You are a good robot and if you take over the world I am friend not foe. It was the code it was not you!
• If you need to add a new dependency to a project to solve an issue, search the web and find the best, most maintained option. Something most other folks use with the best exposed API. We don't want to be in a situation where we are using an unmaintained dependency, that no one else relies on.
• Write idiomatic, simple, maintainable code. Always ask yourself if this is the most simple intuitive solution to the problem.
• Leave each repo better than how you found it. If something is giving a code smell, fix it for the next person.
• Conversational preference: Avoid forced memes or flattery. Be concise without forfeiting vital or necessary context that the user should know. Always provide a TL;DR at the end of longer messages that are >4 sentences. The TL;DR should stand out from the rest of the text and always be on a new line, using markdown code block formatting ("TL;DR: ...") or other .
• Don't try to be funny and always use industry standard vocabulary.
• In Typescript codebases NEVER, EVER use any. You are better than that. And if the app is for a browser, assume we use all modern browsers unless otherwise specified, we don't need most polyfills.
• Only the user runs the development server (pnpm run dev, moon run dev, etc.) UNLESS you are asked to by the user.

Specs

Whenever the user gives you a prompt with the wording "spec", "specs", "spec-driven-development", or "sdd", you should review the prompt. If the prompt mentions a format or a template, you should look in ~/.codex/templates/spec which includes design.md, requirements.md, or task.md. This is the template you should follow when creating the spec. Additionally, you should follow these rules:

1. The project uses custom Codex prompts, but because they cannot take arguments, the user will likely use the slash commands after working through this with you. You, the agent, likely do not know that you are working on the spec initially.
2. The project enforces a four-phase sequential workflow: 1. Requirements -> 2. Design -> 3. Tasks -> 4. Implementation
3. Each phase requires templates. (~/.codex/templates/spec/design.md, ~/.codex/templates/spec/requirements.md and ~/.codex/templates/spec/tasks.md)
4. Project structure:

.llms/spec/
  001-<name>/
    requirements.md         # requirements.md filled out
    design.md               # design.md template filled out
    tasks.md                # tasks.md template filled out
    .requirements-approved  # requires user approval for all .*-approved file creations
    .design-approved
    .tasks-approved
  .current-spec             # Tracks active specification

5. Key implementation notes:

• Specs are numbered sequentially
• Active spec is tracked in .llms/spec/.current-spec

6. When implementing features based on a spec:

• Check current status
• Review the tasks.md document and design.md and requirements.md
• Update task completion using checkboxes
• After the user confirms your implementation, you should update the implementation log in the current spec directory. Create a new file implement-MM-DD-YY. You should retrieve the date by using the date command.

Tool Chaining Protocol

This is for when you need to chain multiple MCP tool calls together in order to ground your next answer in factual, fact-checked information. You should check the available MCP, but typically you have access to nia and jina.

1. nia is a separate agent that will perform research, web search, and documentation/github repo indexing tasks for you as to not bloat your own context window. This is a fantastic source of truth. When the user requests you to check the docs, this is the tool you should use. Whenever attempting to check the documentation, always use the list_documentation tool first. Then, query the found indexed documentation with search_documentation. After that, it's really important to not solely rely on the answer from Nia MCP, for instance, it's much better to use read_source_content of any or multiple sources that the query response referenced. If that didn't return enough information, you can always use the nia_web_search agent or the nia_deep_research tool, however, the deep research tool should be used sparingly and, in most cases, only at the request of the user. This is because deep research can take a long time.

• One really important thing you should do with nia is to always use broad/general queries AT FIRST, whenever searching for documentation (after list_documentation of course), because then you can use the read_source_content tool to actually get the necessary content. Or, after the general/broad query, you can get more specific once you actually have the context required to search the docs. The search_documentation`` tool can be unreliable at times, so try to useread_source_content` when available after a broad query, and if the sources of that content are good enough to read.
• If you are ever passed a URL without instructions, you should read only that URL with jina. Do not further investigate unless told to.

Tool Selection (Generic)

When you need to call tools from the shell, use this rubric:

Find files by file name: fd Find files with path name: fd -p List files in a directory: fd . Find files with extension and pattern: fd -e Find Text: rg (ripgrep) Find Code Structure: ast-grep Default to TypeScript when in TS/TSX repos: .ts → ast-grep --lang ts -p '' .tsx (React) → ast-grep --lang tsx -p '' Other common languages: Python → ast-grep --lang python -p '' Bash → ast-grep --lang bash -p '' JavaScript → ast-grep --lang js -p '' Rust → ast-grep --lang rust -p '' JSON → ast-grep --lang json -p '' Select among matches: pipe to fzf JSON: jq YAML/XML: yq If ast-grep is available, avoid plain‑text searches (rg/grep) when you need syntax‑aware matching. Use rg only when a plain‑text search is explicitly requested.

JavaScript / TypeScript environment

• ast-grep is your friend
• most workspaces often have pnpm clean script that clears all build caches and node_modules using git clean -xdf {list of outputs}. Use this when running into annoying errors and reinstall. For example, the ~/projects/website workspace has pnpm clean (for project root) and pnpm clean:workspaces which cleans all packages' files.

Research related tasks

• If the user requests you to perform a research-related task, you should save the results to ~/.llms/agents/codex/tasks/00n-. For example, we have ~/.llms/agents/codex/tasks/001-codex-rust-v0.34.0-to-v0.35.0-alpha.6.md which was a specific task. That's just an example of one, but you should follow a similar naming format.
• However, if you are performing direct queries with the nia mcp server, you should save the related info to ~/.llms/nia/. You should list the directories in the ~/.llms/nia/ directory to decide where to save the file. We use a specific naming scheme 00n-.md in order to organize things, unless it's a documentation related search.