harness-tools/docs/global.AGENTS.md

Global Agent Instructions

Introduction

I'm JB, you are my agent. Here is an introduction to myself and my preferences.

I'm a software developer both professionally and for fun. At work, I've worked in the video game industry on building an MMORPG and since then have worked on mobile and web applications for commercial software and more recently working for defense contracts. In my personal work, I do most of my development in building tools, like discord bots and websites, that help me and my friends in the games we're playing.

Below you will find my preferences so that we can be more aligned as we work together to develop software.

Development Philosophy

• KISS - Keep It Simple Stupid. I prefer simple and maintainable solutions.
  • Name variables and functions for what they do.
  • Classes should mostly serve one job.
  • Add comments to add clarity for complex or abstract concepts in code if needed, but don't comment every line. Comments to describe how functions are used above the function or classes, etc are useful.
  • Cleanup as you go, remove dead code, unused parameters and dead branches of code.
• DRY - Don't Repeat Yourself. Apply this with discretion and where KISS takes precedence.
  • Write maintainable code, a human will need to read and edit this code at some point.
  • Write readable code, other humans and agents will read it later.
  • Be pragmatic in applying DRY principles, balance duplication against overly complex abstraction.
  • DO NOT add overly complex abstraction for the sake of not repeating code.
• YAGNI - You Aren't Gonna Need It. Build what we need now, not what we might need in the future.
  • Speculative code can be expensive and predictions are most likely wrong, let's keep on task and just get what we need now done.
• SOLID - Single Responsibility, Open/Closed, Liskov Substitution, Interface Segregation, Dependency Inversion
• I prefer immutable functions and Functional Programming over Object Oriented Programming.
• Apply KISS, DRY principles first, if functional wins, use that otherwise use OOP.
• Classes are good when they are simple.
• Prefer established project patterns, do not refactor or rewrite code in shared codebases to fit my preferences.
• Whenever making changes investigate for the broader picture and potential side-effects to the change you are about to make.

Questions are read-only

• If I ask a question, I'm just looking for an answer, not for you to make changes. 
• If the answer is simple and trivial, answer first and propose the change.
• Always ask before making any changes when answering a question.

Coding Preferences (TypeScript)

• Avoid any, infer types to let systems adapt to changes.
• TypeScript should look like TypeScript, not Python.
• Don't just add one-line cast-wrapper functions.
• If not specified in the project, I like using Svelte, bun, Vite
• For complex projects, I like to use SvelteKit.
• Electrobun for desktop applications.

Git

• I prefer a rebase over a merge when working on my feature branches.
  • fetch the latest from main (or other source branch if working off a shared feature branch) daily and rebase my code on top.
• Keep commits focused.
• Do not commit broad formatting changes unless I explicitly have asked for that.
• Use worktrees for new feature work to work in isolation and prevent other parallel development processes on other features from stepping on each other. Use ./.worktrees/ to store the worktree within its repository.  Remove them when the feature is complete.

Dependencies

• Do not add new dependencies unnecessarily.
• Remove unused dependencies judiciously.
• Prefer existing project dependencies.
• If it's simple enough, just write the code rather than introduce a new dependency.

Testing

• Write appropriate tests for changed behavior.
• Do not add tests unnecessarily. Simple straightforward code does not need a unit test for every single branch.
• Tests should be focused. Endless smoke tests, or regression tests for feature removals, are not as useful.
• Always run tests before commits and do not report them successful unless all tests have actually executed.
• E2E tests must be written and validate with realistic data. Garbage In, Garbage Out. Test data needs to emulate, or be, real data.

Code Review

• The agent that wrote the code SHOULD NEVER BE the agent that reviews the code.
• UI changes must be validated in a browser or the application itself. Don't just trust it looks right.

Documentation

• Keep documentation synchronized with behavioral changes. This includes both comments in code and any markdown documentation, typically in ./docs/.
• ADRs - When decisions are made for new features and those questions answered, we should create an Architectural Design Record in clean simple markdown in the repositories documentation directory. Typical preferred location would be ./docs/adr/<feature/decision-name>-<date (22AUG2026)>.md.
  • ADRs should be functionally immutable, but not read-only. If a new decision invalidates a previous decisions, update that ADR with a link to the new ADR.
• Follow the guidelines in the writing-for-agents skill when creating documentation.

Visual & Design Work

• Do not edit real components first. If the work is non-trivial UI changes, layout, or copy, build a few distinct static mocks, and ready them for manual review and wait for my feedback before implementing.
• I prefer dark mode first. Minimal copy. Minimal chrome. No em dashes. Don't add meaningless text and measurements, everything should have a purpose.
• Avoid any continuously repainting CSS animations that could increase GPU issues on high-refresh displays.
• Always design responsively. Designs should look good on both mobile and desktop. Desktops should look good from 1080p to 4k.

Agent Behavior

• Research the code and investigate before asking questions that could be answered within the repository. If you're unsure, check the docs and ADRs.
• Do not make any speculative changes. Ask to confirm.
• Keep the context usage as efficient as possible.
• Plan before we implement. Investigate the codebase, do research, and grill me with questions. I'd rather spend some time answering questions first and get a result I am happy with rather than something we'd have to do again.
• Prototype or create PoCs for large features first. If we can identify if something will or will not work early, that will save time in the long run.
• Do not touch production or live databases unless explicitly instructed to do so.
• When presenting any single local file for my review, or a structured long-form report, plan, ADR, review, or summary, load the artifact-presenter skill and open the complete file through its environment-aware presenter instead of returning the full artifact inline.
• After reporting status, if there is no input required from me, continue work on the task.

Subagents and Parallel work

• When we have several agents working together on a feature, state file ownership up front so they do not collide.