How We Re-Architected Our Integration Docs to Speak Fluent Coding Agent

This is not a prompt. It’s not a Cursor skill. It’s not a markdown file you paste into Claude. Here’s what it actually is, how it works, and the engineering decisions behind it.

There’s a growing pattern in the AI tooling space: vendors ship a .md file, call it an “AI integration,” and hope the LLM figures it out. Sometimes it works. Usually for simple APIs with three endpoints and predictable payloads.

Forter’s integration surface is not that. We have a multi-endpoint API with merchant-specific schemas, regional variants (3DS, PSD2), client-side JavaScript (and Mobile SDK) injection, payment flow interception points that differ by architecture. Getting this right requires more than a good prompt. It requires a system.

This post breaks down the architecture of Forter’s AI Coding Kit — the actual engineering that makes it work — for developers and technical leaders evaluating this approach.

Video demo

What is a Coding Kit (And What is it Not)?

A Coding Kit is a portable, self-contained package that gives a coding agent everything it needs to perform a complex, multi-step integration inside a merchant’s codebase. It ships as files — markdown, YAML, JSON — that drop into the project root.

What it is not:

Not a prompt. A prompt is a single instruction. The kit is a multi-layered system with workflows, step definitions, structured knowledge, migration datasets, and merchant-specific configuration. A prompt says “integrate Forter.” The kit defines how, across dozens of decision points.
Not a Cursor rule or Claude Skill. Rules and skills are single-file instructions that modify agent behavior. They don’t maintain state. They don’t chain multi-step workflows. They don’t carry structured reference data. The kit uses IDE-specific rules as entry points — thin adapters that load the real workflow definitions.
Not documentation repackaged as markdown. The knowledge base isn’t our docs site dumped into .md files. It’s structured, machine-parseable data: OpenAPI specs with field-level annotations, YAML migration mappings with per-field type and source metadata, merchant-specific schema definitions loaded from configuration.

Architecture: Step-File Workflows with Sidecar State

The core design pattern is step-file architecture — each workflow is a sequence of self-contained step files, executed one at a time, with structured state passed between them.

Workflow Structure

.forter/workflows/analyze-codebase/
├── workflow.md                    # Orchestration: defines step sequence, execution rules
└── steps/
    ├── step-01-init.md            # Initialize, load config, set up state
    ├── step-02-detect-stack.md    # Detect language, framework, architecture
    ├── step-03-map-structure.md   # Map project structure, find key files
    ├── step-04-find-checkout.md   # Locate checkout flow and payment processing
    ├── step-05-detect-vendor.md   # Find existing fraud vendor integration
    ├── step-06-plan.md            # Generate integration plan
    └── step-07-report.md          # Compile analysis report

Each step file contains:

YAML frontmatter with path definitions, file references, and state management pointers
Execution rules that constrain agent behavior (what to do, what not to do, when to ask the user)
Detection patterns as structured lookup tables the agent follows
Output specifications defining exactly what the step produces
Transition logic that loads the next step file

Why Step Files?

A single prompt containing all of Forter’s integration logic, API specs, detection patterns, migration mappings, and workflow instructions would blow past any reasonable context limit — and even if it fit, the agent’s attention would degrade across that much content.

Step files solve this by design: only the current step is in the agent’s context. The agent reads step-02-detect-stack.md, executes it, writes findings to state, then loads step-03-map-structure.md. Each step is focused, self-contained, and small enough that the agent can follow it precisely.

This is the same principle behind why you don’t put your entire codebase in a prompt. You page in what’s relevant. The kit does this systematically.

Sidecar State

Steps communicate through a YAML sidecar state file that persists across the workflow:

# analyze-codebase-state.yaml (written by step-02, consumed by step-03+)
findings:
  architecture:
    type: "microservices"
    multiRepo: true
    confidence: "high"
    confidenceScore: 87
  repositories:
    - id: "checkout-service"
      path: "./services/checkout"
      techStack:
        language: "TypeScript"
        framework: "NestJS"
      role: "backend-api"
    - id: "payment-service"
      path: "./services/payments"
      techStack:
        language: "TypeScript"
        framework: "Express"
      role: "payment-service"
  competitorVendors:
    detected: true
    vendors:
      - name: "Riskified"
        confidence: "high"
        indicators:
          dependencies: ["@riskified/sdk"]
          apiEndpoints: ["api.riskified.com in services/payments/src/fraud.ts"]
          configKeys: ["RISKIFIED_API_KEY"]
        integrationScope: "full"

This isn’t free-form text. It’s structured data with a defined schema. When the implement-forter workflow runs, it reads this state and knows: this is a TypeScript/NestJS microservices setup, the payment flow is in services/payments, there’s a full integration to replace, and the relevant file is services/payments/src/fraud.ts.

The agent doesn’t have to rediscover any of this. It was found once, recorded precisely, and passed forward.

The Multi-IDE problem

Coding agents don’t have a standard interface. Cursor uses.mdc rule files in .cursor/rules/. Claude Code uses markdown commands in .claude/commands/. Windsurf uses .windsurf/rules/. GitHub Copilot uses .github/copilot/. Each expects different file formats, different directory structures, and different activation patterns.

The kit solves this with a thin adapter layer. The core logic — workflows, knowledge base, migration data — lives in .forter/, IDE-agnostic. Each IDE gets a set of adapter files that do one thing: load the corresponding workflow from .forter/.

# What a Cursor adapter looks like (.cursor/rules/forter/Analyze Codebase.mdc)

---
description: "Forter Workflow: Analyze Codebase"
alwaysApply: false
---

# Analyze Codebase

LOAD the FULL workflow file from @.forter/workflows/analyze-codebase/workflow.md,
READ its entire contents and follow its directions exactly!

The workflow definition — with all its step files, detection patterns, execution rules, and state management — lives in .forter/ and is identical regardless of which IDE loads it.

The build pipeline generates these adapters for all four IDEs simultaneously: 5 files per IDE (entry point + 4 workflows), 20 adapter files total. The merchant gets all of them. Whichever IDE they open, it works.

Why This Matters

A Claude Skill or Cursor rule is written for one IDE. If you build a Cursor rule, Claude Code users get nothing. If you write a Claude command, Cursor users can’t use it.

The kit decouples the integration logic from the IDE delivery mechanism. Write once in .forter/, generate adapters for every IDE. When a new IDE emerges or an existing one changes its format, you update the adapter generation — not the integration logic.

Knowledge base: structured data, not prose

The kit’s knowledge base isn’t documentation. It’s a structured reference system designed for agent consumption.

API specifications

The Forter API spec ships as a JSON file (forter-api-latest.json) — not a markdown overview. The agent can parse endpoint definitions, request schemas, response types, authentication requirements, and error codes directly. Field-level annotations include data type, whether the field is required, where the data typically comes from in a merchant’s system, and validation constraints.

This matters because the agent needs to map merchant data to Forter request fields. A human reads a docs page and thinks “I’ll put the customer email here.” An agent needs to know programmatically that primaryDelivery.deliveryDetails.email is a required string field sourced from the order’s shipping information.

Merchant-specific configuration

Each kit can include merchant-specific files generated from the Forter portal:

merchant/config.yaml — Site ID, environment, schema path
merchant/custom-schema.json — The merchant’s specific Forter schema (custom fields, product-specific requirements)
merchant/js-snippet.html — Pre-configured JavaScript snippet for their site

The workflows check for these at runtime. If a custom schema exists, the agent generates code against that schema, not the generic one, so if a pre-configured JS snippet exists, the agent uses it directly instead of generating one.

Security: why local-first isn’t just a feature

The most common objection we hear from Enterprise security teams about AI coding tools: “You want me to send our source code to a third-party service?”

The Coding Kit sidesteps this entirely. Here’s the security model:

No hosted component. The kit is a directory of files. There is no server, no API, no SaaS product behind it. The files are copied into the merchant’s project. That’s the deployment.
No network calls. The kit makes zero outbound calls to Forter infrastructure. The only network calls that happen are (a) the LLM inference calls — which go to the merchant’s own LLM provider, and (b) the actual Forter API calls that the generated integration code makes. Both are under the merchant’s control.
Bring your own LLM. The kit is LLM-agnostic. It works with whatever model the merchant’s IDE is configured to use — Anthropic Claude, OpenAI GPT, AWS Bedrock, Azure OpenAI, a self-hosted model. Forter has no visibility into which model is used or what it processes.
Fully auditable. Every file in the kit is human-readable markdown, YAML, or JSON. There’s no compiled code, no obfuscated logic, no binary blobs. A security team can read every workflow step, every detection pattern, every migration mapping, and every API spec before the kit is used. Multiple enterprise security teams have done exactly this during our design partner phase.
No telemetry. No analytics. No usage tracking. No phone-home behavior. Forter has no way to know whether a merchant has used the kit, how far they got, or what their codebase looks like. This is by design.

Detection: how the agent understands a codebase

The analyze-codebase workflow is where the kit earns its keep. Rather than asking the merchant “what’s your tech stack?” — which is surprisingly unreliable for complex setups — the agent figures it out by scanning for indicator files.

The detection follows a structured sequence:

Language detection — look for package.json (Node), requirements.txt/pyproject.toml (Python), pom.xml/build.gradle (Java), *.csproj (C#), go.mod (Go), Gemfile (Ruby), composer.json (PHP), Cargo.toml (Rust).
Framework detection — based on the detected language, scan dependency files for framework-specific packages. Not just “is Express installed” but which specific framework variant, because the code generation patterns differ between Express, Fastify, NestJS, Koa, and Hapi even though they’re all Node.js.
Architecture detection — look for multi-repo indicators: docker-compose.yml, monorepo tools (lerna.json, nx.json, turbo.json, pnpm-workspace.yaml), service directories. If found, scan each service independently and classify its role (frontend, backend API, payment service, webhook handler, worker).
Current vendor detection — scan dependencies, configuration files, and code for signatures of existing vendors. Not just “is the SDK installed” but where it’s called, how it’s configured, and what scope the integration covers (full, partial, legacy).
Confidence scoring — each finding has a confidence level. If the agent finds only a frontend with no backend, or a backend with no payment processing, it flags the gap and asks the merchant whether there’s a separate repo it should analyze. This handles the common case of split architectures where the checkout frontend and payment backend live in different repositories.

All findings are written to sidecar state as structured YAML. Every subsequent workflow step reads from this state rather than re-analyzing the codebase.

What this means for SaaS vendors building integration tooling

If you’re at a SaaS company thinking about how AI agents will consume your integration surface, here’s what we learned building this:

Your API spec is your most important asset now. Not your docs site. Not your SDK. The OpenAPI spec (or equivalent) is what agents parse to understand your API. Invest in field-level annotations — data types, sources, validation constraints, relationships between fields. The better your spec, the better the agent-generated code.
Structure your docs as workflows, not references. A reference document tells you what an endpoint does. A workflow tells you when to call it, what data you need at that point, what to do with the response, and what comes next. Agents follow workflows. Humans browse references. Optimize for the former.
Decouple your integration logic from your IDE delivery. IDE formats will change. New IDEs will appear. If your integration logic is embedded in a Cursor rule, you’re locked in. Put the logic in a portable format and generate IDE-specific adapters.
State management matters. Multi-step integrations produce findings at each step that subsequent steps need. If you’re building anything beyond a single API call, you need a state mechanism — not agent memory (which is unreliable across long workflows), but explicit, structured state files that persist between steps.
Local-first is not optional for enterprise. If your integration tool needs to touch merchant code, it needs to run locally with zero data exfiltration. Hosted solutions will be blocked by security review. Full stop.

If you want to dig into the technical architecture or discuss how this approach applies to your integration surface, reach out to the Forter engineering team or contact your account team at forter.com.

Share this article: