# AgentFlow Runtime Reference

## Workspaces

- `pipelineWorkspace`: the original workspace that owns the AgentFlow pipeline run.
- `workspaceRoot`: current execution workspace. Before CD Workspace it is usually the pipeline workspace; after CD Workspace it becomes the selected project directory.
- `cwd`: current runtime working directory, normally same as `workspaceRoot`.
- `flowDir`: absolute directory containing the current `flow.yaml`.

## Pipeline Locations

- Builtin pipelines: `builtin/pipelines/<flowId>/flow.yaml`
- Workspace pipelines: `.workspace/agentflow/pipelines/<flowId>/flow.yaml`
- User pipelines: `~/agentflow/pipelines/<flowId>/flow.yaml`
- Pipeline scripts: `<flowDir>/scripts/*`
- Flow-local nodes: `<flowDir>/nodes/*.md`

## Run Directory

Each run writes under:

```text
<pipelineWorkspace>/.workspace/agentflow/runBuild/<flowName>/<uuid>/
```

Important files:

- `intermediate/flow.json`: parsed graph snapshot.
- `intermediate/<instanceId>/<instanceId>.prompt.md`: prompt used by a node.
- `intermediate/<instanceId>/<instanceId>.result.md`: node status and result body.
- `intermediate/<instanceId>/<instanceId>.cache.json`: cache metadata.
- `output/<instanceId>/node_<instanceId>_<slot>.md`: output slot files.
- `logs/log.txt`: run events and CLI logs.

## Context Objects

`workspaceContext` is a JSON text value passed between nodes:

```json
{
  "version": 1,
  "label": "workspace",
  "cwd": "/abs/current/workspace",
  "workspaceRoot": "/abs/current/workspace",
  "pipelineWorkspace": "/abs/pipeline/workspace",
  "flowDir": "/abs/flow/dir",
  "previous": null
}
```

`skillsContext` is a JSON text value generated by Load Skills and consumed by downstream agent/tool nodes. It contains selected skill metadata and loaded SKILL.md bodies.

## Git / CD Behavior

- `tool_git_checkout` outputs `workspaceContext` whose `workspaceRoot` is the checked-out repository path.
- `control_cd_workspace` changes downstream execution workspace.
- If Git Checkout is immediately followed by CD Workspace, connect `workspaceContext` and set CD `target` to `.`.
- Do not connect `repoPath:file` to `target:text`; use `workspaceContext` instead.

## Output Resolution

- Edge values are resolved by handle index.
- File slots usually pass paths; text slots may read upstream output file content.
- `display_*.content` should receive the text to render. Pick the display type that matches the payload (`display_markdown`, `display_html`, `display_table`, `display_chart`, …).