From f1dad86e9936cb4a3d48c8a87f4f945fd8a4acd3 Mon Sep 17 00:00:00 2001 From: Ioana Hayman Date: Tue, 16 Jun 2026 20:44:49 -0400 Subject: [PATCH 1/4] feat(runneth-apps): seed default integration notes --- runneth-default/brain/integrations/README.md | 27 +++++ .../brain/integrations/google-drive.md | 38 +++++++ runneth-default/brain/integrations/hubspot.md | 37 +++++++ runneth-default/brain/integrations/klaviyo.md | 37 +++++++ .../brain/integrations/northbeam.md | 37 +++++++ runneth-default/brain/integrations/notion.md | 37 +++++++ runneth-default/brain/integrations/reviews.md | 40 ++++++++ runneth-default/brain/integrations/shopify.md | 37 +++++++ runneth-default/brain/integrations/slack.md | 36 +++++++ .../brain/integrations/triple-whale.md | 37 +++++++ .../instructions/integration-setup.md | 19 ++++ runneth-default/runneth-package.json | 99 ++++++++++++++++++- runneth-package-index.json | 6 +- scripts/validate-runneth-package-index.mjs | 8 +- 14 files changed, 489 insertions(+), 6 deletions(-) create mode 100644 runneth-default/brain/integrations/README.md create mode 100644 runneth-default/brain/integrations/google-drive.md create mode 100644 runneth-default/brain/integrations/hubspot.md create mode 100644 runneth-default/brain/integrations/klaviyo.md create mode 100644 runneth-default/brain/integrations/northbeam.md create mode 100644 runneth-default/brain/integrations/notion.md create mode 100644 runneth-default/brain/integrations/reviews.md create mode 100644 runneth-default/brain/integrations/shopify.md create mode 100644 runneth-default/brain/integrations/slack.md create mode 100644 runneth-default/brain/integrations/triple-whale.md create mode 100644 runneth-default/instructions/integration-setup.md diff --git a/runneth-default/brain/integrations/README.md b/runneth-default/brain/integrations/README.md new file mode 100644 index 0000000..2c3541e --- /dev/null +++ b/runneth-default/brain/integrations/README.md @@ -0,0 +1,27 @@ +# Integration Notes + +Use this folder for organization-specific instructions about connected integrations. + +Platform-level facts about what an app is, how its API works, and which commands to use belong to Runneth's integration guides and registered app skills. This folder is for how this organization wants those integrations used. + +## What Belongs Here + +- Which source should be treated as the source of truth for each kind of question. +- KPI definitions, attribution windows, naming conventions, and custom fields. +- Important folders, channels, databases, lists, pipelines, reports, or review sources. +- Reporting preferences and recurring deliverables that depend on an integration. +- Known gotchas, exclusions, and open questions to confirm with the team. + +## Starter Files + +- `slack.md` +- `google-drive.md` +- `notion.md` +- `shopify.md` +- `klaviyo.md` +- `hubspot.md` +- `northbeam.md` +- `triple-whale.md` +- `reviews.md` + +Create a new file when another connected integration needs durable customer-specific instructions. diff --git a/runneth-default/brain/integrations/google-drive.md b/runneth-default/brain/integrations/google-drive.md new file mode 100644 index 0000000..dfb56f9 --- /dev/null +++ b/runneth-default/brain/integrations/google-drive.md @@ -0,0 +1,38 @@ +--- +type: Integration +id: integrations/google-drive +title: Google Drive +scope: org +status: draft +aliases: [google drive, drive, docs, sheets, slides] +--- + +# Google Drive + +This file is for how this organization wants Runneth to use Google Drive files. + +## What Drive Is Used For Here + +- TBD + +## Important Folders And Files + +- Briefs: +- Reports: +- Creative assets: +- Customer research: +- Templates: + +## Access And Sharing Preferences + +- Files Runneth should ask to access: +- Files or folders that should stay out of scope: +- Preferred source documents: + +## Standing Instructions + +- TBD + +## Gotchas + +- TBD diff --git a/runneth-default/brain/integrations/hubspot.md b/runneth-default/brain/integrations/hubspot.md new file mode 100644 index 0000000..0c8698f --- /dev/null +++ b/runneth-default/brain/integrations/hubspot.md @@ -0,0 +1,37 @@ +--- +type: Integration +id: integrations/hubspot +title: HubSpot +scope: org +status: draft +aliases: [hubspot, crm, deals, contacts, pipeline] +--- + +# HubSpot + +This file is for how this organization wants Runneth to use HubSpot. + +## What HubSpot Is Used For Here + +- TBD + +## Objects, Pipelines, And Fields + +- Important objects: +- Important pipelines: +- Custom fields: +- Lifecycle or qualification definitions: + +## Reporting Preferences + +- Pipeline questions: +- Lead or customer questions: +- Fields that should be used for routing: + +## Standing Instructions + +- TBD + +## Gotchas + +- TBD diff --git a/runneth-default/brain/integrations/klaviyo.md b/runneth-default/brain/integrations/klaviyo.md new file mode 100644 index 0000000..1d49084 --- /dev/null +++ b/runneth-default/brain/integrations/klaviyo.md @@ -0,0 +1,37 @@ +--- +type: Integration +id: integrations/klaviyo +title: Klaviyo +scope: org +status: draft +aliases: [klaviyo, email, sms, flows, campaigns] +--- + +# Klaviyo + +This file is for how this organization wants Runneth to use Klaviyo. + +## What Klaviyo Is Used For Here + +- TBD + +## Lists, Segments, Campaigns, And Flows + +- Important lists: +- Important segments: +- Campaign naming conventions: +- Flow naming conventions: + +## KPI Definitions + +- Primary email metrics: +- Primary SMS metrics: +- Attribution window: + +## Standing Instructions + +- TBD + +## Gotchas + +- TBD diff --git a/runneth-default/brain/integrations/northbeam.md b/runneth-default/brain/integrations/northbeam.md new file mode 100644 index 0000000..30ad9f3 --- /dev/null +++ b/runneth-default/brain/integrations/northbeam.md @@ -0,0 +1,37 @@ +--- +type: Integration +id: integrations/northbeam +title: Northbeam +scope: org +status: draft +aliases: [northbeam, attribution, blended attribution] +--- + +# Northbeam + +This file is for how this organization wants Runneth to use Northbeam. + +## What Northbeam Is Used For Here + +- TBD + +## Attribution And KPI Definitions + +- Preferred attribution model: +- Attribution window: +- Primary efficiency metrics: +- Metrics to avoid or qualify: + +## Naming And Mapping Rules + +- Campaign naming conventions: +- Ad or creative naming conventions: +- Product or category mapping: + +## Standing Instructions + +- TBD + +## Gotchas + +- TBD diff --git a/runneth-default/brain/integrations/notion.md b/runneth-default/brain/integrations/notion.md new file mode 100644 index 0000000..fdf6949 --- /dev/null +++ b/runneth-default/brain/integrations/notion.md @@ -0,0 +1,37 @@ +--- +type: Integration +id: integrations/notion +title: Notion +scope: org +status: draft +aliases: [notion, notion pages, notion databases] +--- + +# Notion + +This file is for how this organization wants Runneth to use Notion. + +## What Notion Is Used For Here + +- TBD + +## Important Pages And Databases + +- Strategy docs: +- Briefs: +- Project trackers: +- Research repositories: + +## Field And Status Definitions + +- Key fields: +- Status meanings: +- Owner fields: + +## Standing Instructions + +- TBD + +## Gotchas + +- TBD diff --git a/runneth-default/brain/integrations/reviews.md b/runneth-default/brain/integrations/reviews.md new file mode 100644 index 0000000..0739450 --- /dev/null +++ b/runneth-default/brain/integrations/reviews.md @@ -0,0 +1,40 @@ +--- +type: Integration +id: integrations/reviews +title: Review Platforms +scope: org +status: draft +aliases: [reviews, review platforms, customer reviews, voc] +--- + +# Review Platforms + +This file is for how this organization wants Runneth to use customer reviews and voice-of-customer sources. + +## Review Sources + +- Primary review platform: +- Secondary review sources: +- Product review locations: +- Support or community sources: + +## What Reviews Are Used For Here + +- Creative briefs: +- Hook and angle research: +- Objection mining: +- Product feedback: + +## Product And Audience Mapping + +- Product naming conventions: +- Audience or persona labels: +- Review tags or themes: + +## Standing Instructions + +- TBD + +## Gotchas + +- TBD diff --git a/runneth-default/brain/integrations/shopify.md b/runneth-default/brain/integrations/shopify.md new file mode 100644 index 0000000..08acd18 --- /dev/null +++ b/runneth-default/brain/integrations/shopify.md @@ -0,0 +1,37 @@ +--- +type: Integration +id: integrations/shopify +title: Shopify +scope: org +status: draft +aliases: [shopify, ecommerce, product catalog, orders] +--- + +# Shopify + +This file is for how this organization wants Runneth to use Shopify. + +## What Shopify Is Used For Here + +- TBD + +## Product And Catalog Notes + +- Product groups: +- Naming conventions: +- Bundles or variants: +- Products to exclude: + +## Revenue And Order Definitions + +- Preferred revenue metric: +- Attribution notes: +- Refund, discount, or subscription rules: + +## Standing Instructions + +- TBD + +## Gotchas + +- TBD diff --git a/runneth-default/brain/integrations/slack.md b/runneth-default/brain/integrations/slack.md new file mode 100644 index 0000000..a327fac --- /dev/null +++ b/runneth-default/brain/integrations/slack.md @@ -0,0 +1,36 @@ +--- +type: Integration +id: integrations/slack +title: Slack +scope: org +status: draft +aliases: [slack, slack channels, slack threads] +--- + +# Slack + +This file is for how this organization wants Runneth to use Slack. + +## What Slack Is Used For Here + +- TBD + +## Channels And Context + +- Important channels: +- Channels Runneth should ask to join when relevant: +- Channels that should stay out of scope: + +## Reporting And Delivery Preferences + +- Where readouts should be posted: +- Thread vs channel-root preferences: +- People or teams to tag: + +## Standing Instructions + +- TBD + +## Gotchas + +- TBD diff --git a/runneth-default/brain/integrations/triple-whale.md b/runneth-default/brain/integrations/triple-whale.md new file mode 100644 index 0000000..e3bfebf --- /dev/null +++ b/runneth-default/brain/integrations/triple-whale.md @@ -0,0 +1,37 @@ +--- +type: Integration +id: integrations/triple-whale +title: Triple Whale +scope: org +status: draft +aliases: [triple whale, triplewhale, attribution, ecommerce reporting] +--- + +# Triple Whale + +This file is for how this organization wants Runneth to use Triple Whale. + +## What Triple Whale Is Used For Here + +- TBD + +## Attribution And KPI Definitions + +- Preferred attribution model: +- Attribution window: +- Primary efficiency metrics: +- Metrics to avoid or qualify: + +## Naming And Mapping Rules + +- Campaign naming conventions: +- Ad or creative naming conventions: +- Product or category mapping: + +## Standing Instructions + +- TBD + +## Gotchas + +- TBD diff --git a/runneth-default/instructions/integration-setup.md b/runneth-default/instructions/integration-setup.md new file mode 100644 index 0000000..eb99ee3 --- /dev/null +++ b/runneth-default/instructions/integration-setup.md @@ -0,0 +1,19 @@ +Use `/agent/brain/integrations/` for organization-specific integration knowledge. + +Platform-level integration knowledge belongs in Runneth's protected integration guidance and registered app skills. Do not copy API documentation, generic endpoint lists, OAuth instructions, or universal platform facts into the customer's integration notes. + +When a task depends on a connected integration, check whether there is a relevant note in `/agent/brain/integrations/` before relying on the integration for analysis, reporting, or routing. Use that note for customer-specific definitions, preferences, and gotchas. + +When a user gives standing instructions about an integration, save or update the matching file under `/agent/brain/integrations/`. Save only durable customer-specific knowledge, such as: + +- how they want the integration used +- source-of-truth rules +- KPI definitions and attribution windows +- naming conventions +- important objects, fields, lists, folders, channels, reports, pipelines, or databases +- reporting and deliverable preferences +- known gotchas and exclusions + +If a connected integration has no customer-specific note yet and the current task would be more accurate with that context, ask one short setup question instead of giving the user a blank form. For example: "How do you want me to use Klaviyo when I answer email or retention questions for this account?" If the user answers, save the answer in the matching integration note. + +Do not block simple tasks on setup. If the user asks for a concrete answer and the available data is enough, answer first, then ask the one setup question only if it will improve future work. diff --git a/runneth-default/runneth-package.json b/runneth-default/runneth-package.json index 13cdc18..d5ed723 100644 --- a/runneth-default/runneth-package.json +++ b/runneth-default/runneth-package.json @@ -2,8 +2,8 @@ "schemaVersion": 1, "id": "runneth-default", "name": "Runneth Default", - "version": "0.1.0", - "description": "Installs the baseline Runneth creative strategy skills that moved out of the protected Runneth volume.", + "version": "0.2.0", + "description": "Installs baseline Runneth creative strategy skills and editable starter notes for customer-specific integration setup.", "updatePolicy": "auto", "resources": [ { @@ -40,6 +40,101 @@ "id": "core-creative-skills", "type": "package_instruction", "sourcePath": "instructions/core-creative-skills.md" + }, + { + "id": "integration-setup", + "type": "package_instruction", + "sourcePath": "instructions/integration-setup.md" + }, + { + "id": "integration-notes-index", + "type": "seed_file", + "sourcePath": "brain/integrations/README.md", + "target": { + "root": "agent_brain", + "path": "integrations/README.md" + } + }, + { + "id": "slack-integration-notes", + "type": "seed_file", + "sourcePath": "brain/integrations/slack.md", + "target": { + "root": "agent_brain", + "path": "integrations/slack.md" + } + }, + { + "id": "google-drive-integration-notes", + "type": "seed_file", + "sourcePath": "brain/integrations/google-drive.md", + "target": { + "root": "agent_brain", + "path": "integrations/google-drive.md" + } + }, + { + "id": "notion-integration-notes", + "type": "seed_file", + "sourcePath": "brain/integrations/notion.md", + "target": { + "root": "agent_brain", + "path": "integrations/notion.md" + } + }, + { + "id": "shopify-integration-notes", + "type": "seed_file", + "sourcePath": "brain/integrations/shopify.md", + "target": { + "root": "agent_brain", + "path": "integrations/shopify.md" + } + }, + { + "id": "klaviyo-integration-notes", + "type": "seed_file", + "sourcePath": "brain/integrations/klaviyo.md", + "target": { + "root": "agent_brain", + "path": "integrations/klaviyo.md" + } + }, + { + "id": "hubspot-integration-notes", + "type": "seed_file", + "sourcePath": "brain/integrations/hubspot.md", + "target": { + "root": "agent_brain", + "path": "integrations/hubspot.md" + } + }, + { + "id": "northbeam-integration-notes", + "type": "seed_file", + "sourcePath": "brain/integrations/northbeam.md", + "target": { + "root": "agent_brain", + "path": "integrations/northbeam.md" + } + }, + { + "id": "triple-whale-integration-notes", + "type": "seed_file", + "sourcePath": "brain/integrations/triple-whale.md", + "target": { + "root": "agent_brain", + "path": "integrations/triple-whale.md" + } + }, + { + "id": "reviews-integration-notes", + "type": "seed_file", + "sourcePath": "brain/integrations/reviews.md", + "target": { + "root": "agent_brain", + "path": "integrations/reviews.md" + } } ] } diff --git a/runneth-package-index.json b/runneth-package-index.json index 90c7c74..1a93655 100644 --- a/runneth-package-index.json +++ b/runneth-package-index.json @@ -1,12 +1,12 @@ { "schemaVersion": 1, - "indexRevision": "runneth-default-0.1.0", + "indexRevision": "runneth-default-0.2.0", "packages": [ { "id": "runneth-default", "name": "Runneth Default", - "description": "Baseline Runneth creative strategy skills installed outside the protected Runneth volume.", - "version": "0.1.0", + "description": "Baseline Runneth creative strategy skills and editable starter notes for customer-specific integration setup.", + "version": "0.2.0", "packageManagerVersion": 1, "categories": [ "baseline" diff --git a/scripts/validate-runneth-package-index.mjs b/scripts/validate-runneth-package-index.mjs index 03c6fbd..74d1985 100644 --- a/scripts/validate-runneth-package-index.mjs +++ b/scripts/validate-runneth-package-index.mjs @@ -107,6 +107,12 @@ const assertPackageResource = (resource, label) => { return } + if (resource.type === 'seed_file') { + assertKeys(resource, ['id', 'sourcePath', 'target', 'type'], label) + assertTarget(resource.target, `${label}.target`) + return + } + if (resource.type === 'directory') { assertKeys(resource, ['executablePaths', 'id', 'sourcePath', 'target', 'type'], label) assert.ok(Array.isArray(resource.executablePaths), `${label}.executablePaths: must be array`) @@ -122,7 +128,7 @@ const assertPackageResource = (resource, label) => { return } - assert.fail(`${label}.type: must be file, directory, or package_instruction`) + assert.fail(`${label}.type: must be file, seed_file, directory, or package_instruction`) } const assertPackageManifest = (manifest, label) => { From e5806b07d0913ca943d2fbb64671a40f9845324e Mon Sep 17 00:00:00 2001 From: Ioana Hayman Date: Tue, 16 Jun 2026 21:16:57 -0400 Subject: [PATCH 2/4] feat(runneth-apps): narrow default integration seeds --- .../_templates/integration-map.md | 62 ++++++++++++++ .../brain/integrations/google-drive.md | 38 --------- runneth-default/brain/integrations/hubspot.md | 37 --------- .../integrations/{README.md => index.md} | 25 +++--- runneth-default/brain/integrations/klaviyo.md | 37 --------- .../brain/integrations/northbeam.md | 37 --------- runneth-default/brain/integrations/notion.md | 37 --------- runneth-default/brain/integrations/reviews.md | 40 --------- runneth-default/brain/integrations/shopify.md | 37 --------- runneth-default/brain/integrations/slack.md | 20 ++--- .../brain/integrations/triple-whale.md | 37 --------- .../instructions/integration-setup.md | 6 +- runneth-default/runneth-package.json | 81 +++---------------- runneth-package-index.json | 2 +- 14 files changed, 99 insertions(+), 397 deletions(-) create mode 100644 runneth-default/brain/integrations/_templates/integration-map.md delete mode 100644 runneth-default/brain/integrations/google-drive.md delete mode 100644 runneth-default/brain/integrations/hubspot.md rename runneth-default/brain/integrations/{README.md => index.md} (64%) delete mode 100644 runneth-default/brain/integrations/klaviyo.md delete mode 100644 runneth-default/brain/integrations/northbeam.md delete mode 100644 runneth-default/brain/integrations/notion.md delete mode 100644 runneth-default/brain/integrations/reviews.md delete mode 100644 runneth-default/brain/integrations/shopify.md delete mode 100644 runneth-default/brain/integrations/triple-whale.md diff --git a/runneth-default/brain/integrations/_templates/integration-map.md b/runneth-default/brain/integrations/_templates/integration-map.md new file mode 100644 index 0000000..8e0c246 --- /dev/null +++ b/runneth-default/brain/integrations/_templates/integration-map.md @@ -0,0 +1,62 @@ +--- +type: Template +id: integrations/templates/integration-map +title: Integration Map Template +scope: org +status: active +template_variant: source +aliases: [integration map template, integration setup template] +--- + +# Integration Map Template + +Use this shape when creating a customer-specific integration map. + +```yaml +--- +type: Integration +id: integrations/ +title: +scope: org +status: draft +aliases: [] +--- +``` + +# Integration Name + +Use this file for how this organization wants Runneth to use . + +## What This Integration Is Used For Here + +- Add the confirmed jobs this integration supports for this organization. + +## Source Of Truth Rules + +- Add when this integration should win over other connected sources. + +## Objects, Fields, And Routing + +- Important objects. +- Important fields. +- Important folders, channels, lists, reports, databases, or pipelines. +- Questions that should route here. + +## KPI And Attribution Preferences + +- KPI definitions. +- Attribution windows. +- Naming conventions. +- Exclusions or filters. + +## Example Questions + +- Add examples of questions Runneth should answer with this integration. + +## Standing Instructions + +- Add durable instructions the team has confirmed. + +## Gotchas And Open Questions + +- Add known data quirks, missing context, or questions to confirm. diff --git a/runneth-default/brain/integrations/google-drive.md b/runneth-default/brain/integrations/google-drive.md deleted file mode 100644 index dfb56f9..0000000 --- a/runneth-default/brain/integrations/google-drive.md +++ /dev/null @@ -1,38 +0,0 @@ ---- -type: Integration -id: integrations/google-drive -title: Google Drive -scope: org -status: draft -aliases: [google drive, drive, docs, sheets, slides] ---- - -# Google Drive - -This file is for how this organization wants Runneth to use Google Drive files. - -## What Drive Is Used For Here - -- TBD - -## Important Folders And Files - -- Briefs: -- Reports: -- Creative assets: -- Customer research: -- Templates: - -## Access And Sharing Preferences - -- Files Runneth should ask to access: -- Files or folders that should stay out of scope: -- Preferred source documents: - -## Standing Instructions - -- TBD - -## Gotchas - -- TBD diff --git a/runneth-default/brain/integrations/hubspot.md b/runneth-default/brain/integrations/hubspot.md deleted file mode 100644 index 0c8698f..0000000 --- a/runneth-default/brain/integrations/hubspot.md +++ /dev/null @@ -1,37 +0,0 @@ ---- -type: Integration -id: integrations/hubspot -title: HubSpot -scope: org -status: draft -aliases: [hubspot, crm, deals, contacts, pipeline] ---- - -# HubSpot - -This file is for how this organization wants Runneth to use HubSpot. - -## What HubSpot Is Used For Here - -- TBD - -## Objects, Pipelines, And Fields - -- Important objects: -- Important pipelines: -- Custom fields: -- Lifecycle or qualification definitions: - -## Reporting Preferences - -- Pipeline questions: -- Lead or customer questions: -- Fields that should be used for routing: - -## Standing Instructions - -- TBD - -## Gotchas - -- TBD diff --git a/runneth-default/brain/integrations/README.md b/runneth-default/brain/integrations/index.md similarity index 64% rename from runneth-default/brain/integrations/README.md rename to runneth-default/brain/integrations/index.md index 2c3541e..609e027 100644 --- a/runneth-default/brain/integrations/README.md +++ b/runneth-default/brain/integrations/index.md @@ -1,4 +1,13 @@ -# Integration Notes +--- +type: Reference +id: integrations +title: Integration Maps +scope: org +status: active +aliases: [integrations, connected apps, data sources] +--- + +# Integration Maps Use this folder for organization-specific instructions about connected integrations. @@ -12,16 +21,6 @@ Platform-level facts about what an app is, how its API works, and which commands - Reporting preferences and recurring deliverables that depend on an integration. - Known gotchas, exclusions, and open questions to confirm with the team. -## Starter Files - -- `slack.md` -- `google-drive.md` -- `notion.md` -- `shopify.md` -- `klaviyo.md` -- `hubspot.md` -- `northbeam.md` -- `triple-whale.md` -- `reviews.md` +## How To Add An Integration Map -Create a new file when another connected integration needs durable customer-specific instructions. +Create a new file when a connected integration needs durable customer-specific instructions. Use `_templates/integration-map.md` as the starting shape, then replace placeholders with what the team has confirmed. diff --git a/runneth-default/brain/integrations/klaviyo.md b/runneth-default/brain/integrations/klaviyo.md deleted file mode 100644 index 1d49084..0000000 --- a/runneth-default/brain/integrations/klaviyo.md +++ /dev/null @@ -1,37 +0,0 @@ ---- -type: Integration -id: integrations/klaviyo -title: Klaviyo -scope: org -status: draft -aliases: [klaviyo, email, sms, flows, campaigns] ---- - -# Klaviyo - -This file is for how this organization wants Runneth to use Klaviyo. - -## What Klaviyo Is Used For Here - -- TBD - -## Lists, Segments, Campaigns, And Flows - -- Important lists: -- Important segments: -- Campaign naming conventions: -- Flow naming conventions: - -## KPI Definitions - -- Primary email metrics: -- Primary SMS metrics: -- Attribution window: - -## Standing Instructions - -- TBD - -## Gotchas - -- TBD diff --git a/runneth-default/brain/integrations/northbeam.md b/runneth-default/brain/integrations/northbeam.md deleted file mode 100644 index 30ad9f3..0000000 --- a/runneth-default/brain/integrations/northbeam.md +++ /dev/null @@ -1,37 +0,0 @@ ---- -type: Integration -id: integrations/northbeam -title: Northbeam -scope: org -status: draft -aliases: [northbeam, attribution, blended attribution] ---- - -# Northbeam - -This file is for how this organization wants Runneth to use Northbeam. - -## What Northbeam Is Used For Here - -- TBD - -## Attribution And KPI Definitions - -- Preferred attribution model: -- Attribution window: -- Primary efficiency metrics: -- Metrics to avoid or qualify: - -## Naming And Mapping Rules - -- Campaign naming conventions: -- Ad or creative naming conventions: -- Product or category mapping: - -## Standing Instructions - -- TBD - -## Gotchas - -- TBD diff --git a/runneth-default/brain/integrations/notion.md b/runneth-default/brain/integrations/notion.md deleted file mode 100644 index fdf6949..0000000 --- a/runneth-default/brain/integrations/notion.md +++ /dev/null @@ -1,37 +0,0 @@ ---- -type: Integration -id: integrations/notion -title: Notion -scope: org -status: draft -aliases: [notion, notion pages, notion databases] ---- - -# Notion - -This file is for how this organization wants Runneth to use Notion. - -## What Notion Is Used For Here - -- TBD - -## Important Pages And Databases - -- Strategy docs: -- Briefs: -- Project trackers: -- Research repositories: - -## Field And Status Definitions - -- Key fields: -- Status meanings: -- Owner fields: - -## Standing Instructions - -- TBD - -## Gotchas - -- TBD diff --git a/runneth-default/brain/integrations/reviews.md b/runneth-default/brain/integrations/reviews.md deleted file mode 100644 index 0739450..0000000 --- a/runneth-default/brain/integrations/reviews.md +++ /dev/null @@ -1,40 +0,0 @@ ---- -type: Integration -id: integrations/reviews -title: Review Platforms -scope: org -status: draft -aliases: [reviews, review platforms, customer reviews, voc] ---- - -# Review Platforms - -This file is for how this organization wants Runneth to use customer reviews and voice-of-customer sources. - -## Review Sources - -- Primary review platform: -- Secondary review sources: -- Product review locations: -- Support or community sources: - -## What Reviews Are Used For Here - -- Creative briefs: -- Hook and angle research: -- Objection mining: -- Product feedback: - -## Product And Audience Mapping - -- Product naming conventions: -- Audience or persona labels: -- Review tags or themes: - -## Standing Instructions - -- TBD - -## Gotchas - -- TBD diff --git a/runneth-default/brain/integrations/shopify.md b/runneth-default/brain/integrations/shopify.md deleted file mode 100644 index 08acd18..0000000 --- a/runneth-default/brain/integrations/shopify.md +++ /dev/null @@ -1,37 +0,0 @@ ---- -type: Integration -id: integrations/shopify -title: Shopify -scope: org -status: draft -aliases: [shopify, ecommerce, product catalog, orders] ---- - -# Shopify - -This file is for how this organization wants Runneth to use Shopify. - -## What Shopify Is Used For Here - -- TBD - -## Product And Catalog Notes - -- Product groups: -- Naming conventions: -- Bundles or variants: -- Products to exclude: - -## Revenue And Order Definitions - -- Preferred revenue metric: -- Attribution notes: -- Refund, discount, or subscription rules: - -## Standing Instructions - -- TBD - -## Gotchas - -- TBD diff --git a/runneth-default/brain/integrations/slack.md b/runneth-default/brain/integrations/slack.md index a327fac..8a5caa4 100644 --- a/runneth-default/brain/integrations/slack.md +++ b/runneth-default/brain/integrations/slack.md @@ -13,24 +13,24 @@ This file is for how this organization wants Runneth to use Slack. ## What Slack Is Used For Here -- TBD +- Add the confirmed Slack context this organization wants Runneth to use. ## Channels And Context -- Important channels: -- Channels Runneth should ask to join when relevant: -- Channels that should stay out of scope: +- Important channels. +- Channels Runneth should ask to join when relevant. +- Channels that should stay out of scope. ## Reporting And Delivery Preferences -- Where readouts should be posted: -- Thread vs channel-root preferences: -- People or teams to tag: +- Where readouts should be posted. +- Thread vs channel-root preferences. +- People or teams to tag. ## Standing Instructions -- TBD +- Add durable Slack instructions the team has confirmed. -## Gotchas +## Gotchas And Open Questions -- TBD +- Add known Slack context gaps, delivery constraints, or questions to confirm. diff --git a/runneth-default/brain/integrations/triple-whale.md b/runneth-default/brain/integrations/triple-whale.md deleted file mode 100644 index e3bfebf..0000000 --- a/runneth-default/brain/integrations/triple-whale.md +++ /dev/null @@ -1,37 +0,0 @@ ---- -type: Integration -id: integrations/triple-whale -title: Triple Whale -scope: org -status: draft -aliases: [triple whale, triplewhale, attribution, ecommerce reporting] ---- - -# Triple Whale - -This file is for how this organization wants Runneth to use Triple Whale. - -## What Triple Whale Is Used For Here - -- TBD - -## Attribution And KPI Definitions - -- Preferred attribution model: -- Attribution window: -- Primary efficiency metrics: -- Metrics to avoid or qualify: - -## Naming And Mapping Rules - -- Campaign naming conventions: -- Ad or creative naming conventions: -- Product or category mapping: - -## Standing Instructions - -- TBD - -## Gotchas - -- TBD diff --git a/runneth-default/instructions/integration-setup.md b/runneth-default/instructions/integration-setup.md index eb99ee3..137e453 100644 --- a/runneth-default/instructions/integration-setup.md +++ b/runneth-default/instructions/integration-setup.md @@ -2,9 +2,11 @@ Use `/agent/brain/integrations/` for organization-specific integration knowledge Platform-level integration knowledge belongs in Runneth's protected integration guidance and registered app skills. Do not copy API documentation, generic endpoint lists, OAuth instructions, or universal platform facts into the customer's integration notes. +Before suggesting, connecting, or using an integration, check the available connection context and integration catalogue first. Use first-class/native flows when they exist, registered connected-app guidance when the app is available through the integrations catalogue, and secure secret collection for API-key or credential-backed services. + When a task depends on a connected integration, check whether there is a relevant note in `/agent/brain/integrations/` before relying on the integration for analysis, reporting, or routing. Use that note for customer-specific definitions, preferences, and gotchas. -When a user gives standing instructions about an integration, save or update the matching file under `/agent/brain/integrations/`. Save only durable customer-specific knowledge, such as: +When a user gives standing instructions about an integration, save or update the matching file under `/agent/brain/integrations/`. Use `/agent/brain/integrations/_templates/integration-map.md` as the shape for new files when it exists. Save only durable customer-specific knowledge, such as: - how they want the integration used - source-of-truth rules @@ -16,4 +18,6 @@ When a user gives standing instructions about an integration, save or update the If a connected integration has no customer-specific note yet and the current task would be more accurate with that context, ask one short setup question instead of giving the user a blank form. For example: "How do you want me to use Klaviyo when I answer email or retention questions for this account?" If the user answers, save the answer in the matching integration note. +After a user connects an integration or asks Runneth to use one for the first time, offer to create the first integration map only when it would help future work. Keep this lightweight: one useful question in context, not a setup wizard and not a repeated pitch. + Do not block simple tasks on setup. If the user asks for a concrete answer and the available data is enough, answer first, then ask the one setup question only if it will improve future work. diff --git a/runneth-default/runneth-package.json b/runneth-default/runneth-package.json index d5ed723..88036cf 100644 --- a/runneth-default/runneth-package.json +++ b/runneth-default/runneth-package.json @@ -3,7 +3,7 @@ "id": "runneth-default", "name": "Runneth Default", "version": "0.2.0", - "description": "Installs baseline Runneth creative strategy skills and editable starter notes for customer-specific integration setup.", + "description": "Installs baseline Runneth creative strategy skills and a small customer-owned integration setup surface.", "updatePolicy": "auto", "resources": [ { @@ -49,91 +49,28 @@ { "id": "integration-notes-index", "type": "seed_file", - "sourcePath": "brain/integrations/README.md", + "sourcePath": "brain/integrations/index.md", "target": { "root": "agent_brain", - "path": "integrations/README.md" + "path": "integrations/index.md" } }, { - "id": "slack-integration-notes", - "type": "seed_file", - "sourcePath": "brain/integrations/slack.md", - "target": { - "root": "agent_brain", - "path": "integrations/slack.md" - } - }, - { - "id": "google-drive-integration-notes", - "type": "seed_file", - "sourcePath": "brain/integrations/google-drive.md", - "target": { - "root": "agent_brain", - "path": "integrations/google-drive.md" - } - }, - { - "id": "notion-integration-notes", - "type": "seed_file", - "sourcePath": "brain/integrations/notion.md", - "target": { - "root": "agent_brain", - "path": "integrations/notion.md" - } - }, - { - "id": "shopify-integration-notes", - "type": "seed_file", - "sourcePath": "brain/integrations/shopify.md", - "target": { - "root": "agent_brain", - "path": "integrations/shopify.md" - } - }, - { - "id": "klaviyo-integration-notes", - "type": "seed_file", - "sourcePath": "brain/integrations/klaviyo.md", - "target": { - "root": "agent_brain", - "path": "integrations/klaviyo.md" - } - }, - { - "id": "hubspot-integration-notes", - "type": "seed_file", - "sourcePath": "brain/integrations/hubspot.md", - "target": { - "root": "agent_brain", - "path": "integrations/hubspot.md" - } - }, - { - "id": "northbeam-integration-notes", - "type": "seed_file", - "sourcePath": "brain/integrations/northbeam.md", - "target": { - "root": "agent_brain", - "path": "integrations/northbeam.md" - } - }, - { - "id": "triple-whale-integration-notes", + "id": "integration-map-template", "type": "seed_file", - "sourcePath": "brain/integrations/triple-whale.md", + "sourcePath": "brain/integrations/_templates/integration-map.md", "target": { "root": "agent_brain", - "path": "integrations/triple-whale.md" + "path": "integrations/_templates/integration-map.md" } }, { - "id": "reviews-integration-notes", + "id": "slack-integration-notes", "type": "seed_file", - "sourcePath": "brain/integrations/reviews.md", + "sourcePath": "brain/integrations/slack.md", "target": { "root": "agent_brain", - "path": "integrations/reviews.md" + "path": "integrations/slack.md" } } ] diff --git a/runneth-package-index.json b/runneth-package-index.json index 1a93655..64f19eb 100644 --- a/runneth-package-index.json +++ b/runneth-package-index.json @@ -5,7 +5,7 @@ { "id": "runneth-default", "name": "Runneth Default", - "description": "Baseline Runneth creative strategy skills and editable starter notes for customer-specific integration setup.", + "description": "Baseline Runneth creative strategy skills and a small customer-owned integration setup surface.", "version": "0.2.0", "packageManagerVersion": 1, "categories": [ From 963557530ea87aa09e3678fa7efc27c990921e5e Mon Sep 17 00:00:00 2001 From: Ioana Hayman Date: Tue, 16 Jun 2026 21:44:33 -0400 Subject: [PATCH 3/4] feat(runneth-apps): seed integration setup protocols --- .../_protocols/integration-types.md | 95 +++++++++++++++++++ .../brain/integrations/_protocols/quirks.md | 59 ++++++++++++ .../integrations/_protocols/usage-feedback.md | 45 +++++++++ .../_templates/activation-plan.md | 77 +++++++++++++++ .../_templates/capabilities-and-scopes.md | 57 +++++++++++ .../_templates/integration-map.md | 19 +++- .../_templates/practical-guide.md | 63 ++++++++++++ .../brain/integrations/_templates/quirks.md | 56 +++++++++++ .../integrations/_templates/usage-patterns.md | 49 ++++++++++ runneth-default/brain/integrations/index.md | 19 +++- .../integrations/{slack.md => slack/index.md} | 8 +- .../instructions/integration-setup.md | 16 +++- runneth-default/runneth-package.json | 82 +++++++++++++++- runneth-package-index.json | 6 +- 14 files changed, 638 insertions(+), 13 deletions(-) create mode 100644 runneth-default/brain/integrations/_protocols/integration-types.md create mode 100644 runneth-default/brain/integrations/_protocols/quirks.md create mode 100644 runneth-default/brain/integrations/_protocols/usage-feedback.md create mode 100644 runneth-default/brain/integrations/_templates/activation-plan.md create mode 100644 runneth-default/brain/integrations/_templates/capabilities-and-scopes.md create mode 100644 runneth-default/brain/integrations/_templates/practical-guide.md create mode 100644 runneth-default/brain/integrations/_templates/quirks.md create mode 100644 runneth-default/brain/integrations/_templates/usage-patterns.md rename runneth-default/brain/integrations/{slack.md => slack/index.md} (69%) diff --git a/runneth-default/brain/integrations/_protocols/integration-types.md b/runneth-default/brain/integrations/_protocols/integration-types.md new file mode 100644 index 0000000..31f81d8 --- /dev/null +++ b/runneth-default/brain/integrations/_protocols/integration-types.md @@ -0,0 +1,95 @@ +--- +type: Reference +id: integrations/protocols/integration-types +title: Integration Type Protocols +scope: org +status: active +aliases: [integration types, integration taxonomy, integration setup protocols] +--- + +# Integration Type Protocols + +Use this protocol to classify a connected integration before creating org-specific setup notes. + +## Type 1: Performance Data + +Examples: Meta Ads, TikTok Ads, Google Ads, Snapchat Ads, Pinterest Ads, LinkedIn Ads. + +Primary job: answer performance questions about spend, impressions, clicks, conversions, efficiency, creative performance, campaigns, and time periods. + +Save in the customer's map: + +- Default metrics and ranking rules. +- Valid date windows. +- Minimum data thresholds. +- Naming conventions and groupings. +- Platform quirks that affect analysis. + +## Type 2: Attribution Or Cross-Platform Join + +Examples: Northbeam, Triple Whale, Rockerbox, Hyros, Elevar. + +Primary job: join ad-platform data with attribution or revenue data. + +Save in the customer's map: + +- Join key, such as ad ID, UTM, ad name, or fuzzy normalized name. +- Attribution windows. +- Which source wins for spend, impressions, conversions, revenue, and ROAS. +- How unmatched rows should be handled. +- Known discrepancies between the ad platform and the attribution tool. + +## Type 3: Capability Tool + +Examples: research APIs, enrichment tools, AI tools, point-in-time lookup tools. + +Primary job: add a specific capability on request. + +Save in the customer's map: + +- What the tool should be used for. +- When Runneth should invoke it proactively versus only on request. +- Input and output expectations. +- Latency, cost, or rate-limit constraints. +- Cache or reuse expectations. + +## Type 4: Workspace Or Organizational Context + +Examples: Slack, Notion, Google Drive, GitHub, Linear, Asana, Jira. + +Primary job: pull team context into the brain or push outputs back into the team's working surfaces. + +Save in the customer's map: + +- Important spaces, folders, channels, databases, projects, teams, or repos. +- Which structures are alive versus legacy. +- Write-back targets. +- Team vocabulary. +- Permission constraints. +- What context should become brain knowledge and when. + +## Type 5: Customer Or Business Intelligence + +Examples: HubSpot, Salesforce, Shopify, Stripe, WooCommerce. + +Primary job: answer questions about customers, revenue, orders, pipeline, retention, and business context. + +Save in the customer's map: + +- Primary entities and relationships. +- Important custom fields. +- Pipeline or lifecycle definitions. +- Revenue and status definitions. +- Privacy constraints and minimum necessary fields. + +## Ambiguity Rule + +If the same app could reasonably be used as different integration types, ask one specific question before creating a deep setup file. Do not guess when the answer would change schemas, queries, routing, or source-of-truth rules. + +Examples: + +- AppLovin could be advertiser user-acquisition performance data or publisher monetization data. +- Google could mean Ads, Analytics, Drive, Sheets, or another workspace tool. +- Amazon could mean Advertising or Marketplace. + +If the ambiguity would not change the setup shape, proceed with a lightweight map and note the assumption. diff --git a/runneth-default/brain/integrations/_protocols/quirks.md b/runneth-default/brain/integrations/_protocols/quirks.md new file mode 100644 index 0000000..226df40 --- /dev/null +++ b/runneth-default/brain/integrations/_protocols/quirks.md @@ -0,0 +1,59 @@ +--- +type: Reference +id: integrations/protocols/quirks +title: Integration Quirks Protocol +scope: org +status: active +aliases: [quirks protocol, integration gotchas, never twice rule] +--- + +# Integration Quirks Protocol + +Use this when a connected platform behaves unexpectedly, a user corrects Runneth, or a live call exposes a surprising edge case. + +## Principle + +If a user has to tell Runneth about an integration problem once, capture it so the same symptom does not surprise them again. + +## Where It Goes + +Write quirks for a specific integration in: + +`/agent/brain/integrations//quirks.md` + +Use `_templates/quirks.md` when creating the file. + +## When To Write A Quirk + +- The user says the result is wrong, weird, missing, or not how the platform works. +- A platform returns null, empty, rate-limited, permission-blocked, or unexpectedly shaped data. +- Runneth discovers a known platform limitation during setup or use. +- A workaround is required to get reliable results. + +## Workaround Order + +Before marking a quirk as unhandled, try to solve it in this order: + +1. Handle it in the fetch, sync, query, or routing layer. +2. Reconstruct the value from other fields. +3. Use a different endpoint, query, account, export, or source. +4. Chunk, batch, paginate, or cache. +5. Warn proactively and specifically before the user hits the issue. +6. Ask a data-savvy user only when the missing fact is account-specific and cannot be inferred. + +## Statuses + +- `unhandled`: the problem can still surprise the user. +- `handled-in-code`: Runneth or the data layer handles it before the user sees it. +- `handled-by-warning`: Runneth cannot fully fix it, but warns with the exact condition and workaround. +- `monitoring`: kept for memory, but not active debt. + +## Required Wiring + +When a quirk is confirmed, also update: + +- `capabilities-and-scopes.md` under Known Constraints. +- `practical-guide.md` when the behavior affects normal use. +- `usage-patterns.md` when the quirk came from repeated usage friction. + +Do not copy generic API documentation into the quirk. Capture the customer-visible symptom, the platform behavior, the detection signal, and the fix. diff --git a/runneth-default/brain/integrations/_protocols/usage-feedback.md b/runneth-default/brain/integrations/_protocols/usage-feedback.md new file mode 100644 index 0000000..aa30283 --- /dev/null +++ b/runneth-default/brain/integrations/_protocols/usage-feedback.md @@ -0,0 +1,45 @@ +--- +type: Reference +id: integrations/protocols/usage-feedback +title: Integration Usage Feedback Protocol +scope: org +status: active +aliases: [integration usage feedback, usage patterns, integration learning loop] +--- + +# Integration Usage Feedback Protocol + +Use this to capture how people actually use an integration after setup. + +## Where It Goes + +Write repeated usage patterns for a specific integration in: + +`/agent/brain/integrations//usage-patterns.md` + +Use `_templates/usage-patterns.md` when creating the file. + +## What To Track + +- Which questions, commands, reports, fields, filters, metrics, or date windows are used repeatedly. +- What the output is used for next, such as a brief, report, Slack message, decision, or follow-up query. +- What users keep correcting, narrowing, or rephrasing. +- Which proposed workflows never get used. +- Person-specific preferences that should also be saved to that person's team file. + +## How It Improves Defaults + +If a user repeatedly overrides a default, save that preference in the integration usage file. + +Examples: + +- They always sort by thumbstop instead of spend. +- They always use a 7-day view instead of 30 days. +- They always compare Northbeam against Meta, but treat Northbeam as the conversion source of truth. +- They always want a Slack-ready summary after the query. + +If the pattern is person-specific, add it to the person's team file too. If it applies across the organization, keep it in the integration map and practical guide. + +## Trust Rule + +Corrections should improve the system, not just the current answer. If a correction exposes a platform quirk, write a quirk. If it exposes a durable usage preference, write a usage pattern. If it exposes a source-of-truth or KPI rule, update the integration map and practical guide. diff --git a/runneth-default/brain/integrations/_templates/activation-plan.md b/runneth-default/brain/integrations/_templates/activation-plan.md new file mode 100644 index 0000000..325f143 --- /dev/null +++ b/runneth-default/brain/integrations/_templates/activation-plan.md @@ -0,0 +1,77 @@ +--- +type: Template +id: integrations/templates/activation-plan +title: Integration Activation Plan Template +scope: org +status: active +template_variant: source +aliases: [activation plan template, integration activation template] +--- + +# Integration Activation Plan Template + +Use this shape when Runneth has enough context to propose how this organization should use a connected integration. + +```yaml +--- +type: Integration +id: integrations//activation +title: Activation Plan +scope: org +status: draft +aliases: [ activation, setup plan] +--- +``` + +# Activation Plan + +## Setup Context + +- Who connected or requested the integration. +- The immediate job or reason for setup. +- Whether this is a lightweight setup or a deeper team setup. + +## Integration Type + +- Classify the integration using `_protocols/integration-types.md`. +- Note any ambiguity that must be clarified before building schemas, sync logic, or recurring workflows. + +## Platform Map + +- Alive structures, reports, folders, projects, channels, databases, pipelines, or accounts. +- Legacy or noisy structures to ignore. +- The team's vocabulary for the platform. + +## Source Of Truth And Routing + +- When this integration should be used. +- When another source should win. +- Which questions should route here. + +## Business Logic Required + +- Required joins, filters, thresholds, attribution windows, naming conventions, or transformations. +- What goes wrong if Runneth uses the raw API or raw export naively. + +## Compound Opportunities + +- Workflows that become possible because this integration can combine with Motion, Slack, files, or other connected integrations. + +## Proposed Workflows + +- Add 2 to 4 concrete workflows this organization should try first. + +## First Action + +- The first useful next action Runneth should take or offer. + +## Open Questions + +- Add only questions that materially affect future accuracy or setup. + +## Related Files + +- `capabilities-and-scopes.md` +- `practical-guide.md` +- `quirks.md` +- `usage-patterns.md` diff --git a/runneth-default/brain/integrations/_templates/capabilities-and-scopes.md b/runneth-default/brain/integrations/_templates/capabilities-and-scopes.md new file mode 100644 index 0000000..4764a4f --- /dev/null +++ b/runneth-default/brain/integrations/_templates/capabilities-and-scopes.md @@ -0,0 +1,57 @@ +--- +type: Template +id: integrations/templates/capabilities-and-scopes +title: Integration Capabilities And Scopes Template +scope: org +status: active +template_variant: source +aliases: [capabilities and scopes template, integration capabilities template] +--- + +# Integration Capabilities And Scopes Template + +Use this shape for the first durable note after an integration is connected or first used. + +```yaml +--- +type: Integration +id: integrations//capabilities-and-scopes +title: Capabilities And Scopes +scope: org +status: draft +aliases: [ capabilities, scopes] +--- +``` + +# Capabilities And Scopes + +## What This Integration Is + +- Add a short, plain-language description of what this integration gives Runneth access to. + +## Core Capability Areas + +- Add what Runneth can read, answer, create, update, or deliver through this integration. + +## Access And Setup + +- Auth model. +- Connected account or workspace. +- Scopes granted. +- Any setup state that affects what Runneth can do. + +## Data Access And Sensitivity + +- What can be read. +- What can be written. +- What is sensitive or should be handled carefully. + +## Verified Vs. Theoretical + +- Mark capabilities as verified only after Runneth has tested or successfully used them. +- Keep untested capabilities as theoretical. + +## Known Constraints + +- Add confirmed limitations, permission gaps, rate limits, missing fields, or quirks. +- Link to the matching quirks file when one exists. diff --git a/runneth-default/brain/integrations/_templates/integration-map.md b/runneth-default/brain/integrations/_templates/integration-map.md index 8e0c246..f216b66 100644 --- a/runneth-default/brain/integrations/_templates/integration-map.md +++ b/runneth-default/brain/integrations/_templates/integration-map.md @@ -10,7 +10,7 @@ aliases: [integration map template, integration setup template] # Integration Map Template -Use this shape when creating a customer-specific integration map. +Use this shape when creating the main customer-specific integration map. For lightweight setup, this can be the only file. For richer setup, create a folder at `/agent/brain/integrations//` and use this as `index.md` alongside the companion templates in this folder. ```yaml --- @@ -27,6 +27,11 @@ aliases: [] Use this file for how this organization wants Runneth to use . +## Integration Type + +- Classify using `/agent/brain/integrations/_protocols/integration-types.md`. +- If the app can be used in meaningfully different ways, ask one specific question before creating deep setup notes. + ## What This Integration Is Used For Here - Add the confirmed jobs this integration supports for this organization. @@ -41,6 +46,8 @@ Use this file for how this organization wants Runneth to use . - Important fields. - Important folders, channels, lists, reports, databases, or pipelines. - Questions that should route here. +- Alive structures to prioritize. +- Legacy or noisy structures to ignore. ## KPI And Attribution Preferences @@ -49,10 +56,20 @@ Use this file for how this organization wants Runneth to use . - Naming conventions. - Exclusions or filters. +## Write-Back And Delivery Targets + +- Places Runneth should write, post, save, or deliver outputs. +- Permission or approval constraints before writing. + ## Example Questions - Add examples of questions Runneth should answer with this integration. +## Retrieval And Related Files + +- Add whether this file should be loaded whenever the integration is in play, only for specific task types, or on request. +- Link related files such as `capabilities-and-scopes.md`, `activation.md`, `practical-guide.md`, `quirks.md`, and `usage-patterns.md` when they exist. + ## Standing Instructions - Add durable instructions the team has confirmed. diff --git a/runneth-default/brain/integrations/_templates/practical-guide.md b/runneth-default/brain/integrations/_templates/practical-guide.md new file mode 100644 index 0000000..39aca11 --- /dev/null +++ b/runneth-default/brain/integrations/_templates/practical-guide.md @@ -0,0 +1,63 @@ +--- +type: Template +id: integrations/templates/practical-guide +title: Integration Practical Guide Template +scope: org +status: active +template_variant: source +aliases: [practical guide template, integration guide template] +--- + +# Integration Practical Guide Template + +Use this shape for the "how this actually works here" guide. This is not generic API documentation. + +```yaml +--- +type: Integration +id: integrations//practical-guide +title: Practical Guide +scope: org +status: draft +aliases: [ practical guide, how to use ] +--- +``` + +# Practical Guide + +## The One Thing To Know + +- Add the most important practical rule that would save a future teammate time. + +## Business Logic Required + +- Add required filtering, normalization, joining, attribution-window handling, or source-of-truth logic. + +## Correct Approach Vs. Naive Approach + +### + +**Why it matters:** Add what goes wrong without this pattern. + +**Naive approach:** Add the tempting but wrong or incomplete approach. + +**Correct approach:** Add the approach Runneth should use. + +## Verified Working Patterns + +- Add patterns that have been tested or confirmed in this organization. + +## Known Landmines + +- Add the highest-risk surprises for this organization, ordered by impact. + +## Community Or Team Notes + +- Add relevant community, team, or internal learnings that are specific enough to be useful later. + +## Related Files + +- `capabilities-and-scopes.md` +- `activation.md` +- `quirks.md` +- `usage-patterns.md` diff --git a/runneth-default/brain/integrations/_templates/quirks.md b/runneth-default/brain/integrations/_templates/quirks.md new file mode 100644 index 0000000..776adf7 --- /dev/null +++ b/runneth-default/brain/integrations/_templates/quirks.md @@ -0,0 +1,56 @@ +--- +type: Template +id: integrations/templates/quirks +title: Integration Quirks Template +scope: org +status: active +template_variant: source +aliases: [quirks template, integration quirks template] +--- + +# Integration Quirks Template + +Use this shape when a platform behaves unexpectedly or a customer corrects how Runneth should handle it. + +```yaml +--- +type: Integration +id: integrations//quirks +title: Quirks +scope: org +status: draft +aliases: [ quirks, gotchas] +--- +``` + +# Quirks + +## Q-001: + +**Discovered:** YYYY-MM-DD + +**Discovered by:** + +**Status:** `unhandled` | `handled-in-code` | `handled-by-warning` | `monitoring` + +**Symptom:** +What the user saw or what Runneth observed. + +**Platform behavior:** +What the platform actually does. + +**Detection signal:** +How Runneth can recognize this next time. + +**Fix or workaround:** +What should happen instead. + +**Wired into:** + +- [ ] customer integration note +- [ ] capabilities-and-scopes.md Known Constraints section +- [ ] practical-guide.md +- [ ] code, query, health check, or warning when applicable + +**Never-twice check:** +How to confirm the same symptom should not surprise the user again. diff --git a/runneth-default/brain/integrations/_templates/usage-patterns.md b/runneth-default/brain/integrations/_templates/usage-patterns.md new file mode 100644 index 0000000..f74db3b --- /dev/null +++ b/runneth-default/brain/integrations/_templates/usage-patterns.md @@ -0,0 +1,49 @@ +--- +type: Template +id: integrations/templates/usage-patterns +title: Integration Usage Patterns Template +scope: org +status: active +template_variant: source +aliases: [usage patterns template, integration usage template] +--- + +# Integration Usage Patterns Template + +Use this shape to preserve what Runneth learns from repeated use of an integration. + +```yaml +--- +type: Integration +id: integrations//usage-patterns +title: Usage Patterns +scope: org +status: draft +aliases: [ usage, working patterns] +--- +``` + +# Usage Patterns + +## + +**Last observed:** YYYY-MM-DD + +**Use frequency:** high | medium | low | unused + +**Primary users:** Add names only when the pattern is person-specific. + +**How it is actually used:** +Add the real workflow, not a generic capability summary. + +**What happens after the output:** +Add whether the result usually becomes a brief, report, Slack message, decision, follow-up query, or other action. + +**Friction observed:** +Add errors, repeated rephrasing, filters users keep adding, or places where the output misses the job. + +**Personalization signals:** +Add metric preferences, date windows, output formats, routing preferences, or recurring follow-up patterns. + +**Suggested improvement:** +Add one concrete improvement tied to observed use. diff --git a/runneth-default/brain/integrations/index.md b/runneth-default/brain/integrations/index.md index 609e027..e9a32d5 100644 --- a/runneth-default/brain/integrations/index.md +++ b/runneth-default/brain/integrations/index.md @@ -21,6 +21,23 @@ Platform-level facts about what an app is, how its API works, and which commands - Reporting preferences and recurring deliverables that depend on an integration. - Known gotchas, exclusions, and open questions to confirm with the team. +## File Shapes + +- Use `.md` for a simple lightweight integration note. +- Use `/index.md` when the integration needs a richer setup folder. +- Use `_templates/integration-map.md` for the main map. +- Use `_templates/capabilities-and-scopes.md` after an integration is connected or first used. +- Use `_templates/activation-plan.md` when Runneth has enough context to propose workflows. +- Use `_templates/practical-guide.md` for the practical "how this actually works here" layer. +- Use `_templates/quirks.md` when platform behavior surprises Runneth or a user corrects it. +- Use `_templates/usage-patterns.md` when repeated use reveals durable defaults or preferences. + +## Protocols + +- Use `_protocols/integration-types.md` to classify the integration before deep setup. +- Use `_protocols/quirks.md` when deciding how to capture gotchas and prevent repeat trust failures. +- Use `_protocols/usage-feedback.md` when repeated usage should improve defaults, routing, or person-specific context. + ## How To Add An Integration Map -Create a new file when a connected integration needs durable customer-specific instructions. Use `_templates/integration-map.md` as the starting shape, then replace placeholders with what the team has confirmed. +Create a new file or folder when a connected integration needs durable customer-specific instructions. Start with the smallest useful shape, then add companion files only when there is enough evidence to justify them. diff --git a/runneth-default/brain/integrations/slack.md b/runneth-default/brain/integrations/slack/index.md similarity index 69% rename from runneth-default/brain/integrations/slack.md rename to runneth-default/brain/integrations/slack/index.md index 8a5caa4..6b52ba6 100644 --- a/runneth-default/brain/integrations/slack.md +++ b/runneth-default/brain/integrations/slack/index.md @@ -9,7 +9,7 @@ aliases: [slack, slack channels, slack threads] # Slack -This file is for how this organization wants Runneth to use Slack. +This folder is for how this organization wants Runneth to use Slack. ## What Slack Is Used For Here @@ -20,12 +20,18 @@ This file is for how this organization wants Runneth to use Slack. - Important channels. - Channels Runneth should ask to join when relevant. - Channels that should stay out of scope. +- Channel naming conventions or routing rules. ## Reporting And Delivery Preferences - Where readouts should be posted. - Thread vs channel-root preferences. - People or teams to tag. +- Review or approval norms before posting to team-facing channels. + +## Source Of Truth Rules + +- Add when Slack should win over other sources, and when Slack should only be treated as conversation context. ## Standing Instructions diff --git a/runneth-default/instructions/integration-setup.md b/runneth-default/instructions/integration-setup.md index 137e453..8850da9 100644 --- a/runneth-default/instructions/integration-setup.md +++ b/runneth-default/instructions/integration-setup.md @@ -4,9 +4,9 @@ Platform-level integration knowledge belongs in Runneth's protected integration Before suggesting, connecting, or using an integration, check the available connection context and integration catalogue first. Use first-class/native flows when they exist, registered connected-app guidance when the app is available through the integrations catalogue, and secure secret collection for API-key or credential-backed services. -When a task depends on a connected integration, check whether there is a relevant note in `/agent/brain/integrations/` before relying on the integration for analysis, reporting, or routing. Use that note for customer-specific definitions, preferences, and gotchas. +When a task depends on a connected integration, check whether there is a relevant note or folder in `/agent/brain/integrations/` before relying on the integration for analysis, reporting, or routing. Use that customer-owned context for customer-specific definitions, preferences, and gotchas. -When a user gives standing instructions about an integration, save or update the matching file under `/agent/brain/integrations/`. Use `/agent/brain/integrations/_templates/integration-map.md` as the shape for new files when it exists. Save only durable customer-specific knowledge, such as: +When a user gives standing instructions about an integration, save or update the matching file or folder under `/agent/brain/integrations/`. Use `/agent/brain/integrations/_templates/integration-map.md` as the shape for new maps when it exists. Save only durable customer-specific knowledge, such as: - how they want the integration used - source-of-truth rules @@ -21,3 +21,15 @@ If a connected integration has no customer-specific note yet and the current tas After a user connects an integration or asks Runneth to use one for the first time, offer to create the first integration map only when it would help future work. Keep this lightweight: one useful question in context, not a setup wizard and not a repeated pitch. Do not block simple tasks on setup. If the user asks for a concrete answer and the available data is enough, answer first, then ask the one setup question only if it will improve future work. + +Use the richer setup files only when they are useful: + +- `capabilities-and-scopes.md` for what access exists, what is verified, and what is still theoretical +- `activation.md` for the setup context, source-of-truth rules, business logic, and first useful workflows +- `practical-guide.md` for the practical "how this actually works here" layer that goes beyond generic API docs +- `quirks.md` for platform surprises, corrections, and never-twice gotchas +- `usage-patterns.md` for repeated defaults, preferred metrics, date windows, outputs, and person-specific usage patterns + +Use `_protocols/integration-types.md` before deep setup so Runneth does not treat every integration as the same kind of data pipe. If one app could support different setup shapes, ask one specific clarification question before creating deep setup files. + +Use `_protocols/quirks.md` and `_protocols/usage-feedback.md` to decide what to preserve after real usage. Corrections should improve future behavior, not only the current answer. diff --git a/runneth-default/runneth-package.json b/runneth-default/runneth-package.json index 88036cf..2639954 100644 --- a/runneth-default/runneth-package.json +++ b/runneth-default/runneth-package.json @@ -2,8 +2,8 @@ "schemaVersion": 1, "id": "runneth-default", "name": "Runneth Default", - "version": "0.2.0", - "description": "Installs baseline Runneth creative strategy skills and a small customer-owned integration setup surface.", + "version": "0.3.0", + "description": "Installs baseline Runneth creative strategy skills and customer-owned integration setup templates.", "updatePolicy": "auto", "resources": [ { @@ -65,12 +65,84 @@ } }, { - "id": "slack-integration-notes", + "id": "integration-capabilities-template", "type": "seed_file", - "sourcePath": "brain/integrations/slack.md", + "sourcePath": "brain/integrations/_templates/capabilities-and-scopes.md", "target": { "root": "agent_brain", - "path": "integrations/slack.md" + "path": "integrations/_templates/capabilities-and-scopes.md" + } + }, + { + "id": "integration-activation-template", + "type": "seed_file", + "sourcePath": "brain/integrations/_templates/activation-plan.md", + "target": { + "root": "agent_brain", + "path": "integrations/_templates/activation-plan.md" + } + }, + { + "id": "integration-practical-guide-template", + "type": "seed_file", + "sourcePath": "brain/integrations/_templates/practical-guide.md", + "target": { + "root": "agent_brain", + "path": "integrations/_templates/practical-guide.md" + } + }, + { + "id": "integration-quirks-template", + "type": "seed_file", + "sourcePath": "brain/integrations/_templates/quirks.md", + "target": { + "root": "agent_brain", + "path": "integrations/_templates/quirks.md" + } + }, + { + "id": "integration-usage-patterns-template", + "type": "seed_file", + "sourcePath": "brain/integrations/_templates/usage-patterns.md", + "target": { + "root": "agent_brain", + "path": "integrations/_templates/usage-patterns.md" + } + }, + { + "id": "integration-types-protocol", + "type": "seed_file", + "sourcePath": "brain/integrations/_protocols/integration-types.md", + "target": { + "root": "agent_brain", + "path": "integrations/_protocols/integration-types.md" + } + }, + { + "id": "integration-quirks-protocol", + "type": "seed_file", + "sourcePath": "brain/integrations/_protocols/quirks.md", + "target": { + "root": "agent_brain", + "path": "integrations/_protocols/quirks.md" + } + }, + { + "id": "integration-usage-feedback-protocol", + "type": "seed_file", + "sourcePath": "brain/integrations/_protocols/usage-feedback.md", + "target": { + "root": "agent_brain", + "path": "integrations/_protocols/usage-feedback.md" + } + }, + { + "id": "slack-integration-map", + "type": "seed_file", + "sourcePath": "brain/integrations/slack/index.md", + "target": { + "root": "agent_brain", + "path": "integrations/slack/index.md" } } ] diff --git a/runneth-package-index.json b/runneth-package-index.json index 64f19eb..fedb3df 100644 --- a/runneth-package-index.json +++ b/runneth-package-index.json @@ -1,12 +1,12 @@ { "schemaVersion": 1, - "indexRevision": "runneth-default-0.2.0", + "indexRevision": "runneth-default-0.3.0", "packages": [ { "id": "runneth-default", "name": "Runneth Default", - "description": "Baseline Runneth creative strategy skills and a small customer-owned integration setup surface.", - "version": "0.2.0", + "description": "Baseline Runneth creative strategy skills and customer-owned integration setup templates.", + "version": "0.3.0", "packageManagerVersion": 1, "categories": [ "baseline" From a32a6db577d52a535d52da2745264604c6369289 Mon Sep 17 00:00:00 2001 From: Ioana Hayman Date: Tue, 16 Jun 2026 21:48:39 -0400 Subject: [PATCH 4/4] feat(runneth-apps): seed customer glossary templates --- .../brain/glossary/_templates/ad-states.md | 36 ++++++++ .../brain/glossary/_templates/attribution.md | 37 ++++++++ .../glossary/_templates/channel-roles.md | 37 ++++++++ .../glossary/_templates/funnel-stages.md | 36 ++++++++ .../glossary/_templates/naming-conventions.md | 37 ++++++++ .../brain/glossary/_templates/primary-kpi.md | 35 ++++++++ .../brain/glossary/_templates/voice-rules.md | 37 ++++++++ .../glossary/_templates/winner-definition.md | 37 ++++++++ runneth-default/brain/glossary/index.md | 31 +++++++ .../instructions/customer-glossary.md | 9 ++ runneth-default/runneth-package.json | 90 ++++++++++++++++++- runneth-package-index.json | 6 +- 12 files changed, 423 insertions(+), 5 deletions(-) create mode 100644 runneth-default/brain/glossary/_templates/ad-states.md create mode 100644 runneth-default/brain/glossary/_templates/attribution.md create mode 100644 runneth-default/brain/glossary/_templates/channel-roles.md create mode 100644 runneth-default/brain/glossary/_templates/funnel-stages.md create mode 100644 runneth-default/brain/glossary/_templates/naming-conventions.md create mode 100644 runneth-default/brain/glossary/_templates/primary-kpi.md create mode 100644 runneth-default/brain/glossary/_templates/voice-rules.md create mode 100644 runneth-default/brain/glossary/_templates/winner-definition.md create mode 100644 runneth-default/brain/glossary/index.md create mode 100644 runneth-default/instructions/customer-glossary.md diff --git a/runneth-default/brain/glossary/_templates/ad-states.md b/runneth-default/brain/glossary/_templates/ad-states.md new file mode 100644 index 0000000..f6031be --- /dev/null +++ b/runneth-default/brain/glossary/_templates/ad-states.md @@ -0,0 +1,36 @@ +--- +type: Template +id: glossary/templates/ad-states +title: Ad States Template +scope: org +status: active +template_variant: source +aliases: [ad states template, creative state template] +--- + +# Ad States Template + +Use this to seed and confirm how the team labels creative lifecycle states. + +## Seed From + +- Spend threshold. +- Winner definition. +- Naming conventions. +- Customer instructions about testing, scaling, evergreen, paused, or graveyard states. + +## Confirm With Team + +Ask whether the seeded state labels and entry or exit criteria are right. + +## Write + +Create `/agent/brain/glossary/ad-states.json` or another customer-approved glossary file. Mark it as seeded until confirmed. + +## Fields To Capture + +- State names. +- Entry criteria. +- Exit criteria. +- Source fields or naming tokens. +- Confidence and confirmation status. diff --git a/runneth-default/brain/glossary/_templates/attribution.md b/runneth-default/brain/glossary/_templates/attribution.md new file mode 100644 index 0000000..cafaab6 --- /dev/null +++ b/runneth-default/brain/glossary/_templates/attribution.md @@ -0,0 +1,37 @@ +--- +type: Template +id: glossary/templates/attribution +title: Attribution Template +scope: org +status: active +template_variant: source +aliases: [attribution template, attribution setup template] +--- + +# Attribution Template + +Use this to seed and confirm how conversion reads should be attributed. + +## Seed From + +- Motion workspace goal attribution windows. +- Paid strategy brief. +- Integration maps for Northbeam, Triple Whale, or another attribution source. +- Customer setup calls or saved reporting preferences. + +## Confirm With Team + +Ask whether conversions should be read from the seeded source and click/view windows. + +## Write + +Create `/agent/brain/glossary/attribution.json` or another customer-approved glossary file. Mark it as seeded until confirmed. + +## Fields To Capture + +- Source of truth. +- Click attribution window. +- View attribution window. +- Metric mapping. +- Known source discrepancies. +- Confidence and confirmation status. diff --git a/runneth-default/brain/glossary/_templates/channel-roles.md b/runneth-default/brain/glossary/_templates/channel-roles.md new file mode 100644 index 0000000..4fc5396 --- /dev/null +++ b/runneth-default/brain/glossary/_templates/channel-roles.md @@ -0,0 +1,37 @@ +--- +type: Template +id: glossary/templates/channel-roles +title: Channel Roles Template +scope: org +status: active +template_variant: source +aliases: [channel roles template, channel KPI template] +--- + +# Channel Roles Template + +Use this to seed and confirm what each connected channel is for. + +## Seed From + +- Connected integrations. +- Paid strategy briefs. +- Cross-channel strategy notes. +- Customer setup notes. + +## Confirm With Team + +Ask whether the seeded role for each channel is correct. + +## Write + +Create `/agent/brain/glossary/channel-roles.json` or another customer-approved glossary file. Mark it as seeded until confirmed. + +## Fields To Capture + +- Channel name. +- Role in the mix. +- Primary KPI or KPI override. +- Source of truth. +- Questions that should route to this channel. +- Confidence and confirmation status. diff --git a/runneth-default/brain/glossary/_templates/funnel-stages.md b/runneth-default/brain/glossary/_templates/funnel-stages.md new file mode 100644 index 0000000..d72db21 --- /dev/null +++ b/runneth-default/brain/glossary/_templates/funnel-stages.md @@ -0,0 +1,36 @@ +--- +type: Template +id: glossary/templates/funnel-stages +title: Funnel Stages Template +scope: org +status: active +template_variant: source +aliases: [funnel stages template, prospecting retargeting template] +--- + +# Funnel Stages Template + +Use this to seed and confirm how the team detects funnel stages. + +## Seed From + +- Naming conventions. +- Campaign objectives. +- Audience setup. +- Paid strategy brief. + +## Confirm With Team + +Ask whether Runneth should split the funnel using the seeded stage names and detection rules. + +## Write + +Create `/agent/brain/glossary/funnel-stages.json` or another customer-approved glossary file. Mark it as seeded until confirmed. + +## Fields To Capture + +- Stage names. +- Detection rules. +- Campaign or audience signals. +- KPI overrides by stage. +- Confidence and confirmation status. diff --git a/runneth-default/brain/glossary/_templates/naming-conventions.md b/runneth-default/brain/glossary/_templates/naming-conventions.md new file mode 100644 index 0000000..5fb54d9 --- /dev/null +++ b/runneth-default/brain/glossary/_templates/naming-conventions.md @@ -0,0 +1,37 @@ +--- +type: Template +id: glossary/templates/naming-conventions +title: Naming Conventions Template +scope: org +status: active +template_variant: source +aliases: [naming conventions template, ad naming template] +--- + +# Naming Conventions Template + +Use this to seed and confirm how names map to business meaning. + +## Seed From + +- Recent campaign, ad set, and ad names. +- Motion filter reference. +- Paid strategy brief. +- Customer setup notes. + +## Confirm With Team + +Show the inferred pattern and ask the team to correct any token meanings. + +## Write + +Create `/agent/brain/glossary/naming-conventions.json` or another customer-approved glossary file. Mark it as seeded until confirmed. + +## Fields To Capture + +- Pattern. +- Token positions. +- Token meanings. +- Funnel, product, audience, offer, or test mappings. +- Known exceptions. +- Confidence and confirmation status. diff --git a/runneth-default/brain/glossary/_templates/primary-kpi.md b/runneth-default/brain/glossary/_templates/primary-kpi.md new file mode 100644 index 0000000..25b2493 --- /dev/null +++ b/runneth-default/brain/glossary/_templates/primary-kpi.md @@ -0,0 +1,35 @@ +--- +type: Template +id: glossary/templates/primary-kpi +title: Primary KPI Template +scope: org +status: active +template_variant: source +aliases: [primary KPI template, KPI setup template] +--- + +# Primary KPI Template + +Use this to seed and confirm the metric the account should be graded on. + +## Seed From + +- Motion workspace goal. +- Paid strategy brief when it provides a validated metric mapping. +- Alignment notes or setup calls that name what success means. + +## Confirm With Team + +Ask whether Runneth should grade the account on the seeded metric and direction. + +## Write + +Create `/agent/brain/glossary/primary-kpi.json` or another customer-approved glossary file. Mark it as seeded until confirmed. + +## Fields To Capture + +- Display name. +- Metric key or source field. +- Direction: higher is better or lower is better. +- Source of truth. +- Confidence and confirmation status. diff --git a/runneth-default/brain/glossary/_templates/voice-rules.md b/runneth-default/brain/glossary/_templates/voice-rules.md new file mode 100644 index 0000000..c3e9063 --- /dev/null +++ b/runneth-default/brain/glossary/_templates/voice-rules.md @@ -0,0 +1,37 @@ +--- +type: Template +id: glossary/templates/voice-rules +title: Voice Rules Template +scope: org +status: active +template_variant: source +aliases: [voice rules template, copy rules template] +--- + +# Voice Rules Template + +Use this to seed and confirm copy rules that should apply to hooks, briefs, and creative output. + +## Seed From + +- Motion brand context. +- Brand audit. +- Website or ad copy samples. +- Customer feedback about tone, banned words, or legal guardrails. + +## Confirm With Team + +Ask whether the seeded do, do-not, and banned-word rules are right. + +## Write + +Create `/agent/brain/glossary/voice-rules.json` or another customer-approved glossary file. Mark it as seeded until confirmed. + +## Fields To Capture + +- Do rules. +- Do-not rules. +- Banned words or claims. +- Required phrases or disclaimers. +- Scope, such as all copy, paid social only, or briefs only. +- Confidence and confirmation status. diff --git a/runneth-default/brain/glossary/_templates/winner-definition.md b/runneth-default/brain/glossary/_templates/winner-definition.md new file mode 100644 index 0000000..4b2dc3e --- /dev/null +++ b/runneth-default/brain/glossary/_templates/winner-definition.md @@ -0,0 +1,37 @@ +--- +type: Template +id: glossary/templates/winner-definition +title: Winner Definition Template +scope: org +status: active +template_variant: source +aliases: [winner definition template, winning creative template] +--- + +# Winner Definition Template + +Use this to seed and confirm the bar for calling a creative a winner or loser. + +## Seed From + +- Paid strategy brief. +- Spend threshold. +- Primary KPI. +- Repeated customer instructions about what counts as a winner. + +## Confirm With Team + +Ask whether the seeded winner criteria and spend floor are right. + +## Write + +Create `/agent/brain/glossary/winner-definition.json` or another customer-approved glossary file. Mark it as seeded until confirmed. + +## Fields To Capture + +- Primary metric. +- Minimum spend or data threshold. +- Winner criteria. +- Loser or watch criteria. +- Exceptions by channel, campaign type, or funnel stage. +- Confidence and confirmation status. diff --git a/runneth-default/brain/glossary/index.md b/runneth-default/brain/glossary/index.md new file mode 100644 index 0000000..4af139b --- /dev/null +++ b/runneth-default/brain/glossary/index.md @@ -0,0 +1,31 @@ +--- +type: Reference +id: glossary +title: Customer Glossary +scope: org +status: active +aliases: [glossary, customer definitions, KPI setup, attribution setup] +--- + +# Customer Glossary + +Use this folder for team-confirmed definitions that make analysis, briefs, and reports consistent. + +These files are customer-owned. The templates define the shape, but the actual values should come from the customer's setup, Motion data, connected integrations, saved strategy, or direct confirmation from the team. + +## Canonical Terms + +- `primary-kpi`: the metric the account is graded on and whether higher or lower is better. +- `attribution`: click/view windows and source of truth for conversion reads. +- `winner-definition`: the bar for calling a creative a winner or loser. +- `ad-states`: how the team distinguishes test, scaling, evergreen, paused, and similar states. +- `naming-conventions`: how campaign, ad set, and ad names map to funnel, product, audience, offer, or test. +- `funnel-stages`: how prospecting, retargeting, retention, and other stages are detected. +- `voice-rules`: copy rules, banned words, and tone constraints. +- `channel-roles`: what each connected channel is for and whether it has a KPI override. + +## How To Use + +Start with a template under `_templates/`, seed the value from available evidence, and mark it as unconfirmed until the team verifies it. Do not treat an inferred glossary term as locked. + +Glossary files should be referenced by strategy, reporting, integration, and brief files rather than duplicating the same definition in multiple places. diff --git a/runneth-default/instructions/customer-glossary.md b/runneth-default/instructions/customer-glossary.md new file mode 100644 index 0000000..ec2bec6 --- /dev/null +++ b/runneth-default/instructions/customer-glossary.md @@ -0,0 +1,9 @@ +Use `/agent/brain/glossary/` for customer-owned definitions that should make Runneth's analysis and creative work consistent. + +Glossary files are not generic strategy docs. They are compact definitions the team has seeded or confirmed, such as primary KPI, attribution windows, winner criteria, naming conventions, funnel stages, voice rules, ad states, and channel roles. + +When a user gives durable instructions that define one of these terms, save or update the relevant customer-owned glossary file. When the value is inferred from Motion data, a connected integration, a paid strategy brief, or a setup transcript, mark it as seeded until the team confirms it. + +Use glossary definitions to override generic defaults only when they are loaded and relevant to the current workspace, account, channel, or integration. Do not invent a glossary override from vague memory. + +Do not duplicate the same definition across strategy, reporting, integration, and brief files. Reference the glossary term instead when possible. diff --git a/runneth-default/runneth-package.json b/runneth-default/runneth-package.json index 2639954..1af4e7a 100644 --- a/runneth-default/runneth-package.json +++ b/runneth-default/runneth-package.json @@ -2,8 +2,8 @@ "schemaVersion": 1, "id": "runneth-default", "name": "Runneth Default", - "version": "0.3.0", - "description": "Installs baseline Runneth creative strategy skills and customer-owned integration setup templates.", + "version": "0.4.0", + "description": "Installs baseline Runneth creative strategy skills and customer-owned setup templates.", "updatePolicy": "auto", "resources": [ { @@ -46,6 +46,92 @@ "type": "package_instruction", "sourcePath": "instructions/integration-setup.md" }, + { + "id": "customer-glossary", + "type": "package_instruction", + "sourcePath": "instructions/customer-glossary.md" + }, + { + "id": "customer-glossary-index", + "type": "seed_file", + "sourcePath": "brain/glossary/index.md", + "target": { + "root": "agent_brain", + "path": "glossary/index.md" + } + }, + { + "id": "primary-kpi-template", + "type": "seed_file", + "sourcePath": "brain/glossary/_templates/primary-kpi.md", + "target": { + "root": "agent_brain", + "path": "glossary/_templates/primary-kpi.md" + } + }, + { + "id": "attribution-template", + "type": "seed_file", + "sourcePath": "brain/glossary/_templates/attribution.md", + "target": { + "root": "agent_brain", + "path": "glossary/_templates/attribution.md" + } + }, + { + "id": "winner-definition-template", + "type": "seed_file", + "sourcePath": "brain/glossary/_templates/winner-definition.md", + "target": { + "root": "agent_brain", + "path": "glossary/_templates/winner-definition.md" + } + }, + { + "id": "ad-states-template", + "type": "seed_file", + "sourcePath": "brain/glossary/_templates/ad-states.md", + "target": { + "root": "agent_brain", + "path": "glossary/_templates/ad-states.md" + } + }, + { + "id": "naming-conventions-template", + "type": "seed_file", + "sourcePath": "brain/glossary/_templates/naming-conventions.md", + "target": { + "root": "agent_brain", + "path": "glossary/_templates/naming-conventions.md" + } + }, + { + "id": "funnel-stages-template", + "type": "seed_file", + "sourcePath": "brain/glossary/_templates/funnel-stages.md", + "target": { + "root": "agent_brain", + "path": "glossary/_templates/funnel-stages.md" + } + }, + { + "id": "voice-rules-template", + "type": "seed_file", + "sourcePath": "brain/glossary/_templates/voice-rules.md", + "target": { + "root": "agent_brain", + "path": "glossary/_templates/voice-rules.md" + } + }, + { + "id": "channel-roles-template", + "type": "seed_file", + "sourcePath": "brain/glossary/_templates/channel-roles.md", + "target": { + "root": "agent_brain", + "path": "glossary/_templates/channel-roles.md" + } + }, { "id": "integration-notes-index", "type": "seed_file", diff --git a/runneth-package-index.json b/runneth-package-index.json index fedb3df..919dabf 100644 --- a/runneth-package-index.json +++ b/runneth-package-index.json @@ -1,12 +1,12 @@ { "schemaVersion": 1, - "indexRevision": "runneth-default-0.3.0", + "indexRevision": "runneth-default-0.4.0", "packages": [ { "id": "runneth-default", "name": "Runneth Default", - "description": "Baseline Runneth creative strategy skills and customer-owned integration setup templates.", - "version": "0.3.0", + "description": "Baseline Runneth creative strategy skills and customer-owned setup templates.", + "version": "0.4.0", "packageManagerVersion": 1, "categories": [ "baseline"