psf-memo-client/doc/plan-swarmforge-dir.md

Plan: Option B — SWARMFORGE_DIR (external machinery, per-project config)

Status: pending implementation — working document to resume later. Context: came out of the trial run with saas-prototype (see the fork README). The goal is that projects do not carry SwarmForge code, only their configuration.

1. Goal

The project stops carrying SwarmForge code (scripts) and shared rules (articles, default roles). It only keeps its own configuration (swarmforge.conf + project.prompt + overrides). The fork (or any shared location via SWARMFORGE_DIR) is the sole source of the machinery. With SWARMFORGE_DIR unset, everything still works as today (full backward compatibility).

2. Design: where each thing lives

SWARMFORGE_DIR (base, e.g. ~/.local/share/swarmforge = fork clone)
├── swarm/ + swarmforge/scripts/          ← launcher, daemon, helpers, adapters
├── swarmforge/roles/*.prompt             ← default roles
└── swarmforge/constitution/articles/     ← engineering, handoffs, workflow (shared)

PROJECT
└── swarmforge/                            ← "thin": ONLY per-project material
    ├── swarmforge.conf                    ← project roles + models
    └── constitution/articles/project.prompt (+ local-*.prompt, role overrides if any)

Merge rule: the project wins by name — if the project has roles/cleaner.prompt, that takes precedence; otherwise the base one is used.

3. Code changes (file by file)

File	Change	Why
swarmforge.bb → context	Add :base-dir = (or (System/getenv "SWARMFORGE_DIR") (fs/path working-dir "swarmforge")); keep :swarm-forge-dir = working-dir/swarmforge (project config)	Shared base vs. per-project config
swarmforge.bb → parse-config	roles-dir = per-role lookup: project/roles/<role>.prompt if it exists, else base/roles/<role>.prompt	Role overrides
swarmforge.bb → new sync-shared-config!	For each worktree and for master: copy from base the shared articles and default roles into the destination swarmforge/ only if missing (project ones win); scripts as today	The agent reads swarmforge/constitution.prompt relative to its cwd — after sync, the merged view is there
swarmforge.bb → prepare-workspace! / setup	When syncing on master (project root), add derived files (shared articles) to .gitignore so the project's git stays clean	Shared articles are generated at startup, not committed
write-agent-instruction-file!	No changes	Relative paths still work because sync merges the view into each worktree
check-helper-scripts!	No changes (validates script-dir, which points at the base)	—
handoffd.bb, helpers, adapters	No changes	Already resolve the project via git (roles.tsv)
swarm wrapper	Small install/docs tweak: when installed globally, it runs the base swarmforge.sh; the download block remains for first-time setup	Global install

Estimated total: ~40-60 new/modified lines in swarmforge.bb + docs. Nothing else.

4. User setup (once)

# 1. Install the machinery once
git clone https://github.com/pablo-io/swarm-forge ~/.local/share/swarmforge
ln -s ~/.local/share/swarmforge/swarm ~/.local/bin/swarm
export SWARMFORGE_DIR=~/.local/share/swarmforge   # (in your .bashrc)

# 2. In any project: create ONLY the config
mkdir -p swarmforge/constitution/articles
# swarmforge.conf + project.prompt (+ local-* / overrides if applicable)

# 3. Run
cd /my/project && swarm

5. Test plan

1. bb test — the existing suite (24 tests) must pass with no semantic changes.
2. Mode B: minimal project with only conf + project.prompt → launch with SWARMFORGE_DIR → verify: worktrees with the merged view (shared articles + roles + scripts), functional master, clean startup.
3. Handoff smoke: a real end-to-end handoff (like the saas-prototype run) under mode B.
4. Backward compatibility: saas-prototype (with full swarmforge/) without the env var → must keep working the same.
5. Sync: change a script in the fork (e.g. a fix) → it is reflected without copying anything into the project.

6. Optional migration of saas-prototype (after validating B)

• Thin its swarmforge/: delete scripts/, roles/, and shared articles; leave swarmforge.conf + project.prompt (with the design rules).
• Re-copy updated prompts from the fork (architect.prompt with the written-report rule) — now via the base, not manual copy.

7. Risks / open decisions

• Shared articles synced onto master will be gitignored (derived) — if someone wants to version them explicitly, they can commit them (sync does not overwrite existing ones).
• roles.tsv and state stay under the project's .swarmforge/ (gitignored) — unchanged.
• Agent instructions remain relative to the worktree — key to the design (zero protocol changes).

8. Suggested implementation order

1. context + parse-config (base dir + role lookup)
2. sync-shared-config! + gitignore for derived files
3. bb test
4. Mode B trial with a minimal project
5. Doc in the fork README ("SWARMFORGE_DIR mode" section)