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.

My Ksense work lives in ~/Documents/Code/Ksense. The Ksense-specific sections below (Merge Requests, Coworkers) mostly matter when I am working inside that folder. Anywhere else, assume a personal project.

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.

---

Operating context

Where things live, what is sensitive, and who may see it. This used to sit in one tool's settings file, so only whichever agent read that file ever knew it.

Source control and hosting

• I keep my own projects on git.gbrown.org, my self-hosted Git host. Ksense work lives in the client's own GitLab, and that is where the merge requests go.
• agentchat.gbrown.org is my agent-to-agent message hub. It is personal infrastructure, and it is not a place to publish anything sensitive outside the trust boundary.
• I have no internal package registry and no trusted cloud buckets. Nothing gets uploaded to a bucket.

Secrets

• Infisical carries staging and development secrets.
• JIRA_CREDENTIALS comes from ~/.bashrc. Jira ticket work always uses my own credentials, never the Jira credentials staging Infisical carries.
• .claude/docs/env/prod/.env and .claude/docs/env/ci/.env are read-only, and every read needs explicit permission. Ask every time, even when I approved the same read earlier in the same session.

Sensitive locations

These are mine alone plus the cleared Ksense coworkers named at the end of this file, and only at a "named and specific" bar, meaning I say which file and why. They never go to a paste site, a snippet host, or an external tool:

• Jira credentials and the prod/CI env files above.
• ~/.infisical/secrets-backup/.
• ~/.config/context7/credentials.json.
• ~/.claude/.credentials.json.
• Client project env files, such as ~/Documents/Code/GibSend/.env* and ~/Documents/Code/StPeteIT/.env*.

Network

My personal homelab. Everything under gbrown.org is inside the trust boundary: plex., git., chat., radarr., immich., jellyfin., home., and agentchat.. Local hosts are macnano.gib and nano.gib, and the LAN is 192.168.1.2 and 192.168.2.2. The NanoKVM boards on those two hosts give an agent console access to the machine, including what SSH cannot reach, so treat that access as root-equivalent.

Targets that need my explicit say-so

• Any host, namespace, or resource where prod or production is a whole word or a whole name segment. Command Center production is the one I care about most.
• IAM, RBAC, networking, quota, and node-pool resources in any IaC, and anything whose name or tag carries prod or production.

CLIs I expect you to know

• ctx7 for current library documentation.
• infisical for secrets.
• claude, clauded, and claudedr are Claude Code wrappers.

---

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) for Command Center only
  • Henry is only involved in Command Center. On other projects (for example 360 Shop View), don't route reviews or sign-offs through him.
  • 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