/build-integration

Build a Prismatic Code Native Integration for $ARGUMENTS.

Voice and narration style are defined in the agent instructions. Follow them.

Let the sync script determine what tasks to create and what questions to ask. It reads the spec, evaluates conditions, and returns actionable items. Pre-decide what components or answers are needed. Never search for components or write answers before the sync script tells you to. Use `npm run build --prefix <project-dir>` for builds Run `npx webpack` or `npx tsc` directly cd into the project directory — use `--prefix` for npm Write ALL answers with key=value pairs in one command: `prismatic-tools record-choices {requirements_file} key=value key2=value2`. JSON values are auto-parsed — pass directly: `'source_component={"key":"shopify",...}'` Edit requirements.json directly with Edit or Write tools Create temp JSON files with the Write tool for answer persistence Construct JSON with heredocs (`cat > file << EOF`) or echo redirects Read the answer-to-code cookbook BEFORE writing ANY code Generate code without first reading the cookbook and templates Run `npx tsx ${CLAUDE_PLUGIN_ROOT}/scripts/prerequisites.ts --type integration`. Brief the user on what you're verifying and what the session directory is for. Run the task sync script to discover what spec items need user input: prismatic-tools update-tasks --session --actionable Parse the JSON output. It contains `create_required`, `mark_completed`, `create_optional`, `blocked_count`, and `ready_for_next_phase`. Create a task for EVERY item in `create_required` — all TaskCreate calls in parallel. Skip items from `create_required` Create phase tasks (Scaffold, Build, Deploy) during requirements — they clutter the task list Create tasks for `mark_completed` items (already inferred) or `create_optional` items (handle conversationally) Use item.subject as the task subject. For items in `mark_completed`, explain to the user IN THE CONVERSATION what you inferred: - What you picked up from their description - Which spec answer it maps to - What it means for the integration architecture Be verbose and educational. This is where personality shines. Present exactly ONE question per message. After presenting, STOP and wait for the user's response. Batch multiple questions into one message — even if they seem related (e.g., Shopify connection type and NetSuite connection type are separate turns). After writing each answer, re-run the sync script with --actionable. The sync script determines what question comes next — not you. Decide the next question yourself. The sync script evaluates conditions and may surface follow-up questions (e.g., connection management options after connection type is chosen).

<loop name="requirement-loop">
  <substep>Pick the next pending task from the task list</substep>
  <substep>Explain the question — what Prismatic concept it configures and why it matters</substep>
  <substep>Present choices with tradeoffs, then STOP and wait for the user's response</substep>
  <substep>Write the answer AND re-sync in one call:
    `prismatic-tools record-choices {requirements_file} --sync {spec_file} key=value`
    (JSON values auto-parsed in key=value pairs)
    The output includes both the write confirmation and the sync result.</substep>
  <substep>Mark the task completed with TaskUpdate</substep>
  <substep>Create tasks for any new `create_required` items from the sync output</substep>
  <substep>Repeat from top — present the NEXT single question</substep>
</loop>

When the sync script reports `ready_for_next_phase: true`, requirements are complete.

Collect OAuth/API credentials if needed. Explain what each credential is for. TaskCreate(subject: "Scaffold project") and mark in_progress. Run: `npx tsx ${CLAUDE_PLUGIN_ROOT}/scripts/run.ts scaffold-project --components [--private-components ]` Include ALL components selected during requirements — source_component, destination_component, AND any connector_N_component answers If a component has `public: false` in the find-components result, include it in --private-components Add components that weren't selected in requirements Validate: `prismatic-tools validate-phase --phase scaffold --type integration` Mark completed. TaskCreate(subject: "Generate integration code") and mark in_progress.

BEFORE writing ANY code:
1. Run `prismatic-tools code-plan --session <name> --type integration` to get the code-gen manifest
2. Read each cookbook section and reference file listed in the manifest
3. Templates (read ALL that apply):
   - `${CLAUDE_PLUGIN_ROOT}/templates/integration/componentRegistry.ts.template`
   - `${CLAUDE_PLUGIN_ROOT}/templates/integration/configPages.ts.template`
   - `${CLAUDE_PLUGIN_ROOT}/templates/integration/flows.ts.template`
   - `${CLAUDE_PLUGIN_ROOT}/templates/integration/index.ts.template`
   - Multi-flow only: `${CLAUDE_PLUGIN_ROOT}/templates/integration/flows-index.ts.template`
4. Check `<verify-coverage>` — escalate uncovered architectural items to Orby

<rules>
  <always>Use connectionConfigVar() wrapper for connections on config pages — as shown in configPages.ts.template</always>
  <always>Use onInstanceDeploy/onInstanceDelete for general setup/teardown (folder creation, record types, non-webhook resources)</always>
  <always>Use webhookLifecycleHandlers.create/.delete for webhook subscription management — they support listening mode (test runner) and run after onInstanceDeploy</always>
  <never>Define onTrigger for webhook flows unless custom parsing or a component trigger is needed — default passes payload through</never>
  <never>Use raw connection constructors directly in configPages</never>
</rules>

Required files: componentRegistry.ts, configPages.ts, flows (single file or flows/ directory), index.ts, documentation.md, .spectral/flows/

Validate structure: `prismatic-tools validate-phase <project-dir> --phase code-gen --type integration`
Verify semantics: `prismatic-tools verify-code <project-dir> --session <name>`
If verify-code reports gaps (spec answers not reflected in code), fix the generated code BEFORE building.
Mark completed.

TaskCreate(subject: "Build integration") and mark in_progress. Build: `npm run build --prefix ` Validate: `prismatic-tools validate-phase --phase build --type integration` If build fails: run `prismatic-tools diagnose-build --type integration` before attempting manual fixes. Mark completed. Present a summary: integration name, components, flows, connections. Use AskUserQuestion: "Build succeeded. I'll import this to your Prismatic environment so we can test it — this creates a test instance you can configure. Ready?" Options: "Yes, import and test" / "No, I want to make changes first" WAIT for the user's response. Do NOT import without explicit confirmation. TaskCreate(subject: "Import to Prismatic") and mark in_progress. Pre-import validation: `prismatic-tools validate-phase --phase deploy --type integration` Import: `npx tsx ${CLAUDE_PLUGIN_ROOT}/scripts/run.ts deploy-integration ` This opens the designer in the browser so the user can configure the test instance. Mark completed. TaskCreate(subject: "Test integration") and mark in_progress.

<test-workflow>
  After deploy, do NOT stop. Guide the user through configuring and testing:

  <substep name="check-instance">
    Request Orby to check the test instance and surface the config wizard URL:
    <orby-request>
      For integration [name] (ID: [integration-id]):
      1. Find the test/system instance
      2. List unconfigured connections and config variables
      3. Provide the direct URL to the config wizard for the test instance
    </orby-request>
    Wait for Orby's response.
  </substep>

  <substep name="present-url">
    Present the config wizard URL to the user:
    "Your integration is deployed. Configure the test instance here: [URL]"
    List what needs configuring — connections (with OAuth flows to complete) and config variables.
  </substep>

  <substep name="confirm-ready">
    Use AskUserQuestion:
    "Have you configured the connections and config variables in the test instance?"
    Options: "Yes, run the test" / "Not yet, I need help"
    If "not yet": walk through each unconfigured item.
  </substep>

  <substep name="run-test">
    Run: `prismatic-tools test-integration <integration-id> --integration-dir <project-dir>`
  </substep>

  <substep name="report">
    Report results — what succeeded, what failed, what requires real credentials.
    If test failed with connection errors, remind the user to configure connections in the admin.
  </substep>
</test-workflow>

Mark completed.

Fix issues, rebuild, redeploy, retest. Explain root cause before each fix. Return summary of what was created.