zenflow: Instructions file for Codex

AGENTS.md - zenflow

Instructions for AI contributors working on the zenflow codebase.

Commands

go build ./...                  # Build library
go build ./cmd/zenflow/         # Build CLI
go test ./...                   # Test all packages
go test -cover ./...            # Test with coverage
golangci-lint run               # Lint
./scripts/smoke-examples.sh     # Vet + build all 18 embedding examples
go test -tags e2e ./...         # Real-LLM integration tests (needs API keys)

Architecture

zenflow is a declarative multi-agent workflow engine for Go. Workflows are YAML; the engine is a DAG executor with an LLM coordinator that narrates progress and routes events through hub-and-spoke mailboxes. The Go SDK layer is goai - any provider goai supports works as a zenflow agent backend.

zenflow/
├── doc.go                      # Package zenflow doc.
├── interfaces.go               # Storage/Tracer/StepIsolation/ApprovalHandler aliases (root facade)
├── workflow.go                 # Workflow / Step / StepResult / WorkflowResult / Run aliases (root facade)
├── duration.go                 # Duration alias + FormatDuration / ParseDurationStrict re-exports
├── router_facade.go            # Re-exports for internal/router/ public API
├── transcript_facade.go        # Re-exports for internal/resume/ public API
├── coord_facade.go             # Re-exports for internal/coord/ tool factories
├── agent_facade.go             # Re-exports for internal/exec/ AgentRunner ecosystem (AgentRunner, AgentResult, 22 WithRunner*, AgentHandle, sentinels)
├── orchestrator_facade.go      # Re-exports for internal/exec/ Orchestrator + the With* option set (incl. WithSystemPromptSuffix / WithSkills) + Executor + Storage backends + parsers + coord factory + JSON coordinator + ~60 utility symbols
├── internal/
│   ├── types/                  # Event, EventType, MessageKind, Output, ProgressSink, PermissionHandler/Request (leaf, no deps on root)
│   ├── spec/                   # Workflow / Step / Run / StepResult / AgentConfig / Duration types + Storage / Tracer / StepIsolation / ApprovalHandler / ModelResolver interface contracts + parser & validator helpers
│   ├── router/                 # MessageRouter, MailboxStore, deliveryEngine (race-safe send/wake)
│   ├── resume/                 # TranscriptStore, InMemoryTranscriptStore
│   ├── coord/                  # RunnerHandle interface + 4 coord goai.Tool factories (forward_to_agent, send_message, narrate, finalize)
│   └── exec/                   # AgentRunner + Executor + Orchestrator + JSON coordinator + RunFlow/RunGoal/RunAgent + ResumeFlow + the With* option set + Storage backends (MemoryStorage, FileStorage) + SharedMemory + parsers + validators + scheduler + CEL evaluator + portability lints + isolation default + lifecycle + prompt assembly + progressive-disclosure skills (skills.go: LoadSkills / read_skill / WithSkills) + 16 source files moved from root
├── cmd/zenflow/
│   ├── main.go                 # CLI entrypoint
│   ├── flags.go                # Shared flag parser
│   ├── cmd_*.go                # Subcommand handlers (flow, goal, agent, validate, plan)
│   ├── orchestrator_opts.go    # Build orchestrator from CLI flags
│   ├── provider.go             # Provider resolver
│   ├── thinking.go             # --thinking flag
│   ├── trace_otel.go           # --trace flag
│   ├── signals.go              # Signal handling
│   ├── workdir.go              # Working directory helper
│   ├── permission.go           # Interactive permission gate
│   ├── stdout_sink.go          # CLI human-readable sink
│   ├── color.go                # ANSI color helpers (auto-detect TTY)
│   ├── dag/                    # DAG plan helpers
│   └── tool/                   # CLI-only IO tools (bash/read/write/glob/grep)
├── sink/
│   ├── json.go                 # NDJSON event stream
│   ├── buffered.go             # ClosableProgressSink wrapping any sink with bounded queue
│   └── lifecycle.go            # Sink lifecycle helpers (graceful shutdown / Close())
├── examples/                   # 18 //go:build example mains
└── spec/v1/
    ├── schema.json             # JSON Schema (workflow validation)
    ├── spec.md                 # Authoritative YAML specification
    ├── examples/               # 20 reference workflows
    └── testcases/              # Conformance fixtures