elastic/new-entity-requirements

New Entity Requirements

Gather initial requirements for an entirely new Terraform resource or data source, then materialize them as an OpenSpec proposal: a change under openspec/changes/<name>/ with proposal.md, design.md, tasks.md, and delta capability specs. Sources: repo API client code, Elastic API documentation (via the Elastic docs MCP server when available, otherwise web fetch/search), and user input for decisions the code and docs cannot answer.

For the CLI sequence (create change, resolve artifact order, run openspec instructions, write files), follow openspec-propose. This skill adds what to research and what to put in each artifact for a new Terraform entity.

Input

• Entity concept: User specifies the target (e.g. “Elasticsearch API key”, “Kibana SLO”, “Fleet integration”). Optionally: resource vs data source, proposed type name.
• API scope: Which backend (Elasticsearch vs Kibana/Fleet) and, if known, API name or doc URL.
• Change name (optional): Kebab-case id for openspec new change (e.g. add-elasticsearch-security-api-key-resource). If missing, derive one from the entity and confirm with the user if ambiguous.

Workflow

1. Resolve API surface

• Elasticsearch: Wrappers live in internal/clients/elasticsearch/ (e.g. security.go, cluster.go). They call apiClient.GetESClient() and use the go-elasticsearch client (e.g. esClient.Security.PutUser). Shared models: internal/models/. If no wrapper exists yet, search the go-elasticsearch API (dependency github.com/elastic/go-elasticsearch/v8) for the relevant namespace (e.g. Security, Watcher, Transform).
• Kibana and Fleet: OpenAPI-generated client: generated/kbapi/kibana.gen.go. Higher-level wrappers: internal/clients/kibanaoapi/ and internal/clients/fleet/ (e.g. alerting_rule.go, connector.go). Use kbapi types and ClientWithResponses methods for the target API.

Identify: create/update (PUT/POST), read (GET), delete (DELETE), request/response shapes, identifiers (name, id, composite id). Note any version or feature flags in the client or API.

2. Examine Elastic API docs

• Preferred: Use the Elastic docs MCP server when available. Call its tools to search or fetch Elastic documentation (e.g. by API name, topic, or URL). See reference.md for how to use the MCP server.
• Fallback: If the MCP server is not configured or does not return the needed content, fetch docs via web (e.g. mcp_web_fetch for a known URL, or web search for the API name).
• URL patterns: See reference.md for elastic.co/guide and elastic.co/docs URL patterns when constructing or citing links.
• Extract: Endpoint names, required vs optional fields, validation rules, version requirements, error semantics (e.g. 404 = not found), and whether create/update are the same or separate.
• If the user provided a doc URL, use it (via MCP if the server supports fetch-by-URL, or via web fetch); otherwise search by API name (e.g. “Elasticsearch security API create API key”, “Kibana SLO API”).

3. Create the OpenSpec proposal (change + artifacts)

Do not write directly to canonical openspec/specs/<capability>/spec.md as the primary deliverable. Instead:

1. Create the change
   Run openspec new change "<name>" (requires OpenSpec CLI; make setup installs it). This creates openspec/changes/<name>/ with .openspec.yaml.

2. Build all apply-ready artifacts
   Follow openspec-propose steps 3–4: openspec status --change "<name>" --json, then for each artifact in dependency order use openspec instructions <artifact-id> --change "<name>" --json, read dependencies, write to outputPath using template and instruction, re-run status until every id in applyRequires is done.

3. Entity-specific content

   • proposal.md: What & why for this resource/data source; problem, scope, non-goals if useful; link to Elastic docs URLs gathered in step 2.
   • design.md: How the provider will map API ↔ Terraform (client package, identity, import id shape, version gates, error handling). Reference client paths from step 1.
   • tasks.md: Concrete implementation steps (schema, CRUD, acceptance tests, docs)—aligned with repo conventions in dev-docs/high-level/.
   • Delta spec(s) (openspec/changes/<name>/specs/.../spec.md): Normative requirements per dev-docs/high-level/openspec-requirements.md: ## Purpose, optional ## Schema, ## Requirements with ### Requirement: / #### Scenario:; bodies MUST include SHALL or MUST (for openspec validate). Draft HCL-style schema, API/identity/import/connection/compatibility requirements from steps 1–2. Mark unknowns as “TBD” or “(to confirm)”.

Use TodoWrite to track artifact creation, as in openspec-propose.

4. Interview the user

• Collect unanswered questions from the draft artifacts (schema ambiguities, id format, import support, lifecycle, version support). Use the question bank in reference.md.
• Prefer the AskQuestion tool when available (one question per call, clear options). Otherwise ask conversationally and list options.
• Record answers by updating the delta spec and, where relevant, proposal or design—replace TBDs, refine requirements, add Lifecycle, Plan/State, or StateUpgrade if the user specifies them.
• If the user defers a decision, leave TBD in the delta spec and add a short “Open point” note.

5. Finalize

• Ensure every requirement is either derived from the API/client/docs or from user answers. Remove or rewrite speculative claims.
• Add a short “Sources” note in design.md or the delta spec if helpful: API client paths, doc URLs, and whether Elastic docs came from the MCP server or web.
• Run openspec status --change "<name>" and confirm the change is apply-ready. Validate per project docs (make check-openspec / openspec validate as appropriate for specs in the change).

Output

• Deliverable: A complete OpenSpec change at openspec/changes/<name>/ with all artifacts required for implementation (applyRequires), including delta capability specs—not a standalone file only under openspec/specs/.
• Traceability: Requirements in delta specs tied to API docs (links) or user decisions; no invented behavior.

Reference

• Proposal workflow (CLI): openspec-propose
• Authoring: dev-docs/high-level/openspec-requirements.md
• Example canonical spec (style reference): openspec/specs/elasticsearch-security-role/spec.md
• Example archived change layout: openspec/changes/archive/ (proposal, design, tasks, specs/…/spec.md)
• API client locations, doc URLs, interview question bank: reference.md