Droid Runbook: Generating Terraform Data Sources and Acceptance Tests

A practical guide for using AI droids (coding agents) to generate Terraform datasources, resources, and acceptance tests for the Couchbase Capella provider.

Overview

This provider uses a skill-based droid system (located in .factory/skills/) to automate the creation of Terraform data sources, resources, and acceptance tests from the OpenAPI spec. Instead of hand-writing boilerplate, you describe what you need and the droid generates the relevant code, schema, tests, and provider registration.

Available skills:

Skill	Purpose
`tf-datasource-gen`	Generate a Terraform data source from an OpenAPI spec endpoint
`tf-resource-gen`	Generate a Terraform resource from an OpenAPI spec endpoint
`tf-acceptance-test-gen`	Generate acceptance tests for a named resource or data source

QE engineers: If you are here to write acceptance tests, go straight to Writing Acceptance Tests.

Requirements

Git
Go >= 1.21
Terraform >= 1.5.2
A coding agent / AI droid with access to the workspace
The OpenAPI spec (openapi.generated.yaml) at the project root

Quick Start

0. Verify the Droid is Installed

Before starting, confirm your coding agent / AI droid is available and can access the workspace:

# Check that the skill file exists
ls .factory/skills/tf-datasource-gen/SKILL.md


# Check that Go is installed
go version

# Check that Terraform is installed
terraform version

# Check that goimports is installed (needed for code review steps)
which goimports || go install golang.org/x/tools/cmd/goimports@latest

If any of these checks fail, install the missing tool before proceeding. If the skill file (.factory/skills/tf-datasource-gen/SKILL.md) is missing, the droid will not know how to generate data sources — restore it from the repository first.

Tip: If you're using a specific droid platform (e.g., GitHub Copilot, Cursor, Cline), make sure the agent has workspace-level file access and can read/write files in internal/, acceptance_tests/, and .factory/.

1. Identify the Feature

Determine which Capella API resource you want to expose as a Terraform data source. Check the OpenAPI spec for available endpoints:

# Search for your feature in the spec
grep -i "your-feature" openapi.generated.yaml

You need to identify:

GET endpoint — for fetching a single resource (e.g., GET /v4/organizations/{id}/projects/{id}/clusters/{id}/buckets/{id})
LIST endpoint — for fetching all resources (e.g., GET /v4/organizations/{id}/projects/{id}/clusters/{id}/buckets)

If only one endpoint exists, only that data source will be generated.

2. Invoke the Droid

To invoke the droid and generate code:

Run droid in your terminal.
Type /settings to configure the droid. We suggest the following settings:
- Spec mode model: Claude Opus 4.6
- Default mode model: Gemini 3 Flash
- Reasoning effort: High
- Autonomy: Medium
Switch to spec mode by pressing Shift + Tab.
Enter your prompt (see examples below).
Review, edit, and approve the generated plan.

Run-the-Droid Examples

Copy any prompt below and paste it into your coding agent to kick off the full generation workflow. Each example targets a real Capella API feature.

▶️

Example 1 — Snapshot Backups (GET single backup + LIST all backups)