theaiautomators/agentic-workflows

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.