Skip to content

overview.md

Latest commit

 

History

History
58 lines (38 loc) · 2.66 KB

overview.md

File metadata and controls

58 lines (38 loc) · 2.66 KB
Raw

Overview

@teqfw/github-flows is a TeqFW library for GitHub webhook driven agent execution.

It accepts GitHub webhooks on a fixed ingress, builds one admitted-event model, derives package-owned base attributes from it, resolves zero or one effective profile from workspaceRoot/cfg/, and starts at most one isolated execution for each admitted event.

After one profile is selected, prompt variables may be materialized from admitted-event fields under event.*, host-provided additional attributes under host.*, and preparation-time workspace values under workspace.*.

This package is not a standalone application. The host application owns process lifecycle, runtime infrastructure, and startup orchestration.

Mental Model

The package handles one event at a time:

GitHub event -> admitted-event model -> package-owned base attributes + optional host-provided additional attributes -> merged profiles -> trigger-array expansion -> candidate profile set -> zero or one effective profile -> launch contract -> one isolated run

Important boundaries:

  • one event may produce zero or one execution
  • profile selection is deterministic and attribute-based
  • the persisted effective profile records the selected expanded scalar trigger values rather than trigger arrays as active matching conditions
  • prompt variables are applied after profile selection
  • host-provided attributes may be reused as explicit host.* prompt-variable sources for that same event
  • cross-event orchestration is outside the package

Documentation Map

Use these guides in this order:

  1. single-event-launch.md for configuring one agent run for one GitHub event.
  2. profile-layout.md for structuring cfg/, profile fragments, and matching logic.
  3. profile-example.md for one complete fragment example with trigger, handler, prompt variables, and runtime fields together.
  4. event-attributes.md for available matching inputs and host-provided attributes.
  5. event-chains.md for designing multi-step automation as independent stages triggered by GitHub repository events.

Typical Use

Use the package when you need:

  • a fixed GitHub webhook ingress
  • deterministic event-to-profile routing
  • one isolated execution per admitted event
  • host-controlled runtime and deployment

Do not use the package as:

  • a workflow engine
  • a cross-event state machine
  • a standalone GitHub bot application

Runtime Entry Points

The public package surface starts with:

  • Github_Flows_Config_Runtime
  • Github_Flows_Event_Attribute_Provider_Holder
  • Github_Flows_Web_Server
  • Github_Flows_Web_Handler_Webhook