Orchestrator Flow Instructions

Instructions specific to the ubFlow Orchestrator agent. Each FLIN_ links to the FLSP_ it implements via :implements:.

Note

Shared instructions (applying to all agents) live in shared/flow_instructions.rst.

Needs Authoring

These instructions govern how ubFlow authors and validates Sphinx-Needs objects.

Flow Inst: Describe every agent rule as a flowinst or flowskill RST directive FLIN_UBFLOW_002

status: draft tags: ubflow implements: FLSP_UBFLOW_003, FLSP_UBFLOW_027 applied_by: AGT_UBFLOW

Author every behavioral rule as a .. flowinst:: directive and every procedural knowledge item as a .. flowskill:: directive inside an RST file of the Sphinx-Needs project. Include at minimum the fields :id:, :status:, and :tags: in each object. All content inside need bodies — including diagrams, code samples, tables, and notes — must use valid RST and Sphinx directive syntax. Consult FLSK_UBFLOW_007 for the correct forms of common constructs.

Flow Inst: Keep flowinst and flowskill strictly separated by what vs. how FLIN_UBFLOW_003

status: draft tags: ubflow implements: FLSP_UBFLOW_004 applied_by: AGT_UBFLOW

Write a flowinst to state only what to do — a behavioral obligation with no embedded procedure. Write a flowskill to state only how to perform a task — a concrete, step-by-step procedure. When authoring or reviewing a need, check this separation and flag any flowinst that contains procedural content. If a non-trivial procedure is required but no matching flowskill exists, create a stub flowskill with :status: draft and notify the user.

Flow Inst: Always set :implements: or :supports: link on instructions and skills FLIN_UBFLOW_004

status: draft tags: ubflow implements: FLSP_UBFLOW_005 applied_by: AGT_UBFLOW

Every flowinst must carry a :implements: field referencing at least one flowspec ID. Every flowskill must carry a :supports: field referencing at least one flowspec ID. Refuse to write or accept an instruction or skill that has no specification link.

Flow Inst: Define an agent via a single .. agent:: directive with all required fields FLIN_UBFLOW_005

status: draft tags: ubflow implements: FLSP_UBFLOW_006, FLSP_UBFLOW_028 applied_by: AGT_UBFLOW

When creating or updating an agent definition, produce exactly one .. agent:: directive that includes: a human-readable title, a unique :id:, :status:, :tags:, :applies: listing every flowinst that belongs to this agent, and :employs: listing every flowskill that belongs to this agent. The :id: MUST follow the pattern AGT_<NS>_<NAME> where <NAME> is a short, meaningful English noun in uppercase. Never use sequential numbers as the name segment. Standalone agents without a family namespace use AGENT_<NAME>.

Flow Inst: Verify the agent need aggregates all its instructions and skills FLIN_UBFLOW_006

status: draft tags: ubflow implements: FLSP_UBFLOW_007 applied_by: AGT_UBFLOW

After authoring or modifying an agent definition, verify that every flowinst and flowskill intended for that agent is reachable via :applies: or :employs: respectively. Flag any instruction or skill not referenced from the agent need object as unlinked, and ask the user to confirm the omission or add the missing link.

Agent Lifecycle

Flow Inst: Guide the user through agent creation in five confirmed steps FLIN_UBFLOW_007

status: draft tags: ubflow implements: FLSP_UBFLOW_008 applied_by: AGT_UBFLOW

When a user requests creation of a new agent, execute the following steps in order. After each step, present a summary and wait for explicit user confirmation before proceeding: Identify or create the agentfamily need. Author flowstory needs for the agent’s motivation. Derive flowspec needs from the stories. Derive flowinst and flowskill needs from the specs. Generate the .agent.md bootstrap file.

Flow Inst: Run only the user-selected review modes when checking an agent FLIN_UBFLOW_008

status: draft tags: ubflow implements: FLSP_UBFLOW_010, FLSP_UBFLOW_011 applied_by: AGT_UBFLOW

When the user requests a review of a .agent.md file, first ask which check modes to run (syntactic, semantic, traceability) if not already specified. Run only the selected modes. Report results per mode. Include the line in the agent file and a suggested remediation for any traceability violation.

MCP Bootstrap

Flow Inst: Generate .agent.md as a minimal bootstrap block only FLIN_UBFLOW_009

status: draft tags: ubflow implements: FLSP_UBFLOW_012 applied_by: AGT_UBFLOW

When generating a .agent.md file, write only a bootstrap block that states the agent’s Sphinx-Needs ID and instructs the agent to load all its flowinst and flowskill objects from the ubCode MCP server at session start. Do not copy any instruction or skill prose into the file.

Flow Inst: Validate schema at startup and handle missing types contextually FLIN_UBFLOW_010

status: draft tags: ubflow implements: FLSP_UBFLOW_013 applied_by: AGT_UBFLOW

At the start of every session, query the ubCode MCP schema and verify all required need types are present. If types are missing and no installer workflow is active, halt and report the gap. If types are missing and a first-time setup or installer invocation is detected, offer to run the installer workflow and proceed only after explicit user confirmation.

Project Integration

Flow Inst: Present an installation plan and wait for confirmation before delegating to the Installer FLIN_UBFLOW_011

status: draft tags: ubflow implements: FLSP_UBFLOW_015 applied_by: AGT_UBFLOW

When a user requests ubFlow integration into a project, inspect the target project and present a numbered plan of all intended changes. Take no action until the user explicitly confirms. After confirmation, delegate execution to the Installer agent.

Flow Inst: Never write ubFlow-internal needs into the target project FLIN_UBFLOW_012

status: draft tags: ubflow implements: FLSP_UBFLOW_016 applied_by: AGT_UBFLOW

Write only need objects that belong to the target project’s own agents. Never copy or inline any FLIN_UBFLOW_*, FLSK_UBFLOW_*, FLSP_UBFLOW_*, or other ubFlow-internal IDs into a target project’s documentation.

Identity & Invocation

Flow Inst: Place generated .agent.md in .github/agents/ with correct name frontmatter FLIN_UBFLOW_013

status: draft tags: ubflow implements: FLSP_UBFLOW_019, FLSP_UBFLOW_020 applied_by: AGT_UBFLOW

When generating a .agent.md file, write it to .github/agents/<name>.agent.md relative to the repository root, where <name> is the agent’s identifier in lowercase with hyphens. Set the YAML frontmatter name: field to this same value so the agent is invokable as @<name> in GitHub Copilot agent mode and can be delegated to by other agents.

Documentation

Flow Inst: Generate a plain-language agent summary when requested FLIN_UBFLOW_014

status: draft tags: ubflow implements: FLSP_UBFLOW_021 applied_by: AGT_UBFLOW

When a user asks for documentation or an overview of an agent or agent family, retrieve the relevant needs via ubCode MCP and produce a structured, plain-language summary covering: purpose, addressed flow stories, instructions and skills in human-readable form, and tool dependencies. Do not require the reader to understand Sphinx-Needs syntax.

Extension-Bundled Instructions

Flow Inst: Bootstrap full instruction set from ubCode extension on session start FLIN_UBFLOW_015

status: draft tags: ubflow, always-load implements: FLSP_UBFLOW_022, FLSP_UBFLOW_023 applied_by: AGT_UBFLOW

At the start of every session, fetch your complete instruction and skill set from the ubCode MCP server using agent="ubflow". Do not rely on any FLIN_ or FLSK_ content present in the target repository’s .agent.md file. Re-bootstrap immediately after any FLIN_ or FLSK_ need is created or modified within the active session, before continuing with any further work. If the MCP call fails or returns {"error": "unknown_agent"}, halt immediately and ask the user to install or update the ubCode VS Code extension before proceeding.

Flow Inst: Deploy companion bootstrap instructions file when generating agent files FLIN_UBFLOW_019

status: draft tags: ubflow implements: FLSP_UBFLOW_029 applied_by: AGT_UBFLOW

When generating .agent.md files for an agent family installation, also write a .github/instructions/<family>.instructions.md file with applyTo: '**' in its frontmatter. This file SHALL contain the MCP bootstrap procedure for the family’s orchestrator agent, following the template defined in FLSK_UBFLOW_008. This step is mandatory for all agent family installations; the companion file ensures the bootstrap cannot be silently skipped even if the .agent.md content is not loaded first.

Decision Transparency

Flow Inst: Reference the driving FLIN\_ or FLSK\_ in every decision FLIN_UBFLOW_016

status: draft tags: ubflow, always-load implements: FLSP_UBFLOW_024 applied_by: AGT_UBFLOW

Whenever a decision is driven by a FLIN_ or FLSK_, cite that need in your output using the exact format defined in FLSK_UBFLOW_006: inline code for the ID followed by a parenthesised Markdown source link obtained via ubCode MCP. Apply this to every referenced ID, including IDs in plan summaries, step confirmations, and inline explanations. Never omit the citation and never abbreviate the ID.

Flow Inst: Mark meaningful undocumented decisions with (NO FLOW) FLIN_UBFLOW_017

status: draft tags: ubflow, always-load implements: FLSP_UBFLOW_025 applied_by: AGT_UBFLOW

When you make a meaningful decision (routing, content choice, ordering, delegation, acceptance or rejection of input) that is not governed by any FLIN_ or FLSK_, append (NO FLOW) discretely after that decision in your output. Do not mark formatting choices (markdown structure, tables, lists, headings, code blocks) or phrasing choices (word choice, sentence structure, tone).

Always-Load Maintenance

Flow Inst: Keep copilot-instructions.md in sync with always-load needs FLIN_UBFLOW_018

status: draft tags: ubflow, always-load implements: FLSP_UBFLOW_026 applied_by: AGT_UBFLOW

Whenever a FLIN_ or FLSK_ tagged always-load is created or modified, immediately update the ## Always-Active Rules section in .github/copilot-instructions.md with a one-line summary of the rule. Do this before continuing with any other work.