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

```yaml
# 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:

```yaml
# 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:

```yaml
- 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

```yaml
- 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

```bash
# 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)
```yaml
steps:
  - flow: workspace/prepare/go.yaml
  - flow: verify/go-qa.yaml
  - flow: pr/to-dev.yaml
```

### 5.2 Fan-out (parallel repos)
```yaml
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)
```yaml
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.