Project Sync — CLI Bridge to Web Database

This skill provides sync.ts, the CLI script that bridges agent skills to the web database.

All release-decision skills call this script to persist state changes. No skill should construct HTTP requests or JSON payloads directly — always use sync.ts.

Script Location

scripts/sync.ts

(Relative to this skill's root directory.)

Run with:

npx tsx scripts/sync.ts <command> [args]

Environment

Set SYNC_API_URL if the web app is not running at the default http://localhost:3000.

Commands

get-project

Read full project state (includes experiments, activities, messages).

npx tsx scripts/sync.ts get-project <project-id>

update-state

Push one or more decision fields to the web DB.

npx tsx scripts/sync.ts update-state <project-id> --goal "..." --hypothesis "..." --primaryMetric "..."

Allowed fields: goal, intent, hypothesis, change, variants, primaryMetric, guardrails, constraints, openQuestions, lastAction, lastLearning, flagKey

set-stage

Advance the project stage.

npx tsx scripts/sync.ts set-stage <project-id> <stage>

Valid stages: intent, hypothesis, implementing, exposing, measuring, deciding, learning

add-activity

Log an activity event.

npx tsx scripts/sync.ts add-activity <project-id> --type stage_update --title "Intent clarified" [--detail "..."]

--type and --title are required. --detail is optional.

upsert-experiment

Create or update an experiment by slug.

npx tsx scripts/sync.ts upsert-experiment <project-id> <slug> --status running --primaryMetricEvent "click_cta" [--field value ...]

Experiment fields: status, hypothesis, primaryMetricEvent, guardrailEvents, controlVariant, treatmentVariant, minimumSample (integer), observationStart (ISO 8601 date), observationEnd (ISO 8601 date), priorProper (boolean, default false), priorMean (float), priorStddev (float), inputData (JSON string — mirrors input.json), analysisResult (JSON string — mirrors analysis.json), decision, decisionSummary (plain-language action), decisionReason (technical rationale), whatChanged, whatHappened, confirmedOrRefuted, whyItHappened, nextHypothesis

How Other Skills Use This Skill

Each satellite skill that needs to persist state declares a dependency on this project-sync skill, then lists the commands and arguments it needs. The satellite skill does not hardcode script paths or execution details.

Every stage transition follows this write pattern:

update-state <project-id> --field "value" — push fields to web DB
set-stage <project-id> <stage> — advance stage
add-activity <project-id> --type <type> --title "..." — log transition

When experiment data changes, also call:

upsert-experiment <project-id> <slug> --status running ...

Architecture

Agent skill → references project-sync → npx tsx sync.ts <command> → HTTP API → Prisma → SQLite → Web UI

The web database (via API + Prisma) is the canonical source for all project state
Skills call sync.ts with simple string arguments — no JSON construction needed