Skip to content

docs(agents): codify merge/worktree discipline + shared read-only permission allowlist #1555

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
xuyushun441-sys merged 1 commit into from
Jun 3, 2026
Merged

docs(agents): codify merge/worktree discipline + shared read-only permission allowlist #1555

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
24 changes: 24 additions & 0 deletions .claude/settings.json
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,24 @@
{
"permissions": {
"allow": [
"mcp__Claude_Preview__preview_screenshot",
"mcp__Claude_Preview__preview_network",
"mcp__Claude_Preview__preview_console_logs",
"mcp__Claude_Preview__preview_snapshot",
"mcp__Claude_Preview__preview_list",
"mcp__Claude_Preview__preview_logs",
"mcp__chrome-devtools__take_snapshot",
"mcp__chrome-devtools__take_screenshot",
"mcp__chrome-devtools__list_pages",
"mcp__chrome-devtools__list_console_messages",
"mcp__chrome-devtools__list_network_requests",
"mcp__Claude_in_Chrome__read_network_requests",
"mcp__Claude_in_Chrome__get_page_text",
"mcp__Claude_in_Chrome__find",
"mcp__Claude_in_Chrome__read_console_messages",
"mcp__Claude_in_Chrome__list_connected_browsers",
"Bash(agent-browser snapshot *)",
"Bash(agent-browser skills *)"
]
}
}
15 changes: 11 additions & 4 deletions AGENTS.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
# ObjectStack — AGENTS.md

Primary AI instruction file for this repo. Mirrored at `.github/copilot-instructions.md` — keep both in sync.
Primary AI instruction file for this repo. Read natively by Claude Code, GitHub Copilot (coding agent + CLI, since Aug 2025), and other agents — no separate `.github/copilot-instructions.md` mirror needed.

> **v5.0 breaking rename: `project` → `environment`** everywhere (CLI `-e`, `/api/v1/environments/:id`, header `X-Environment-Id`, `OS_ENVIRONMENT_ID`, DB column `environment_id`). No aliases. See ADR-0006. "Project" now only means the npm/monorepo sense.

Expand Down Expand Up @@ -63,9 +63,12 @@ Other scripts: `objectui:bump` (pull only), `objectui:build`, `objectui:clean`.

## Multi-agent working discipline

This repo is worked on by **multiple agents in parallel**. Branches get switched
and shared files change *under you* mid-task — this is expected, not a bug.
Operate defensively:
This repo is worked on by **multiple agents in parallel**. Prefer **one git
worktree per agent/task** (`git worktree add ../framework-<task> -b <branch>`;
run `pnpm install` in the new tree) so file systems are physically isolated —
that avoids most of the contention below. When agents must share one working
tree, branches get switched and shared files change *under you* mid-task — this
is expected, not a bug. Operate defensively:

1. **Only touch the files your task needs.** Don't "fix" unrelated diffs,
reverts, or other agents' in-flight edits, and don't try to manage the whole
Expand All @@ -84,6 +87,10 @@ Operate defensively:
your working-tree change between the edit and the commit. On a real conflict,
re-apply only *your* lines and let the PR merge integrate the rest.
6. **Don't rebase or force-update shared branches** to tidy other agents' commits.
7. **Merge only after remote CI is fully green. Never `gh pr merge --auto`.**
Auto-merge can land a still-red PR onto shared `main` and break it for every
parallel agent (see #1475). Merge serially; rebase other open branches before
merging the next one.

---

Expand Down