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 --------------- .. flowspec:: flowinst and flowskill described as RST directives :id: FLSP_UBFLOW_003 :status: draft :satisfies: FLST_UBFLOW_005 :tags: ubflow 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:``. .. flowspec:: flowinst separates what from how :id: FLSP_UBFLOW_004 :status: draft :satisfies: FLST_UBFLOW_005 :tags: ubflow 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``. .. flowspec:: flowinst and flowskill link to a flowspec :id: FLSP_UBFLOW_005 :status: draft :satisfies: FLST_UBFLOW_006 :tags: ubflow 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. .. flowspec:: agent need as single identity object :id: FLSP_UBFLOW_006 :status: draft :satisfies: FLST_UBFLOW_007 :tags: ubflow 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:``. .. flowspec:: agent need as complete aggregation point :id: FLSP_UBFLOW_007 :status: draft :satisfies: FLST_UBFLOW_008 :tags: ubflow 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 --------------- .. flowspec:: Step-by-step agent creation workflow :id: FLSP_UBFLOW_008 :status: draft :satisfies: FLST_UBFLOW_001 :tags: ubflow 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: 1. Identify or create the ``agentfamily`` need in the target project. 2. Author ``flowstory`` needs that capture the agent's motivation. 3. Derive ``flowspec`` needs from the stories. 4. Derive ``flowinst`` and ``flowskill`` needs from the specs. 5. Generate the ``.agent.md`` file as a minimal bootstrap referencing the agent's need ID. .. flowspec:: Agent creation verifies all linked IDs via MCP before writing :id: FLSP_UBFLOW_009 :status: draft :satisfies: FLST_UBFLOW_001 :tags: ubflow 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. .. flowspec:: Agent review supports three selectable check modes :id: FLSP_UBFLOW_010 :status: draft :satisfies: FLST_UBFLOW_002; FLST_UBFLOW_003 :tags: ubflow 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. .. flowspec:: Traceability review resolves every instruction and skill ID :id: FLSP_UBFLOW_011 :status: draft :satisfies: FLST_UBFLOW_004 :tags: ubflow 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 ------------- .. flowspec:: Minimal bootstrap-only .agent.md :id: FLSP_UBFLOW_012 :status: draft :satisfies: FLST_UBFLOW_009 :tags: ubflow 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. .. flowspec:: Schema validation at startup with installer-aware fallback :id: FLSP_UBFLOW_013 :status: draft :satisfies: FLST_UBFLOW_010 :tags: ubflow 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. .. flowspec:: Built-in ubCode MCP knowledge requires no manual setup :id: FLSP_UBFLOW_014 :status: draft :satisfies: FLST_UBFLOW_015 :tags: ubflow 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 ------------------- .. flowspec:: Guided project integration with confirmation gate :id: FLSP_UBFLOW_015 :status: draft :satisfies: FLST_UBFLOW_011 :tags: ubflow 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. .. flowspec:: ubFlow internals never written to target project :id: FLSP_UBFLOW_016 :status: draft :satisfies: FLST_UBFLOW_012 :tags: ubflow 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 --------------------- .. flowspec:: ubFlow delivered as ubCode chat participant :id: FLSP_UBFLOW_017 :status: draft :satisfies: FLST_UBFLOW_013 :tags: ubflow 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. .. flowspec:: ubFlow is non-editable after delivery :id: FLSP_UBFLOW_018 :status: draft :satisfies: FLST_UBFLOW_014 :tags: ubflow 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. .. flowspec:: Generated agent file placed in .github/agents/ with @-invokable name :id: FLSP_UBFLOW_019 :status: draft :satisfies: FLST_UBFLOW_017 :tags: ubflow Every ``.agent.md`` file generated by ubFlow shall be written to ``.github/agents/.agent.md`` where ```` matches the ``name:`` field in the YAML frontmatter. This ensures the agent is directly invokable as ``@`` in GitHub Copilot agent mode. .. flowspec:: Generated agents support delegation from other agents :id: FLSP_UBFLOW_020 :status: draft :satisfies: FLST_UBFLOW_018 :tags: ubflow ubFlow shall ensure that every generated ``.agent.md`` file is structured so that it can be invoked by another Copilot agent via its ``@`` prompt. The file shall not contain any configuration that would prevent cross-agent delegation. Documentation ------------- .. flowspec:: Human-readable agent overview on request :id: FLSP_UBFLOW_021 :status: draft :satisfies: FLST_UBFLOW_016 :tags: ubflow 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 -------------------------------- .. flowspec:: ubFlow stub contains bootstrap call only :id: FLSP_UBFLOW_022 :status: draft :satisfies: FLST_UBFLOW_036 :tags: ubflow 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. .. flowspec:: ubFlow fetches its instructions via agent-scoped MCP call :id: FLSP_UBFLOW_023 :status: draft :satisfies: FLST_UBFLOW_036 :tags: ubflow 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: 1. ``get_schema_for_need_filter(agent="ubflow")`` — verify the bundled project is reachable and retrieve the available field schema. 2. ``query_needs(type="flowinst", tags=["ubflow"], agent="ubflow")`` — load all binding instructions. 3. ``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. .. flowspec:: Installer deploys companion bootstrap instructions file per family :id: FLSP_UBFLOW_029 :status: draft :satisfies: FLST_UBFLOW_042 :tags: ubflow The ubFlow installer SHALL deploy a ``.github/instructions/.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.