serejaris Swarm Workspace
Owns the per-subagent git-worktree lifecycle over a two-tier filesystem, so swarm subagents can edit and build in parallel without colliding.
Two-tier filesystem
| Path | Role | Rules |
|---|---|---|
/mnt/agents/output/app |
Shared coordination repo. A plain git repo (no remote). The branch-creation / merge hub. | Do NOT build or edit code here. |
$HOME/app-<branch> |
Local worktree. Fast filesystem where a subagent edits and builds. | Each subagent uses a unique path. |
Key facts that follow from this layout:
- No remote, no push. All worktrees share the shared repo's
.gitobject store, so a commit on any branch is immediately visible to the main agent — it justgit merge <branch>from inside the shared repo. There is nogit push. node_modules,dist, and.envare gitignored. They never sync via git, sogit worktree adddoes NOT carry them into a new worktree. Each worktree gets its own copy — that is whysetup-local.shcopiesnode_modules(and optionally.env) in.- Never run
git worktree prune. Every agent's worktree metadata lives in the shared repo's.git/worktrees/directory; pruning destroys peers' worktrees. - Each parallel subagent MUST pass a unique
$HOME/app-<branch>path — a collision corrupts shared worktree metadata.
setup-local.sh — per-subagent worktree setup
[REPO_PATH=<shared-repo>] [NODE_MODULES_SRC=<prebuilt-node_modules>] [ENV_SRC=<.env-file>] \
bash /app/.agents/skills/swarm-workspace/scripts/setup-local.sh <branch> <local-path>
| Var | Meaning | Default |
|---|---|---|
REPO_PATH |
shared coordination repo | /mnt/agents/output/app |
NODE_MODULES_SRC |
a prebuilt node_modules dir copied into the worktree for a fast start |
unset → rely on npm install |
ENV_SRC |
a .env file copied into the worktree |
unset → $REPO_PATH/.env (the graft's staged .env), so backend/db/build worktrees auto-inherit DATABASE_URL; no-op when that file is absent (frontend-only) |
Pass NODE_MODULES_SRC pointing at the prebuilt node_modules for your stack
(e.g. …/scripts/template/node_modules) so the worktree starts with the right
dependencies overlaid; npm install then reconciles anything else.
Behavior:
- Fresh:
git worktree add --force, copyNODE_MODULES_SRC(+.envifENV_SRCset), thennpm install. - Re-entry on the same branch: reuse the worktree, skip
npm install, still refresh.envifENV_SRCis given. - Re-entry on a different branch / stale dir: recreate cleanly.
--forcetolerates stale worktree entries left by dead sandboxes.
Prerequisite
setup-local.sh assumes the shared coordination repo already exists at
REPO_PATH. Creating it (laying down the initial project and git clone-ing it
there) is the job of whatever workflow lays the first template — not this skill.