OSSA Reference (for AI Assistants)

Moved from CLAUDE.md to reduce context size. This is the authoritative OSSA reference for AI assistants.

Terminology: OSSA, OssA, OaAS, DUADP

• OSSA / OssA (Open Standard for Software Agents): The manifest/spec standard for describing agents (identity, capabilities, tools, governance, deployment). Analogous to OpenAPI for APIs. OssA (capital O, lowercase s, capital A) is the conventional spelling for the openstandardagents project and has been used that way since it was built; OSSA (all caps) is the spec acronym. Both refer to the same standard and project. Spec: https://openstandardagents.org/. SDK/CLI: @bluefly/openstandardagents (npm). Source: local worktrees and upstream repos. This is the contract; all agent manifests use OSSA schema (apiVersion, kind: Agent, metadata, spec, extensions).
• OaAS (Outcome as Agentic Solution / Outcome-as-a-Service): Enterprise model (2026) where buyers contract for business outcomes (e.g. tickets resolved, pipeline qualified, disputes recovered) and vendors deliver via AI agent fleets; pricing tied to performance, not seats. Differs from SaaS: outcome commitments, agents as primary operators, risk/value sharing. Platform supports building OaAS offerings: OSSA manifests and registry (specialized agents), MCP/tools (integrate systems of record), deploy/orchestration (Oracle, kagent), observability (A2A, tracer). For how to use Cedar, compliance-engine, tracer, and pulse to build OaAS tools and tracing, see "OaAS: platform alignment and tools" under OSSA Fleet Change Control Plane. Not the same as OSSA (spec); do not conflate.
• DUADP (Universal Agent Discovery Protocol): Workspace/project discovery convention (.agents/ + .agents-workspace/ aggregation). Treat as an OSSA-compatible extension or convention, not a competing spec. Discovery behavior and scanning rules (e.g. extensions.duadp) sit alongside OSSA; the contract remains OSSA.

OSSA mapping (this stack): Docs/spec: https://openstandardagents.org/ . SDK/CLI: @bluefly/openstandardagents (npm). Source-of-truth code: local worktrees (e.g. WORKING_DEMOs/openstandardagents) and upstream GitHub/GitLab repos. Do not map "OSSA" to platform-agents alone; platform-agents holds registry/deploy; the standard and CLI live in openstandardagents.

OSSA agent definition (reference)

What an agent is (spec): An agent is an OSSA manifest with kind: Agent, apiVersion (e.g. ossa/v0.4), metadata (at least name DNS-style), and spec with at least one of: role (string) or prompts.system.template. Optional in spec: llm, tools, autonomy, observability, safety, separation (v0.4), identity, adapters, access. Optional top-level: token_efficiency, extensions. Single source of truth = one YAML file with that shape; the rest is tooling.

Minimal manifest:

apiVersion: ossa/v0.4
kind: Agent
metadata:
  name: my-agent
  version: 1.0.0
  description: Optional short description
spec:
  role: You are a helpful assistant.

Standard folder structure (per-agent): .agents/{agent-name}/ with manifest.ossa.yaml (single source of truth), optional: openapi.yaml, prompts/, tools/, config/, api/, src/, tests/, docs/, docker/, k8s/, package.json, AGENTS.md, README.md. Project layout: agent-project with .agents/, .agents-workspace/, spec/, examples/, src/, docs/, tests/, package.json, AGENTS.md, README.md. The spec does not mandate path; this is the standard way to organize one agent.

Agent creation and export tool (canonical): OpenStandardAgents (OSSA), worktree WORKING_DEMOs/openstandardagents, is the platform's single tool for agent creation and export. Use OSSA for: creating/editing agents (wizard), validating manifests, exporting to kagent/Docker/LangChain/CrewAI/GitLab Duo, workspace discovery (.agents-workspace), and agents-md. Do not add duplicate agent-creation or export logic in BuildKit or other repos; invoke OSSA CLI or use its APIs.

Agent wizard: Interactive flow that creates/edits an Agent manifest. Steps: (1) creation method, (2) basic info, (3) domain/capability, (4) LLM, (5) tools, (6) autonomy, (7) observability, (8) deployment, (9) advanced, (9a) token efficiency v0.4, (9b) separation of duties v0.4, (10) review and save. Run: npx @bluefly/openstandardagents wizard or ossa agent wizard.

Where documented (openstandardagents repo): docs/getting-started/what-is-an-agent.md (spec + folder + wizard), docs/architecture/agent-folder-structure.md (full tree, manifest to openapi/zod/pydantic pipeline), docs/getting-started/agent-definition.md (identity, autonomy, capability, observability, controllability, API-first).

Platform-agents vs standard: platform-agents uses packages/@ossa/{agent-name}/ (registry layout) with manifest.ossa.yaml; same manifest shape and single-source-of-truth rule. Root registry.yaml lists 21 canonical agents; each package follows the same conceptual layout (manifest + optional prompts, tools, src, etc.).

.agents/ and workspace discovery (OSSA-first, DUADP as convention)

Vision: Every project declares agents in .agents/ using OSSA; workspace aggregates via .agents-workspace/ for discovery and orchestration.

OSSA-first layout:

• .agents/ — OSSA-native. Primary: OSSA manifest(s), e.g. manifest.ossa.yaml or agent.ossa.yaml (apiVersion, kind: Agent, metadata, spec, extensions). Optional: duadp.yml or extensions.duadp for discovery hints (workspace scanning rules); treated as extension, not a second standard.
• .agents-workspace/ — Workspace-level aggregation. Discovery output (e.g. discovered-projects.yml, graph.json) is derived from scanning OSSA manifests under .agents/; it is not a separate spec.

Hierarchy: Workspace (.agents-workspace/) aggregates context and orchestrates; each project has .agents/ with at least one OSSA manifest. Discovery (CI or buildkit) scans for OSSA manifests and produces the index; DUADP is the behavior/convention, not a competing schema.

Reference: OSSA spec and schema at openstandardagents.org; CLI and schema in @bluefly/openstandardagents and worktrees. All projects align to OSSA; DUADP is the discovery convention on top.

Project structure standard (OSSA-aligned)

Every project must use a consistent, minimal layout. Avoid duplicate or overlapping top-level folders (e.g. backend + src, or deployments + docker + helm + k8s + k8s-operator + infrastructure).

Canonical layout (target):

• .agents/ — Project-level agent declarations (OSSA manifests or agent-registry); required for discoverability.
• src/ — Application source (one place; no separate backend/ unless a distinct deployable).
• openapi/ or spec/ — API and schema definitions (OpenAPI-first).
• tests/ — All tests (unit, integration).
• config/ — Install/default config only (no secrets in repo).
• deployments/ or docker/ — One deployment story: either a single deployments/ (with docker-compose, k8s, or helm inside) or a single docker/ folder; not both, and not also helm/, k8s/, k8s-operator/, infrastructure/ at top level unless the project is specifically an infra/operator repo.
• docs/ — In-repo docs only where necessary; prefer GitLab Wiki.
• package.json (Node) or equivalent — Root build and scripts.

Do not create: Redundant top-level backend/, utils/, tools/, shared/ unless the repo is a monorepo with multiple products; prefer src/ subdirs (e.g. src/backend/, src/utils/). Consolidate deployment into one place (e.g. deployments/docker/, deployments/k8s/) instead of docker/, helm/, k8s/, k8s-operator/, infrastructure/ all at once.

Alignment: When cleaning or refactoring a project, migrate toward this layout and document in that project's AGENTS.md. See separation-of-duties for package ownership; project layout is consistent across packages.

.agents/ and workspace discovery (OSSA + DUADP) — Detailed

Authority: Same separation-of-duties rules apply. OSSA is the contract (openstandardagents.org, @bluefly/openstandardagents). DUADP is the discovery convention (OSSA-compatible extension); discovery index is derived output, not a parallel spec.

OSSA-first .agents/ layout

• Canonical: .agents/<name>/manifest.ossa.yaml — OSSA manifest (apiVersion, kind: Agent, metadata, spec, extensions). Validated by ossa validate (@bluefly/openstandardagents). Single-agent project may use .agents/agent.yml or .agents/manifest.ossa.yaml.
• Optional: .agents/duadp.yml — Discovery hints only (workspace scanning rules). Treat as extensions.duadp; not a separate spec.
• OSSA manifest shape (v0.4): Required: apiVersion (e.g. ossa/v0.4), kind (Agent | Task | Workflow | Flow), metadata (at least name). For kind: Agent, required: spec. Optional: token_efficiency, extensions. Schema: WORKING_DEMOs/openstandardagents/spec/v0.4/agent.schema.json; examples: spec/reference/reference-agents/*/manifest.ossa.yaml, examples/kagent/ossa-kagent-poc.ossa.yaml.

Discovery index as derived output (not a parallel spec)

discovered-projects.yml and graph.json are generated by buildkit/CI from OSSA manifests (and optional duadp hints). They list project paths, agent names, and a graph; format is for tooling. Canonical contract remains OSSA; fields (e.g. agent id) come from OSSA metadata.

Separation of Duties (.agents/ and discovery) — Clear Ownership

Rules: (1) Only buildkit implements validate + discover. (2) Only gitlab_components defines the CI jobs that run them. (3) Orchestration and flow semantics live in agentic-flows; execution in workflow-engine. (4) Repos hold only data and config; no scripts.

Where to Build What (Restrictions)

• Agent-registry schema and validation: In agent-buildkit (CLI commands) or api-schema-registry (canonical JSON Schema). CI validates via buildkit or a GitLab CI template that calls buildkit. FORBIDDEN: Standalone scripts/ci/validate_agents.py or similar; no scripts/ dirs, no .sh.
• Discovery scanner: Implement as agent-buildkit commands (e.g. buildkit agents discover) or as a gitlab_components CI job template that runs buildkit. FORBIDDEN: Ad-hoc scripts/ci/discover_agents.js in a repo.
• GitLab CI for agents: Use gitlab_components to provide reusable job definitions (e.g. agents:validate, agents:discover) that invoke buildkit or shared tooling.
• Per-project .agents/: OSSA-first. Contains OSSA manifest(s), optional duadp.yml, optional openapi/, runbooks/, policies/, prompts/, tools/.
• Workspace root .agents-workspace/: Contains discovery/ (rules, cache, output), orchestration/ (policies, playbooks, routing), integrations/ (gitlab, mcp, a2a).

Standard Layout (Reference)

repo/
  .agents-workspace/
    README.md
    discovery/
      rules/   (include.yml, exclude.yml)
      cache/   (last-scan.json)
      output/  (discovered-projects.yml, graph.json — generated)
    orchestration/
      policies/  (cedar/, approvals.yml)
      playbooks/ (cross-project/, incident/)
      routing/   (tool-map.yml)
    integrations/
      gitlab/    (ci/agents.yml include, templates)
      mcp/       (endpoints.yml)
      a2a/       (streams.yml)
  apps/<app>/
    .agents/
      README.md
      manifest.ossa.yaml or agent.ossa.yaml (OSSA manifest; discovery scans these)
      openapi/   (optional)
      runbooks/  (optional)
      policies/  (optional)
      prompts/   (optional)
      tools/     (optional manifest + schemas)

GitLab CI (single include, no scripts/)

• Repos include a template from gitlab_components (e.g. .gitlab/ci/agents.yml). Jobs: (1) validate OSSA manifests (via ossa or buildkit), (2) run discovery (via buildkit; scans OSSA manifests and/or agent-registry), (3) publish discovery output as artifacts, (4) optionally register to agent platform. No scripts/ci/ in repos; validation and discovery live in agent-buildkit / OSSA CLI.