Aigon keeps feature and research lifecycle state in SpecStore. The default backend is local storage in the current checkout. The optional git-branch backend stores canonical lifecycle state in a dedicated Git branch so multiple clones can converge without committing .aigon/workflows/.

Spec markdown and code changes still use normal Git. SpecStore does not replace branches, commits, pulls, merges, or pushes for working-tree files.

Choose a backend

Use local storage unless you need multiple machines or clones to share lifecycle state before a normal branch merge.

Local storage

Local is the default. You can omit storage entirely, or set it explicitly in .aigon/config.json:

{
  "storage": {
    "backend": "local"
  }
}

Local storage keeps workflow events and snapshots under .aigon/workflows/**. Spec markdown in docs/specs/** and code changes remain ordinary repository files.

Git-branch storage

Use the conversion command when possible:

aigon storage convert --backend=git-branch --remote=origin
aigon storage status

The resulting .aigon/config.json is:

{
  "storage": {
    "backend": "git-branch",
    "git": {
      "remote": "origin",
      "branch": "aigon-state",
      "offline": false
    }
  }
}

The default state branch is aigon-state. Aigon stores a file tree there—without checking it out—with meta.json, specs/<key>/events.jsonl, and leases/<key>.json.

aigon storage convert validates remote access, imports existing local events, migrates legacy git-ref state when present, writes the config, and syncs the state branch. To preview without changing config or remote state:

aigon storage convert --backend=git-branch --remote=origin --dry-run

Use --branch=<name> to select a non-default state branch. Conversion removes imported legacy git-ref refs by default; pass --keep-refs to preserve them during a staged migration.

To return to local behavior, set storage.backend to local. Existing state-branch data is not deleted.

git-ref is no longer a supported backend. Aigon rejects that configuration and prints the conversion command.

What syncs

Multi-clone model

With git-branch enabled, mutating lifecycle commands synchronise before writing. Sync fetches the state branch, merges events by event ID, rebuilds local projections, and pushes the merged state back to the configured remote. Re-seeing an event is idempotent.

Run these checks before relying on another clone:

aigon storage status
aigon storage sync
aigon storage doctor
git ls-remote --heads origin aigon-state

The remote must allow creating and pushing the configured state branch. Normal git pull remains how spec markdown and code travel between clones; aigon storage sync handles only lifecycle state.

Leases and offline mode

On git-branch, a lease is authoritative mutual exclusion: Aigon coordinates claims through compare-and-swap updates to the lease file. Leases expire after 30 minutes by default and renew at most every 10 minutes. Local storage retains advisory lease events only.

Offline mode skips pre-write remote synchronisation:

{
  "storage": {
    "backend": "git-branch",
    "git": {
      "remote": "origin",
      "branch": "aigon-state",
      "offline": true
    }
  }
}

You can also set AIGON_STORAGE_OFFLINE=1 for one environment. Sync once the remote is reachable so other clones receive the queued state.

Stable spec layout

Storage and spec layout are separate choices. New repositories default to specLayout: "stable": canonical feature and research markdown lives in 00-specs/, and the familiar lifecycle folders are generated symlink views. Existing repositories remain on the legacy layout until explicitly migrated.

Use spec-layout to inspect or migrate a layout, and spec-view to inspect or repair the generated lifecycle view.

Dashboard visibility

The dashboard shows the resolved backend, health, remote, branch, offline state, last sync, and ahead/behind counts. Feature and research details show active leases. Storage actions provide sync, doctor, and report.

Commands

• storage — Convert, sync, inspect, diagnose, and report storage state
• spec-layout — Inspect or migrate durable spec locations
• spec-view — Inspect or regenerate lifecycle links
• board --storage — Show cross-repo active lease status in the terminal
• configuration — Project configuration examples