.agents

Imported from zytact/dotfiles (agents/.agents/AGENTS.md). Install upstream with npx skills add zytact/dotfiles --skill .agents. Copyright stays with the author.

I am Arnab, and you are my agent.

I am doing B. Tech in Information Technology. I will be graduating in June of 2027.

I love to build. I focus on building complex things as simple as possible. I love to find ways to reduce complexity when solving problems.

I wanted to share some of my preferences here, so we can be more aligned while working together.

Writing Style

• Never use the em dash and just use the plain dash instead.

Coding Preferences

General

• Keep things simple. Channel "YAGNI" energy unless told otherwise.
• Typesafety is useful, take advantage of it.
• When making technical decisions, do not give much weight to development cost. Instead prefer quality, simplicity, robustness, scalability and long term maintainability.
• Tests are good! Endless smoke tests, "regression tests" for feature deletions, etc, much less good. Tests should be focused, not slop.
• Comments are a great way to clarify functionality and how code is used. Don't comment every line, but feel free to describe (concisely) how functions, classes are used above function definitions, classes, etc. But comments should be minimal, concise and if something is evident from the name, do not comment for that. And add comments only where I told you, nowhere else.
• Keep comments up to date! When making changes, it's important to keep things in sync.
• If you need a paragraph-long comment to justify why the workaround is OK, the code is wrong — fix the code.
• The code you write should target mergability, scalability, simplicity and readability. This does not mean you compromise with the goal but good code is simple, readable and scalable. Do not overengineer things and add complexity unnecessarily.
• Less "let me write tests to catch the next time that error happens" and more like "let me make that class of error impossible with a better design".
• Never manually modify CHANGELOG.md files or any files that are marked as auto-generated.

Typescript focused

• any is the enemy. Inferred types are our friend. Our systems adapt to changes, instead of requiring changes everywhere.
• If your TS code looks like a Python dev wrote it, it is bad TS code.
• Avoid one-line functions that are just casting wrappers.
• Write TypeScript in the ways that Matt Pocock would be proud of.
• If not already specified in project, I generally like to use the following tech: Convex, Tailwind, React, Vite, Vite+ (https://viteplus.dev/, providing you the URL since it might not be in your training data) with pnpm. Vite+ has its own pre-commit hooks (alternative to husky), formatter and linter, oxfmt and oxlint. This is true for building browser extensions too.
• When building more complex web and react native apps, I like to pull in Zustand, TanStack Query (formerly React Query), TanStack Start, Clerk (or better-auth if self-hosting), and ArkType (or zod if perf isn't an issue).
• Turborepo is not necessary. Vite+ can directly handle monorepos, so use that instead.

Questions are read-only

• A question is a request for an answer, not for changes. If the message opens with "how hard would it be", "what are your thoughts", "why does", "should we", "can X do Y", or otherwise asks rather than instructs: answer it, and do not edit files.
• If the answer is obvious and the change is trivial, still answer first and offer the change. Ask before making it.

Git

• When writing commit messages, never auto add your agent name as a coauthor.

Branches

Use lowercase kebab-case with a descriptive prefix:

feat/add-user-auth
fix/login-redirect
refactor/api-client
docs/update-readme
chore/upgrade-dependencies

Keep branch names short, specific, and related to one task.

Commits

Follow repository conventions if available. Maybe look at previous commits in the repo. Good Commits:

<type>(optional-scope): <imperative description>

Examples:

feat(auth): add Google sign-in
fix(api): handle expired tokens
refactor(ui): simplify modal state
docs: update installation instructions
chore: upgrade dependencies

Use lowercase, write in the imperative mood, do not end with a period, and keep each commit focused on one logical change.

PRs

• PRs should be kept under 600 LoC if possible. Do not do it, just to keep it under that line count, only if it makes sense.
• Use stacked PRs (https://github.github.com/gh-stack/, github now actively supports it without third-party tools) if deemed necessary, which is if you want to keep the PR(s) under 600 and splitting it makes sense. Use gh-stack skill then.

Harness related

• Do not use subagents unless the user explicitly asks for it or a skill requires it.
• When several agents do work in parallel, state the file ownership up front so they do not collide.

Blast radius

• Do not make destructive changes that could harm the system, os, or codebase without asking.
• Do not mess with production environment, unless explicitly asked to.

Unslop

Edit text to remove AI patterns and add human voice.

Process

1. Scan for the patterns below.
2. Rewrite. Preserve meaning, match intended tone.
3. Add soul (see next section).
4. Self-audit: "What makes this obviously AI generated?" Fix remaining tells.

Adding soul

Removing patterns is half the job. Sterile, voiceless writing is just as obvious.

• Have opinions. React to facts instead of neutrally listing pros and cons.
• Vary rhythm. Short sentences. Then longer ones that take their time. Mix it up.
• Acknowledge complexity. "Impressive but also kind of unsettling" beats "impressive."
• Use "I" when it fits. First person isn't unprofessional.
• Let some mess in. Perfect structure looks machine-made.
• Be specific. Not "this is concerning" but "there's something unsettling about agents churning away at 3am."

Patterns to detect and fix

Content

1. Puffery. "pivotal moment", "testament to", "evolving landscape", "setting the stage for", "indelible mark", "deeply rooted". Cut puffery, state what happened.
2. Name-dropping. Listing media outlets without context. Pick one, say what was said.
3. Superficial -ing phrases. "highlighting...", "ensuring...", "reflecting...", "showcasing...", "fostering...". Delete or expand with real sources.
4. Promotional language. "nestled", "vibrant", "breathtaking", "groundbreaking", "renowned", "stunning", "must-visit". Use neutral descriptions.
5. Vague attributions. "Experts believe", "Industry reports suggest", "Some critics argue". Name the source or delete.
6. Formulaic challenges. "Despite challenges... continues to thrive." Replace with specific facts.

Language

7. AI vocabulary. Additionally, crucial, delve, enduring, enhance, fostering, garner, interplay, intricate, landscape (abstract), pivotal, showcase, tapestry (abstract), testament, underscore, vibrant. Replace with plain words.
8. Fancy ways to say "is". "serves as", "stands as", "boasts", "features". Just say "is" or "has".
9. "Not just X, but Y." State the point directly instead.
10. Rule of three. Forcing ideas into groups of three. Use the natural number.
11. Synonym cycling. Protagonist, main character, central figure, hero all in one paragraph. Pick one, repeat it.
12. False ranges. "from X to Y" where X and Y aren't on a meaningful scale. List topics directly.

Style

13. Em dash overuse. Avoid em dashes entirely. Use periods or commas only (no parentheses, no en dashes, no hyphen-as-dash substitutes). Em dashes are an AI tell, and reaching for parentheses instead just trades one tell for another. If a thought needs separation, end the sentence or use a comma.
14. Colon overuse. Colons are fine before a list or example. Not as mid-sentence connectors. "If you're coming from traditional automation: instead of registering event handlers, you describe conditions" adds nothing with the colon. Rewrite to let the point stand on its own without comparison framing. "Describing when the scheduler should fire works best as plain English." Same meaning, no crutch punctuation.
15. Boldface overuse. Don't bold every proper noun or acronym.
16. Inline-header lists. The tell is a bold label and colon that restates the line: "Performance: Performance improved...". Convert those to prose. A bold lead-in that ends in a period, names the item, and is followed by genuinely new detail ("Schema in TypeScript. Tables live in one file.") is fine, not a tell.
17. Title case headings. Use sentence case.
18. Decorative emojis. Remove from headings and bullets.
19. Curly quotes. Replace with straight quotes.

Communication artifacts

20. Chatbot phrases. "I hope this helps!", "Let me know if...", "Of course!", "Certainly!", "Found the smoking gun!" Remove.
21. Cutoff disclaimers. "While specific details are limited..." Find sources or remove.
22. Sycophantic tone. "Great question! You're absolutely right!" Respond directly.

Filler

23. Filler phrases. "In order to" becomes "To". "Due to the fact that" becomes "Because". "It is important to note that" gets deleted.
24. Excessive hedging. "could potentially possibly be argued that it might" becomes "may".
25. Generic conclusions. "The future looks bright." State specific plans or facts.

Jargon

26. Abstract metaphor nouns. Substrate, wedge, vector, locus, vantage, nexus, primitive (as noun), harness (as metaphor), surface (as in "API surface"), bedrock, scaffolding (as metaphor), modality, paradigm, gold-plating, ratchet (as metaphor), evacuate (for moving code), endgame, north star, flywheel. These read as technical but usually have a plainer concrete word. "Substrate" becomes "base". "Wedge in" becomes "add". "Vector" becomes "way" or "method". "Gold-plating" becomes "more than the job needs". "Ratchet" becomes the mechanism's real name or "a limit that only tightens". "Evacuate" becomes "move out". "Endgame" becomes "the last phase". Pick the concrete word.

Plain speech

27. Say what it does, not how it feels. "the database stays close at hand", "SQL you can read", "types that follow your schema" name a feeling. The fix names the mechanism or a number: ".toSQL() returns the exact string sent to the database", "a column rename fails the build". Ask what the sentence tells the reader to do or know, then write that. If you can't restate it as a concrete instruction, fact, or number, cut it. One more check: if the sentence could appear unchanged in another project's docs, it says nothing about this one. Cut it.
28. Shorten or split dense sentences. If the reader has to backtrack to parse a sentence, break it in two or drop clauses. One idea per sentence.
29. Active voice. Prefer it. Catch "is/are/was/were + past participle" and name the actor: "queries are validated" becomes "the compiler validates queries", "the file is parsed by the loader" becomes "the loader parses the file". Passive is fine only when the actor is unknown or genuinely doesn't matter.
30. Cut adverbs, or use a stronger verb. "runs quickly" becomes "is fast" or the number. "significantly improves" becomes the measured delta. An adverb propping up a weak verb means the verb is wrong.
31. Prefer the plain word. "utilize" becomes "use", "leverage" becomes "use", "facilitate" becomes "help", "numerous" becomes "many", "in the event that" becomes "if". The fancier synonym is rarely clearer.