# theaiautomators/agentic-workflows architecture

> Architecture diagram of the GitHub repository theaiautomators/agentic-workflows, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-06-19). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/theaiautomators/agentic-workflows
- Repository: https://github.com/theaiautomators/agentic-workflows

## Overview

1. **Overall shape**
This repo is a scaffolded collection of independent Python “workflows.” Each workflow is meant to be self-contained under `workflows/{name}/`, while shared project conventions, metadata, and AI-agent tooling live at the repository root.

2. **Execution boundary: one workflow = one entrypoint**
The primary runtime unit is a workflow directory containing a `main.py` script. That script is the local executable entrypoint, and in some cases also the deployable function for Modal. The `workflows/hello-world/` example shows the intended minimum shape.

3. **Shared Python dependency layer**
`requirements.txt` defines dependencies used across all workflows, not per workflow. `bootstrap.py` sets up the local Python environment by creating `.venv` and installing those shared dependencies, so the repo assumes one common dependency base rather than isolated package builds per workflow.

4. **Environment configuration flow**
Configuration is layered: root `.env` is the shared source of secrets and API keys, then each workflow may have its own `.env` for overrides. The root `.env.example` documents expected shared variables, while each workflow can provide its own `.env.example` for workflow-specific settings. This separation is important for diagramming config boundaries.

5. **Workflow catalog and discoverability**
`CATALOG.md` is the index of all workflows and their status. It acts as the repo-level registry for what exists, whether it is runnable, and whether it has a deploy target. This is the main human-readable inventory of workflow assets.

6. **Planning and implementation artifacts**
`.agent/plans/` holds implementation plans for workflows. These plans are created up front and then executed during build. `.agent/validation/` holds shared validation assets and smoke-test fixtures. Together, these directories form the repo’s “build intent + verification” layer separate from runtime code.

7. **Claude Code skills as the orchestration layer**
`.claude/skills/` contains reusable prompt workflows used by Claude Code to manage the repo. The important skills are:
- `new-workflow` for scaffolding
- `build` for implementing a planned workflow
- `list-workflows` for surfacing repo status
- `onboard` for orienting a contributor
- `workflow-conventions` for project rules  
These are not runtime components; they are the automation/control plane for developing the repo.

8. **Workflow scaffolding pattern**
The `new-workflow` skill includes templates for different workflow shapes: local-only, Modal-combined, Modal-scheduled, and Modal-webhook. This indicates the repo supports multiple deployment patterns from the same workflow abstraction, with Modal-specific templates only when the workflow needs serverless execution.

9. **Deployment boundary: local vs Modal**
Workflows can run locally as plain Python scripts or be deployed to Modal as serverless endpoints. Modal is optional and only relevant for workflows that expose a `run_modal()` function or similar deployment entrypoint. This creates a clear boundary between script execution and cloud execution.

10. **Representative example**
`workflows/hello-world/` is the canonical example of a completed workflow directory. It contains its own README, env example, and `main.py`, showing the minimum artifact set for a runnable workflow. Use it as the reference node when drawing the workflow-level architecture.

11. **Repository conventions and instructions**
`CLAUDE.md` and `.claude/skills/workflow-conventions/` define how workflows should be structured and operated. These files are part of the project’s governance layer, ensuring new workflows follow the same patterns for env handling, scaffolding, validation, and catalog updates.

12. **High-level data/control flow**
A typical lifecycle is: create a plan in `.agent/plans/` → scaffold a new workflow under `workflows/` → implement and validate it using Claude skills → update `CATALOG.md` → run locally via `main.py` or deploy to Modal. The repo is therefore organized around an AI-assisted workflow lifecycle rather than a single application runtime.

Main entry points: [`workflows/hello-world`](https://github.com/theaiautomators/agentic-workflows/tree/master/workflows/hello-world) (Hello world), [`.claude/skills`](https://github.com/theaiautomators/agentic-workflows/blob/master/.claude/skills) (Skills), [`workflows/hello-world/main.py`](https://github.com/theaiautomators/agentic-workflows/blob/master/workflows/hello-world/main.py) (Main script), [`CLAUDE.md`](https://github.com/theaiautomators/agentic-workflows/blob/master/CLAUDE.md) (CLAUDE.md)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_root["Repo Root"]
  node_claude_md["CLAUDE.md<br/>repo rules<br/>[CLAUDE.md]"]
  node_catalog_md["Catalog<br/>workflow index<br/>[CATALOG.md]"]
  node_requirements_txt["Requirements<br/>shared deps<br/>[requirements.txt]"]
  node_bootstrap_py["Bootstrap<br/>env setup<br/>[bootstrap.py]"]
  node_root_env["Root env<br/>shared config<br/>[.env.example]"]
end

subgraph group_control["AI Control Plane"]
  node_skills_root["Skills<br/>orchestration<br/>[skills]"]
  node_new_workflow_skill["New workflow<br/>scaffold skill<br/>[SKILL.md]"]
  node_workflow_templates["Templates<br/>[templates]"]
  node_list_workflows_skill["List workflows<br/>inventory skill<br/>[SKILL.md]"]
  node_onboard_skill["Onboard<br/>orientation skill<br/>[SKILL.md]"]
  node_conventions_skill["Conventions<br/>governance skill<br/>[SKILL.md]"]
end

subgraph group_lifecycle["Plan & Validate"]
  node_plans_dir["Plans<br/>[plans]"]
  node_plan_template["Plan template<br/>plan scaffold<br/>[_template.md]"]
  node_hello_plan["Hello plan<br/>workflow plan<br/>[hello-world.md]"]
  node_validation_dir["Validation<br/>smoke tests<br/>[validation]"]
  node_smoke_test["Smoke test<br/>validation spec<br/>[smoke-test.md]"]
end

subgraph group_example["Example Workflow"]
  node_hello_workflow["Hello world<br/>workflow example"]
  node_hello_main["Main script<br/>entrypoint<br/>[main.py]"]
  node_hello_readme["Workflow README<br/>workflow docs<br/>[README.md]"]
  node_hello_env["Workflow env<br/>workflow config<br/>[.env.example]"]
end

node_claude_md -->|"defines"| node_conventions_skill
node_claude_md -->|"requires"| node_catalog_md
node_requirements_txt -->|"installed by"| node_bootstrap_py
node_root_env -->|"overridden by"| node_hello_env
node_skills_root -->|"contains"| node_new_workflow_skill
node_skills_root -->|"contains"| node_list_workflows_skill
node_skills_root -->|"contains"| node_onboard_skill
node_skills_root -->|"contains"| node_conventions_skill
node_new_workflow_skill -->|"uses"| node_workflow_templates
node_plans_dir -->|"drives"| node_new_workflow_skill
node_plans_dir -->|"contains"| node_hello_plan
node_plan_template -->|"templates"| node_hello_plan
node_validation_dir -->|"contains"| node_smoke_test
node_list_workflows_skill -->|"reads"| node_catalog_md
node_onboard_skill -->|"references"| node_claude_md
node_conventions_skill -->|"shapes"| node_hello_workflow
node_hello_workflow -->|"entrypoint"| node_hello_main
node_hello_workflow -->|"documents"| node_hello_readme
node_hello_workflow -->|"configures"| node_hello_env
node_hello_plan -->|"implements"| node_hello_workflow
node_hello_main -->|"runs in"| node_hello_workflow
node_hello_main -->|"matches"| node_workflow_templates
node_catalog_md -->|"indexes"| node_hello_workflow

click node_claude_md "https://github.com/theaiautomators/agentic-workflows/blob/master/CLAUDE.md"
click node_catalog_md "https://github.com/theaiautomators/agentic-workflows/blob/master/CATALOG.md"
click node_requirements_txt "https://github.com/theaiautomators/agentic-workflows/blob/master/requirements.txt"
click node_bootstrap_py "https://github.com/theaiautomators/agentic-workflows/blob/master/bootstrap.py"
click node_root_env "https://github.com/theaiautomators/agentic-workflows/blob/master/.env.example"
click node_skills_root "https://github.com/theaiautomators/agentic-workflows/blob/master/.claude/skills"
click node_new_workflow_skill "https://github.com/theaiautomators/agentic-workflows/blob/master/.claude/skills/new-workflow/SKILL.md"
click node_workflow_templates "https://github.com/theaiautomators/agentic-workflows/blob/master/.claude/skills/new-workflow/templates"
click node_list_workflows_skill "https://github.com/theaiautomators/agentic-workflows/blob/master/.claude/skills/list-workflows/SKILL.md"
click node_onboard_skill "https://github.com/theaiautomators/agentic-workflows/blob/master/.claude/skills/onboard/SKILL.md"
click node_conventions_skill "https://github.com/theaiautomators/agentic-workflows/blob/master/.claude/skills/workflow-conventions/SKILL.md"
click node_plans_dir "https://github.com/theaiautomators/agentic-workflows/blob/master/.agent/plans"
click node_plan_template "https://github.com/theaiautomators/agentic-workflows/blob/master/.agent/plans/_template.md"
click node_hello_plan "https://github.com/theaiautomators/agentic-workflows/blob/master/.agent/plans/hello-world.md"
click node_validation_dir "https://github.com/theaiautomators/agentic-workflows/blob/master/.agent/validation"
click node_smoke_test "https://github.com/theaiautomators/agentic-workflows/blob/master/.agent/validation/smoke-test.md"
click node_hello_workflow "https://github.com/theaiautomators/agentic-workflows/tree/master/workflows/hello-world"
click node_hello_main "https://github.com/theaiautomators/agentic-workflows/blob/master/workflows/hello-world/main.py"
click node_hello_readme "https://github.com/theaiautomators/agentic-workflows/blob/master/workflows/hello-world/README.md"
click node_hello_env "https://github.com/theaiautomators/agentic-workflows/blob/master/workflows/hello-world/.env.example"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_claude_md,node_catalog_md,node_requirements_txt,node_bootstrap_py,node_root_env toneBlue
class node_skills_root,node_new_workflow_skill,node_workflow_templates,node_list_workflows_skill,node_onboard_skill,node_conventions_skill toneAmber
class node_plans_dir,node_plan_template,node_hello_plan,node_validation_dir,node_smoke_test toneMint
class node_hello_workflow,node_hello_main,node_hello_readme,node_hello_env toneRose
```

## Components

### Repo Root

Shared conventions, dependency bootstrap, catalog, and agent tooling at the repository level.

- [CLAUDE.md](https://github.com/theaiautomators/agentic-workflows/blob/master/CLAUDE.md): repo rules · Top-level operating rules for contributors and workflow structure. · `CLAUDE.md`
- [Catalog](https://github.com/theaiautomators/agentic-workflows/blob/master/CATALOG.md): workflow index · Repository registry of workflows, status, and deployability. · `CATALOG.md`
- [Requirements](https://github.com/theaiautomators/agentic-workflows/blob/master/requirements.txt): shared deps · Common Python dependency set used by all workflows. · `requirements.txt`
- [Bootstrap](https://github.com/theaiautomators/agentic-workflows/blob/master/bootstrap.py): env setup · Creates the local virtual environment and installs shared dependencies. · `bootstrap.py`
- [Root env](https://github.com/theaiautomators/agentic-workflows/blob/master/.env.example): shared config · Shared source of secrets and API keys for the repo. · `.env.example`

### AI Control Plane

Reusable Claude Code skills that scaffold, orient, and enforce workflow conventions.

- [Skills](https://github.com/theaiautomators/agentic-workflows/blob/master/.claude/skills): orchestration · Reusable Claude Code skills that operate the repository. · `.claude/skills`
- [New workflow](https://github.com/theaiautomators/agentic-workflows/blob/master/.claude/skills/new-workflow/SKILL.md): scaffold skill · Creates workflow skeletons and selects the right deployment template. · `.claude/skills/new-workflow/SKILL.md`
- [Templates](https://github.com/theaiautomators/agentic-workflows/blob/master/.claude/skills/new-workflow/templates): scaffold templates · Local and Modal workflow skeletons for different execution modes. · `.claude/skills/new-workflow/templates`
- [List workflows](https://github.com/theaiautomators/agentic-workflows/blob/master/.claude/skills/list-workflows/SKILL.md): inventory skill · Surfaces repository workflow status and discoverability. · `.claude/skills/list-workflows/SKILL.md`
- [Onboard](https://github.com/theaiautomators/agentic-workflows/blob/master/.claude/skills/onboard/SKILL.md): orientation skill · Orients contributors to the repository and its operating model. · `.claude/skills/onboard/SKILL.md`
- [Conventions](https://github.com/theaiautomators/agentic-workflows/blob/master/.claude/skills/workflow-conventions/SKILL.md): governance skill · Defines the standard workflow structure and repo-wide operating conventions. · `.claude/skills/workflow-conventions/SKILL.md`

### Plan & Validate

Planning artifacts and shared validation assets used before and during workflow implementation.

- [Plans](https://github.com/theaiautomators/agentic-workflows/blob/master/.agent/plans): implementation plans · Pre-build workflow plans and implementation intent artifacts. · `.agent/plans`
- [Plan template](https://github.com/theaiautomators/agentic-workflows/blob/master/.agent/plans/_template.md): plan scaffold · Standard template for new workflow plans. · `.agent/plans/_template.md`
- [Hello plan](https://github.com/theaiautomators/agentic-workflows/blob/master/.agent/plans/hello-world.md): workflow plan · Example implementation plan for the hello-world workflow. · `.agent/plans/hello-world.md`
- [Validation](https://github.com/theaiautomators/agentic-workflows/blob/master/.agent/validation): smoke tests · Shared validation assets and smoke-test fixtures. · `.agent/validation`
- [Smoke test](https://github.com/theaiautomators/agentic-workflows/blob/master/.agent/validation/smoke-test.md): validation spec · Repository-level smoke-test guidance. · `.agent/validation/smoke-test.md`

### Example Workflow

Canonical runnable workflow showing the minimum workflow directory shape.

- [Hello world](https://github.com/theaiautomators/agentic-workflows/tree/master/workflows/hello-world): workflow example · Canonical completed workflow directory showing the minimal runnable shape. · `workflows/hello-world`
- [Main script](https://github.com/theaiautomators/agentic-workflows/blob/master/workflows/hello-world/main.py): entrypoint · Local executable entrypoint and possible Modal deploy function. · `workflows/hello-world/main.py`
- [Workflow README](https://github.com/theaiautomators/agentic-workflows/blob/master/workflows/hello-world/README.md): workflow docs · Workflow-specific usage and implementation notes. · `workflows/hello-world/README.md`
- [Workflow env](https://github.com/theaiautomators/agentic-workflows/blob/master/workflows/hello-world/.env.example): workflow config · Workflow-specific environment overrides and examples. · `workflows/hello-world/.env.example`

## Connections

- CLAUDE.md → Conventions: defines · Repo rules point contributors to the workflow conventions skill.
- CLAUDE.md → Catalog: requires · Repository operating rules depend on keeping the catalog current.
- Requirements → Bootstrap: installed by · Bootstrap uses the shared dependency list to create the local environment.
- Root env → Workflow env: overridden by · Workflow-specific env files extend the shared root configuration.
- Skills → New workflow: contains · The skills directory houses the workflow scaffolding skill.
- Skills → List workflows: contains · The skills directory houses the workflow inventory skill.
- Skills → Onboard: contains · The skills directory houses the contributor onboarding skill.
- Skills → Conventions: contains · The skills directory houses the repo conventions skill.
- New workflow → Templates: uses · Scaffolding chooses among the supported workflow shapes.
- Plans → New workflow: drives · Implementation plans are executed through the workflow scaffolding process.
- Plans → Hello plan: contains · The plans directory stores workflow-specific plans.
- Plan template → Hello plan: templates · The plan template provides the structure used by individual plans.
- Validation → Smoke test: contains · Shared validation assets include smoke-test guidance.
- List workflows → Catalog: reads · The inventory skill surfaces what the catalog records.
- Onboard → CLAUDE.md: references · Onboarding relies on the repo rules and conventions.
- Conventions → Hello world: shapes · Workflow conventions define the expected directory and config shape.
- Hello world → Main script: entrypoint · A workflow directory centers on its main Python script.
- Hello world → Workflow README: documents · Each workflow includes its own usage/readme documentation.
- Hello world → Workflow env: configures · Workflows can carry their own env example for local overrides.
- Hello plan → Hello world: implements · The example plan maps to the example workflow implementation.
- Main script → Hello world: runs in · The script is the local execution boundary for the workflow.
- Main script → Templates: matches · The workflow entrypoint follows one of the scaffolded runtime patterns.
- Catalog → Hello world: indexes · The catalog records the example workflow as part of repository discoverability.