diff --git a/docs/build-plan.md b/docs/build-plan.md new file mode 100644 index 0000000..55ad0b6 --- /dev/null +++ b/docs/build-plan.md @@ -0,0 +1,129 @@ +# 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.