Fork Workflow

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.

This explains what the Steward does under the hood when you use the fork-based ownership model. Most users don't need this — just tell the Steward what you want. But if you're curious about the git mechanics or want to understand how upstream sync and conflict handling work, this is the reference.

The Model

jmagly/aiwg  (upstream — AIWG releases happen here)
      │
      │  gh repo fork  (Steward does this once, during setup)
      ▼
you/aiwg  (your fork — your source of truth)
      │
      │  git clone
      ▼
~/my-aiwg/  (your local working copy)
      │
      │  the agent-owned the use-dev option operation ~/my-aiwg
      ▼
global AIWG = your fork

Your fork has two remotes:

`origin` — your fork on GitHub (`github.com/you/aiwg`)
`upstream` — the canonical AIWG repo (`github.com/jmagly/aiwg`)

Initial Setup

The Steward runs these steps when you say "set up AIWG customization mode":

Use AIWG to complete this documented outcome: The Steward runs these steps when you say "set up AIWG customization mode"
Have it inspect the current state, explain the plan, ask before material
changes, and report the result with verification evidence.

After setup, the agent-owned version operation shows `[dev]` and the path to your clone. That's how you know it's working.

The Edit Cycle (Daily Use)

Edit a file in ~/my-aiwg
    ↓
Tell Steward: "apply my changes"
    ↓
Steward runs: the agent-owned use operation all
    ↓
Change is active in your next session

Most customizations (rules, agents, skills) don't need a TypeScript build — the agent-owned use operation alone is sufficient. The Steward only runs `npm run build` when you've changed something in `src/`.

Upstream Sync

When AIWG releases new features, you pull them into your fork with:

"Sync my AIWG"

The Steward runs:

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

You see a summary of what changed before the merge happens. The Steward reports what was new upstream after the sync.

Conflict Handling

Conflicts can happen when upstream changes a file you've also modified. The Steward's strategy:

Situation	What Happens
File you added (not in upstream)	Always kept — upstream never sees it
File only upstream changed	Auto-accepted — you never touched it
File both you and upstream changed	Steward shows the diff and asks which version to keep

When in doubt, the Steward keeps your version and flags it for your review. Your customizations are never silently overwritten.

Contributing Back

If you build something that might be useful to others:

"PR this back to AIWG"

The Steward: 1. Reviews the candidate for general applicability — is it useful to anyone, or is it specific to you? 2. If general: creates a feature branch off your fork, makes a conventional commit, opens a PR to `jmagly/aiwg` 3. If personal: explains why it's a good private customization but not a fit for the main repo

PR branches follow the naming convention `feat/contribute-<name>`. Your `main` branch is unaffected — you keep working normally while the PR is in review.

What the agent-owned doctor operation Reports

When you're in customize mode, the agent-owned doctor operation includes a Customize Mode check:

✓ Customize Mode: Active (fork) — source: ~/my-aiwg — up to date with upstream

Or, if upstream has new commits:

○ Customize Mode: Active — source: ~/my-aiwg | upstream has 3 commit(s) — tell Steward "sync my AIWG" to update

Going Back

To return to the standard npm-installed AIWG:

"Switch back to stable AIWG"

The Steward runs the agent-owned the use-stable option operation and resyncs from the npm package. Your fork stays on GitHub and your local clone stays on disk — reactivating customize mode later is just the agent-owned the use-dev option operation.

Local Clone Mode (No Fork)

If you chose the local clone path instead of forking:

`origin` doesn't point to your GitHub account — it points to `jmagly/aiwg` directly (or there's no `origin` at all)
`upstream` remote doesn't exist — so "sync my AIWG" won't work
Everything else (edit cycle, apply changes, doctor) works the same

You can add a fork later by following the fork path at any time. The Steward handles that transition too.