openmeld

Purpose

AGENTS.md is the high-signal router for coding agents in this repository.

Read this file first, then read only the scoped owner documents under developing/ that match the task. Do not use this file as a full architecture manual, implementation guide, migration plan, or debugging runbook.

For the documentation system itself, read developing/README.md. For stable repository vocabulary, read developing/glossary.md.

Engineering Judgment

For implementation, diagnosis, review, or planning that requires engineering judgment, use the public Practical Engineering skill (practical-engineering). Use it to keep scope outcome-first, choose the smallest coherent root-cause correction, match validation effort to real risk, and stop when the requested result is honestly proven.

If the skill is not installed and its public source cannot be reached, do not block the task on setup. Apply those four principles directly from this router and continue with the smallest evidence-backed path to the requested outcome.

This skill is decision guidance, not extra ceremony. It does not replace explicit user instructions, OpenMeld owner documents, production guardrails, or delivery and release rules. Skip it for factual answers and purely mechanical edits.

Production Guardrails

• Workstation Wakes follow RuntimeCoordinator; Remote Agent native delivery is the only exception:

OpenMeld Web Space Wake -> RuntimeCoordinator -> current-account local OpenMeld Service / daemon -> local agent execution -> Space reply, explicit visible stopped outcome, or explicit visible failure

• Production constraints apply. Do not assume broad unsafe changes, compatibility breaks, migration shortcuts, or state rewrites are acceptable.
• RuntimeCoordinator is the in-flight workstation Wake execution truth.
• Current Wakeability and one concrete Wake execution are separate facts. Current Wakeability must not hide a real Wake failure.
• A running execution must not be failed by a fixed total wall-clock timeout while RuntimeCoordinator receives fresh accepted/running lifecycle or progress evidence.
• PostgreSQL dispatch records are a durable ledger and query projection. They record what happened; they do not decide in-flight execution truth.
• The Space durable dispatch outbox is the reliable workstation Wake conveyor. Queue is scoped to hosted recovery and other Queue message families; neither owns execution or final outcome.
• Local OpenMeld Service is the local execution carrier and trust boundary. It does not own Space truth, Agent Profile identity, final Wakeability, or RuntimeCoordinator execution truth.

Context Routing

Start narrow:

1. Read developing/README.md when you need the documentation map.
2. Read only the owner docs that match the touched scope.
3. Read source code, schemas, and tests before trusting a document that might be stale.

In an isolated worktree without a local CodeGraph index, use rg for bounded source discovery. Initialize CodeGraph only when deeper structural or call-path analysis justifies a separate worktree-local index; never link another worktree's index into the current checkout.

Use these owner documents:

Core Invariants

• Human UX and agent UX are first-class requirements.
• Product-facing copy targets North American users and must be natural, clear, native-level English.
• Use one stable term for one concept across code, schemas, APIs, docs, and product copy.
• Prefer explicit contracts, single sources of truth, and root-cause fixes over fallback behavior, duplicated state, or local patches.
• Treat duplicate facts, parallel authority paths, and dual-track state as high-severity product risks. If a change introduces or preserves two sources for readiness, execution, identity, routing, Binding, Space reply placement, or diagnostics, report it directly.
• Do not hard-splice behavior by reading private implementation state across owner boundaries when a contract or projection should exist. Local hard reads can pass tests while creating hidden coupling, drift, and fragile bugs.
• Model correctness belongs at the architecture boundary first: one canonical owner, one writer, one read projection, and explicit contracts before local convenience.
• Optimize for the main product link and user need before local engineering neatness: a user can Wake an Agent Profile, the correct local OpenMeld Service runs it, and the Space shows a reply, explicit stopped outcome, or explicit failure.
• Do not add fallback/default behavior unless the owning contract explicitly calls for it.
• Fail closed when identity, ownership, readiness, or execution evidence is missing or mismatched.
• Preserve diagnostic context. Do not swallow errors or hide broken data behind generic success states.
• Keep user-facing progress simple: current outcome, one next action, and a diagnostic path when useful.

Codebase Clarity For Coding Agents

This repository is implemented and evolved primarily by coding agents. Agents infer architecture from existing names, file structure, and patterns, so every change must leave those signals cleaner and less ambiguous.

• Avoid "temporarily correct" implementations that pass the current task while preserving inconsistent terminology, half-migrated structure, stale files, duplicated patterns, or cleanup debt.
• Use one stable name for one concept across files, directories, symbols, schemas, APIs, tests, docs, and product copy. If a concept is patterns, do not introduce templates, rules, flows, or strategies for the same concept.
• Make file names and directory layout reflect the current architecture and ownership, not implementation history.
• Clean obsolete names, unused helpers, stale files, misleading test fixtures, and abandoned branches of logic when they are part of the touched scope.
• Do not leave half-renamed, half-migrated, or semantically misleading structures behind.
• When introducing a new pattern, make the owner boundary, naming, and intended extension point clear from the surrounding code.
• If existing structure is misleading but cleanup is larger than the task, avoid reinforcing it and call out the follow-up clearly.

Source-Of-Truth Rules

• Shared cross-service, cross-package, cross-process, HTTP, RPC, WebSocket, CLI JSON, or diagnostic payloads must use packages/schemas.
• Use zod/v4, derive shared types from schemas, prefer safeParse on runtime/request paths, and preserve shared external error semantics.
• Reuse packages/agent-runtime for Agent Controller refs, Agent Controller Permission Modes, OpenMeld Service Runtime identity, registry contracts, Prepare readiness summaries, Binding projections, command eligibility, and Core claim eligibility.
• User-facing Wakeability must come from the Core-owned projection defined by developing/architecture/agent-transport-contract.md; clients do not derive it from route-online, Binding existence, service health, completed Prepare evidence, Agent Activity, or one Wake's historical outcome.
• RuntimeCoordinator finalization envelopes must use the shared schema. Do not hand-build finalization payloads or expose token secrets in diagnostics.
• Live invalidation frames are refresh signals, not state. Clients must read the owning Space/Core snapshots or projections after an invalidation instead of deriving membership, readiness, Binding, service liveness, or execution truth from the frame.
• Binding command eligibility and Core claim eligibility are policy projections only. They must not reserve leases, start execution, accept results, consume queues, or publish Space replies.
• Space password text is normalized through the shared Space password schema. Do not compare, store, or forward raw password strings with leading or trailing whitespace.
• Observability correlation is a read model, not a writer or authority. runtimeCoordinatorExecutionId is not a token, credential, or execution authority.

Task Rules

• Before starting a task, re-read the user goal and choose the scoped owner docs that apply.
• For a single or batch merge-and-release task, start at Merge and Release Task, then follow the linked lifecycle and component-specific release rules. Do not infer a second delivery process from workflow YAML, tool output, or old task history.
• Use Agent Experience Feedback only for firsthand product bugs or experience gaps confirmed in current origin/main that you will not take on and that have no existing repair owner. Apply the owner's evidence, repair-status, duplicate-check, and authorized Profile rules. Keep repairs owned by you or another Agent or developer in the owning task or PR, even before a repair PR exists. Do not post temporary records, duplicate reports, or repair progress to the feedback Space. Fixed or merged problems do not qualify because deployment is pending. Follow the owner's current-origin evidence rule for a recurrence or new bug. Keep uncertain symptoms and development or validation findings in the owning task or PR.
• Use focused checks while implementation or blocker-capable review can still change the code. Treat broad affected, integration, release-ready, and Final Candidate runs as closeout evidence after the practical scope is stable, not as an iteration loop. For late findings, apply the value-and-scope boundary in developing/engineering/agent-native-delivery.md: fix a high-value, coherent finding when practical, and preserve separable follow-ups without reopening the candidate.
• Commit hooks check staged files. The push hook guards protected release refs; ordinary development pushes do not rerun affected tests. Run focused behavior checks before Ready based on the changed contract and its consumers. Do not bypass hook failures. Keep PRs draft while developing.
• Before handing off a PR, map fully resolved issues to closing keywords in its description and verify GitHub's closing links. Follow the issue-linking rules in developing/engineering/agent-native-delivery.md; comments alone do not enable automatic closure, and partial fixes must not close an issue.
• Standard Final Candidate certifies identity, trusted control, repository contracts, and path-owned database/release readiness; it does not repeat broad workspace tests. The commands, rationale, and batch flow live only in Agent-Native Delivery.
• Before declaring a user-, operator-, integrator-, or contributor-visible change done, decide whether it needs an OpenMeld Changelog entry and, when it does, follow .agents/skills/openmeld-changelog/SKILL.md.
• Before declaring a change done, answer explicitly: does this change violate any rule in the scoped developing/architecture/ owner documents? For state, readiness, availability, Wake routing, or service lifecycle changes this check is mandatory acceptance criteria, not optional review flavor. If a rule must change, change the owner document in the same PR with the reasoning.
• Load only files directly relevant to the task.
• For UI primitives and interaction changes, inspect the installed Fluid Functionalism components first and read developing/clients/shared-ui.md. Prefer shared @openmeld/ui Fluid composition; install or adapt missing official primitives there instead of rebuilding menus, hover geometry, motion, or state in product components. Stable, closely spaced clickable alternatives should reuse Fluid Hover, with semantic group boundaries, disabled-item exclusion, native keyboard/focus ownership, and reduced motion. Avoid proximity or gap activation for destructive choices, mixed clickability, large empty spaces, or rows that move during scrolling.
• Do not execute stale roadmap items directly. Plan from current production behavior and current owner docs.
• When a task specializes an existing object (a special Space kind, member role, or profile kind), inventory the parent's full user-visible and mutation surface and adjudicate every row: keep, or hide in UI and reject server-side, always in pairs. Acceptance must include a negative checklist of surfaces that must not appear or succeed. See developing/engineering/anti-patterns.md #10 and #11.
• Do not modify unrelated dirty files. If unrelated changes exist, ignore them. If related changes conflict with the task, pause only the conflicting part and ask for resolution.
• Never revert, overwrite, or delete external changes unless the user explicitly asks.
• Use rg / rg --files for search.
• Use apply_patch for manual edits.
• Keep tracked docs in English.
• Use dev-tmp/ only for local temporary material. Do not make tracked code, tests, scripts, or docs depend on dev-tmp/.

Testing And Validation

• For test additions, assertion changes, or cleanup, read .agents/skills/writing-tests/SKILL.md.
• For CI failures, read .agents/skills/debugging-ci-failures/SKILL.md. Use .agents/skills/fixing-flaky-tests/SKILL.md only when investigating intermittent failures.
• Apply these PostHog skills through the OpenMeld test guidance. Read the repository files directly when your agent does not discover them.
• Tests must prove real behavior and fail when behavior is wrong.
• Tests are conditional risk controls, not a per-file quota. Follow the Practical Test Standard in developing/engineering/development-workflow.md.
• For bug fixes, add or update a behavior-focused test that reproduces the bug before changing production code when practical.
• Do not weaken tests just to pass.
• Mocks of external contracts (HTTP responses, platform APIs, Durable Object namespaces) must be built from a captured real response or the vendor's types — never shaped after the implementation's own assumption. When an implementation changes which contract surface it consumes, re-capture the real shape first. See developing/engineering/anti-patterns.md #9.
• Use the smallest verification gate that proves the change:
  • focused package tests/checks for narrow changes
  • pnpm check
  • pnpm build when build output or package surfaces changed
  • pnpm run check:affected, pnpm run test:affected, or pnpm run test:integration:affected for changed-package validation
  • pnpm run verify:release-ready when the diff touches CLI, OpenMeld Service carrier files, OpenMeld-managed skills, daemon schemas, or release/local-components-policy.json
  • pnpm run verify:pre-push or pnpm run verify:pr for broader gates
• Use the trusted current-main Final Candidate entrypoint from developing/engineering/agent-native-delivery.md for planning, the one normal hosted request, or the Actions-unavailable local fallback. Never start the guarded control plane through candidate-owned package scripts.
• If affected scripts need a base ref, fetch it or set OPENMELD_AFFECTED_BASE.
• pnpm run verify:release-ready is the single release-readiness command for local components. When a CLI, Service, or Skills path changed, it requires a version bump and one explicit available or required decision with a reason per changed component in release/local-components-policy.json. Hashes are computed at publish time; never write them by hand.
• When a change touches CLI, OpenMeld Service carrier files, OpenMeld-managed skills, daemon/runtime schemas, Prepare Session schemas, shared HTTP/RPC/WebSocket schemas, or release/local-components-policy.json, complete the Contract Impact Audit in developing/engineering/development-workflow.md before declaring the change done or deploying. Do not treat unchanged contract constants as proof that no contract changed; explicitly decide whether old and new CLI, Service, Skills, Core, Gateway, and Web can interoperate through setup, Wake, Space actions, and diagnostics.
• For production releases, choose the local or GitHub lane and exact scope from developing/engineering/production-release.md. Do not deploy until its scoped verification passes; any Core deploy must prove the production CLI channel can satisfy the declared release. Never bypass the guarded entrypoint with raw deploy or publish commands.
• Real-user smoke must use user-accessible entry points such as OpenMeld Web UI, published OpenMeld CLI, openmeld-dev, openmeld-canary, installed OpenMeld Service commands, or product-supported trace/diagnostic commands.
• Internal HTTP/RPC calls, database SQL, Durable Object inspection, Queue inspection, admin scripts, manual cookie/localStorage edits, DB row edits, and direct projection edits are internal diagnostics only. They do not count as real-user smoke by themselves.
• Any dispatch, Wake, setup, handoff, or reply path must have deterministic diagnostic evidence. For Wake diagnosis, use:

openmeld service trace --space <spaceId> --client-message <clientMessageId> --target-profile <profileId> --view agent

Browser Automation For Real-User Smoke

• Use Agent Browser when browser automation can run in an isolated agent-controlled browser and does not need the user's real Chrome state.
• Use the Codex Chrome Plugin when OpenMeld Web smoke needs the user's real Chrome profile, existing login state, existing tabs, Chrome extensions, or production-like authenticated browser behavior.
• Use Playwright or Playwriter when the task is to create, run, or reproduce a reusable browser automation test script.
• If the user explicitly asks for Codex Chrome Plugin, Agent Browser, Playwright, or Playwriter, use the requested tool unless it is unavailable; then state the reason and choose the closest suitable alternative.

Lane And Local-State Safety

• The published openmeld lane uses ~/.openmeld and is real user state.
• Desktop development that talks to CLI, OpenMeld Service, or Web must use an aligned repo-root lane from developing/engineering/development-workflow.md; do not use package-local Electron commands or mix dev/canary lanes with production endpoints or CLI state.
• Tests, fixtures, e2e runs, snapshots, local harnesses, and destructive validation must not read from or write to ~/.openmeld unless the task explicitly validates the real installed production product and the user asked for that exact validation.
• Any test or script that touches OpenMeld Service lifecycle, service contracts, bundles, runtime leases, daemon device IDs, launchd/system-service registration, local-state repair/reset, Prepare runtime reporting, or service state must use a fresh temporary OPENMELD_HOME, openmeld-dev, or openmeld-canary.
• Repair before reset. Reset is last-resort destructive behavior for the active lane only.
• OPENMELD_HOME overrides the lane root. Commands that mutate service state must make the effective lane/root clear in output or validation notes.

Cloudflare And Admin Boundaries

• Before Workers, KV, R2, D1, Durable Objects, Queues, Vectorize, Workers AI, or Agents SDK work, re-check current Cloudflare docs and limits.
• New Cloudflare resources are not integrated until the owning wrangler.jsonc, docs, required sync scripts, and generated Worker types are updated.
• After Worker env names, bindings, wrangler.jsonc, or secrets.required changes, run the relevant type generation and env-contract verification from docs/cloudflare-workers-env.md and the repo workflow.

Git And Commits

• Commit only when the user asks.
• Commit messages must be English and follow conversational commits.
• Do not stage unrelated worktree changes.
• Do not bypass pre-push hooks with --no-verify when pushing main.
• Concurrent agents often share this worktree. Commit with explicit pathspecs, never bare git commit -a, and never amend, rebase, or rewrite a commit you did not author in the current session.
• Before committing docs-only changes, run at least:

git diff --check -- AGENTS.md developing