From Fork to Project-Local

Migrate fork-based customization

From Fork to Project-Local

Prompt-first procedure: Describe the outcome you want in your agent conversation. The agent should select and load the appropriate AIWG assets, explain material changes, request any needed approval, and report verification evidence. Exact commands and flags appear only in the CLI reference.

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):

Use AIWG to complete this documented outcome: In your project (not your AIWG fork)
Have it inspect the current state, explain the plan, ask before material
changes, and report the result with verification evidence.

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

Use AIWG to complete this documented outcome: 4. Validate
Have it inspect the current state, explain the plan, ask before material
changes, and report the result with verification evidence.

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

5. Deploy and compare

Use AIWG to complete this documented outcome: 5. Deploy and compare
Have it inspect the current state, explain the plan, ask before material
changes, and report the result with verification evidence.

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 the agent-owned the use-dev option operation to point at your fork, switch back to stable:

Use AIWG to complete this documented outcome: If you were running the agent-owned the use-dev option operation to point at your fork, switch back to stable
Have it inspect the current state, explain the plan, ask before material
changes, and report the result with verification evidence.

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 — the agent-owned promote operation 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.

Use AIWG to complete this documented outcome: 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.
Have it inspect the current state, explain the plan, ask before material
changes, and report the result with verification evidence.

In each repo's `aiwg.config`, register the corpus source. Updates to the corpus apply on next the agent-owned refresh operation 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 — the agent-owned doctor operation will report drift on

the deployed files until you re-run the agent-owned use operation 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