synergy AGENTS.md

Synergy Repository Rules

These rules apply to the Bun/TypeScript monorepo. Read the nearest package AGENTS.md before editing package code. Each rule links the document holding its 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.
• 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 <[email protected]> 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.