agentic-workflows-api-documentation-lungo

name

agentic-workflows-api-documentation-lungo

description

Authors and maintains the human-facing Agentic Workflows API documentation for the lungo subproject at coffeeAGNTCY/coffee_agents/lungo/docs/workflow-instance_api.md. OpenAPI under coffeeAGNTCY/coffee_agents/lungo/schema/openapi/ is the HTTP contract source of truth (paths, shapes, response statuses): updated manually or via LLM, never generated from code. Covers the catalog API, workflow-instance lifecycle/state, internal event ingress, SSE and NDJSON streaming, event_v1, and topology/use-case shapes. Use when documenting or updating the lungo workflow API; when schema/openapi/ or schema/jsonschemas/ changes; or when a prompt references a ticket/issue, pull request, or file/folder that changes lungo API contracts. DO NOT TRIGGER AUTOMATICALLY. ASK THE USER IF THE SKILL SHOULD BE USED.

Agentic Workflows API documentation (lungo)

Produces and maintains a single human-facing reference document for the lungo Agentic Workflows API from the machine-readable contracts already in the repo. The document is a guide, not the contract.

Source of truth: schema/openapi/ (HTTP paths, shapes, response statuses) and schema/jsonschemas/ (instance/event payloads). Read those folders fresh on every run; resolve $refs from the OpenAPI entry point. Do not trust the existing human doc or this skill to list every file inside those trees - layout may change.

The lungo project root is coffeeAGNTCY/coffee_agents/lungo/. The output document lives at docs/workflow-instance_api.md and links to in-repo specs with paths relative to docs/ (e.g. ../schema/...).

Scope: This skill updates OpenAPI under schema/openapi/ and workflow-instance_api.md only. Python routers/DTOs: openapi-to-python-lungo. Pydantic types from JSON Schema: jsonschema-to-pydantic-lungo. For trigger-condition prose or streaming behavior OpenAPI omits, read implementation only as needed via openapi-to-python-lungo's scope - do not treat Python files as contract sources.

Output

• Human guide: docs/workflow-instance_api.md
• OpenAPI (when paths, shapes, or response statuses change): files under schema/openapi/ - discover path items, shared schemas, and reusable error responses by reading the tree

Keep the human guide aligned with the resolved OpenAPI document. Reconcile using Document structure whenever the API surface changes. When HTTP statuses change, follow OpenAPI status codes before updating prose.

Where to look

Role	Path (relative to lungo root)
HTTP contract	schema/openapi/
Event / instance JSON Schema	schema/jsonschemas/
Human guide (output)	docs/workflow-instance_api.md

Enumerate endpoints, fields, and status codes from the specs - do not hard-code counts or names from memory. For worked examples in prose (patterns, use-cases, sample topology), pull real values from catalog data under api/agentic_workflows/ when present.

Sibling skills run after contract edits (as the user directs):

• openapi-to-python-lungo - align FastAPI routers/DTOs and read handler behavior
• jsonschema-to-pydantic-lungo - regenerate Pydantic mirrors

Document structure

Keep the document organized in this order (headings are stable). Re-derive content from schema/openapi/ and schema/jsonschemas/:

1. Title + intro - one-paragraph scope covering catalog, instance lifecycle, streaming, and event schema
2. Authoritative sources - table linking in-repo specs and example payloads; note any temporary DTO/catalog gaps pending schema consolidation
3. Conventions - identifier URI schemes; path-UUID vs payload-URI rule; authentication; storage model; default port
4. Endpoint summary - one table row per operation from OpenAPI (purpose, method and path, response type)
5. Catalog API - list/catalog/documentation/chat endpoints declared in OpenAPI
6. Workflow details and topology response shapes - workflow GET, topology_only, node/edge field breakdown, example topology from catalog data when available
7. Workflow-instance lifecycle and state - instantiate, list, get state, delete, each with status codes from OpenAPI
8. Internal event ingress - events POST (internal), validation, status codes
9. Streaming formats - SSE instance stream and NDJSON pattern chat (implementation notes where OpenAPI only declares success)
10. Workflow-instance state JSON Schema - link to published schema; full snapshot vs delta; top-level shape; $defs table; event types; worked examples
11. Frontend integration checklist - end-to-end flow (selectors, list, graph, instantiate, SSE, reconcile, delete)

Workflow

- [ ] 1. Read schema/openapi/ and schema/jsonschemas/ (resolve OpenAPI from its entry point)
- [ ] 2. Enumerate endpoints and response statuses from the resolved spec (do not hard-code)
- [ ] 3. If a new status is needed, update OpenAPI first (see OpenAPI status codes)
- [ ] 4. Write/refresh each section per Document structure from the specs
- [ ] 5. For trigger conditions or streaming details OpenAPI omits, read handler code only as needed; surface drift to the user
- [ ] 6. Use real catalog example values where helpful; link full example payloads rather than inlining
- [ ] 7. Apply the writing conventions
- [ ] 8. Verify links, lint, and OpenAPI unit tests (see Verification)
- [ ] 9. If handlers must align with new statuses or shapes, tell the user to run openapi-to-python-lungo (not this skill)
- [ ] 10. If new contract folders or doc sections appear, update Document structure here; keep AGENTS.md in sync if skill scope changes

Source-of-truth rules

• OpenAPI first. Paths, request/response shapes, and declared HTTP status codes live in schema/openapi/. Change the spec first, then the human doc and generated types (frontend npm run generate:api-types; Python via openapi-to-python-lungo).
• Derive, never invent. Every endpoint, field, and status code in the human doc must trace to OpenAPI (plus global 401 from security) or JSON Schema under schema/jsonschemas/.
• Surface drift. If implementation returns a status OpenAPI does not declare, add it to OpenAPI via this skill and ask the user to align handlers via openapi-to-python-lungo. Do not document undeclared codes only in markdown.
• Enumerate, don't count. Build tables and lists by reading the specs, not from cached skill text.
• Generic skill, specific repo. This skill names folders, not every file inside them; discover current layout when you run.

Writing conventions

• Markdown prose is not hard-wrapped for length: one paragraph or list item per line. Keep tables, fenced code blocks, and JSON/SSE/NDJSON examples structured as-is.
• Link to source files with paths relative to docs/. Link full example payloads rather than pasting them; excerpt only small fragments.
• Use fenced code blocks with a language tag for samples; these are illustrative, not citations of repo lines.
• Keep terminology consistent: "endpoint", "workflow instance", "topology", "event".
• Present per-endpoint status codes as a markdown bullet list after a Status codes: (or similar) lead-in, one code per item: - `<code>` - <condition>. Derive codes from OpenAPI responses plus global 401 where auth applies.

OpenAPI status codes

When an operation needs a new or changed HTTP status:

1. Update OpenAPI - under schema/openapi/, add or adjust responses on the operation (discover path items and shared components/responses by reading the tree):
   • 401 - rely on global security on the OpenAPI root document; do not repeat on every operation unless the spec already does
   • 422 - reference UnprocessableEntity (ValidationError body: { detail: [...] })
   • Other errors - $ref shared components/responses by status: 400 → BadRequest, 404 → NotFound, 500 → InternalServerError, 503 → ServiceUnavailable, 504 → GatewayTimeout (ApplicationError body: { detail: string }). Do not use inline description-only error responses for those codes.
   • Body schemas - ApplicationError vs ValidationError live under components/schemas/ in schema/openapi/; response components point at the matching schema.
2. Update the human doc - status bullets and conditions aligned with the spec
3. Align implementation - ask the user to run openapi-to-python-lungo so handlers use only declared statuses
4. Regenerate consumers - npm run generate:api-types in the lungo frontend when applicable; Python via openapi-to-python-lungo when shapes changed
5. Same change set - OpenAPI and markdown together in one PR; handler alignment via openapi-to-python-lungo when the user requests it

Do not add error responses= on FastAPI decorators unless the user explicitly asks; YAML under schema/openapi/ remains the published contract.

Verification

Run from the repo root:

cd coffeeAGNTCY/coffee_agents/lungo/docs
for p in $(grep -oE '\]\(\.\.?/[^)]+\)' workflow-instance_api.md | sed -E 's/^\]\(//; s/\)$//'); do
  [ -e "$p" ] && echo "OK   $p" || echo "MISS $p"
done

Fix any MISS link before finishing.

From coffeeAGNTCY/coffee_agents/lungo/:

uv run pytest tests/unit/openapi/ -q

Fix OpenAPI validation or spec drift when you changed schema/openapi/. Report handler drift to the user; do not fix handlers from this skill.

Keeping this skill current

When a prompt references a new ticket, pull request, or contract folder:

1. Contract edits first - update schema/openapi/ and/or schema/jsonschemas/; invoke sibling codegen skills as the user directs
2. Update OpenAPI before prose - follow OpenAPI status codes; do not document new errors only in markdown
3. Refresh the human doc - re-run the Workflow
4. Adjust this skill sparingly - prefer updating Document structure over growing file inventories; keep AGENTS.md in sync if name or scope changes

Surface spec vs implementation inconsistency to the user; do not paper over drift in prose.