abdullahbeam/add-integration

🎯 Onboarding Awareness (CHECK BEFORE STARTING)

Before building an integration, AI MUST check stats.pending_onboarding for learn_integrations:

Pre-Flight Check (RECOMMENDED)

Check if learn_integrations is in stats.pending_onboarding. If present:

💡 Before building your first integration, would you like a quick 10-minute
tutorial on how Nexus integrations work? It covers:
- What MCP (Model Context Protocol) is
- Available integration patterns
- When to use integrations vs other approaches

Say 'learn integrations' to start the tutorial, or 'skip' to build directly.

If user says 'skip': Proceed with integration building but add this note at the end:

💡 Tip: Run 'learn integrations' later to understand the integration ecosystem.

If learn_integrations NOT in pending_onboarding: Proceed normally without suggestion.

Context Awareness

If user mentions connecting to external tools but learn_integrations is pending:

• Gently suggest learning first if they seem unfamiliar with MCP concepts
• Skip suggestion if they clearly know what they're doing (e.g., mention specific API endpoints)

---

Add Integration

Build complete API integrations following the master/connect/specialized pattern.

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ ⚠️ CRITICAL: MUST LOAD create-project SKILL ⚠️

MANDATORY: In Step 4, load the create-project skill:

python 00-system/core/nexus-loader.py --skill create-project

Then follow its workflow to create the integration project. ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Purpose

The add-integration skill transforms API documentation into a complete, production-ready integration. It:

1. Discovers available API endpoints via web search
2. Presents endpoints for user selection
3. Plans the integration architecture
4. Creates a project for implementation (via create-project skill)

Architecture Pattern: See references/integration-architecture.md

Time Estimate: 15-25 minutes (planning phase)

---

Workflow Overview

┌─────────────────────────────────────────────────────────┐
│                   ADD INTEGRATION                        │
├─────────────────────────────────────────────────────────┤
│  Step 1: Initialize TodoList                            │
│  Step 2: Ask which service to integrate                 │
│  Step 3: Web search for API documentation               │
│  Step 4: Create integration project (saves progress)    │
│  Step 5: Parse and present available endpoints          │
│  Step 6: User selects endpoints to implement            │
│  Step 7: Gather authentication details & finalize       │
│  Step 8: Prompt user to close session & start project   │
└─────────────────────────────────────────────────────────┘

---

Workflow

Step 1: Initialize TodoList

Create TodoWrite with all workflow steps:

- [ ] Ask which service to integrate
- [ ] Search for API documentation
- [ ] Create integration project
- [ ] Parse and present endpoints
- [ ] User selects endpoints
- [ ] Gather authentication details & finalize
- [ ] Prompt close session

Mark tasks complete as you finish each step.

---

Step 2: Interactive Service Selection

Display:

Let's build a new integration! 🔌

Which service would you like to integrate?

Examples:
• HubSpot (CRM, marketing automation)
• Stripe (payments, subscriptions)
• Twilio (SMS, voice, messaging)
• Airtable (databases, spreadsheets)
• Slack (messaging, notifications)
• GitHub (repos, issues, PRs)
• Linear (issue tracking)
• Notion (notes, databases)
• Or any service with a REST API

Tell me the service name:

Wait for user response.

Capture and normalize:

• Store service name (e.g., "HubSpot")
• Generate slug (e.g., "hubspot")
• Note any specific features mentioned

---

Step 3: Web Search for API Documentation

CRITICAL: Use WebSearch to find current API documentation

AI Action:
1. WebSearch: "{service_name} REST API documentation endpoints"
2. WebSearch: "{service_name} API reference authentication"
3. Identify official API docs URL
4. Use WebFetch on official docs to get endpoint details

Search targets:

• Official API documentation
• Authentication methods
• Available endpoints by category
• Rate limits and requirements

Display progress:

Searching for {Service} API documentation...

Found:
• Official docs: {url}
• API version: {version}
• Auth type: {oauth2/api_key/bearer}

---

Step 4: Create Integration Project

Create project immediately after discovering API docs to save progress.

Load the create-project skill:

python 00-system/core/nexus-loader.py --skill create-project

Follow its workflow with project name: "{Service Name} Integration"

This creates:

02-projects/{next_id}-{service_slug}-integration/
├── 01-planning/
│   ├── overview.md          # Project metadata (template)
│   ├── plan.md              # Approach and decisions (template)
│   └── steps.md             # Implementation checklist (template)
├── 02-resources/            # For integration-config.json
├── 03-working/
└── 04-outputs/

After project is created, update the generated files with integration-specific content.

Initial overview.md:

---
id: {next_id}-{service_slug}-integration
name: {Service Name} Integration
status: PLANNING
description: Load when user mentions '{service_slug} integration', 'implement {service_slug}', 'build {service_slug} skills'
created: {today}
---

# {Service Name} Integration

Build complete {Service Name} integration following the master/connect/specialized pattern.

## Discovery

- **Service**: {Service Name}
- **API Docs**: {api_docs_url}
- **Auth Type**: {detected_auth_type}
- **Base URL**: {detected_base_url}

## Status

Endpoints: Pending selection
Configuration: In progress

## References

- Pattern: See 00-system/skills/system/add-integration/references/integration-architecture.md

Initial integration-config.json (partial, will be updated):

{
  "service_name": "{Service Name}",
  "service_slug": "{service_slug}",
  "base_url": "{detected_base_url}",
  "auth_type": "{detected_auth_type}",
  "api_docs_url": "{api_docs_url}",
  "endpoints": [],
  "status": "planning",
  "created": "{timestamp}",
  "created_by": "add-integration skill"
}

Display:

Project created: 02-projects/{id}-{service_slug}-integration/

Your progress is now being saved. Let's continue with endpoint selection...

---

Step 5: Parse and Present Endpoints

After fetching API docs, categorize and present.

Save discovered endpoints to project (02-resources/discovered-endpoints.json):

{
  "discovered_at": "{timestamp}",
  "source": "{api_docs_url}",
  "categories": [
    {
      "name": "Authentication",
      "endpoints": [...]
    },
    {
      "name": "Contacts",
      "endpoints": [...]
    }
  ],
  "total_count": {N}
}

Display to user:

I found {N} API endpoints for {Service}:

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
AUTHENTICATION
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
  [1] POST /oauth/token - Get access token
  [2] POST /oauth/refresh - Refresh token

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
{CATEGORY 1} (e.g., CONTACTS)
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
  [3] GET /contacts - List all contacts
  [4] GET /contacts/{id} - Get contact by ID
  [5] POST /contacts - Create contact
  [6] PATCH /contacts/{id} - Update contact
  [7] DELETE /contacts/{id} - Delete contact

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
{CATEGORY 2} (e.g., DEALS)
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
  [8] GET /deals - List deals
  [9] POST /deals - Create deal
  ...

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Which endpoints do you want to implement?

Options:
• "all" - Implement everything ({N} endpoints)
• "1,3,5,8" - Select by number
• "contacts, deals" - Select by category
• "core" - Essential CRUD operations only

Wait for user response.

---

Step 6: User Selects Endpoints

Process user selection:

• "all" → Select all endpoints
• "1,3,5,8" → Select by number
• "contacts, deals" → Select by category name
• "core" → Select GET/POST for main resources

Update integration-config.json with selected endpoints:

{
  "endpoints": [
    {
      "name": "List Contacts",
      "slug": "list-contacts",
      "method": "GET",
      "path": "/contacts",
      "description": "Retrieve all contacts",
      "triggers": ["list contacts", "get contacts", "show contacts"]
    },
    ...
  ]
}

Display confirmation:

Selected {N} endpoints for implementation:
• List Contacts (GET /contacts)
• Create Contact (POST /contacts)
• ...

Saved to project. Now let's confirm the authentication setup...

---

Step 7: Gather Authentication Details & Finalize Project

Based on API docs discovered:

Authentication Setup
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

{Service} uses {auth_type} authentication.

To set up:
{auth_instructions from API docs}

I'll need this info for the integration config:

1. API Base URL: {detected_base_url}
   Is this correct? (or provide alternative)

2. Auth type: {oauth2/api_key/bearer}
   Confirm or correct

3. Environment variable name suggestion:
   {SERVICE_SLUG}_API_KEY

   Okay? Or suggest different name

Wait for user confirmation/corrections.

Finalize project files:

1. Update integration-config.json with confirmed values:

{
  "service_name": "{Service Name}",
  "service_slug": "{service_slug}",
  "base_url": "{confirmed_base_url}",
  "auth_type": "{confirmed_auth_type}",
  "env_key": "{ENV_KEY}",
  "api_docs_url": "{api_docs_url}",
  "endpoints": [...],
  "status": "ready",
  "created": "{timestamp}",
  "created_by": "add-integration skill"
}

2. Update overview.md with final scope:

---
id: {next_id}-{service_slug}-integration
name: {Service Name} Integration
status: PLANNING
description: Load when user mentions '{service_slug} integration', 'implement {service_slug}', 'build {service_slug} skills'
created: {today}
---

# {Service Name} Integration

Build complete {Service Name} integration following the master/connect/specialized pattern.

## Scope

- **Service**: {Service Name}
- **Base URL**: {base_url}
- **Auth Type**: {auth_type}
- **Endpoints**: {count} selected

## Architecture

Will create:
- `{service_slug}-master/` - Shared resources
- `{service_slug}-connect/` - Meta-skill entry point
- `{service_slug}-{operation}/` - One skill per endpoint

## References

- API Docs: {api_docs_url}
- Pattern: See 00-system/skills/system/add-integration/references/integration-architecture.md

3. Generate steps.md with implementation checklist:

# Implementation Steps

## Phase 1: Setup Master Skill
- [ ] Create {service_slug}-master/ directory structure
- [ ] Generate {service_slug}_client.py from template
- [ ] Generate check_{service_slug}_config.py
- [ ] Generate setup_{service_slug}.py wizard
- [ ] Create references/setup-guide.md
- [ ] Create references/api-reference.md
- [ ] Create references/error-handling.md
- [ ] Create references/authentication.md

## Phase 2: Setup Connect Skill
- [ ] Create {service_slug}-connect/ directory
- [ ] Generate SKILL.md with routing table
- [ ] Map workflows to endpoints

## Phase 3: Create Operation Skills
{for each selected endpoint:}
- [ ] Create {service_slug}-{endpoint_slug}/ skill
- [ ] Generate SKILL.md with API reference
- [ ] Generate {endpoint_slug}.py script

## Phase 4: Test & Validate
- [ ] Run config check script
- [ ] Test authentication flow
- [ ] Test each endpoint script
- [ ] Verify error handling

## Phase 5: Documentation
- [ ] Update master SKILL.md with all skills
- [ ] Document any service-specific quirks
- [ ] Add usage examples

Display confirmation:

Project Finalized!
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

📁 02-projects/{id}-{service_slug}-integration/

This project contains:
• Full implementation plan in steps.md
• Configuration saved in integration-config.json
• {N} endpoints ready to implement

The implementation will create:
• {service_slug}-master/ (shared resources)
• {service_slug}-connect/ (meta-skill)
• {count} operation skills

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

---

Step 8: Prompt Close Session & Start Implementation

Final message:

Integration planning complete! 🎉

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
NEXT STEPS
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

1. Say "done" to close this session
   (This saves your planning work)

2. Start a new session

3. Say "work on {service_slug} integration"
   (This will execute the implementation project)

The project will guide you through:
• Creating all skill folders
• Generating scripts from templates
• Setting up authentication
• Testing each endpoint

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Ready to close this session? Say "done"

Wait for user to say "done" → Triggers close-session skill

---

Project Execution Notes

When the user returns and says "work on {service} integration", the execute-project skill will:

1. Load the integration-config.json
2. Run scaffold_integration.py with the config:

   python 00-system/skills/system/add-integration/scripts/scaffold_integration.py \
     --config 02-projects/{id}-{service_slug}-integration/02-resources/integration-config.json
   

3. Check off steps.md tasks as completed
4. Guide through testing and validation

---

Templates & Scripts

Templates (in templates/)

• master-skill.md.template - Master SKILL.md
• connect-skill.md.template - Connect SKILL.md
• operation-skill.md.template - Operation SKILL.md
• api-client.py.template - API client class
• config-check.py.template - Config validator
• setup-wizard.py.template - Setup wizard
• operation-script.py.template - Operation script
• references/*.template - Reference documents

Scripts (in scripts/)

• scaffold_integration.py - Main scaffolding script

---

Error Handling

Web Search Fails

I couldn't find official API documentation for {Service}.

Options:
1. Provide the API docs URL directly
2. Tell me the base URL and auth type manually
3. Try a different service name

What would you like to do?

No Endpoints Found

I found {Service} docs but couldn't parse specific endpoints.

Let me try:
1. Fetching a different docs page
2. You provide endpoint list manually

Which approach?

User Cancels

No problem! Integration planning cancelled.

Your progress was not saved. Run "add integration"
again when you're ready.

---

Notes

Why projects?

• Integration implementation is multi-step work (project)
• Planning is reusable (skill handles discovery)
• Separates planning from execution

Why web search?

• APIs change frequently
• Ensures current endpoint info
• Discovers auth requirements automatically

Pattern consistency:

• All integrations follow same architecture
• Matches existing Beam integration
• Templates ensure quality

---

References

• Integration Architecture - The pattern explained
• MCP Introduction - What MCP is
• MCP Setup Guide - Manual MCP setup
• Troubleshooting - Common issues
• Integration Ideas - Use cases

---

Version: 2.0 Updated: 2025-12-11 Major change: Now creates projects for implementation instead of doing everything in one session