From Fork to Project-Local

Migrate fork-based customization

From Fork to Project-Local

If you're already maintaining a fork of AIWG to inject custom rules, agents, or skills, project-local bundles let you move that customization into your project repository without giving up the customization or the upstream sync workflow.

When to migrate

Stay on Path B (fork)Migrate to Path A (project-local)
You modify AIWG core (TS source, deploy pipeline, build)You only add rules / skills / agents / templates
Your customizations are generally useful and you contribute most of them upstreamYour customizations are project-specific or team-specific
You want to live on bleeding-edge AIWG branchesYou're fine with stable npm releases
You manage > 5 customized repos via the same forkYou only customize one or a few repos

If you nodded at the right column more than the left, project-local is probably the simpler path for the parts of your fork that aren't AIWG core changes.

What stays in the fork, what moves to project-local

A typical fork-based customization has three kinds of changes:

ChangeMigrate to project-local?
New rules under `agentic/code/addons/<your>/rules/`Yes — these are the easiest case
New skills under `agentic/code/addons/<your>/skills/`Yes
New agents under `agentic/code/addons/<your>/agents/`Yes
Edits to existing upstream rules / skillsYes, as overrides — declare them in `manifest.json` `overrides:`
Edits to AIWG TypeScript source (`src/`)No — keep in fork or PR upstream
New CLI commandsNo — extend AIWG itself
Build / deploy pipeline changesNo

The first four categories are exactly what `.aiwg/{extensions,addons,frameworks}/<name>/` content bundles are for. Use `.aiwg/plugins/<name>/` only when wrapping one of those bundles for marketplace delivery, and `.aiwg/providers/<name>/` when you need a custom provider selector that reuses an existing adapter. The last three need the fork.

You can mix: keep the fork for AIWG core changes, and use project-local bundles in your repo for everything else. The two compose cleanly.

Migration walkthrough

Suppose your fork adds an addon `agentic/code/addons/my-team-helpers/` with a couple of rules and a skill. Here's how to move it to project-local in your project.

1. Scaffold an empty project-local addon

In your project (not your AIWG fork):

aiwg new-bundle my-team-helpers --type addon

This creates `.aiwg/addons/my-team-helpers/` with a valid manifest + README + starter skill.

2. Copy your fork's content over

The directory structure is identical — copy file-for-file:

cp -r /path/to/your-fork/agentic/code/addons/my-team-helpers/rules \
      .aiwg/addons/my-team-helpers/

cp -r /path/to/your-fork/agentic/code/addons/my-team-helpers/skills \
      .aiwg/addons/my-team-helpers/

# Replace the scaffold's manifest with your fork's manifest:
cp /path/to/your-fork/agentic/code/addons/my-team-helpers/manifest.json \
   .aiwg/addons/my-team-helpers/

Because the on-disk layout is byte-identical between project-local and upstream (identical-form ADR), no rewrite is needed.

3. Audit `@-references`

Open the rules and skills you copied and search for any ``@.aiwg/...`` references. Those are project-output references — they only resolve in the project that contains them. If your fork has any, you'll see them because the fork's `.aiwg/` is the AIWG repo's own dogfooding output.

grep -r "@\.aiwg/" .aiwg/addons/my-team-helpers/

If you find any, decide:

  • Replace with `@$AIWG_ROOT/...` if the reference points at upstream content
  • Leave it if the reference is intentionally project-output (the bundle reads project artifacts)

The promote pre-flight refuses dangling `@.aiwg/` refs; project-local deploy doesn't care.

4. Validate

aiwg doctor --project-local

Should report 0 validation errors. If anything fails, see Troubleshooting.

5. Deploy and compare

aiwg use my-team-helpers
diff -r /path/to/your-fork/.claude/rules .claude/rules
diff -r /path/to/your-fork/.claude/skills .claude/skills

Files should match. If they don't, something in the bundle differed from your fork — fix it.

6. Switch off the fork (for this project)

If you were running `aiwg --use-dev` to point at your fork, switch back to stable:

aiwg --use-stable
aiwg use sdlc      # re-deploy upstream from npm
aiwg use my-team-helpers   # re-deploy your project-local addon

Both deploy together. Project-local artifacts shadow upstream cleanly.

7. Decide what to do with the fork

You have three reasonable options:

1. Keep the fork if you're still using it for AIWG core changes 2. Archive the fork if all your customization moved to project-local 3. PR the addon back upstream if it's generally useful — `aiwg promote my-team-helpers` graduates the project-local bundle to upstream form, then file a PR

Per-repo migration

If you have many repos that all use the same forked addon, each repo needs its own project-local copy. Three patterns:

A. Manual per-repo copy

Best for ≤ 3 repos. Copy the bundle into each repo's `.aiwg/`. Each repo's manifest can drift independently if needed.

B. Corpus path (Path C)

Promote the bundle to a corpus path once, then point each repo's `aiwg.config` at the corpus. The bundle lives in one place and updates propagate.

aiwg promote my-team-helpers --to corpus ~/team-corpus/

In each repo's `aiwg.config`, register the corpus source. Updates to the corpus apply on next `aiwg refresh` per repo.

C. Git submodule

Add a submodule under `.aiwg/addons/` pointing at a private repo containing the bundle. Heavier than a corpus path; better when you want explicit version pinning per repo.

Sync drift between fork and project-local

If you keep the fork as the canonical source of the addon and re-copy into project-local from time to time, watch for:

  • Manifest version drift — bump the version in both places when you

publish a change

  • Schema additions — if AIWG's manifest schema gains a required

field, both copies need it

  • Hash drift — `aiwg doctor --project-local` will report drift on

the deployed files until you re-run `aiwg use` after the copy

The cleanest workflow is to pick one source of truth (either fork or project-local) and not maintain both indefinitely.

See also