Orchestrator Flow Specifications

Specifications specific to the ubFlow Orchestrator agent. Each FLSP_ links back to one or more FLST_ via :satisfies:.

Note

Shared specifications (applying to all agents) live in shared/flow_specs.rst.

Needs Authoring

Flow Spec: flowinst and flowskill described as RST directives FLSP_UBFLOW_003

status: draft tags: ubflow satisfies: FLST_UBFLOW_005 implemented_by: FLIN_UBFLOW_002

Every behavioral rule of an agent shall be described as a .. flowinst:: directive and every procedural knowledge item shall be described as a .. flowskill:: directive inside an RST file of the Sphinx-Needs project. Each object requires at minimum the fields :id:, :status:, and :tags:.

Flow Spec: flowinst separates what from how FLSP_UBFLOW_004

status: draft tags: ubflow satisfies: FLST_UBFLOW_005 implemented_by: FLIN_UBFLOW_003 supported_by: FLSK_UBFLOW_002

A flowinst shall describe exclusively what the agent must do (a behavioral obligation). It must not contain step-by-step procedures. A flowskill shall describe exclusively how the agent performs a task (a reusable, step-by-step procedure). No flowinst may contain procedural content; that content belongs in a flowskill.

Flow Spec: flowinst and flowskill link to a flowspec FLSP_UBFLOW_005

status: draft tags: ubflow satisfies: FLST_UBFLOW_006 implemented_by: FLIN_UBFLOW_004

Every flowinst shall reference at least one flowspec via its :implements: field. Every flowskill shall reference at least one flowspec via its :supports: field. Orphaned instructions or skills that have no specification link are not permitted.

Flow Spec: agent need as single identity object FLSP_UBFLOW_006

status: draft tags: ubflow satisfies: FLST_UBFLOW_007 implemented_by: FLIN_UBFLOW_005

An agent shall be defined by exactly one .. agent:: directive in the Sphinx-Needs project. This object shall contain the agent’s human-readable name, a unique :id:, :status:, :tags:, links to all its behavioral instructions via :applies:, and links to all its skills via :employs:.

Flow Spec: agent need as complete aggregation point FLSP_UBFLOW_007

status: draft tags: ubflow satisfies: FLST_UBFLOW_008 implemented_by: FLIN_UBFLOW_006

The agent need object shall be the single entry point from which all behavioral rules and skills of an agent can be fully resolved. Every flowinst belonging to an agent must be reachable via :applies: and every flowskill via :employs:. No instruction or skill may belong to an agent without being referenced from that agent’s need object.

Agent Lifecycle

Flow Spec: Step-by-step agent creation workflow FLSP_UBFLOW_008

status: draft tags: ubflow satisfies: FLST_UBFLOW_001 implemented_by: FLIN_UBFLOW_007 supported_by: FLSK_UBFLOW_003

When a user requests creation of a new agent, ubFlow shall guide through the following steps in order, waiting for user confirmation before proceeding to the next: Identify or create the agentfamily need in the target project. Author flowstory needs that capture the agent’s motivation. Derive flowspec needs from the stories. Derive flowinst and flowskill needs from the specs. Generate the .agent.md file as a minimal bootstrap referencing the agent’s need ID.

Flow Spec: Agent creation verifies all linked IDs via MCP before writing FLSP_UBFLOW_009

status: draft tags: ubflow satisfies: FLST_UBFLOW_001 supported_by: FLSK_UBFLOW_003

Before generating a .agent.md file ubFlow shall retrieve the target agent need object via the ubCode MCP server and verify that every ID referenced via :applies: and :employs: can be resolved. If any ID is unresolvable, ubFlow shall report the missing IDs and abort generation. No instruction or skill text shall be inlined into the .agent.md file; the file contains only a bootstrap block that loads behavior at runtime.

Flow Spec: Agent review supports three selectable check modes FLSP_UBFLOW_010

status: draft tags: ubflow satisfies: FLST_UBFLOW_002, FLST_UBFLOW_003 implemented_by: FLIN_UBFLOW_008 supported_by: FLSK_UBFLOW_004

ubFlow shall support three review modes for an existing .agent.md file: Syntactic: valid Markdown frontmatter, all required sections present, correct heading hierarchy. Semantic: instructions are behavioral obligations (no procedures embedded), skills are step-by-step procedures (no bare obligations). Traceability: every FLIN_ and FLSK_ ID referenced in the file exists and is resolvable via the ubCode MCP server. The user may select one, several, or all modes. ubFlow shall run only the selected checks and report results per mode.

Flow Spec: Traceability review resolves every instruction and skill ID FLSP_UBFLOW_011

status: draft tags: ubflow satisfies: FLST_UBFLOW_004 implemented_by: FLIN_UBFLOW_008 supported_by: FLSK_UBFLOW_004

During a traceability review ubFlow shall query every FLIN_ and FLSK_ ID found in the .agent.md file against the ubCode MCP server. Any ID that cannot be resolved shall be reported as a traceability violation including the line in the agent file where it appears and a suggested remediation (create the missing need or correct the ID).

MCP Bootstrap

Flow Spec: Minimal bootstrap-only .agent.md FLSP_UBFLOW_012

status: draft tags: ubflow satisfies: FLST_UBFLOW_009 implemented_by: FLIN_UBFLOW_009

The .agent.md file generated by ubFlow shall contain only a single bootstrap instruction block. This block identifies the agent by its Sphinx-Needs ID and instructs it to load all flowinst and flowskill objects at session start via the ubCode MCP server. No instruction or skill text shall be inlined into the file; the Sphinx-Needs project is the single source of truth for all behavior.

Flow Spec: Schema validation at startup with installer-aware fallback FLSP_UBFLOW_013

status: draft tags: ubflow satisfies: FLST_UBFLOW_010 implemented_by: FLIN_UBFLOW_010 supported_by: FLSK_UBFLOW_005

At the start of every session ubFlow shall call the ubCode MCP schema tool and verify that the need types flowinst, flowskill, flowspec, flowstory, agent, and agentfamily are all present in the project. If required types are absent and the current request is not an installer workflow, ubFlow shall halt, report the missing types, and ask the user to run the installer first. If required types are absent and the request appears to be a first-time setup or the user explicitly invokes the installer, ubFlow shall offer to run the installer workflow to add the missing configuration, and proceed only after explicit user confirmation.

Flow Spec: Built-in ubCode MCP knowledge requires no manual setup FLSP_UBFLOW_014

status: draft tags: ubflow satisfies: FLST_UBFLOW_015 supported_by: FLSK_UBFLOW_005

ubFlow shall carry built-in knowledge of the ubCode MCP server — its tool names, required parameters, and usage patterns — so that it can query needs, schemas, and project structure without relying on additional setup instructions from the user or the target project.

Project Integration

Flow Spec: Guided project integration with confirmation gate FLSP_UBFLOW_015

status: draft tags: ubflow satisfies: FLST_UBFLOW_011 implemented_by: FLIN_UBFLOW_011

When a user requests ubFlow integration into an existing or new Sphinx project, ubFlow shall inspect the project (check for ubproject.toml, existing need types, .github folder) and present a structured installation plan listing all changes to be made. ubFlow shall wait for explicit user confirmation before delegating execution to the Installer agent. No files shall be written before confirmation.

Flow Spec: ubFlow internals never written to target project FLSP_UBFLOW_016

status: draft tags: ubflow satisfies: FLST_UBFLOW_012 implemented_by: FLIN_UBFLOW_012

ubFlow shall never copy its own FLIN_UBFLOW_*, FLSK_UBFLOW_*, or any other internal need object into a target project. ubFlow’s instructions and skills are delivered exclusively via the ubCode VS Code extension. Only need objects explicitly authored for the target project’s agents may be written to that project’s documentation.

Identity & Invocation

Flow Spec: ubFlow delivered as ubCode chat participant FLSP_UBFLOW_017

status: draft tags: ubflow satisfies: FLST_UBFLOW_013

ubFlow’s instructions and skills shall be encapsulated inside the ubCode VS Code extension and exposed exclusively as a chat participant. They shall not be present in or readable from the target project’s file system.

Flow Spec: ubFlow is non-editable after delivery FLSP_UBFLOW_018

status: draft tags: ubflow satisfies: FLST_UBFLOW_014

The ubFlow agent itself shall be non-editable by the end user. Behavioral updates are delivered exclusively through the ubFlow repository and the ubCode distribution channel. Agents generated by ubFlow for target projects may be edited by the developer.

Flow Spec: Generated agent file placed in .github/agents/ with @-invokable name FLSP_UBFLOW_019

status: draft tags: ubflow satisfies: FLST_UBFLOW_017 implemented_by: FLIN_UBFLOW_013

Every .agent.md file generated by ubFlow shall be written to .github/agents/<name>.agent.md where <name> matches the name: field in the YAML frontmatter. This ensures the agent is directly invokable as @<name> in GitHub Copilot agent mode.

Flow Spec: Generated agents support delegation from other agents FLSP_UBFLOW_020

status: draft tags: ubflow satisfies: FLST_UBFLOW_018 implemented_by: FLIN_UBFLOW_013

ubFlow shall ensure that every generated .agent.md file is structured so that it can be invoked by another Copilot agent via its @<name> prompt. The file shall not contain any configuration that would prevent cross-agent delegation.

Documentation

Flow Spec: Human-readable agent overview on request FLSP_UBFLOW_021

status: draft tags: ubflow satisfies: FLST_UBFLOW_016 implemented_by: FLIN_UBFLOW_014

When asked, ubFlow shall generate a human-readable summary of an agent or agent family. The summary shall include: the agent’s purpose, the flow stories it addresses, its instructions and skills expressed in plain language, and its tool dependencies. The output shall be self-contained so that a team member unfamiliar with Sphinx-Needs can understand the agent’s role and behavior without navigating raw RST files.

Extension-Bundled Instructions

Flow Spec: ubFlow stub contains bootstrap call only FLSP_UBFLOW_022

status: draft tags: ubflow satisfies: FLST_UBFLOW_036 implemented_by: FLIN_UBFLOW_015

The .agent.md file installed into a target repository for the ubFlow agent SHALL contain only a bootstrap block — no instruction text, no skill text, and no Sphinx-Needs IDs. The bootstrap block SHALL consist of a single instruction that directs the agent to fetch its full instruction set via the ubCode MCP server using agent="ubflow" (see SWSP_UBCODE_001, SWSP_UBCODE_002). The stub file MUST NOT contain any FLIN_ or FLSK_ content. All behavioral rules reside exclusively in the ubCode extension’s bundled documentation project.

Flow Spec: ubFlow fetches its instructions via agent-scoped MCP call FLSP_UBFLOW_023

status: draft tags: ubflow satisfies: FLST_UBFLOW_036 implemented_by: FLIN_UBFLOW_015

On every session start, the ubFlow agent SHALL call the ubCode MCP server with the parameter agent="ubflow" to retrieve its current instructions and skills. The sequence SHALL be: get_schema_for_need_filter(agent="ubflow") — verify the bundled project is reachable and retrieve the available field schema. query_needs(type="flowinst", tags=["ubflow"], agent="ubflow") — load all binding instructions. query_needs(type="flowskill", tags=["ubflow"], agent="ubflow") — load all skills. The same bootstrap sequence SHALL be repeated immediately after any FLIN_ or FLSK_ need is created or modified within an active session, so that the agent’s active rule set reflects the latest written state before continuing. If the MCP call returns {"error": "unknown_agent"} or any other error, the agent SHALL halt and inform the user that the ubCode extension must be installed or updated before ubFlow can operate.

Flow Spec: Installer deploys companion bootstrap instructions file per family FLSP_UBFLOW_029

status: draft tags: ubflow satisfies: FLST_UBFLOW_042 implemented_by: FLIN_UBFLOW_019 supported_by: FLSK_UBFLOW_008

The ubFlow installer SHALL deploy a .github/instructions/<family>.instructions.md file alongside every agent family installation. This file SHALL carry applyTo: '**' in its YAML frontmatter and SHALL instruct GitHub Copilot to execute the MCP bootstrap sequence for the family’s agents before responding to any request. The companion file ensures the bootstrap cannot be silently skipped even if the .agent.md content is not read during a particular Copilot session.