Skip to content

MIGRATION-forge.md

Latest commit

 

History

History
97 lines (67 loc) · 5.34 KB

MIGRATION-forge.md

File metadata and controls

97 lines (67 loc) · 5.34 KB
Raw

Migration — Forge harness layout (v3)

User-facing migration guide for target repos sitting on the pre-v3 distribution layout. What changed, what survives, and how to re-sync.

If you're installing into a fresh repo, skip this file — just run the install once. This page only matters if your repo was synced before the Forge refactor.

TL;DR

  1. Brand rename — inbest → Forge everywhere it shows in target repos: marker tags (<!-- inbest:* --> → <!-- forge:* -->), .inbest/ config dir → .forge/, skill ids (inbest-* → forge-*). One re-sync rewrites everything in place.
  2. Layout split (distribution side) — the harness now ships from src/ only; plugins/ is opt-in extras. Nothing on the target-repo side moves because of this — it's purely a source-tree change.
  3. Installer is Python — cli/install.js and the bash setup scripts are gone. The GitHub Action is unchanged from your point of view; it just calls python -m installer under the hood.
  4. Plugins are opt-in — Engram, Context7, LSP, Serena, Playwright bridge, Agent browser, ccstatusline, GSAP. None install by default; pick what you want with -f plugins="engram,context7".
  5. Tools dropped — Cursor and Copilot are no longer supported tool targets. If you had .cursor/ or .github/copilot-instructions.md markers, they're left alone but no longer maintained by the installer.

The migration is idempotent and non-destructive — re-running the install converges any partial state without rewriting user content.

Re-syncing a target repo

gh workflow run sdd-sync-targeted.yml \
  -f repos="my-org/my-repo" \
  -f preset="solo" \
  -f dry_run="true"      # preview first

Drop dry_run="true" once the diff looks right. The installer:

  • Rewrites stale inbest:* HTML markers to forge:* in AGENTS.md, CLAUDE.md, skills, agents.
  • Renames .inbest/config.json → .forge/config.json (content preserved).
  • Updates skill folder names (inbest-explore → forge-explore, etc.) on tools that own the skill copies.
  • Leaves .cursor/ and .github/copilot-instructions.md untouched.

Existing user content under managed sections is preserved by version-aware section markers (<!-- forge:section:<name>:<version> -->); content outside markers is never touched.

Opting into plugins

gh workflow run sdd-sync-targeted.yml \
  -f repos="my-org/my-repo" \
  -f preset="solo" \
  -f plugins="engram,context7,lsp"
Plugin What it adds Install ownership
engram (default set) Persistent memory MCP, hooks, allowlist user installs the engram binary once
context7 (default set) Live library docs MCP harness wires it; no user binary needed
agent-browser (default set) Chrome DevTools MCP (lower token surface than full Playwright) user installs Chrome
rtk (default set, W2 of token-cascade refactor) Advisory PreToolUse Bash hook + RTK.md fragment — 60-90% token reduction on the rtk coverage set user installs rtk binary, then rtk init -g once per machine
lsp (opt-in) LSP bridge MCP + forge:lsp-explore skill user installs language servers
playwright-bridge (opt-in) Microsoft's official Playwright MCP user runs npx playwright install once
ccstatusline (opt-in) Claude Code statusline widget user has Node (already required)
gsap (opt-in) GSAP animation skill bundle for the frontend agent harness ships the skill

W2 default-set behavior change (token-cascade refactor) — target repos that re-sync via the GitHub Action without specifying plugins: will install the default set (engram, context7, agent-browser, rtk) on next sync. Repos that genuinely want zero plugins must pass an explicit --plugins gsap (stub no-op) to skip the default-set wiring. The non-interactive driver also surfaces a User action required block listing missing binaries + post-install setup steps (e.g., rtk init -g). Previously empty --plugins meant zero plugins.

The serena plugin from earlier drafts was deleted in W1 (feat/forge-token-cascade-refactor) — the lsp plugin's forge:lsp-explore skill remains the supported semantic-code-search story.

Removing a plugin later: drop it from -f plugins=, re-run sync. The cleanup pass scrubs harness-owned files; user-installed binaries are never removed.

What if I'm on cli/install.js locally?

The JS CLI was removed in the W2.4 cut. Switch to:

git pull
pip install -e .[interactive]
python -m installer install --target-root /path/to/your/repo

Same install pipeline as the Action, no PR overhead. Details in INSTALL-CI.md for non-interactive flows.

Rollback

The installer never destroys user content. If a re-sync looks wrong:

  1. Reject the PR the Action opened (the local install path doesn't open PRs).
  2. The previous layout stays exactly as it was.

There's no "downgrade" command — you just don't merge.

Related docs

  • STRUCTURE.md — distribution-repo layout (src/ ships, plugins/ opts in, rest is meta)
  • OWNERSHIP.md — the four install-ownership categories and the per-plugin matrix
  • UPGRADE-v2.md — earlier audit-v2 migration (preset model, mode renumbering, validator scorecard)
  • INSTALL-CI.md — non-interactive install reference