​

Agents and connectors

• which agents exist
• what they are allowed to do
• which prompt owns sequencing
• how artifacts project into connector targets

​

Agent SAF files

• who the agent is
• which generic kind of work it owns
• which prompt file it uses
• which workflow and coding tools it may call

​

SAF format

​

Example

{
  "saf_version": "1.0.0",
  "agent": {
    "id": "planner",
    "name": "Planner",
    "kind": "planning"
  },
  "system_prompt": "prompts/planner.md",
  "tools": {
    "workflow": [
      "capabilities",
      "workflow_get",
      "artifact_type_get",
      "artifact_list",
      "artifact_get",
      "artifact_validate",
      "artifact_create",
      "artifact_update",
      "relation_add",
      "relation_list"
    ],
    "coding": [
      "read_file",
      "web_search",
      "fetch"
    ]
  }
}

​

Field-by-field guidance

• saf_version
  • Keep this at the SAF version Fabriqa supports.
• agent.id
  • Must stay stable because workflows reference agents by ID in workflow.yaml.
• agent.kind
  • Declares the generic Fabriqa behavior this agent participates in.
  • Use planning for agents that coordinate, inspect, and shape work.
  • Use execution for agents that perform execution work.
  • Keep it consistent with tools.coding. Planning agents should not declare execute or "full". Execution agents should declare execute or "full".
• system_prompt
  • Should point to a markdown file in prompts/.
  • Put long behavior instructions there instead of embedding them in JSON.
• tools.workflow
  • Declare the workflow tools the agent is allowed to use.
  • This is always a subset selected from Fabriqa’s predefined workflow-tool list.
• tools.coding
  • Declare coding and external-read tools.
  • This is always a subset selected from Fabriqa’s predefined coding-tool list, or the special "full" mode.

​

Runtime ownership

• ACP decorator policy
• LLM provider capability requirements
• runtime-specific builtin tool allowlists
• per-agent budget or max-turn transport policy

​

tools.workflow

• routing or coordinator agents usually need a read-oriented subset such as capabilities, workflow_get, artifact_list, artifact_get, and relation_list
• planning agents usually add artifact_validate, artifact_create, artifact_update, and sometimes workspace_project_list
• execution agents usually add workflow_ready, workflow_claim, and artifact_complete

​

tools.coding

"coding": []

"coding": ["read_file", "fetch"]

"coding": "full"

• omit coding or use [] for no coding-tool access
• use a string list when the agent needs only a narrow subset
• use "full" when the agent needs unrestricted coding-tool access
• "full" is a mode, not a tool name
• there is no authored "read_only" literal in the SAF format

• planning agents usually use read_file, web_search, and fetch
• operations-style agents may add execute
• implementation agents typically use "full"

• workflow authors cannot invent custom coding tool names
• if a SAF file declares an unknown coding tool, Fabriqa should reject the workflow definition during validation and loading

​

Example: AI-DLC inception

{
  "saf_version": "1.0.0",
  "agent": {
    "id": "inception",
    "name": "Inception",
    "kind": "planning"
  },
  "system_prompt": "prompts/inception.md",
  "tools": {
    "workflow": [
      "capabilities",
      "workflow_get",
      "artifact_type_get",
      "artifact_list",
      "artifact_get",
      "artifact_validate",
      "artifact_create",
      "artifact_update",
      "relation_add",
      "relation_list"
    ],
    "coding": [
      "read_file",
      "web_search",
      "fetch"
    ]
  }
}

• system_prompt points to prompts/inception.md, which contains the actual planning ritual and sequencing rules
• agent.kind marks Inception as a planning agent, so Fabriqa treats it as planning behavior instead of execution behavior
• tools.workflow gives Inception the planning subset it needs to inspect, validate, create, update, and relate workflow artifacts
• tools.coding is intentionally narrow because Inception is a planning agent, not a coding agent

• SAF defines the portable agent contract
• prompt defines the behavior

​

SAF guidance

• Put long behavior instructions in the prompt file, not in the SAF JSON itself.
• Keep the agent object minimal: id, name, and kind.
• Use agent.kind to declare generic planning versus execution behavior.
• Keep workflow tool access explicit and minimal.
• Treat coding tool access as part of the workflow contract.
• Select both tools.workflow and tools.coding from Fabriqa’s predefined vocabularies.
• Expect workflow validation to fail if a SAF file uses an unknown tool name.
• Do not encode ACP or provider-specific behavior in the SAF file.

​

Prompt responsibilities

• when to create a run
• when to create a bolt
• when to create design docs
• when to create execution outputs
• when to replan
• when to complete work

​

Good prompt boundary

• sequencing
• prioritization
• whether to replan
• whether a new output artifact is needed

• what artifacts exist
• what each artifact means
• which parent association is required
• which fields are required
• how the artifact renders

​

Connector configs

• subscribes to built-in connector kinds in workflow.yaml
• provides connector-specific mapping files in connectors/*.yaml

​

File connector

# workflow.yaml
connectors:
  file: connectors/file.yaml

# connectors/file.yaml
kind: file

artifacts:
  walkthrough:
    template: templates/walkthrough.md.tmpl
    filename: walkthroughs/{{ artifact.display_id }}.md

• markdown snapshots of artifacts
• handoff docs in the repo
• workflow-friendly exports for code review and history

​

Future platform connectors

# connectors/linear.yaml
kind: linear

objects:
  work_item:
    target: issue
    fields:
      title: title
      description: description
      tags: labels

​

Runtime settings live in Fabriqa

• connector enable or disable state
• connection or account selection
• target workspace project selection
• sync state and execution behavior

​

Authoring checklist

1. Keep workflow.yaml orchestration-focused.
2. Keep artifact-local meaning in the artifact schema file.
3. Prefer markdown sections for the main body of documents.
4. Keep primitive status and scope fields in schema.properties and let Fabriqa surface them as metadata automatically when they are not used by a document section.
5. Write description on every field that an agent could misread.
6. Keep artifact behavior in prompts and keep artifact schemas structural.
7. Keep the prompt responsible for sequencing.
8. Add connector config files only when the workflow needs projection or sync.
9. Keep runtime connector settings out of the DSL.

​

Related pages