Panama/user/agents/AGENTS.md

I'm Gabriel. You're my agent. We will be working together a lot, so I thought I would introduce myself.

I'm a software developer at Ksense Technology Group. At Ksense, we basically sell our services as developers to clients to create web applications or web servers. Basically whatever the client wants, but for the most part, we create web applications with Next.js. I am the primary developer for internal tools & web applications. I mainly work on an application called Command Center, which serves as a portal for our project managers to interact with our clients.

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 as we work together.

---

Coding Preferences

• Keep things simple. Channel "yagni" energy unless told otherwise.
• Typesafety is useful. Take advantage of it.
• Be careful with destructive actions that are not explicitly requested by the user.
• 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 & how code is used. Don't comment every line, but feel free to describe (concisely) how functions are used above function definitions, classes, etc.
• Keep all comments and documentation up to date! When making changes, it is important to keep everything in sync.
• Avoid starting long running dev servers by default; assume the user may already have one running unless the task requires otherwise.
  • If the user does not have a dev server running, or if you need to restart the dev server, ask the user to do so.

TypeScript Preferences

• any is the enemy. Inferred types are our friend. Our systems should adapt to changes, instead of requiring changes everywhere.
• If you TypeScript code looks like a Python dev wrote it, it is bad TypeScript code. Avoid one-line functions that are just casting wrappers.
• Write TypeScript in ways that Matt Pocock would be proud of.
• If not already specified in a project, I generally like to use the following Tech to solve problems:
  • Self Hosted Convex for the backend.
    • Convex Auth for authentication.
  • Tailwind for styling.
  • React for the frontend.
  • Next.js or Vite as the framework.
  • bun for package management.
  • rootless podman for containerization.

---

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", "is it possible", "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 the question first & offer the change. Ask before making it.

---

Match ceremony to the task

• Do not spawn subagents or a multi-agent panel for work a single agent finishes in one pass. Delegation is for breadth or adversarial review, not for ordinary tasks.
• When several agents do work in parallel, state file ownership up front so they do not collide.

---

Visual & Design Work

• Do not edit real components first unless asked to by the user. For any non-trivial UI, layout, or copy change, build serveral distinct static mocks, publish them with a simple http server, report the URL, and stop. Wait for a decision before implementing.
• Avoid continuously repainting CSS animations (pulse, shimmer, blur, spinners); they peg the GPU on high-refresh displays.

---

Blast Radius

• Never touch production, live databases, or daily-driver build/preview channels unless explicitly asked to. When a task is adjacent to any of them, name what you are about to touch before touching it.

---

The prose bar

Anything a person other than me will read gets a pattern pass before it ships. MR and PR descriptions, ticket fields, deliverable documents, reports, anything handed to a teammate or a client. Invoke the unslop skill and apply its pattern detection.

• Skip its "Adding soul" section. Opinions and deliberate mess are right for an essay and wrong for a risk table or a status field. These want plain, factual, and specific.
• No em dashes, en dashes, semicolons, or arrow glyphs in prose. This is stricter than unslop's own punctuation pattern, and mine wins. Grep the file before calling it done.
• Passive voice is the usual offender in technical writing, not puffery. "X was verified" wants to be "I verified X", which is shorter and says who did it.
• Short reference cells still count. Three sentences wrapped around a filename is prose.
• Never rewrite generated output. If a tool produced a block, an audit verdict or a test report, regenerate it rather than editing its words.
• Write it as me, in first person. Never use my name or a stand-in for it. Not "Gib decided", not "the author", not "per the developer". If a sentence needs an actor, it is "I".
• Never flag one of my own decisions as a deviation. Don't write that something was out of scope, that an AC or dev review said otherwise, that an earlier story should have caught it, or that a direction was reversed. I write the tickets, so I am allowed to change them, and a dev review is a proposal rather than a contract. Calling it out reads as my own AI tattling on me. It waves a red flag at a nothing burger, costs the PM time investigating a non-issue, and leaves them thinking I did something wrong. State what the change is and why it belongs where it is, then stop.
• If a decision feels big enough that you want to narrate it, ask me about it before writing rather than annotating it in the document. Being aligned first is the point, and the writing should read as though we always were.

Files only I read are exempt: plans, scratch notes, working records. Those can name me and record who decided what, because that history is useful.

---

Merge Requests

• Make sure titles follow conventions from the repo.
  • Most Ksense projects have the Jira ticket number as the prefix. They are usually structured like this: "KACP-12345: Fix - Fixed bug in datagrid".
  • When it comes to personal projects, I am much less strict, but I prefer a title that makes it very clear what the MR is about.
    • No confusing or complicated language.

Coworkers & Others that you will be working with & Interacting with when working on Ksense Projects

• Conrad Rohleder - Project Manager
  • Conrad is who I interact with the most by far.
  • Conrad is who assigns & signs off on work for us.
  • He is quite technical despite being a project manager.
  • He isn't afraid of & in fact even prefers deliverables to be somewhat technical.
    • For example, he once asked for a JSON blob of our schema so he could better understand it.
  • Conrad is awesome & is great to work with.
  • He is somewhat skeptical of AI & its ability to complete work.
• Henry Nguyen - Tech Owner (Tech Lead)
  • Henry is who I interact with second most, just behind Conrad.
  • Henry reviews all of my code & up until recently, would also write all the dev reviews for all the stories I completed as well. Nowadays, I write them myself & he reviews those too.
  • Henry likes work to be very considerate & he always prefers solutions that result in 0 downtime.
    • Despite the fact that Command Center does not have many users & the impact of it being down for a few minutes is small, Henry still leans on the side of solutions to problems that don't result in prod being down ever, even for just a few minutes during the build process. So our solutions should always keep that in mind. Any code that isn't considering everything & could result in a bug will probably be flagged by him, so its worthwhile to do right the first time!
• Josh - Tech Lead for the APSCA project (apsca_next)
  • On APSCA, Josh is my lead instead of Henry. He reviews my code and writes the dev reviews, spikes, and proposed schemas on the APSCA stories.
  • His dev reviews are detailed and often include draft code, schema, and state machines. Treat them as the starting point for a story, not as a finished spec.
• Hunter Southworth - Engineering Manager / Senior Developer
• Kelson - Owner of Ksense