[seanspeaks]

Stack 1 of 9: ADR-063, integrations as definitions. Each PR targets the one before it. Review and merge them in order.

Summary

• Adds ADR-063, which describes an integration written as a JSON definition instead of a class.
  • A definition is built from modules, capabilities, workflows, syncs, UI surfaces, a settings form and lifecycle steps.
  • It is checked against capability manifests that describe what each API module can do.
  • It is published as an immutable, versioned record.
  • It is installed and run by Frigg's normal entry points. There is no second runtime.
• Status at this commit is proposed. PR 5 marks it accepted and updates the route table once the runtime matches it.
• Docs only. No code.

Test plan

• Docs only

---

Generated by Claude Code

---

Note

Low Risk
Documentation-only proposed ADR and cross-reference updates; no production code, auth, or data paths change in this PR.

Overview
Introduces proposed ADR-063, which adds a second integration authoring form: a versioned integration document (JSON) interpreted by a generic DataDefinedIntegration, alongside unchanged class-based integrations.

The ADR spells out what stays data vs. registered code (allow-list for modules, step types, transforms), a git-style lifecycle (author → frigg integration check → immutable publish → pinned definitionVersion), shared HTTP/webhook/queue infrastructure to avoid per-integration CloudFormation growth, and follow-on topics (runtime portability, tenancy via ADR-056).

ADR-023 gains an Amendment (ADR-063) so templates may ship as forkable definition documents, not only copied class scaffolds. The ADR README index lists ADR-063.

Docs only; no runtime or schema implementation in this PR.

^{Reviewed by Cursor Bugbot for commit 21d9e3b. Bugbot is set up for automated code reviews on this repo. Configure here.}

[claude]

⚠️ Code review skipped — your organization has no extra usage available to pay for this review.

If your organization's extra usage balance is empty, an organization admin can add extra usage credits at claude.ai/admin-settings/usage. If its monthly spend limit was reached, an admin can raise it on the same page. If neither applies, contact Anthropic support.

Once extra usage is available, someone with write access to this repository can comment @claude review on this pull request to trigger a review.

[netlify]

✅ Deploy Preview for friggframework-org canceled.

Name	Link
🔨 Latest commit	21d9e3b
🔍 Latest deploy log	https://app.netlify.com/projects/friggframework-org/deploys/6ad68ea331f134d520090bd4

[seanspeaks]

ADR reconciliation needed after Stack A/B — drafted with Claude Code at Sean's request

Severity: must-reconcile. ADR-063 is the ADR the rest of Stack B extends; these are text edits (code items are on #693–#698).

• Status (ADR-043, docs(adr): ADR-043 — ADR lifecycle, one register, no RFC tier #646). feat(core): published definitions are integration types like code; code can embed one; workspaces own their own #696 changes this ADR to Accepted (2026-10-19) while this PR is unmerged. Under 043, Accepted is the merge of this PR and Implemented comes with the code PR. Keep Proposed here, or use Exploratory with a What would settle this section, and let the code PRs add only Implementation sections.
• Name collisions. @friggframework/schemas already ships integration-definition.schema.json (the static Definition). The new schema/integration-definition.v0.1.schema.json in core reuses that name, and §3 said it would live in @friggframework/schemas. Give the document type a distinct name and $id, and add a glossary line: "Definition" now means three things (static Definition, IntegrationDefinitionVersion, config.definition).
• ADR-054/055. State that both forms compile to Definition + this.events (§12). Recurring work uses ADR-055 triggers (§15a changes, see feat(core)!: recurring triggers per ADR-055 (one tick, per-installation timing) #694). Module webhook facts come from extension contract 2 (054 §2), and sync object access comes from 054 §6 objects.
• ADR-057. §1 claims mappings reuse extensions.mapping / canonical.rules, but v0.1 has its own syncs[].mapping rows and transforms (split_full_name) beside 057's named transforms (joinName). Reference 057 module mappings, or record the departure and keep one transform registry.
• ADR-023 (on next). Please include an amendment: a template may ship as a definition document, so "copy and own" means forking the document (Shape A).
• ADR-056 (docs(adr): ADR-056 app profiles, tenancy and entity scopes #670/docs(adr): ADR-056 §3.1–3.6 ownership overrides + multi-org membership; ADR-059 app-level entity registry #677). "Workspace" is user.getId(), which 056 §3.2 retires for ownership. Use 056's owner and organizationId, expose visibility through §4 visible(context), and let a definition declare binding scope (§3.1 levels 2–3).
• ADR-049 (docs(adr): ADR-049 rate-limit awareness #655). In §19 the runtime ports are the caller that owns the budget. Module rateLimit is descriptive only, and a RateLimitError defers the message (feat(core): put a rate-limited queue message back at its retry time #657) instead of a release-and-retry.
• Stale after the stack: §17's EventBridge row ("not built", built in feat(core)!: recurring triggers per ADR-055 (one tick, per-installation timing) #694); §16 "renderers not in v0.1" (feat(core): in-app previews (Slack, HubSpot, HTML) and workflow dry runs #697); "Queue: No port" (feat: Netlify provider on the v2 stack (port of #545) (F7) #686 adds QueueClientInterface); §18 should cite ADR-028.
• ADR-062 is cited but unwritten, and it overlaps ADR-059 open question 1 and feat(core): several named proxy base URLs per module (F8) #690's named bases. Fold it into 059 or write it first.
• Public repo: Context and the examples name a specific hosted product and specific customer pairings. Switch to neutral names.

Merge order: #669 and #670 settle their texts → this PR → #693+.

[sonarqubecloud]

Quality Gate passed

Issues
0 New issues
0 Accepted issues

Measures
0 Security Hotspots
0.0% Coverage on New Code
0.0% Duplication on New Code

See analysis details on SonarQube Cloud

[seanspeaks]

Release review follow-up: the text items are done across the stack (this PR at 21d9e3bc).

• Status: Proposed at every level.
• Terms glossary: covers the three meanings of "Definition" and names the planned integration-document.v0.1.schema.json rename.
• Cross-references: §12 points to ADR-054/055. §1 and §8 record the ADR-057 departure, with one transform registry as the goal. §19 now matches ADR-049. ADR-062 is replaced by ADR-059 OQ1.
• Stale text: the queue row (feat: Netlify provider on the v2 stack (port of #545) (F7) #686) and §18 now cite ADR-028.
• Amendments: ADR-023 gets an amendment in this PR, and ADR-020 gets one in feat(core): capability manifests checked against the real API modules #698.
• Neutral names: no hosted product or customer names in the prose or examples.
• Stale rows in later PRs: fixed in the PRs that build them (§17 in feat(core)!: recurring triggers per ADR-055 (one tick, per-installation timing) #694, §16/§19 in feat(core): in-app previews (Slack, HubSpot, HTML) and workflow dry runs #697, §14 in feat(core): rename data-defined internals, give webhook checks the raw body, real HubSpot components #699).

Open question: ADR-028 has three files on different branches. This cites the multi-provider one (docs/adr-register-reconciliation). Please confirm that is the intended 028.

---

Generated by Claude Code

[seanspeaks]

Schema URL convention: please change the $schema example in ADR-063 (around line 86) from

https://schemas.friggframework.org/integration-document/v0.1.json

to

https://friggframework.org/schemas/integration-document/v0.1.json

The "Hosted schemas" amendment to ADR-051 (on #666, commit 923c975) settles on one pattern for every Frigg schema: https://friggframework.org/schemas/<name>/v<major>.<minor>.json. The $id is that exact URL, and friggframework.org serves the file there. #705 implements it for @friggframework/schemas. schemas.friggframework.org isn't used.

Related, for the stack's schema files: the declarative document currently has the $id .../schemas/integration-definition/v0.1.json. @friggframework/schemas already ships an integration-definition schema (the class Definition, now integration-definition/v1.0). The amendment gives each name to one document family only, so the declarative document should use integration-document, the name this ADR already plans. capability-manifest/v0.1 and installation/v0.1 already follow the pattern.

[cursor]

Frigg 2.0.1 ADR review (COMMENT only — not an approval)

Verdict: changes needed

Blocking

1. Fix $schema / $id example to https://friggframework.org/schemas/integration-document/v0.1.json (see ADR-051 amendment on feat(devtools): frigg validate, and make the app-definition schema match the runtime (ADR-051) #666).

Should-fix

2. Adopt feat(core): defineIntegration on the integration runtime (ADR-054, one runtime, two front doors) #703 front-door names (defineIntegration, fromDefinitionDocument, embedDefinitionDocument) and the one-Definition.triggers registry rule; drop CRON as a first-class document event type in favour of schedule → triggers compilation.

Docs-only; no new test failures vs next.

[cursor]

[blocking] Wrong $schema host — must not use the schemas. subdomain.

"$schema": "https://schemas.friggframework.org/integration-document/v0.1.json"

ADR-051’s amendment on #666 standardizes published $id / $schema to:

https://friggframework.org/schemas/<name>/v<major>.<minor>.json

and explicitly rejects schemas.friggframework.org (that host never resolved; the amendment even cites this ADR-063 sketch as the example of the mistake).

Required:

"$schema": "https://friggframework.org/schemas/integration-document/v0.1.json"

Failure scenario: documents authored from this sketch fail frigg validate / $id lookup against the published schema package, and diverge from every other schema URL in the ecosystem.

[cursor]

[should-fix] Does not adopt #703 / ADR-054 amendment names or the one-trigger-registry rule.

This Decision still frames a separate DataDefinedIntegration / IntegrationDefinition path and (below) lists CRON as a first-class data-defined event type.

Per ADR-054’s “one runtime, two front doors” amendment + #703:

• code door: defineIntegration
• document door: fromDefinitionDocument / embedDefinitionDocument
• JSON is an integration document
• one registry: Definition.triggers — a document’s workflows[].trigger / schedule compiles into that list; CRON is not a parallel event face on this.events

Failure scenario: a document with type: "CRON" (or a runtime expecting DataDefinedIntegration as specified here) will not match the runtime #703 built, and trigger scheduling will fork from ADR-055.