pig/docs/build-plan.md

Build plan

Where PIG stands, what remains, and what can be built in parallel.

Written so that work can be handed to several people (or several agents) at once without them colliding. The dependency edges are real — the waves are not decoration.

---

What already works

Live at primeintellectgrowth.com. ~10.7k lines, 39 tests, green CI.

• The ontology and margin engine, with the allocations join at the centre
• Both pipelines, capacity availability / matching / idle alerts
• Auth: sign in, register with an invite code, profile creation, sign out
• Theming (7 accents, light/dark, server-persisted), responsive to 393px
• MCP server (9 tools), Prime Intellect API client, demo dataset
• Docker + compose + Caddy, deploy script, CI on Gitea Actions

The two gaps that block a demo

1. No write path for allocations or commitments. The core table can only be populated by seed. A visitor can look at the demo book but cannot enter a deal of their own.
2. No way to mint an API key, so the MCP server is unreachable in production despite being the headline feature.

Everything else is additive. These two are load-bearing.

---

On borrowing from Comp AI CRM

Their repo (MIT) was cloned and inventoried. Findings that shaped this plan:

Their component library is far deeper — 68 primitives to our 9. Notably data-table, command, sheet, drawer, combobox, chart, sortable-list, and a set of agent-chat components (message, reasoning, thinking-indicator, thread-message, suggestion) that map almost exactly onto what Piggy will need.

SourcedValue / Provenance is worth adopting outright. A dotted underline on any agent-derived value, with a tooltip carrying the claim, the reasons, when it was observed, and the source URL. PIG already has that data — facts holds score, band, evidence and sourceUrl — and nothing currently surfaces it.

But we are ahead of them on mobile, not behind. Measured across both repos:

	Comp AI	PIG
tsx files	329	16
Responsive utilities	211 (0.6/file)	58 (3.6/file)
Safe-area handling	0	5
Mobile nav	none found	bottom tab bar

They have no drawer or sheet used for navigation, no viewport-fit, and no safe-area insets anywhere. Their app is effectively desktop-only. So the plan below adds depth from them, not mobile behaviour.

Do not copy their component files. Most are shadcn/ui originals, which are MIT and designed to be installed from upstream — take them from source, where they are canonical and current. Borrow their compositions (data-table, provenance, agent chat) as ideas, and credit in NOTICE as already done.

---

Waves

Wave 0 — Foundation (must finish before Wave 1 UI work)

Two tracks, independent of each other, so both can run at once.

	Task	Why it blocks
F1	Install the shadcn primitive set: dialog, sheet, drawer, select, dropdown-menu, table, tabs, tooltip, popover, command, form, switch, textarea, label, separator, sonner, avatar, checkbox, radio-group	Every form and table below needs these. Building them ad hoc in parallel guarantees five inconsistent buttons.
F2	A shared write-path convention in the API: zod schemas derived from the ontology, a mutation helper, consistent error shapes, and activity logging on every mutation	Eight CRUD tasks land at once in Wave 1. Without a settled pattern they will each invent one.

Wave 1 — Parallel build (up to ~10 tracks)

Backend tracks need only F2. Frontend tracks need F1.

Backend

	Task	Depends on
A1	Allocations + capacity commitments write API, with the availability invariant enforced server-side (cannot allocate beyond the shape)	F2
A2	API keys: generate, list, revoke. Show the plaintext once.	F2
A3	Auth-provider seam — extract Supabase behind an interface so OIDC is a second implementation	—
A4	Piggy: worker draining agent_tasks, AgentProvider interface, prime-agent adapter using defineTool with PIG tools only (no bash, no filesystem), writing to facts	—
A5	Slack adapter: link channels to accounts, post stage changes and idle alerts, slash command for capacity match	F2
A6	Buzz adapter behind the same notifier interface as Slack	A5
A7	pig CLI with --json output, for prime-agent's kernel and for scripts	A2

Frontend

	Task	Depends on
A8	Data table (sort, filter, paginate, column visibility) + ⌘K command palette	F1
A9	SourcedValue / provenance display, wired to facts; fact review queue (approve/dismiss proposals)	F1
A10	Contracts UI — the schema is rich and nothing surfaces it	F1
A11	Record create/edit sheets for accounts, contacts, demand deals, supply deals	F1, F2

Wave 2 — Integration (needs Wave 1)

	Task	Depends on
B1	Allocation UI: allocate capacity to a deal from the matcher, place and release holds	A1, A8, A11
B2	Piggy chat UI: streaming, reasoning, tool calls, in-record ask	A4, F1
B3	Settings for Slack/Buzz connections and channel links	A5, A6, F1
B4	End-to-end tests over the critical paths: register → create a commitment → allocate → see margin move	B1

---

Sequencing advice

Build F1 and F2 first and alone. They are small and they are the interface every other track codes against. Starting Wave 1 before they settle is how parallel work turns into merge conflict.

A1 and A2 are the highest value in Wave 1 — they close the two gaps that block a demo. If only two things get done, do those.

A4 (Piggy) is fully independent and can start immediately alongside Wave 0; it touches no UI and no shared API conventions.

A3 (auth seam) should land before any second deployment exists. It is cheap now and expensive once an on-prem install has to keep working.