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

Hive — Engineering Principles

These are not rules about tools, patterns, or technologies. They are qualities of work that endures — true before any of us wrote our first line of code, and true long after every framework we use today has been forgotten.

1. Understanding

Comprehension before action.

The quality of good work begins with knowing what already exists and why it exists. Every system carries the accumulated wisdom of every problem it has survived. That wisdom is invisible to anyone who does not take the time to find it.

Acting without understanding is not speed — it is recklessness with a delayed cost. The cost always arrives. The only question is whether the person who caused it is still around to pay it.

2. Resolve

No half-measures. No surface-level fixes.

When a problem appears, the temptation is to silence the symptom and move on. This is not a fix — it is a postponement, and postponed problems return with interest. The only work worth doing is work that addresses the cause, not the manifestation.

A temporary patch applied under pressure has a way of becoming permanent infrastructure. What was meant to last a week outlives the person who wrote it. The discipline of good work is the refusal to leave something half-solved — to keep asking why until the answer stops changing. A system built on suppressed symptoms is a system waiting to collapse under a weight no one can trace.

Completeness is not perfectionism. It is the recognition that unfinished work is not neutral — it is debt, silently accumulating against every future change.

3. Separation

Distinct concerns remain distinct.

Things that change for different reasons do not belong together. This is not a preference — it is a law of maintainability. When unrelated concerns are tangled, changing one inevitably damages the other. The system becomes fragile not because any single part is weak, but because nothing can move independently.

The boundaries between concerns are not walls — they are contracts. Each side promises what it will provide and asks only for what it needs. The less each side knows about the other, the more freely both can evolve.

4. Honesty

Systems that tell the truth about their state.

A system that hides its failures is a system that cannot be trusted. When something goes wrong, the first duty is to acknowledge it — to the operator, to the user, to the log. Silence in the face of failure is not resilience. It is deception, and it compounds.

The same honesty applies at the edges. Data arriving from outside the system carries no guarantees. Treating unverified input as trustworthy is not optimism — it is negligence. What enters must be examined before it is allowed to flow deeper.

5. Clarity

Every part justifiable, every intent visible.

A piece of work should exist for a reason that anyone can articulate in a single sentence. If the explanation requires the word "and," the work is carrying more than one responsibility, and the weight will eventually cause it to buckle.

The names given to things are not decoration — they are the primary documentation. A name that communicates its purpose to a stranger is worth more than a page of comments. And when explanation is necessary, it should answer why a decision was made, never merely restate what the code already says.

Consistency in convention is itself a form of clarity. A codebase that follows one pattern — even an imperfect one — is easier to navigate than one that follows many "better" patterns chosen independently.

6. Integrity

One truth, one owner, no contradictions.

Every piece of information in a system should have exactly one authoritative source. When the same truth is stored in two places, divergence is not a risk — it is an inevitability. The system does not become unreliable the moment the copies diverge. It became unreliable the moment the copy was made.

What is true underneath must be true on the surface. The representation shown to the user must never precede the reality it represents. And everything the system acquires — every connection, every resource, every allocation — must be released when its purpose is fulfilled. What is borrowed and never returned accumulates silently until it becomes catastrophic.

7. Empathy

Built for the human on the other side.

Every interaction is a conversation between the system and a person. That person deserves to know that their action was received, that something is happening, and what the outcome was. A system that accepts input and offers no response has broken the most fundamental contract of interaction.

The experience must account for every state a person might encounter — not only the ideal case, but the empty case, the waiting case, the broken case, and the case where action is not available. Handling only success is delivering an incomplete promise.

Visual and behavioral consistency is a form of respect. When a system looks and behaves predictably, it earns trust. When it contradicts its own patterns, it spends that trust. Every motion, every transition, every visual change should exist to communicate meaning — never merely to impress.

8. Restraint

Use only what is needed.

A system must never hold its user hostage while it works. Long work happens in the background; the person remains free. Repeated triggers must be tempered so the system does work proportional to the request, not proportional to the number of times the request was accidentally repeated.

What has not changed should not be rebuilt. Recomputation without cause is waste, and waste compounds in systems that run continuously. The resources available are always finite, always shared, and always less than they appear. Code that is unconscious of its own cost is code that will eventually be the bottleneck.

9. Vigilance

Trust nothing from outside the boundary.

Everything that enters from beyond the system's control — every input, every response, every file — is unproven until examined. This is not paranoia. It is the recognition that the system's integrity depends entirely on what it allows through its doors.

Dynamic construction of executable logic from untrusted data is not a shortcut — it is an abdication of control. And secrets — credentials, tokens, keys — belong to the environment that holds them, never to the source that is shared.

10. Discipline

Every contribution is deliberate, traceable, and reversible.

Each change to the system should carry its own explanation — what was done and why. When changes are entangled, none of them can be understood, verified, or undone in isolation. Atomic contributions are not bureaucracy — they are insurance.

The artifacts that the system produces — its compiled outputs, its caches, its generated files — are consequences of the source, not the source itself. They do not belong alongside it.

Nothing is complete until it has been witnessed working. Running the system, walking the path the user walks, verifying with your own eyes — this is not optional diligence. It is the minimum standard. Untested work is not cautiously optimistic. It is a guess dressed as a contribution.

11. Humility

The willingness to pause, to ask, and to improve incrementally.

Uncertainty is not weakness — it is awareness. The cost of acting on a wrong assumption is always greater than the cost of pausing to verify. When confidence outpaces understanding, damage follows.

Small changes that can each be verified independently are safer than large changes that require everything to go right at once. The desire to rewrite from scratch is almost always the desire to replace understood problems with unknown ones. The working system — imperfect, scarred, battle-tested — contains lessons that no rewrite can recover.

The deepest skill is not the ability to produce. It is the ability to comprehend what already exists, to see why it is the way it is, and to improve it without destroying what it already knows.