Roadmap

Running status tracker for the core build. Each phase has a full spec under docs/spec/. Check boxes off as you land each acceptance criterion so someone picking this up after a break (including future-you) can see exactly where we are.

Naming note. The specs refer to packages as @forumone/claude-cms-*. The actual package names in this repo use throughline. Mentally substitute when reading the specs.

Phase index

Phase	Title	Status
C0	Monorepo Scaffold	✅ Done
C1	Plugin Architecture	✅ Done
C2	Design Contract Package	✅ Done
C3	Reference Design System	✅ Done
C4	Core Plumbing Package	✅ Done
C5	Component Server	✅ Done
C6	Publishing Server	✅ Done
C7	Approvals Server	✅ Done
C8	Audit Query Server	✅ Done
C9	Integrations Server	✅ Done
C10	Workflows Package	✅ Done
C11	Email Package	✅ Done
C12	Forms Package	✅ Done
C13	CLI Scaffolder	✅ Done
C14	Documentation (markdown only; site deferred)	✅ Done

Throughline 1.0

Spec: docs/spec/1.0-plan.md. Checklists are below.

Phase	Title	Status
1.0-P0	Stabilize 0.x	✅ Done
1.0-P1	Jobs interface (0.x)	✅ Done
1.0-P2	Moves and MCP tools (0.x)	✅ Done
1.0-P3	Consolidate and release 1.0	✅ Done
1.0-P4	Migrate forumone-2026	✅ Done
1.0-P5	After 1.0	⬜ When a second site arrives

C0 — Monorepo Scaffold

Spec: docs/spec/C0-monorepo-scaffold.md

Goal: Turborepo + pnpm workspaces + changesets + shared tooling + CI that builds, tests, and publishes to npm on tagged releases.

Repo at github.com/forumone/throughline with Turborepo + pnpm workspaces
Shared TypeScript, ESLint, Prettier configs exist as internal packages
Changesets initialized and configured for @forumone scope
CI workflow runs build, typecheck, lint, test on every PR
Release workflow connected to npm (trusted publishing via OIDC); opens release PRs on changeset merges
README, CONTRIBUTING, LICENSE exist
pnpm build, pnpm typecheck, pnpm lint, pnpm test all run cleanly from root
Branch protection on main requires PR + CI
npm publish round-trip verified end-to-end — @forumone/throughline-design-contract@0.2.0 and @forumone/throughline-reference-ds@0.2.0 live on npm via trusted publishing (OIDC)

Notes:

Skipped C0.8/C0.9 smoke-test round-trip in favor of exercising the publish pipeline with the first real package (C2).
Removed the scaffolded smoke-test package in PR #6.
Since @forumone scope-level trusted publishing isn't available, every new package needs a one-time bootstrap: placeholder publish via npx setup-npm-trusted-publish <name> --access public, then configure a trusted publisher in the npm web UI (npmjs.com/package/<name>/access → GitHub Actions → owner forumone, repo throughline, workflow release.yml). Done once for all 12 packages currently planned (10 pre-provisioned for C4–C13, plus the 2 already published).

C1 — Plugin Architecture

Spec: docs/spec/C1-plugin-architecture.md

Goal: Define the Payload plugin contract every core package satisfies — the shape, the MCP mounting pattern, the composition model, the shared options contract.

@forumone/throughline-plugin-contract exists as a private workspace package
CorePlugin, BaseCorePluginOptions, McpToolDefinition, McpToolContext exported
Example plugin pattern (examplePlugin) compiles and shows every required step
Plugin registry (register, has, get, list, requireCapability) implemented
apps/playground/ exists with Next.js 16 + Payload 3.83, runs locally against Postgres
Example plugin imported into the playground and the app boots (verified end-to-end by creating the first admin user)
docs/plugin-composition.md written
docs/building-plugins.md written
pnpm build, pnpm typecheck, pnpm lint all pass from root

Notes:

Packages use throughline not claude-cms.
Example's global hook uses hooks.afterError (the only top-level Config.hooks in Payload v3) rather than the spec's hooks.afterChange.
Playground Postgres runs on :5433 to avoid collision with native Postgres installs.

C2 — Design Contract Package

Spec: docs/spec/C2-design-contract.md

Goal: Build the package that defines what it means to be an AI-ready design system. Exports the Zod schema for component contracts, the manifest format, the manifest loader, the CI lint rules. Every future design system satisfies this.

Notes:

Package name is @forumone/throughline-design-contract (spec says claude-cms-design-contract).
Recursive ContentField schema uses z.lazy with explicit z.ZodType<Output, Def, Input> three-generic form because exactOptionalPropertyTypes: true + .default(false) on required make input and output diverge.
_fixtures.ts holds test fixtures and is excluded from the emitted dist/.

C3 — Reference Design System

Spec: docs/spec/C3-reference-ds.md

Goal: A brand-neutral design system with 10–12 components, full contracts, generated manifest, Storybook, and CI validation. Test fixture for core + demonstration of contract compliance + starting template for clients without their own DS.

Notes:

Package name is @forumone/throughline-reference-ds (spec says claude-cms-reference-ds).
Storybook ^10.3.5 on @storybook/react-vite; spec's addon-essentials is rolled into SB 10 core and not listed separately.
CSS Modules type declaration lives at src/css-modules.d.ts.
Contracts explicitly set defaulted fields (behavior, antiExamples) because the output type of ComponentContract is stricter than the input type under exactOptionalPropertyTypes: true.
Storybook story IDs derive from each story's title; multi-word components use space-separated titles ('Section Intro' → section-intro--default) so the IDs match the contracts.
Gesso (forumone/nextjs-project) was not reused: only 5/12 components overlap, it's coupled to @storybook/nextjs, has no contracts, and lives inside a monolithic Next.js template. It informed naming conventions only. The lint integration pattern from the previous note (Storybook's index.json → availableStoryIds) is wired into scripts/validate.ts.

C4 — Core Plumbing Package

Spec: docs/spec/C4-core-plumbing.md

Goal: The foundation every server package depends on — audit log, MCP auth pattern, shared types beyond the plugin contract, Inngest client factory, env handling, _meta convention. Unblocks C5–C9 to be developed in parallel.

Notes:

Package name @forumone/throughline-core (spec said claude-cms-core).
Inngest pinned to ^4.0.0, not the spec's ^3.0.0 (Inngest 3 is end-of-life). The constructor's signingKey field was removed in v4 — signing is set via env on the serve handler instead — so the factory's option list is shorter than the spec's.
FrameworkEvents has an empty body (it's the augmentation seam); the eslint no-empty-object-type rule is suppressed at the declaration with an explanatory comment.
Hashing uses Web Crypto (crypto.subtle.digest) so the same code runs in Node and edge runtimes.

C5 — Component Server

Spec: docs/spec/C5-component-server.md

Goal: First custom MCP server. Exposes a design system manifest as conversational primitives (list components, get contracts, suggest components, validate compositions, detect anti-patterns) against any contract-compliant DS.

Notes:

Embeddings matcher deferred per the spec's note: "Don't ship half-working embeddings." TF-IDF lands now; the matcher interface is strategy-agnostic so swapping in embeddings won't change the tool surface.
JSON-imported manifests need an as unknown as Manifest cast because TS doesn't widen JSON literal types to the schema's tuple types (e.g. placement). The plugin's Zod validation enforces the actual shape at load time.
Action tools take their AuditWriter as a constructor dep instead of calling getAuditWriter inside the handler. Cleaner composition, easier unit-testing.

C6 — Publishing Server

Spec: docs/spec/C6-publishing-server.md

Goal: The framework's trust boundary. Policy-gated publish pipeline wrapping Payload's update: composition validation, a11y checks, required-field checks, embargo, approval gating, downstream event orchestration.

Notes:

Inngest pinned to ^4.0.0 (matches the rest of the framework; spec said ^3.0.0 but that major is EOL).
routePrefix defaults to /publishing (not /api/publishing) — Payload prepends /api automatically. Documented in building-plugins.md.
Tools take AuditWriter as a constructor dep instead of calling getAuditWriter inside the handler — same pattern as components.
Rollback restores the version into draft and stops there; users explicitly call publish if they want it live. Lighter-weight than the spec's "validate-then-publish" approach but easier to reason about.
Built-in heading-hierarchy check is structural (multiple Heroes flagged) rather than rendering-based. Full a11y rendering analysis is a Phase 2 service.

C7 — Approvals Server

Spec: docs/spec/C7-approvals-server.md

Goal: Workflow + conversational approvals. Collection schema, MCP tools, HMAC action tokens, and the approval resolver the Publishing Server consumes.

Notes:

Inngest pinned to ^4.0.0 (matches the rest of the framework; spec said ^3.0.0).
routePrefix defaults to /approvals (not /api/approvals) since Payload prepends /api automatically.
First-decision-wins is a Phase 1 deliberate choice — multi-party approvals (legal AND comms both required) are deferred until a real client needs them.
Action tokens are single-use and 14-day default lifetime. Replay protection is consumedTokens on the approval record.
Group resolution is left to the consumer via groupResolver.resolveUsers; core doesn't hardcode membership lookup logic. Playground stubs it with [] until the playground gains a richer Users schema.
Action endpoint HTML is intentionally minimal/unbranded — clients can register a custom-branded endpoint that calls into verifyActionToken if they want richer pages.

C8 — Audit Query Server

Spec: docs/spec/C8-audit-query-server.md

Goal: Expose the audit log (written by C4) as conversational query tools so Claude can answer "what did I change this week?", "who published the homepage?", etc. Small package, high leverage.

packages/audit/ scaffolded with options surface (collectionSlug, readAccess) and validateOptions gate
Conversational formatting helpers (formatRelativeTime, formatAuditEvent) handling user/integration/system actor variants and dropping non-string optional fields cleanly under exactOptionalPropertyTypes
Five purpose-built MCP tools — query_audit, get_change_history, who_changed_what, what_changed_in_range, get_recent_failures — with bounded result sets, conservative defaults, and prose summaries Claude can relay directly
Tiered access control: admin/editor for broad-scope tools; who_changed_what always allows self-lookup so anyone can ask about their own changes without knowing their user ID
auditQueryPlugin (named to disambiguate from core's auditPlugin) registers the MCP handler, requires the audit-log capability, and fails fast if auditPlugin isn't installed first
26 unit tests covering relative-time edge cases, formatter variants, every tool's filter shape, and access denial paths via a fake Payload that applies the equals / greater_than_equal / less_than_equal operators we use
Playground composes auditQueryPlugin({}) after publishing; full root build/lint/typecheck/test green

Notes:

routePrefix defaults to /audit (Payload prepends /api, so the endpoint is /api/audit/mcp).
The plugin layers an admin/editor gate on top of the collection's own access control. The readAccess option sits on the collection in core; tool-level gating is hard-coded for now and can be unified once a client has a real role-model deviation.
Tools take a { payload, collectionSlug } deps object — same shape as the other server packages. Tools are cast through unknown as McpToolDefinition[] at the array level because each factory returns a narrowed McpToolDefinition<typeof inputSchema> for handler-input safety.

C9 — Integrations Server

Spec: docs/spec/C9-integrations-server.md

Goal: Plugin architecture for connecting Payload to external systems. Integration interface, registry, per-instance config collection, MCP tools, and a generic outbound-webhook integration as the first concrete example.

Notes:

Inngest 4.x's createFunction takes a single options object with a triggers array (the spec's three-arg form is from older Inngest releases).
trigger_sync is admin-only because triggering an outbound POST is a write-side action even though it doesn't change configuration. Read tools (status, list, test) only need editor.
Outbound headers are x-throughline-event, x-throughline-signature, x-throughline-timestamp (the spec used x-claude-cms-*). Receivers verify sha256=<hex> against the body using the shared signing secret.
Plugin registers integrations into the registry but does not serve their Inngest functions; the client app composes them via getIntegrationRegistry(payload). Documented as a Phase 1 wart in docs/integrations-wiring.md.

C10 — Workflows Package

Spec: docs/spec/C10-workflows.md

Goal: Composable Inngest functions for common async work (revalidation on publish, scheduled publishes, stale-approval expiry, audit echo, healthchecks). Clients import what they want and merge into their Inngest endpoint.

packages/workflows/ scaffolded as factories-only (no Payload plugin); next listed as an optional peer (peerDependenciesMeta.next.optional = true); ambient next/cache shim so the dynamic import typechecks under module: NodeNext
Shared types module covers every factory's options surface with built-in defaults, optional id overrides, and JSDoc on each option
createRevalidateOnPublishFunction subscribes to content/page.{published,unpublished,rolled_back} and revalidates page path / listings / sitemap; site-supplied urlBuilders (required since 0.5 — the built-in pages/posts builders guessed paths); revalidate option for non-Next.js frontends; default revalidator dynamic-imports next/cache
createTagRevalidationHooks — collection afterChange/afterDelete and global afterChange hooks that drop Next cache tags (revalidateTag(tag, { expire: 0 })), skip draft writes via publishing's isDraftWrite, and log rather than throw (debug outside a Next request, error otherwise); createCacheTags builds every tag for writers and readers alike, also on the dependency-free /cache-tags subpath
createExecuteScheduledPublishesFunction cron (default every 5 min) finds _status: draft docs past scheduledPublishAt, calls Publishing Server's MCP publish tool with Bearer auth (env fallback PUBLISHING_SYSTEM_API_KEY), counts published vs blocked vs error outcomes, never throws on policy rejections
createExpireStaleApprovalsFunction daily cron (2am UTC) flips pending approvals past expiresAt to expired, writes approval.expired audit via getAuditWriter, fires approval/expired Inngest event for downstream notifications; supports both string and { id } requestedBy shapes
createAuditEventEchoFunction subscribes to audit/event.recorded, fires notification/send-approval-{request,decision} for the approval lifecycle, runs each handler in its own step.run so fan-out failures isolate
createHealthcheckFunction runs configurable checks isolated behind step.run, reports failures via onFailure, fires system/healthcheck heartbeat every tick; ships createPayloadReachableCheck and createManifestReachableCheck helpers
28 unit tests via fake Inngest (captures createFunction definitions and send events) + fake Payload (applies equals/less_than/less_than_equal/exists); covers triggers, default schedules, custom URL builders, env-fallback API key, policy-rejection counting, audit fan-out, and healthcheck onFailure routing

Notes:

No playground hookup: the playground doesn't ship an Inngest endpoint yet, so workflows are documented and tested but not exercised end-to-end here. A later phase will add the endpoint and wire factories into it.
Inngest 4.x's createFunction takes a single options object with triggers (array) and cron triggers expressed as { cron }. The spec used the older 3-arg form.
executeScheduledPublishes deliberately does not retry on policy errors. Cron retries on a permanent error (e.g. composition failure) would log noise without making progress; the document stays at _status: draft until an admin intervenes.
audit-event-echo is the single fan-out point. email (C11) subscribes to the notification/send-approval-* events fired here.

C11 — Email Package

Spec: docs/spec/C11-email.md

Goal: Resend wrapper, React Email base layout with brand tokens, transactional templates (approval request / decision / expired), and Inngest functions subscribing to C10's audit-echo events.

Notes:

Inngest 4.x's createFunction takes one options object with a triggers array. Spec used the older 3-arg form.
react.json tsconfig (jsx: react-jsx) is required for the .tsx templates; library tsconfig isn't enough.
Templates expose  comment markers between adjacent text + expression children (a React renderer artifact). Tests assert on identity-bearing fragments (names, titles, URLs) rather than verbatim sentences so renderer changes don't break them.
Brand-name centralization is deliberate: From display name falls back through EMAIL_FROM_NAME → tokens.brandName → 'Your Site'. Same brand string the layout shows in the header.
No playground hookup: the playground doesn't ship an Inngest endpoint yet; the email plugin needs that to fire. Documented as a follow-up phase.

C12 — Forms Package

Spec: docs/spec/C12-forms.md

Goal: Policy-aware forms. Wraps Payload's Form Builder with privacy notices, a11y, spam protection, destination allowlist, submitter confirmation. MCP tools for conversational create/update/query. Public submission endpoint + Inngest fan-out.

Notes:

@payloadcms/plugin-form-builder peers are version-locked to payload (3.83.0 plugin needs 3.83.0 payload), not caret-compatible. The package.json pins the exact form-builder version.
Inngest 4.x's createFunction shape (single options object with triggers) is used throughout. Spec used the older 3-arg form.
next and Inngest endpoint serving are the consumer's responsibility; getFormsFunctions(payload) returns the four functions and the README documents the wire-up.
No playground hookup: playground doesn't ship an Inngest endpoint and doesn't have formBuilderPlugin wired. The forms package is documented and tested but not exercised end-to-end here. Same Phase 2 follow-up as workflows + email.

C13 — CLI Scaffolder

Spec: docs/spec/C13-cli.md

Goal: create-throughline CLI. pnpm create @forumone/throughline my-client-site → ready-to-run monorepo, env stubs, example collection + DS reference, first-deployment checklist.

C14 — Documentation

Spec: docs/spec/C14-docs.md (live site deferred; markdown-in-repo only)

Goal: Documentation that makes the framework usable by someone who didn't build it — architecture, getting started, per-package API reference, customization guides, DS-contract authoring guide.

The original spec called for a Nextra-based docs site. We're shipping the content now (under docs/) and deferring the live-site publishing flow to a later phase.

Top-level docs/README.md Diátaxis-style index
Getting-started tutorials (4 pages): scaffolding, first Claude connection, first publish, deploying to Vercel
Concepts (6 pages): architecture overview, plugin composition, the trust boundary, design system contracts, event-driven workflows, client-agnostic core
How-to guides (9 pages): adding a collection, authoring contracts, theming emails, adding an integration, configuring approvers, customizing accessibility checks, migrating content, upgrading, building a plugin
Operations (5 pages): deployment options, env vars, observability, security model, Phase 2 expansions
Reference (13 pages): one per published package, plus an index
Live docs site (Nextra + Vercel deployment) — deferred to a future phase
Auto-generated typedoc reference replacing the hand-authored reference pages — deferred

Throughline 1.0

Spec: docs/spec/1.0-plan.md. Add first, break once: P1 and P2 ship as 0.x and reach forumone-2026's production one piece at a time, and nothing breaks until P3. Each phase ends at a gate. Tick a box when it is merged on main, and link the PR.

1.0-P0 — Stabilize 0.x

Gate: forumone-2026 pins a released 0.x, and #166 is closed.

Merge the #166 platform fixes: #186, #190, #191, #192, #193, #196, #197, #198, #200
forumone-2026 takes each one up in the PR that pins it, removing its workaround (forumone-2026 #789, #794, #792, #793, #795; tracked and closed in forumone-2026#782)
forumone-2026's CI refuses a pin that is not on this repo's main (check-throughline-pin.sh, forumone-2026#789)
forumone-2026 aligns every @payloadcms/* package on 3.90.2, and drops the unused plugin-form-builder (forumone-2026#789)
check-block-props loads TSX args and CSS modules (#207, #208; forumone-2026#796)
Release the 0.x final: #199, then #209 for #208
forumone-2026 pins the release commit 5613d4c (forumone-2026#797)
#166 closed

1.0-P1 — Jobs interface (0.x)

Gate: the workflow tests pass against both adapters, the playground runs on Payload Jobs, and forumone-2026 runs inngestJobs in production with its function ids unchanged. Additive only: nothing merged may break the site's imports, options or schema.

1.0-P2 — Moves and MCP tools (0.x)

Gate: every moved feature runs from the package in forumone-2026's production, with its site copy deleted, and each has its MCP tool and a parity test. Additive only, as in P1. Each row is a 0.x release, then a site PR.

Promoted to forumone-2026's production 2026-10-02 (live at forumone-2026 c331cb12), and checked there: the dashboard panels, both reports, the Reports nav, Cmd-K and a media item's "Used on" panel.

1.0-P3 — Consolidate and release 1.0

Gate: 1.0.0 is on npm. Breaking changes start here, and only here.

1.0-P4 — Migrate forumone-2026

Gate: forumone-2026 runs 1.0 in production, and the submodule is gone. Packaging only, since the code arrived in P1 and P2. The steps are in the spec, under "Migrating forumone-2026".

One site PR: dependencies, codemod, throughline({...}), generated files, repo rules (forumone-2026#814, at 1.0.1; the codemod rewrote 163 files, and HubSpot and Greenhouse became jobs)
migrate:create finds nothing to change (run with the Blob token set); payload-types.ts and select-options.json regenerate byte-identical
Full fast and verify, a prerender-manifest diff, and an admin smoke test against a local Postgres. Green on 1.0.0-next.2, 1.0.0 and 1.0.1; the manifest is identical to main's (27 prerendered and 8 dynamic routes, no change in cache life); the smoke test found request_approval unable to store a request on Postgres, in 0.x as well, fixed in 1.0.1 (#270)
A preview with a publish scheduled ten minutes out: it published on time
Merged and promoted to production (forumone-2026#814; live at 3194a383 on 1.0.1, 2026-10-03)
The submodule, check:boundary and check-throughline-pin.sh retired (forumone-2026#814); v0 closed: it releases and runs CI no more, and stays for its history

1.0-P5 — After 1.0

When a second site shows which configuration points are real: Okta generalised to OIDC, draft preview, HubSpot and Greenhouse, narration, AI Suggest, llms.txt.

Left from P3 and P4, each documented as it stands until fixed:

editorial, references, check_slug and list_job_failures record no system.error on a throw. Each needs a value in the audit log's mcp_server enum, which is a migration in every host, so it ships with one: 1.1, and a test now holds every collector server name to an audit name
The scaffold: .env.local written at the root, where next dev in apps/web does not read it; every new user defaults to admin; stale "Payload MCP API Keys" and "Pick a User" wording. Now apps/web/.env.local; the first account is the admin and every later one an editor, with roles and groups admin-set; the wording with the template docs sweep
request_approval stores the request and then reports the call as failed when its approval/requested event cannot be sent; publishing treats the same failure as a warning on a write that landed. Now a warning in request_approval, respond_to_approval and the email action endpoint — which also could not record a decision on Postgres, its decidedBy the same string-id defect #270 fixed in the tools

FilesExpand file tree

roadmap.md

Latest commit

History

roadmap.md

File metadata and controls

Roadmap

Phase index

Throughline 1.0

C0 — Monorepo Scaffold

C1 — Plugin Architecture

C2 — Design Contract Package

C3 — Reference Design System

C4 — Core Plumbing Package

C5 — Component Server

C6 — Publishing Server

C7 — Approvals Server

C8 — Audit Query Server

C9 — Integrations Server

C10 — Workflows Package

C11 — Email Package

C12 — Forms Package

C13 — CLI Scaffolder

C14 — Documentation

Throughline 1.0

1.0-P0 — Stabilize 0.x

1.0-P1 — Jobs interface (0.x)

1.0-P2 — Moves and MCP tools (0.x)

1.0-P3 — Consolidate and release 1.0

1.0-P4 — Migrate forumone-2026

1.0-P5 — After 1.0