@agent-ix/filament-plan-sync

Bidirectional synchronization between a canonical plan tree and an external issue tracker.

The engine keeps a plan tree and a tracker in agreement without either side owning the truth outright: a per-target base/shadow store records what was last agreed, a three-way merge reconciles divergence, and a conflict policy decides what a machine may resolve and what a person must.

Trackers sit behind a driver interface with an invertible hierarchy projection, so a plan's shape survives the round trip into a tracker that models hierarchy differently. GitHub (including Projects v2 boards) and Jira drivers ship with the engine. Authentication is always explicitly user-initiated.

Use

The engine carries no host assumptions. The same core runs in a hosted worker, embedded in-process, and behind a CLI command.

As an oclif core plugin it contributes a sync command to its host:

// host package.json
{
  "dependencies": { "@agent-ix/filament-plan-sync": ">=0.1.0" },
  "oclif": { "plugins": ["@agent-ix/filament-plan-sync"] }
}

The host's oclif Config loader discovers it as a core plugin — bundled as a dependency, with no runtime install step — so sync is available the moment the host is installed. @agent-ix/quoin ships it this way.

Used as a library, the package's main entry exports the plan-tree model, the synchronization operations, and the driver interface directly.

Requirements

Node.js 18 or newer.

License

MIT — see LICENSE.