Integration and API Spec

Integration and API Spec

New Initiative Scoping and Approval

Google Forms acts as the intake trigger (Agent 1) and as the reviewer assessment submission point (Agent 2). Two separate forms are required: one for proposer intake and one for reviewer structured feedback. Both are connected via the Google Forms API through the orchestration layer.

// Input
GET /v1/forms/{INTAKE_FORM_ID}/responses
  param: filter = timestamp gt {last_poll_timestamp}
// Output
responses[].answers[questionId].textAnswers.answers[0].value
responses[].responseId  -> used as external reference key

Notion stores the structured scoping record for each initiative and is updated at two points: when the Scoping and Routing Agent creates the page, and when the reviewer outcome is written back. A locked page template in a dedicated Notion database is the source of structure for all scoping records.

// Create page (Agent 2)
POST /v1/pages
  parent.database_id = NOTION_SCOPING_DB_ID
  properties: { Initiative_Title, Reference_ID, Status='Pending Review',
    Reviewer_Name, Review_Deadline, Budget_Estimate }
// Update page with review outcome (Agent 2, webhook poll)
PATCH /v1/pages/{page_id}
  properties: { Status, Reviewer_Recommendation }
// Output
page.id  -> stored as NOTION_PAGE_ID in run context
page.url -> included in Slack notification to reviewer

Google Sheets acts as the central initiative pipeline tracker. Agent 2 writes a new row on each validated submission. Agent 3 reads the tracker daily to identify initiatives awaiting a leadership decision and writes the final decision status once recorded in Notion.

// Append new row (Agent 2)
POST /v4/spreadsheets/{SHEETS_TRACKER_ID}/values/{TRACKER_SHEET_NAME}!A:K:append
  values: [ [Reference_ID, Proposer_Name, Submission_Date,
    Initiative_Title, Category, Budget_Estimate,
    Reviewer_Name, Review_Deadline, Status,
    Notion_Page_URL, Leadership_Decision] ]
// Read pending rows (Agent 3)
GET /v4/spreadsheets/{SHEETS_TRACKER_ID}/values/{TRACKER_SHEET_NAME}!A:K
  filter client-side: Status IN ('Under Review', 'Revision Requested')
  and Reviewer_Recommendation IN ('Approve', 'Revise')

Slack is used by Agent 1 to notify the proposer of any incomplete fields in their submission, and by Agent 2 to notify the assigned reviewer with a link to the Notion scoping page and the review deadline. A Slack app with a bot token is required. The bot must be invited to all channels used for notifications.

// Agent 1: gap notification to proposer
POST https://slack.com/api/chat.postMessage
  token: SLACK_BOT_TOKEN
  channel: {proposer_slack_user_id} OR SLACK_PROPOSER_FALLBACK_CHANNEL
  blocks: [ section(missing_fields_list), section(resubmit_link) ]
// Agent 2: reviewer notification
POST https://slack.com/api/chat.postMessage
  token: SLACK_BOT_TOKEN
  channel: {reviewer_slack_user_id}
  blocks: [ section(initiative_title, reference_id),
    section(notion_page_url), section(review_deadline) ]

Gmail is used exclusively by Agent 3 to send the daily leadership approval digest. The digest is a formatted HTML email sent to the founder or CEO each weekday morning at 08:00 AM if at least one initiative is pending a leadership decision. The automation sends via the Gmail API using a designated sender account.

// Agent 3: send digest
POST https://gmail.googleapis.com/gmail/v1/users/me/messages/send
  Authorization: Bearer {access_token from GMAIL_SENDER_REFRESH_TOKEN}
  body.raw: base64url({
    From: GMAIL_SENDER_ADDRESS,
    To: GMAIL_DIGEST_RECIPIENT,
    Subject: 'Initiative Decisions Pending - {digest_date}',
    Content-Type: text/html; charset=utf-8,
    body: rendered(GMAIL_DIGEST_TEMPLATE, { initiative_rows,
      total_budget_pending, digest_date })
  })

# Google Workspace (shared service account)
GOOGLE_SERVICE_ACCOUNT_JSON       = { ... }   # full service account key JSON
GOOGLE_DELEGATED_USER_EMAIL       = 'automation@[YourCompany.com]'

# Google Forms
INTAKE_FORM_ID                    = 'string'  # Google Form ID for proposer intake
REVIEWER_FORM_ID                  = 'string'  # Google Form ID for reviewer assessment
FORMS_LAST_POLL_TIMESTAMP         = 'ISO8601' # updated after each successful poll
FORMS_WEBHOOK_SECRET              = 'string'  # shared secret if Apps Script webhook used

# Notion
NOTION_INTEGRATION_TOKEN          = 'secret_xxxxxxxxxxxxxxxxxxxx'
NOTION_SCOPING_DB_ID              = 'string'  # Notion database ID for scoping records
NOTION_TEMPLATE_PAGE_ID           = 'string'  # ID of the locked scoping page template

# Google Sheets
SHEETS_TRACKER_ID                 = 'string'  # Spreadsheet ID
TRACKER_SHEET_NAME                = 'Initiative Tracker'
TRACKER_DATA_RANGE                = 'Initiative Tracker!A:K'

# Slack
SLACK_BOT_TOKEN                   = 'xoxb-xxxxxxxxxxxx-xxxxxxxxxxxx-xxxxxxxxxxxxxxxxxxxxxxxx'
SLACK_PROPOSER_FALLBACK_CHANNEL   = '#initiative-submissions'

# Gmail
GMAIL_SENDER_ADDRESS              = 'initiatives@[YourCompany.com]'
GMAIL_DIGEST_RECIPIENT            = 'founder@[YourCompany.com]'
GMAIL_SENDER_REFRESH_TOKEN        = 'string'  # OAuth refresh token for sender account
GMAIL_DIGEST_TEMPLATE             = 'string'  # HTML template with {{placeholders}}

# Routing and sequencing
REVIEWER_ROUTING_TABLE            = '{"Product": {"name": "...", "email": "..."},
                                      "Operations": {"name": "...", "email": "..."},
                                      "Finance": {"name": "...", "email": "..."}}'
INITIATIVE_SEQUENCE_COUNTER       = 1         # integer, incremented atomically
DIGEST_TIMEZONE                   = 'America/New_York'  # adjust to business timezone

# Validation thresholds
MIN_WORD_COUNT_STRATEGIC_RATIONALE = 30       # minimum words required in rationale field
MIN_WORD_COUNT_INITIATIVE_TITLE    = 3        # minimum words required in title field