Skip to content

Authoring

OpenUdon has two supported authoring paths. Both produce the same reviewable package shape: a human-readable project.md, a structured workflows/intent.hcl, public UWS artifacts, expected plans, review evidence, quality reports, and a handoff manifest.

Path 1: Guided iCoT

Use iCoT when you want an operator-guided session that starts from a goal and writes the initial brief plus intent.

go run ./cmd/icot --example ./examples/<name>

iCoT writes project.md and workflows/intent.hcl; it does not execute workflows. It can run with LLM assistance, with the fixed manual flow, from an existing example, or from YAML/JSON answers. Use --prompt-mode full|normal|fast to choose between full confirmation, visible default acceptance, or minimal prompting.

After iCoT saves artifacts, continue with:

go run ./cmd/openudon build --example ./examples/<name>
go run ./cmd/openudon assess --example ./examples/<name>

Use iCoT for command details and Project Briefs for the sections a good project.md should contain.

Path 2: Brief And Synthesis

Use synthesis when you already have a project brief or are updating a fixture.

go run ./cmd/openudon synthesize --example ./examples/<name>
go run ./cmd/openudon build --example ./examples/<name>
go run ./cmd/openudon assess --example ./examples/<name>

synthesize reads project.md, discovers or imports local API/event source metadata, creates or updates intent, and writes the generated package artifacts. OpenAPI, Google Discovery, AWS Smithy JSON, AsyncAPI, GraphQL, OpenRPC, gRPC/protobuf, and OData can be staged directly as UWS source descriptions when the trusted executor supports them. AsyncAPI source-bound workflows emit UWS 1.3; GraphQL, OpenRPC, gRPC/protobuf, and OData source-bound workflows emit UWS 1.4. OpenUdon validates and packages those source-bound workflows, but protocol execution remains trusted-runtime-owned. build regenerates from existing intent. assess reruns deterministic quality checks without synthesizing new intent.

Before searching public catalogs, inspect first-class provider metadata from apitools:

go run ./cmd/openudon catalog list
go run ./cmd/openudon catalog inspect github
go run ./cmd/openudon catalog advisory --example ./examples/<name>

When a provider has a directly importable OpenAPI reference, import it into the package-local openapi/ directory:

go run ./cmd/openudon catalog import-openapi --provider stripe --example ./examples/<name>

Discovery, Smithy, AsyncAPI, GraphQL, OpenRPC, gRPC/protobuf, and OData catalog entries can be materialized as first-class API/event source inputs when a package needs them. Stone, Postman Collection, RAML, API Blueprint, and human-docs catalog entries remain advisory metadata until lowered or reviewed separately.

Use Synthesize, intent.hcl, and Data Flow for the artifact contracts.

Agentic SaaS Authoring

For common SaaS workflows, use Agentic SaaS Authoring as the contract. The AI-assisted path can draft goals, operation choices, request mappings, credential binding names, and unresolved assumptions. Use the n8n Pattern Bridge only as service-priority and mapping evidence; the generated artifacts stay OpenUdon-native and continue through deterministic validation, review, packaging, and trusted handoff.

Use iCoT when the brief is not precise yet. Its guided loop starts from provider/catalog metadata when available, asks for listed OpenAPI operation IDs, lets the LLM draft request field sources from selected operation details, and asks the operator only for unresolved credential bindings, mappings, response/output sources, or side-effect boundaries before saving source artifacts.

Safety Rules

  • Put credential binding names in artifacts, never credential values.
  • Keep side-effectful workflows in generated/review state until approval.
  • Use sandbox proof-run language for examples that send email, write records, call commands, or otherwise produce effects.
  • Use openudon run --dry-run to validate the handoff package without invoking the executor.