Architecture: agent-setup as the seed (mobile + web + shared packages)

[teslashibe]

Architecture

The three layers

SHARED LIBRARIES        ← versioned packages, updated centrally
        ↓
SEED REPO (agent-setup) ← the "starter": shared libs + Claude agent + web/mobile shells
        ↓
CLIENT REPOS            ← forked from seed per client, customized

Layer 1 — Shared libraries (the only things that need to "flow downstream")

Package	What it is	How it's consumed
magiclink-auth-go	Go auth lib (already exists)	Go module — go get
@teslashibe/expo-ui-kit	Mobile UI primitives (Button, Card, Input, OTP, …)	npm — file: in dev, npm later
@teslashibe/expo-magiclink	AuthSessionProvider + API client	npm
@teslashibe/web-ui-kit	Web equivalents (when we add web)	npm

Security/feature update workflow: push to package → npm update / go get -u in client repos → done.

Layer 2 — The seed (agent-setup)

A GitHub Template Repository, not a dependency.

agent-setup/
├── backend/        Fiber + Goose + TimescaleDB + Claude agent loop  ✅ done
├── mobile/         Expo app (consumes the shared packages)          🚧 to add
├── web/            Next.js app (consumes the shared packages)       🚧 to add
└── deploy/         Fly.io / Cloud Run / K8s manifests                ✅ done

The seed is mostly thin glue — screens, routes, agent tools. Heavy reusable code lives in the packages (Layer 1), so when we update them, every client app pulls fixes via standard package updates.

Layer 3 — Client repos

For each client: "Use this template" on GitHub → new repo → customize.

What flows down:

• ✅ Package updates (npm update, go get -u) — automatic via Dependabot/Renovate
• ✅ Seed-level improvements via periodic git merge upstream/main (or cherry-pick)
• ❌ Client-specific code stays in the client repo

Concrete next steps (in order)

• Add Expo mobile/ to agent-setup (port from template-app, one-time copy)
• Add Next.js web/ to agent-setup
• Wire both frontends to the agent SSE endpoints (sessions list + streaming chat)
• Extract @teslashibe/expo-ui-kit and @teslashibe/expo-magiclink only when a second consumer (a real client app) needs them — YAGNI until then
• Wire Dependabot in client repos so package updates auto-PR
• Mark agent-setup as a GitHub Template Repository so "Use this template" appears

What we are explicitly NOT doing (avoiding over-engineering)

• ❌ Monorepo with workspaces — adds tooling complexity for two apps
• ❌ Git submodules — annoying and we'll regret them
• ❌ Extracting packages today before we have two consumers
• ❌ Treating template-app as anything other than a reference; it will be replaced by agent-setup once it has mobile + web

TL;DR

agent-setup is the seed (a GitHub Template Repo). Reusable code lives in versioned packages. Clients fork the seed and get updates via npm update and the occasional upstream merge.

[teslashibe]

Update: dependency chain is now wired

template-app is public: https://github.com/teslashibe/template-app

Actual dep chain

teslashibe/template-app   ← public GitHub Template Repo (base: auth, UI, Go patterns)
         ↓  git upstream
teslashibe/agent-setup    ← public GitHub Template Repo (adds: Claude agent layer)
         ↓  "Use this template"
client repos              ← forked per client, customized

How updates flow downstream

# in agent-setup:
make sync-upstream   # = git fetch upstream && git merge upstream/main

Shared files merge cleanly. The ~5 agent-specific files that diverge (go.mod, config, main.go, docker-compose, home screen) need a quick conflict resolution. That's it.

What was removed

Deleted a 60-line selective-sync bash script. Replaced with two git commands. git merge already does what the script was trying to do manually.

Closes checklist items

• Add Expo mobile/ to agent-setup
• Wire frontend to agent SSE endpoints
• Mark agent-setup as a GitHub Template Repository
• Extract @teslashibe/expo-ui-kit / @teslashibe/expo-magiclink — deferred until second consumer exists
• Document upgrade path for client forks

[teslashibe]

Resolved: agent-setup is now the one template

template-app is archived. Everything it had is in agent-setup, plus the Claude agent layer.

Final dep chain

magiclink-auth-go    ← Go module, shared auth library
        ↓
agent-setup          ← THE template (this repo)
        ↓  "Use this template"
client repos         ← one per client

What changed

• Removed upstream remote + make sync-upstream + UPSTREAM.md — no upstream to sync from
• Added .cursor/rules/ — Go backend and Expo mobile coding conventions for AI assistance
• README updated to reflect agent-setup is the root, not a downstream
• template-app archived with redirect notice

All architecture checklist items resolved

• Expo mobile/ in agent-setup with sessions + streaming chat
• Web (served by same Expo codebase via react-native-web)
• SSE agent endpoints
• GitHub Template Repo flag
• Upgrade path for client forks (just magiclink-auth-go go get -u)
• One repo, no sync friction