ome-api

name	ome-api
version	1.0.0
description	Integrate API clients, services, and contracts using project rules.
author	oh-my-engine
tags	["ome","api","integration","workflow"]

ome-api

Workflow Session Start (MANDATORY)

Before reading source files, planning, editing, or running verification for this workflow, you MUST start the OME workflow session by running:

ome api $ARGUMENTS

This creates .ome/.session so the final ome finish command can record the execution into .ome/memory/executions/.

If a Windows PowerShell policy blocks the ome shim, run the same step through the cross-shell fallback: cmd.exe /c ome.cmd api $ARGUMENTS. Do not hardcode this fallback on non-Windows platforms.

Claude Code fast path (other agents: ignore the leading ! and run the bare command via your shell tool):

!ome api $ARGUMENTS

Purpose

Integrate an API contract or endpoint with typed, maintainable project code while preserving security, compatibility, and error-handling expectations.

When to Use

• Use for OpenAPI/Swagger files, endpoint descriptions, service clients, request/response types, and API error handling.
• Use when API behavior must align with project conventions.
• Do not use to invent an API contract when requirements are unclear; use ome define or ome plan first.

Inputs

• API spec, URL, local file, or endpoint description.
• Existing API clients, service modules, types, mocks, and tests.
• OME.md, .ome/rules/, and ome guidance api-integration --input "<api-spec>".
• References: security.md, testing.md, and performance.md.

Process

1. Load OME guidance and project rules before changing code.
2. Identify contract assumptions, auth requirements, error shapes, and compatibility constraints.
3. Reuse existing client, service, type, and mock patterns.
4. Implement the smallest integration slice.
5. Add or update tests for success, error, and boundary cases.
6. Verify type safety, tests, and security-sensitive paths.
7. Report changed files, contract assumptions, verification, and remaining risks.

Red Flags

• The API contract is incomplete or conflicts with existing code.
• Auth, tenant isolation, or secret handling is ambiguous.
• The implementation requires a new dependency without explicit user approval.
• Generated code would bypass existing error handling or typed contracts.
• Tests cannot cover key success or failure paths.

Common Rationalizations

• "The spec says it, so no runtime error handling is needed."
• "Generated types are enough verification."
• "This one endpoint can use a different client pattern."
• "Auth details can be wired later."

Verification

• Run targeted API/client tests or equivalent contract checks.
• Run typecheck when types or public interfaces change.
• Verify error handling, auth-sensitive behavior, and backward compatibility where relevant.
• State any contract assumptions that could not be verified.

Output Contract

Final response must include:

• Changed files
• Contract and implementation summary
• Verification
• Remaining risks

Workflow Completion (SUBSTANTIVE WORK ONLY)

Run ome finish only after a substantive workflow loop is complete, and only after you have reported results to the user.

Substantive work means at least one of these is true:

• You changed files or wrote new code/docs.
• You ran verification and the result matters to the task outcome.
• You made a durable technical decision, diagnosis, or reusable learning that should be available later.

Do NOT run ome finish for ordinary conversation, quick explanations, brainstorming with no conclusion, or read-only exploration that produced no reusable outcome.

When the work is substantive, run this as the final shell command:

ome finish

This records the execution into .ome/memory/executions/; the engine policy decides whether it is valuable enough to persist or later evolve.

Claude Code fast path (other agents: ignore the leading ! and run the bare command via your shell tool):

!ome finish