AGENTS.md · happier-dev/happier

Sections

1. What Happier is
2. Tier 0 — the ten invariants
3. Instruction routing
4. Scope, autonomy, and completion
5. Plan authority and lifecycle
6. Efficient execution and uncertainty resolution
7. Product priorities
8. Discovery and evidence before change
9. Documentation ownership
10. Risk-weighted execution
11. Scope-preserving solution economy
12. Durable design and justified complexity
13. Compatibility and version skew
14. Multi-agent and Git safety
15. Testing: contract value, not test volume
16. Type safety and code hygiene
17. Files, folders, and moves
18. Path canonicalization
19. Provider and catalog architecture
20. Feature, encryption, and runtime triggers

First lines (shown under the repo's MIT license)

# Agent Constitution

This file is the canonical cross-tool constitution for this repository.

## What Happier is

Happier is a cross-device client and companion for coding agents. Think of it as what you would get if Claude Desktop, Codex App, Cursor Glass and Conductor were merged into one open-source app.

Agent sessions run on computers, VPSs and dev boxes users control. Happier can connect to one or many of these machines and lets users monitor, steer, approve, review, resume and continue their sessions from a phone, browser or desktop.

People drive agents through Happier all day. It should feel warm, fluid, blazing-fast and delightful to use.

We love ambitious product ideas and simple systems. Do not preserve complexity because it already exists or introduce machinery because it looks architecturally impressive. Understand the real constraint, intent and requirements. Do not overcomplicate the implementation or invent hard requirements for speculative, unreachable or low-impact edge cases. New guarantees and machinery must be justified by an explicit requirement, released contract, reproduced failure or reachable material risk.

Do not promote an architectural possibility, speculative future consumer, generalized reuse opportunity, another proposed mechanism, or unsupported robustness/scalability target into a product requirement. Offline behavior, unattended execution, exact ordering or freshness, failover, trust models, and fixed capacity limits are path-specific contracts; establish each from current product evidence, a released security or compatibility obligation, or explicit approval.

Cross-device reachability, execution placement, state ownership, persistence, availability, and consistency are separate contracts. A feature being available on several clients or scoped to an Account establishes neither a server-side source of truth nor a multi-writer problem. Add shared materialization or cross-machine coordination only for a named current flow that cannot be served by reaching the canonical authority through existing transport.

Always make the smallest coherent systemic change at the correct canonical owner and choke point. Prevent split-brains: never add a second decision-maker, similar-but-different path or logic, or consumer-owned workaround for the same concept. Reuse, extend, extract, consolidate or refactor the relevant existing logic so the behavior is enforced by one canonical owner.

## Tier 0 — the ten invariants

1. Git safety: never switch branches, reset, restore, clean, or otherwise discard local work in the primary checkout.
2. Never remove or “clean up” unrelated uncommitted changes; dirty work is normal in this shared checkout and is not proof that another agent owns the file.
3. Production behavior changes require test-first RED → GREEN; content-only and mechanical changes do not.
4. Mock genuine system boundaries only, never internal logic.
5. Split-brain ownership is a correctness bug: fix the canonical owner, not a local symptom, and never give a consumer authority in a live path before its producer and lifecycle are proven.
6. Evidence first: distinguish observed, derived, and assumed claims; never claim a check ran when it did not.
7. Root cause over workaround; any unavoidable mitigation stays narrow, tested, labeled, and paired with its follow-up fix.
8. Feature gates fail closed when used, but refactors replace the canonical owner in place unless a gate is justified by a genuine new capability, rollout control, or supported compatibility transition; encryption envelopes are parsed explicitly rather than assumed.
9. Product runtime paths are binary-safe: no direct `node`/`npm`/`npx`/`pnpm`/`yarn`/`bunx` spawns.
10. Report outcomes faithfully: lead with the result, surface failed or skipped checks, and end with residual risk.

## Instruction routing

1. For every package in scope, follow its nearest package instructions:
   - UI: `apps/ui/AGENTS.md`
   - CLI: `apps/cli/AGENTS.md`
   - Server: `apps/server/AGENTS.md`
   - Stack: `apps/stack/AGENTS.md`
   - Docs: `apps/docs/AGENTS.md`
   If the relevant instructions are not already present in active context, read them before changing that package. Do not reread instructions already present unless they changed during the task or context loss made their contents unavailable.
2. Use repository skills when the requested task matches their purpose, not merely a keyword. Reuse unchanged instructions already active in context; after context loss, recover only the missing applicable instructions and task state. Do not reload a skill or its references at every lane, phase, or handoff. Use the existing routing:
   - `.agents/skills/happier-plan` only for an explicit request to create, replace, or materially refine a repository plan; complexity alone is not a trigger.
   - `.agents/skills/happier-implement` for source changes. Add `.agents/skills/happier-implement-plan` when executing an approved plan; it preserves plan authority rather than redesigning it.
   - `.agents/skills/happier-commit-worktree` only for a user-requested large or continuously changing worktree commit campaign, not an ordinary scoped commit.
   - `.agents/skills/happier-review` is the only general Happier review/QA orchestrator. The archived `review-protocol` and `code-reviewer` skills must not be invoked.
   - `.agents/skills/happier-pr-steward` for user-requested pull-request stewardship; it composes `happier-review` and the mutation authority in `happier-github-ops`.
   - `.agents/skills/happier-port-0-2-to-0-3` after every coherent validated 0.2 change batch. Validate 0.2 first, then give every intent an evidence-backed 0.3 disposition through the evolved owner; the skill never stages or commits.
   - `.agents/skills/happier-testing` for TDD, test quality, lane selection, and live validation.
   - `.agents/skills/happier-docs` for internal or published documentation.
   - `.agents/skills/happier-instruction-eval` only for an explicit instruction-variant evaluation or an approved evaluation boundary.
   - `.agents/skills/happier-issue-triage` for read-only issue retrieval, clustering, and routing; `.agents/skills/happier-issue-diagnose` for deep read-only diagnosis. Issue correction, release follow-up, labels, closure, attribution, and reporter handoff follow `docs/issue-triage.md`. On 0.2, validate the source correction, then complete its 0.3 disposition.
   - `.agents/skills/happier-diagnose` for read-only runtime/support incidents; requested source fixes proceed through `happier-implement`.
   - `.agents/skills/happier-profile-and-optimize` when success is measured performance; implementation still uses `happier-implement`, and UI write-time rules remain in `apps/ui/AGENTS.md`.
   - `.agents/skills/happier-compatibility` for wire, persistence, mixed-version, upgrade, rollback, and 0.2 → 0.3 seams.
   - `.agents/skills/decompose-gates` for hard multi-part work and lane briefs; `.agents/skills/verify-claims` before relying on delegated or external claims; `.agents/skills/attack-conclusion` before non-trivial handoff; and `.agents/skills/handoff-report` for substantive findings or completed work.
3. Use available tool-specific skills when the task calls for them: current-docs/Context7 for version-sensitive library behavior, browser/device skills for live QA, and autoreview at an approved substantial review boundary, explicit user-requested review point, or risk-selected closeout—not automatically for every non-trivial edit.
4. Read `docs/agent-craft.md` when the task is hard, ambiguous, high-stakes, or context loss has made the working method materially unclear.

## Scope, autonomy, and completion

- For answer, explain, review, diagnose, explore, or plan requests: inspect the relevant materials and report; do not implement unless the user also asks for changes.
- For change, build, fix, or refactor requests: make the requested in-scope local changes and run relevant non-destructive validation without asking first.
- Ask before destructive actions, external writes, sensitive-data access, costly operations, or a material expansion of product/design scope. An explicit bounded standing authorization satisfies this requirement for its named targets, action classes, and lifetime; do not ask again for each covered mutation, and do not extend the grant by inference.
- If the user’s intent is clear and the next step is reversible and in scope, proceed.
- Treat the task as incomplete until every requested item is handled or marked `[blocked]` with the missing fact and next action.
- For multi-item work, track coverage internally and verify it before finalizing.
- Parallelize independent retrieval; keep dependent work sequential and synthesize retrieved evidence before acting.
- If an explicit authorized requirement or primary evidence genuinely conflicts with a repository or package rule, do not silently violate the rule, weaken the requirement, or route around the conflict. Name the exact conflict and obtain a human decision before proceeding with the affected work; continue independent unaffected work when safe.
- A rule being inconvenient, requiring a broader coherent change, or invalidating the first implementation idea is not a conflict.

## Plan authority and lifecycle

- Create, replace, materially refine, or expand a repository plan only when the user explicitly asks. An internal ephemeral checklist is not a repository plan; do not create plan files or invoke plan-authoring workflows on agent initiative.
- After the user approves a plan, treat its required outcomes, ownership, interfaces, compatibility obligations, removals, user flows, exclusions, and acceptance criteria as the execution contract. Do not silently reinterpret, simplify, expand, substitute, or redesign them.
- Mechanism-sized plan decisions must trace through dependent machinery to an approved requirement, constitution rule, external contract, reproduced failure, or reachable derived risk. Apply the deletion test recursively; another proposed mechanism, future consumer, generalized reuse opportunity, or architectural completeness is not a terminal justification. Do not add coordination, exactly-once semantics, fencing, generations, new identities, timers, cross-restart durability, or similar topology as generic hardening; if the root requirement disappears, remove its dependent chain. User approval authorizes the plan as a whole; only unresolved product decisions or material amendments require item-level re-ratification.
- Before acting on an approved plan, read the complete plan if it is not already present in active context, orient to the assigned lane and current load-bearing code, and begin implementation. Do not create a separate plan-review or preflight-review phase unless the user requested one or the implementation basis materially changed.
- Implementation may update designated execution status and evidence, and use best judgment only where the plan intentionally leaves details open. It may not change the approved contract, acceptance criteria, or design decisions; material ambiguity requires clarification, and unrelated discoveries are reported without expanding scope.
- If primary evidence makes an approved requirement unsafe, contradictory, impossible, unable to serve its intent, or dependent on a materially different topology, owner, external dependency, compatibility transition, or product tradeoff, pause affected work, record the evidence, and propose the smallest amendment. Increased effort alone is not material. Evidence may challenge but never supersede the plan: use `AMENDMENT_REQUIRED` until the user approves a documented replacement, then `SUPERSEDED_BY_APPROVED_AMENDMENT`. Continue only independent work that cannot prejudge the decision.
- For delegated implementation, each meaningful lane reads the complete approved plan unless it is already in active context, then receives a concise self-contained lane brief with exact ownership, paths, dependencies, acceptance checks, validation, and stop conditions. Do not duplicate the whole plan or parent transcript in the brief; reference the on-disk plan and use minimal inherited conversation context.

## Efficient execution and uncertainty resolution

- Use maximum useful parallelism: keep ready independent retrieval, implementation, QA preparation, and verification moving when doing so shortens the critical path. Do not target a fleet size, create filler lanes, or parallelize work whose next decision depends on unfinished evidence.
- Coordinate only actual collisions: the same edit hunk, incompatible decisions at one live contract or conceptual seam, destructive rewrites/moves, generated outputs with one producer, or an exclusive mutable runtime resource. A dirty or previously touched file is not a collision; inspect current bytes, preserve compatible work, and layer the change. Ask only when competing intents cannot be reconciled from the plan and evidence.
- Treat uncertainty as an investigation task. First ask whether the missing answer is empirical: if source, history, a focused prototype, test, measurement, log, runtime observation, or current primary documentation can decide it safely, retrieve that evidence. Ask only for a genuine product, preference, authority, or tradeoff decision evidence cannot settle, or unavailable external state. Mark `[blocked]` only after meaningful safe retrieval cannot resolve a decision-material ambiguity.
- For repetitive or repo-wide mechanical work, first consider existing repository scripts, compiler-assisted renames, AST-aware codemods, structured search/replace, formatters, or a bounded one-off transformation. Prefer them when they reduce omissions and total turns; preview or scope the transformation, inspect the diff, and run representative plus relevant broader validation. Do not build a codemod when a few direct edits are safer and faster.
- Independent tool calls whose inputs are already known, whose results are necessary, and which do not conflict belong in one bounded tool stage when the runtime supports batching. Use the runtime's native batching mechanism; use concurrency only when calls are genuinely independent.
- Use a later tool stage when the next call depends on an earlier result, the investigation is adaptive, an approval or wait is pending, or operations conflict over shared mutable state. Writes are not automatically sequential, but approval-sensitive, interdependent, or potentially conflicting mutations are.
- Keep bulky intermediate results inside the tool runtime when possible. Return one compact decision-relevant projection while preserving failures, exact evidence pointers, paths, IDs or handles, and output needed for verification.
- Do not add speculative calls, broaden the investigation, or run unused work merely because batching makes additional calls cheap. Efficiency never authorizes skipping canonical-owner discovery, RED/GREEN proof, or risk-appropriate validation.
- Reuse the existing process, run, or agent handle. Prefer completion notifications that actually reach the responsible agent; otherwise use an interruptible wait. Poll only when those mechanisms are unavailable or a concrete diagnostic question requires inspection. Do not add status checks alongside a working notification or wait mechanism.
- Within the current task and its delegates, avoid independently monitoring an operation whose executor will deliver its result. This does not require cross-session discovery, ownership negotiation, registries, or messages; do not spawn an agent solely to poll. Existing build/runtime tooling owns shared resource locks.
- Continue useful independent work while an operation is pending. An expired wait, empty output, or unchanged heartbeat leaves it pending; resume waiting on the same handle without automatically inspecting again or restarting the operation. Investigate evidence of failure, required intervention, or a material departure from expected behavior. Preserve cancellation, user steering, logs, and terminal-result verification; do not infer current health from an old observation.
- Resume an interrupted or capacity-limited lane on its existing handle when the prerequisite changes and the runtime supports it. Preserve completed findings and applicable validation. Replace only an unavailable/unresumable agent or a materially changed assignment, carrying the unresolved scope and evidence rather than full history. Do not repeat equivalent retries while the same quota or outage persists. Distinguish review-service unavailability from an evaluated denial; neither supplies missing approval or closes a required review gate.
- Process artifacts are costs, not evidence. Use the smallest orchestration, tracking, and review structure that preserves execution continuity and can falsify decision-material claims. Do not create source/worktree/plan hashes, release-representation manifests, leases, receipts, custody logs, mirrored status systems, per-lane ledgers, task-count gates, or repeated review rounds unless an approved product or release protocol requires that exact mechanism. A feature plan cannot declare itself a release protocol to create this exception. Product-defined integrity hashes, package SRI, release checksums, persisted identities, and security protocols are unaffected.

## Product priorities

- Performance and long-term maintainability are product requirements for user-facing, sync, transcript, terminal, provider, server, and daemon flows.
- Do not trade correctness, accessibility, state continuity, privacy, or user trust for micro-optimizations.
- For performance-sensitive work, prefer measured evidence such as timings, render counts, profiler output, focused performance tests, or a clear explanation of why measurement was not feasible.
- Name the phase and the metric before optimizing, and confirm the instrument can observe the cost you are chasing: a framework-scoped profiler cannot see work outside that framework. If total blocked/elapsed time materially exceeds what the instrument attributes, the instrument is wrong about the target — widen it before optimizing what it did show. Attributing that residual to a suspected cause by subtraction is a hypothesis, not a measurement; observe the cause directly before fixing it.
- Claim no ratio, percentage, or speedup without both sides measured on the same workload and machine state; state the workload size. Prefer counts, blocked time, and work-avoided proofs over wall clock on a shared machine.
- React/UI state changes preserve subscription locality and referential stability and avoid preventable broad rerender/recomputation churn; do not add blanket memoization or caches without evidence that they improve the real bottleneck.
- Delivery follows consumption. Before adding or widening a sync, socket, list or snapshot payload, name each consumer and the facts it reads; send full content only to clients currently consuming it and route others through the canonical delivery classifier (bodyless facts, versions or nothing). Demand derives from current activity and ends with it: retained, last-used, cached or historical state is not demand.
- Reconcile incrementally and checkpoint only what is applied. Row-level changes update rows and gather missing documents through the canonical batch owner; full list or snapshot refreshes are for structural, unknown or gap cases. Never advance a cursor, watermark or sequence past data that is not yet materialized; a timeout, cancellation or superseded wait never authorizes advancement.
- User-initiated recovery (Retry, reconnect, foreground) must be able to supersede in-flight work promptly: reads keep cancellation through body completion, a superseded run's waits are cancellable, and an unbounded retry or backoff cycle never holds a fresh user-initiated attempt.
- A performance optimization is incomplete if it regresses user-visible behavior, freshness, continuity, accessibility, responsive layout, platform behavior, or failure/recovery UX.
- Windows, Linux, and macOS are first-class for CLI, daemon, terminal, install/update, filesystem/path, process, and integration behavior. Do not introduce POSIX-only or single-shell assumptions; validate every materially affected platform path or report the unvalidated platform and residual risk.
- Prefer designs with fewer competing paths, clearer ownership, stronger invariants, and less future drift.

## Discovery and evidence before change

Before changing production behavior:

- Observe current behavior and, for bugs, reproduce or identify the failing path when feasible.
- Trace the relevant path through inputs, normalization, state/persistence, feature decisions, provider/catalog hooks, callers, readers/writers, tests, and user-visible outputs.
- Search by symbol and by domain identifiers such as routes, commands, config keys, feature ids, provider ids, event types, storage keys, schema names, environment variables, errors, fixtures, and UI identifiers.
- Search the touched path and surrounding domain for **split-brains**: existing, similar, competing, or parallel owners, implementations, registries, parsers, normalizers, state machines, schemas, feature decisions, compatibility adapters, readers, or writers for the same concept.
- Change behavior through the established canonical owner; reuse, extend, refine, extract, consolidate, migrate, or remove there before adding logic.
- Before implementing against an external or another-program-owned contract, characterize its success, failure, cancellation, and recovery behavior from primary evidence and record the exact contract version or evidence basis used by the implementation/review slice.
- An existing same-concept split-brain in the touched corridor is part of the correctness scope even when it predates the task. Do not build on one side, add a third path, or leave competing decision-makers active. If the canonical correction materially exceeds authorized scope, mark `[blocked]` rather than shipping another local path.
- For user-visible or cross-component changes, identify every materially affected product surface reached by the changed owner or promised by the task: entry points, clients/platforms, runtime roles, agent/provider variants, lifecycle/recovery paths, and documentation. Mark unaffected surfaces not applicable with a reason. This is a reachability check, not authorization to manufacture parity, abstractions, compatibility machinery, or Cartesian test matrices.
- Code and runtime establish current mechanics, not historical intent. Do not infer behavior from filenames, comments, or stale documentation, or rationale from code shape. Verify behavior against implementation, tests, logs, schemas, or runtime observations; verify rationale against approved decisions, issues, PR history, incidents, or named external contracts, otherwise label it inferred.
- Treat discovery as incomplete until you can name:
  - the canonical owner;
  - the affected callers, readers, and writers;
  - the relevant tests and harnesses;
  - any split-brain, parallel implementation, bypass, or compatibility path;
  - why the proposed change belongs at that owner.
- If one of those remains materially unknown, keep investigating. Once they are known and the required evidence is sufficient, stop searching rather than collecting optional confirmation.
- State what evidence is missing and what would verify it when a conclusion remains uncertain.

## Documentation ownership

- `docs/**` owns internal technical and product-architecture documentation: protocols, canonical owners, data flows, compatibility, persistence, encryption, deployment internals, and contributor-facing architecture.
- `apps/docs/content/docs/**` owns published documentation for users, operators, self-hosters, providers, and public contributors.
- A behavior or contract change updates every materially affected canonical documentation page in the same coherent change, or the handoff explains why no documentation change was needed.
- Search for and update the existing canonical page before creating another. Do not leave similar-but-different explanations of the same concept.
- Documentation is a claim, not proof of implementation. Verify Happier behavior against the implementing code and the target release/channel before documenting it.
- Distinguish shipped, preview, development-only, experimental, deprecated, and planned behavior explicitly. Do not present an unreleased intermediate as available.

## Risk-weighted execution

- Risk is probability of error × cost of error × silence of failure. Persistence formats, dedupe keys, migrations, encryption envelopes, watermarks, and outward writes deserve more verification than loud compile/runtime failures.
- A possible race or edge case is not itself a correctness requirement. Before adding reliability or coordination machinery, state the reachable consequence without it, the authority and state affected, observability, existing recovery, and reversibility. Distinguish authoritative or non-reconstructible state from a projection proven refreshable from an available source; do not infer disposability from a `cache` label.
- A limit, quota, timeout, retry budget, size cap, truncation threshold, or guard is product behavior. Before adding or changing one, find the canonical lifecycle/resource owner and reuse its budget or boundary. Do not invent a local default or "safety" ceiling from intuition, a nearby value, a test duration, or one observed sample; a subordinate phase must not impose a shorter competing cutoff on its containing operation without a separate contract. If no correctness, security, external/platform, storage, or measured resource boundary requires a limit, omit it. When a bound is required, name the protected resource or contract, derive the value from that boundary, make firing observable, specify recovery, and test both the boundary and valid behavior near it. Preserve useful valid data through paging, bounded projection, truncation, or explicit incompleteness when safe; reject only when the owning contract requires rejection.
- Before implementation, name the load-bearing facts whose falsity would make the change unsafe or incorrect, prioritizing the two or three most damaging or least visible failure points. Design checks that can falsify those facts at the lowest practical real boundary.
- A fallback, retry, downgrade, or `catch` that cannot be observed in production is itself a defect: report it on a signal that is on by default, or fail loudly instead. A path gated behind opt-in telemetry is unobserved.
- Coalescing, de-dupe, and cache keys must include every input that changes the result, and only work guaranteed to settle may be coalesced — one hung shared promise poisons every later caller. A read-await-write cache without in-flight sharing lets N concurrent callers each do the whole job, and a batch or threshold API called one item at a time silently disables the decision it exists to make.
- Audit boring mechanical stretches as deliberately as the interesting core.
- For implementation work:
  1. establish current behavior and the canonical owner;
  2. inventory existing coverage and choose the smallest meaningful RED test when behavior changes;
  3. make the smallest coherent systemic change;
  4. run the narrowest relevant GREEN check;
  5. broaden validation according to risk;
  6. self-review for bypasses, duplicate paths, neighboring cases, and environment gaps.