agent/docs/flow/RFC.md

core/agent/flow RFC — YAML-Defined Agent Workflows

The authoritative spec for the Flow system — declarative, composable, path-addressed agent workflows. No code changes needed to improve agent capability. Just YAML + rebuild.

Package: core/agent (pkg/lib/flow/) Repository: dappco.re/go/agent Related: Pipeline Orchestration (core/agent/RFC.pipeline.md)

---

1. Overview

Flows are YAML definitions of agent workflows — tasks, prompts, verification steps, security gates. They're composable: flows call other flows. They're path-addressed: the file path IS the semantic meaning.

1.1 Design Principle

Path = semantics. The same principle as dAppServer's unified path convention:

flow/deploy/from/forge.yaml    ← pull from Forge
flow/deploy/to/forge.yaml      ← push to Forge (opposite direction)

flow/workspace/prepare/go.yaml
flow/workspace/prepare/php.yaml
flow/workspace/prepare/devops.yaml

An agent navigating by path shouldn't need a README to find the right flow.

1.2 Why This Matters

• Scales without code: Add a flow YAML, rebuild, done. 20 repos → 200 repos with same effort.
• Separates what from how: Flow YAML = intent (what to do). Go code = mechanics (how to do it).
• Self-healing: Every problem encountered improves the flow. DevOps lifecycle: hit problem → fix flow → automated forever.
• Autonomous pipeline: Issue opened → PR ready for review, without human or orchestrator touching it.

---

2. Flow Structure

2.1 Basic Flow

# flow/verify/go-qa.yaml
name: Go QA
description: Build, test, vet, lint a Go project

steps:
  - name: build
    run: go build ./...

  - name: test
    run: go test ./...

  - name: vet
    run: go vet ./...

  - name: lint
    run: golangci-lint run

2.2 Composed Flow

Flows call other flows via flow: directive:

# flow/implement/security-scan.yaml
name: Security Scan Implementation
description: Full lifecycle — prepare, plan, implement, verify, PR

steps:
  - name: prepare
    flow: workspace/prepare/go.yaml

  - name: plan
    agent: spark
    prompt: "Create a security scan implementation plan"

  - name: implement
    agent: codex
    prompt: "Implement the plan"

  - name: verify
    flow: verify/go-qa.yaml

  - name: pr
    flow: pr/to-dev.yaml

2.3 Agent Steps

Steps can dispatch agents with specific prompts:

- name: implement
  agent: codex                    # Agent type
  prompt: |                       # Task prompt
    Read CODEX.md and the RFC at .core/reference/docs/RFC.md.
    Implement the security scan findings.
  template: coding                # Prompt template
  timeout: 30m                    # Max runtime

2.4 Conditional Steps

- name: check-language
  run: cat .core/manifest.yaml | grep language
  output: language

- name: go-verify
  flow: verify/go-qa.yaml
  when: "{{ .language == 'go' }}"

- name: php-verify
  flow: verify/php-qa.yaml
  when: "{{ .language == 'php' }}"

---

3. Path Convention

3.1 Directory Layout

pkg/lib/flow/
├── deploy/
│   ├── from/
│   │   └── forge.yaml          # Pull from Forge
│   └── to/
│       ├── forge.yaml          # Push to Forge
│       └── github.yaml         # Push to GitHub
├── implement/
│   ├── security-scan.yaml
│   └── upgrade-deps.yaml
├── pr/
│   ├── to-dev.yaml             # Create PR to dev branch
│   └── to-main.yaml            # Create PR to main branch
├── upgrade/
│   ├── v080-plan.yaml          # Plan v0.8.0 upgrade
│   └── v080-implement.yaml     # Implement v0.8.0 upgrade
├── verify/
│   ├── go-qa.yaml              # Go build+test+vet+lint
│   └── php-qa.yaml             # PHP pest+pint+phpstan
└── workspace/
    └── prepare/
        ├── go.yaml             # Prepare Go workspace
        ├── php.yaml            # Prepare PHP workspace
        ├── ts.yaml             # Prepare TypeScript workspace
        ├── devops.yaml         # Prepare DevOps workspace
        └── secops.yaml         # Prepare SecOps workspace

3.2 Naming Rules

• Verbs first: deploy/, implement/, verify/, prepare/
• Direction explicit: from/forge vs to/forge
• Language suffixed: verify/go-qa vs verify/php-qa
• No abbreviations: workspace not ws, implement not impl

---

4. Execution Model

4.1 Flow Runner

The Go runner in pkg/lib/flow/ executes flows:

1. Load YAML flow definition
2. Resolve flow: references (recursive)
3. Execute steps sequentially
4. Capture output variables
5. Evaluate when: conditions
6. Dispatch agents via Core IPC (runner.dispatch Action)
7. Collect results

4.2 CLI Interface

# Run a flow directly
core-agent run flow pkg/lib/flow/verify/go-qa.yaml

# Dry-run (show what would execute)
core-agent run flow pkg/lib/flow/verify/go-qa.yaml --dry-run

# Run with variables
core-agent run flow pkg/lib/flow/upgrade/v080-implement.yaml --var repo=core/go

---

5. Composition Patterns

5.1 Pipeline (sequential)

steps:
  - flow: workspace/prepare/go.yaml
  - flow: verify/go-qa.yaml
  - flow: pr/to-dev.yaml

5.2 Fan-out (parallel repos)

steps:
  - name: upgrade-all
    parallel:
      - flow: upgrade/v080-implement.yaml
        var: { repo: core/go }
      - flow: upgrade/v080-implement.yaml
        var: { repo: core/go-io }
      - flow: upgrade/v080-implement.yaml
        var: { repo: core/go-log }

5.3 Gate (human approval)

steps:
  - flow: implement/security-scan.yaml
  - name: review-gate
    gate: manual
    prompt: "Security scan complete. Review PR before merge?"
  - flow: pr/merge.yaml

---

6. End State

core-agent CLI runs as a native Forge runner:

1. Forge webhook fires (issue created, PR updated, push event)
2. core-agent picks up the event
3. Selects appropriate flow based on event type + repo config
4. Runs flow → handles full lifecycle
5. No GitHub Actions, no external CI
6. All compute on our hardware
7. Every problem encountered → flow improvement → automated forever

---

7. Reference Material

Resource	Location
core/agent	Flows dispatch agents via Core IPC
core/agent/plugins	Flows reference agent types (codex, spark, claude)
dAppServer	Unified path convention = same design principle
core/config	.core/ convention for workspace detection

---

Changelog

• 2026-03-27: Initial RFC promoted from memory + existing flow files. Path-addressed, composable, declarative.