AGENTS.md

Synergy Repository Rules

Bun/TypeScript monorepo rules. Read the nearest package AGENTS.md before editing code. Rules link their rationale. Placement and budgets follow docs/AGENTS.md.

Work from Current Evidence

• Verify the implementation, tests, schemas, generated contracts, and current CLI before changing code or docs.
• Use Scope for workspace resolution/context and Library for the knowledge subsystem. Keep retired names inside docs/migrations/ or docs/research/ only.
• Start architecture work at docs/README.md, then read only the relevant document.
• Inspect adjacent domains before assuming a directory boundary.
• Keep a nearest AGENTS.md in every workspace package; update it when that package's ownership, public boundary, or verification commands change.
• Fix the root cause with a focused change; preserve unrelated user work and avoid opportunistic cleanup.

The project-local architecture skill provides the code-tracing workflow and links canonical documents instead of duplicating them.

Protect Checkouts and Runtimes

The primary checkout, pre-existing checkouts, and active Synergy runtime may be shared by concurrent sessions.

• Inspect git status, the current branch, and the worktree list before editing or performing Git operations. Direct edits in the current checkout are allowed; preserve unrelated dirty and untracked files.
• Do not run git checkout/git switch or rebase a shared checkout unless the user explicitly requests it; these change state observed by every session using that directory.
• Use a task-owned worktree when concurrent work needs branch or file isolation; reuse an existing task worktree when it already owns the branch.
• Stage and commit only when the user requests it. Local commits on dev or main are permitted but advance a shared branch and must never be pushed directly; publish a topic branch and open its PR against dev. Release is the only path from dev to main.
• Preserve unrelated dirty and untracked files; inspect status again before staging and stage only files owned by the current task.
• Do not use destructive Git commands, force pushes, or hook bypasses without explicit user authority and a reviewed recovery plan.
• Push, open a PR, or mutate external systems only when the user requests that action.
• A pull request whose intent corresponds to a BlueprintLoop is accepted only when that loop reached completed through blueprint_loop_approve. An executor's self-assessment, or a loop that stalled in auditing, failed, or was rejected without a fresh audit, is not acceptance. State the loop's final status and audit conclusion in the pull request body.
• Keep local/runtime paths, session/Scope IDs, logs, credentials, and private endpoints out of commit messages, PR bodies, comments, and reviews. Every agent-created commit uses a concise conventional type and the Co-authored-by: synergy-agent <299070056+synergy-agent@users.noreply.github.com> footer.
• Never stop, restart, signal, or modify the SYNERGY_HOME of the Synergy instance carrying the current task.
• Run source changes in an isolated second home with explicit alternate ports. Load develop-synergy for the exact workflow.

Load git-guide for worktrees, history, commits, rebases, pushes, and PRs.

Development Entry Points

The root bun dev orchestrator is for source development; the installed synergy CLI is a product surface.

bun dev prepare
bun dev server
bun dev app --open
bun dev web
bun dev desktop
bun dev desktop --managed
bun dev send "request"

See Development reference for modes, isolated instances, builds, tests, and SDK generation. Desktop packaging and updates follow Desktop release.

Implementation Discipline

• Match established namespace/module patterns. Import z from "zod"; infer types from schemas and avoid any.
• Prefer const, early returns, async/await, and real Promise.all() parallelism.
• Preserve structured error data. Use NamedError.create() or local error classes where the owning domain already does.
• Use Bun file APIs where they improve clarity and match surrounding code.
• Do not add inline comments, headers, adapters, fallbacks, or abstractions unless they explain a durable non-obvious constraint.
• Cite materially used papers, standards, upstream or community work, benchmarks, experiments, and research beside the authoritative implementation; development-standards defines format and the decision record holds the rationale.

Persistence and compatibility

• Put versioned persisted-state upgrades in the owning domain migration plus the central migration runner. Test fresh-install and upgrade paths.
• Do not scatter one-off backfills through handlers or startup logic.
• Prefer one current code path after migration. Keep unavoidable compatibility shims narrow, named, tested, and time-bounded.
• Do not reintroduce retired session/message booleans or derive canonical semantics outside MessageV2.deriveSemantics() and MessageV2.isSystemPart(). Read Sessions and messages.

APIs and frontend calls

• Add OpenAPI metadata to server routes and run ./script/generate.ts after route or API-schema changes.
• Use createSynergyClient() and generated methods for internal Web APIs. Reserve raw browser transports for streams, external URLs, browser file/blob flows, and platform-provided fetch injection.
• Preserve auth, Scope/directory parameters, error semantics, and asset URL formats when changing a client call.
• Product color utilities must follow Frontend themes and color and resolve through the public canonical contract in packages/plugin/src/theme; packages/ui/src/theme is the compatibility/runtime boundary. No Tailwind palette colors, literal color utilities, or component-local light/dark palettes. Change seeds or typed overrides in a structured theme, run the theme generator, and never hand-edit generated fallbacks. Plugin Kit and the host share the validated Theme JSON parser.

Configuration and credentials

• Canonical global and project config uses the domain files documented in Configuration. Monolithic config is migration input only.
• Keep openai-codex OAuth/Codex-backend auth separate from openai Platform API-key auth and billing language.
• Treat auth stores, plugin credentials, diagnostics, logs, and secret-like files as sensitive. Use redacted metadata for model-assisted permission decisions.

Durable Architecture Boundaries

Read the owning architecture document before changing these areas:

• session/message/compaction and LLM loop: docs/architecture/session-and-messages.md, llm-loop.md
• frontend snapshots, events, replay, reconcile, and eviction: frontend-data-sync.md
• capability classification, control profiles, permissions, and sandbox: execution-boundaries.md
• Cortex child sessions and task outputs: cortex.md
• Plan, Blueprints, BlueprintLoop, Light Loop, and Lattice: workflows.md
• Browser Desktop-native presentation, page collections and identity ownership: browser-runtime.md
• Channels, managed Projects, provider lifecycle, and Native Clarus tasks: channels.md

Do not create compatibility paths that violate those contracts. In particular:

• guarded is the only standard interactive profile; autonomous never asks; full_access silently allows permission-system capabilities but cannot suppress ordinary runtime failures.
• Worktree isolation permits ordinary external reads while protecting sensitive paths and blocking unapproved external writes/execution.
• Browser is Desktop-local and uses real WebContentsView pages with immutable identities and explicit Agent page targets. Keep human selection independent; do not add WebRTC, headless, iframe or screenshot-stream fallbacks.

Tool, Agent, and Plugin Changes

• Load add-tool, add-agent, or add-cli-command for their complete implementation and verification workflows.
• A first-party tool requires backend registration, taxonomy, and all Web presentation/classifier registrations described by add-tool.
• Built-in primary agents are Atlas (general), Forge (coding), and Pico (lightweight); use Harness agent/primary-identity. Visibility masks and delegation groups define subagent catalogs. BlueprintLoop and Light Loop reviewers stay host-selected; Workbench-enabled sessions show their recorded Cortex tasks in Task details; minimal servers retain installed Cortex interfaces.
• Plugins use the public definition, generated manifest, capability-gated Host Services, process runtime, operation/event/hook, approval, and trusted UI contracts in Plugin documentation. Do not import private runtime modules into plugins.

Testing and Quality

Write a failing behavioral test first for new behavior and bug fixes. Test public invariants, not source text or incidental implementation. Use real temporary Scope/storage fixtures instead of broad mocks; load testing-guide for selection and isolation rules.

Every test file must live under the test/ directory of its owning package, mirroring the relevant source domain when useful; repository-level script and policy tests belong under the root test/ directory. Do not colocate *.test.*/*.spec.* beside src/, script/, or implementation directories; bun run test-layout:check enforces this.

Core tests run from packages/harness:

cd packages/harness
bun test test/<domain>/<file>.test.ts
bun test
bun run test:ci
bun run test:coverage

Frontend suites run via bun run --cwd apps/web test and bun run --cwd packages/ui test, both part of the Turbo test graph. Browser capability or App bootstrap changes also run the browser crypto contract and the production-build private HTTP browser smoke in apps/web/AGENTS.md.

Coverage has a floor: bun run coverage:check enforces per-package thresholds via script/coverage-exempt.json (exclusions only through that manifest; every entry carries a reason; broad ones rejected). Run the narrowest relevant check locally and let CI own the full matrix — never default to the full suite for a commit or push. Use verify local --test <path> for focused checks and verify plan for scope. Hooks reuse identical local static inputs; CI runs independently.

Never raw bun test --coverage/--parallel on packages/harness — workers drop preload env, writing into the real home. TestHomeGuardError blocks without SYNERGY_TEST_HOME unless SYNERGY_ALLOW_REAL_HOME=1.

Documentation and Decision Records

Update documentation in the same task when behavior changes; placement follows the tier table in docs/AGENTS.md. Generated reference pages (cli.md, configuration.md, tools.md) must never be hand-edited; run their script/gen/* generators instead.

Every non-trivial change MUST add or update an implemented decision record in docs/decisions/ in the same PR; only mechanical or local edits are exempt. Records follow the path-encoded lifecycle/class scheme and format contract in Decision records; bun run decision:check gates them. Bugs go to postmortems, rationale to decision records, procedures to cookbooks — see docs/AGENTS.md.

Review at least README.md, relevant setup/help text, and the owning Skill when a change affects CLI, agents, tools, config, paths, startup, logs, storage, tests, packages, release, or user-facing product areas.

Development standards live in Skills

.synergy/skill/ is the executable source-development handbook for this repository. When implementation or review reveals a reusable development rule that no Skill captures, update the focused owning Skill or create one in the same change. Keep AGENTS.md focused on safety, global invariants, and routing; keep step-by-step procedures, examples, and verification checklists in Skills. Load development-standards when ownership is unclear.

Release and Security

• Product and package releases run through .github/workflows/release.yml; do not update main manually.
• Keep package/release behavior aligned with docs/operations/desktop-release.md and docs/operations/open-source-quality.md.
• Never open a public issue for a vulnerability. Follow .github/SECURITY.md.

Repository Skills

development-standards (route changes, capture rules), architecture (trace ownership), develop-frontend/integrate-llm (Web UI, model-backed), change-server-api/change-persistence (API, durable state), change-execution-boundaries (permissions, sandboxing), change-browser-runtime (Browser/Desktop presentation), change-computer-runtime (native Computer), change-channel-runtime (Channels, providers, Clarus), change-plugin-runtime (Plugin API), develop-synergy (isolated instance), testing-guide (fixtures), develop-benchmark (evaluation infrastructure), git-guide (worktrees, PRs), add-agent/add-cli-command/add-tool (workflows), find-logs/inspect-sessions (diagnostics), report-bug (issue drafting), find-simplifications (surface audits), release-log-workflow (notes).