synergy: Instructions file for Codex

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 implementation, tests, schemas, generated contracts and CLI before editing.
• 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 ownership.
• Keep a nearest AGENTS.md in every workspace package; update it when that package's ownership, public boundary, or verification commands change.
• Fix root causes; preserve unrelated 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

Checkouts and active Synergy runtimes may be shared.

• 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 <[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.