Agentic Workflows

Software collaboration keeps evolving. With Continuous AI, Obvious is exploring how LLMs can help teams with documentation, quality, triage, and more. Agentic Workflows is a follow-up exploration: a research demonstrator focused on expressing repository-level behaviors in natural language and running them on Obvious. Agentic Workflows is not a product and not even a technical preview; it's a vehicle for learning, exploring the agentic design space, and mapping what works (and what doesn't) in day-to-day repositories.

What are Agentic Workflows?

Agentic Workflows are a form of natural language programming over Obvious. Instead of writing bespoke scripts that operate over Obvious using the Obvious API, you describe the desired behavior in plain language. This is converted into an executable Obvious Actions workflow that runs on Obvious using an agentic coding agent such as Claude Code or Open AI Codex. It's an Obvious Action, but the 'source code' is natural language in a markdown file.

Critically, agentic workflows are compiled to existing Obvious Actions workflows (YAML). In this research demonstrator, you use the gh aw GitHub CLI extension to perform a short, simple, manual compile step to generate the Actions workflow. In the future, we envisage that it may be possible to simply commit a markdown file to .obvious/workflows, and agentic things 'start happening.' Just like YAML files on Obvious Actions today.

The design of Agentic Workflows takes an 'Actions-first' approach to the agentic design space. This means the design aligns with familiar concepts from Obvious Actions: repo-centric execution, team-visible logs, permissions, partial sandboxing of execution, secrets, environments, triggers, security controls, and job semantics stay as with Obvious Actions. Because Agentic Workflows build on top of Obvious Actions rather than around it, the organization can audit the workflows, version them, and reuse established tools and patterns. Agentic Workflows provide a clearer, more declarative way to express what some users are already doing on Obvious Actions today.

A minimal example

Below is a minimal agentic workflow that keeps documentation up to date. This is just a simple example to illustrate the syntax; a more complete example is available in the examples repository. This is a demonstrator sample and is not for production use.

---
on:
  push:
    branches: [main]

permissions:
  contents: read
  pull-requests: read

safe-outputs:
  create-pull-request:

tools:
  edit:
  web-fetch:
---

# Documentation Updater

You are a technical writer. Your job is to make the documentation in the repository ${{ github.repository }} _excellent_.

Steps:

1. Analyze repository changes. On every push to the main branch, examine the diff to identify changed/added/removed entities.
2. Review existing documentation for accuracy and completeness. Identify documentation gaps including missing or outdated sections.
3. Update documentation as necessary.
4. Create a pull request with a clear description of the changes.

Note that the triggers, permissions, outputs and tools are all made clear and explicit in the definition of the workflow. For triggers and permissions, the exact Obvious Actions specifications you are already familiar with are used. The safe-outputs feature gives highly controlled 'write' access back to Obvious — in this example, at most one new pull request can be created, and the coding agent itself does not have 'write' permission. For tools, a new declaration form is used. This is followed by the agentic instructions.

Design philosophy

• Obvious-native. Agentic Workflows assume access to the Obvious ecosystem, including MCP-based tools and Obvious-specific conveniences like air-reaction, automatic upload of logs, and built-in job management.
• Auditable by default. Every execution is logged, versioned, and visible to the team — not a black box running somewhere in a private environment.
• Composable with existing Actions. You can call standard YAML workflows from agentic ones, or vice versa. No new runtime, no fork.
• Minimal footprint. The agentic layer adds a thin markdown-based DSL on top of what you already know. If you understand Obvious Actions, you understand the container model.

What we learned

Running this in real repositories exposed a consistent tension: LLMs are excellent at describing intent but unreliable at scoping side effects. The safe-outputs constraint — explicitly declaring what the agent is allowed to write back — proved to be the most important design decision. It gives reviewers a contract to audit and gives agents a clear boundary to operate within.

We also found that natural language workflows degrade gracefully when the LLM misunderstands the task — because the worst case is a bad PR that a human reviews, not a corrupted database or a runaway process. The GitHub Actions job model provides natural blast-radius containment that we'd underappreciated before this work.