# vxcozy/workflow-orchestration architecture

> Architecture diagram of the GitHub repository vxcozy/workflow-orchestration, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-03-09). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/vxcozy/workflow-orchestration
- Repository: https://github.com/vxcozy/workflow-orchestration

## Overview

##### What this project is (type + purpose)

This repo is **not an application runtime** (no `src/`, no services, no code modules). It’s a **portable “skill” package** for AI coding agents (AgentSkills-compatible), intended to be installed into an agent environment (e.g., Claude Code, Cursor, Copilot) to enforce a disciplined workflow: planning, delegation, verification, and self-improvement loops.

- **The host agent runtime** (external)
- **This skill package** (static assets + instructions)
- **The user’s project workspace** where tasks and outputs are created
- **Optional supporting artifacts** created during use (`tasks/todo.md`, lessons, etc.)

Treat it like a **plugin / policy module** rather than a service.

##### Architecture cues from the file tree

Top-level contents:

- `SKILL.md` — the *core entrypoint* (what gets loaded/executed by the agent runtime)
- `docs/` — Diataxis docs for onboarding and usage patterns
- `references/` — canonical formats/templates and detailed reference behavior
- `README.md`, `LICENSE`, `.gitignore`
- No executables, no language build files, no dependencies → this is **documentation-driven orchestration**.

##### What to capture from the README (behavioral architecture)

Key functional “subsystems” described:

- **Plan Mode** (create and follow a plan; often `tasks/todo.md`)
- **Subagent Delegation** (offload to subagents to keep main context clean)
- **Verification** (prove completeness before done)
- **Self-Improvement** (capture corrections/lessons; feed back into future runs)
- **Autonomous Fixing** (reduce user burden)
- **Activation modes**: direct invocation (`/workflow-orchestration`) or automatic triggers (3+ steps, bugfixes, refactors)

These are best represented as **a state machine / workflow loop** layered over the host agent.

##### User
- provides goal, constraints, reviews verification results

##### Agent Runtime (external) (e.g., Claude Code / Cursor / Copilot / Gemini CLI)
- executes instructions, manages context, may spawn subagents
- *owns* the execution environment; this repo plugs into it

##### Workflow Orchestration Skill (this repo)
- **SKILL.md** (primary “controller” instruction set)
- **Docs (Diataxis)**: tutorial/howto/explanation (human learning + correct usage)
- **References/Templates**: reference spec, task templates, lessons format (standardized artifacts)

##### Workspace Artifacts (in the user’s project)
- `tasks/todo.md` plan/progress tracker (explicitly mentioned)
- optional “lessons” file(s) based on `references/lessons-format.md`
- any code changes produced by executing the plan (outside this repo)

##### Subagents (optional, spawned by agent runtime)
- handle focused subtasks; return results to main agent

- **Orchestration Policy** (from `SKILL.md`)
- **Planning/Task Tracking Format** (from `references/task-templates.md`)
- **Verification Checklist/Method** (from `references/REFERENCE.md`)
- **Learning Capture Format** (from `references/lessons-format.md`)

- User → Agent Runtime: task request / feedback
- Agent Runtime → Skill (SKILL.md): loads skill content; uses it to decide behavior
- Skill → Agent Runtime: prescribes phases (Plan → Execute → Verify → Learn)
- Agent Runtime ↔ Workspace: reads/writes `tasks/todo.md`, edits code, runs checks
- Agent Runtime → Subagents: delegates subtasks
- Subagents → Agent Runtime: returns findings/patches/summaries
- Verification results → User: proof-of-done, test outputs, checklist completion
- Lessons learned → Workspace Artifacts: persistent learning notes/templates for future tasks

##### Architectural pattern

This is essentially:

- **Plugin/Skill architecture** (static skill instructions loaded by a host)
- **Workflow/state-machine overlay** on agent execution
- **Artifact-driven process control** (plans, checklists, lessons are first-class objects)

Call out that the “business logic” is **procedural guidance**, not code.

##### Relevant technologies / standards

- **AgentSkills-compatible** skill package
- **Diataxis documentation model** (`docs/tutorial.md`, `docs/howto.md`, `docs/explanation.md`, and `references/REFERENCE.md`)
- **Invocation modes**: `/workflow-orchestration` and **automatic activation conditions**
- **Artifacts**: `tasks/todo.md`, “lessons” format, templates

## Diagram (Mermaid)

```mermaid
flowchart TD
  %% =========================
  %% Diagram 1: System Context
  %% =========================
  subgraph "System Context (Plugin/Skill Integration)"
    direction TB

    User["User"]:::external

    subgraph "Host Agent Environment (External Runtime)"
      direction TB
      AgentRuntime["Agent Runtime (Claude Code / Cursor / Copilot / Gemini CLI)"]:::runtime

      Trigger["Activation\n- Manual: /workflow-orchestration\n- Auto: 3+steps | bugfix | refactor"]:::event

      Subagents["Subagents (optional, spawned)"]:::subagent
    end

    subgraph "Workflow Orchestration Skill Package (This Repo)"
      direction TB
      SkillEntry["SKILL.md (Skill Entrypoint / Orchestration Policy)"]:::skill

      subgraph "Docs (Diataxis)"
        direction TB
        DocsRoot["Docs/"]:::docs
        Tutorial["Tutorial (Onboarding)"]:::docs
        HowTo["How-To (Usage Patterns)"]:::docs
        Explanation["Explanation (Rationale/Concepts)"]:::docs
      end

      subgraph "References & Templates"
        direction TB
        ReferencesRoot["References/"]:::refs
        ReferenceSpec["REFERENCE.md (Verification Checklist/Method)"]:::refs
        TaskTemplates["task-templates.md (Plan/Task Tracking Format)"]:::refs
        LessonsFormat["lessons-format.md (Learning Capture Format)"]:::refs
      end
    end

    subgraph "User Project Workspace (Target)"
      direction TB
      Workspace["Project Workspace (User Codebase + Files)"]:::workspace
      Todo["tasks/todo.md (Plan/Progress Tracker)"]:::artifact
      Lessons["Lessons (persistent notes in lessons format)"]:::artifact
      CodeChanges["Code Changes (implementation outputs)"]:::artifact
    end
  end

  %% Context relationships (vertical, information/control flow)
  User -->|"requests_goal+constraints"| AgentRuntime
  User -->|"reviews_results+feedback"| AgentRuntime

  AgentRuntime -->|"invokes_or_auto-activates"| Trigger
  Trigger -->|"loads_skill_content"| SkillEntry

  SkillEntry -->|"prescribes_phases(Plan→Execute→Verify→Learn)"| AgentRuntime
  SkillEntry -->|"consults"| DocsRoot
  SkillEntry -->|"uses_standards/templates"| ReferencesRoot

  AgentRuntime <-->|"reads/writes"| Workspace
  AgentRuntime -->|"writes_plan/progress"| Todo
  AgentRuntime -->|"produces"| CodeChanges
  AgentRuntime -->|"captures_lessons"| Lessons

  AgentRuntime -->|"delegates_subtasks"| Subagents
  Subagents -->|"returns_summary/patch/findings"| AgentRuntime

  AgentRuntime -->|"presents_verification_proof"| User

  ReferenceSpec -->|"drives_verification_checklist"| AgentRuntime
  TaskTemplates -->|"structures_plans_and_tasks"| Todo
  LessonsFormat -->|"structures_learning_notes"| Lessons

  %% =========================
  %% Diagram 2: Workflow Loop
  %% =========================
  subgraph "Workflow Loop (Behavior / State Machine Overlay)"
    direction TB

    Start["Start"]:::event
    Decide["Activation Decision\n(manual command or auto trigger)"]:::event

    Plan["Plan Mode\nCreate/Update tasks/todo.md"]:::phase
    Execute["Execute Steps\nEdit code / run commands"]:::phase
    Delegate["Delegate (Optional)\nSpawn subagents for focused work"]:::phase
    Verify["Verification\nChecklist + tests + completeness proof"]:::phase
    FixLoop{"Complete?\nAll checks pass"}:::decision
    Learn["Self-Improvement\nCapture lessons in workspace"]:::phase
    Done["Done\nDeliver results + proof"]:::event
  end

  %% Workflow relationships
  Start --> Decide
  Decide -->|"activated"| Plan
  Plan -->|"tracks_progress_in"| Todo
  Plan --> Execute
  Execute -->|"optional"| Delegate
  Delegate -->|"returns_results"| Execute
  Execute --> Verify
  Verify --> FixLoop
  FixLoop -->|"no: gaps/failures"| Execute
  FixLoop -->|"yes"| Learn
  Learn -->|"write_lessons"| Lessons
  Learn --> Done
  Done -->|"report_to_user"| User

  %% Cross-links to references/specs
  Verify -->|"follows"| ReferenceSpec
  Plan -->|"follows"| TaskTemplates
  Learn -->|"follows"| LessonsFormat
  Decide -->|"uses_entrypoint_policy"| SkillEntry

  %% =========================
  %% Click Events (from mapping)
  %% =========================
  click SkillEntry "https://github.com/vxcozy/workflow-orchestration/blob/main/SKILL.md"
  click DocsRoot "https://github.com/vxcozy/workflow-orchestration/tree/main/docs/"
  click Tutorial "https://github.com/vxcozy/workflow-orchestration/blob/main/docs/tutorial.md"
  click HowTo "https://github.com/vxcozy/workflow-orchestration/blob/main/docs/howto.md"
  click Explanation "https://github.com/vxcozy/workflow-orchestration/blob/main/docs/explanation.md"
  click ReferencesRoot "https://github.com/vxcozy/workflow-orchestration/tree/main/references/"
  click ReferenceSpec "https://github.com/vxcozy/workflow-orchestration/blob/main/references/REFERENCE.md"
  click LessonsFormat "https://github.com/vxcozy/workflow-orchestration/blob/main/references/lessons-format.md"
  click TaskTemplates "https://github.com/vxcozy/workflow-orchestration/blob/main/references/task-templates.md"

  %% =========================
  %% Styles
  %% =========================
  classDef external fill:#FDE68A,stroke:#B45309,stroke-width:1px,color:#111827
  classDef runtime fill:#E5E7EB,stroke:#374151,stroke-width:1px,color:#111827
  classDef skill fill:#93C5FD,stroke:#1D4ED8,stroke-width:1px,color:#0B1220
  classDef docs fill:#BFDBFE,stroke:#2563EB,stroke-width:1px,color:#0B1220
  classDef refs fill:#A7F3D0,stroke:#047857,stroke-width:1px,color:#052e2b
  classDef workspace fill:#DDD6FE,stroke:#6D28D9,stroke-width:1px,color:#111827
  classDef artifact fill:#FFFFFF,stroke:#6B7280,stroke-width:1px,color:#111827
  classDef subagent fill:#FBCFE8,stroke:#BE185D,stroke-width:1px,color:#111827,stroke-dasharray: 4 3
  classDef phase fill:#C7D2FE,stroke:#4338CA,stroke-width:1px,color:#111827
  classDef event fill:#FEF3C7,stroke:#D97706,stroke-width:1px,color:#111827
  classDef decision fill:#FFE4E6,stroke:#9F1239,stroke-width:1px,color:#111827
```
