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. .. flowinst:: Describe every agent rule as a flowinst or flowskill RST directive :id: FLIN_UBFLOW_002 :status: draft :tags: ubflow :implements: FLSP_UBFLOW_003; FLSP_UBFLOW_027 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. .. flowinst:: Keep flowinst and flowskill strictly separated by what vs. how :id: FLIN_UBFLOW_003 :status: draft :tags: ubflow :implements: FLSP_UBFLOW_004 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. .. flowinst:: Always set :implements: or :supports: link on instructions and skills :id: FLIN_UBFLOW_004 :status: draft :tags: ubflow :implements: FLSP_UBFLOW_005 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. .. flowinst:: Define an agent via a single .. agent:: directive with all required fields :id: FLIN_UBFLOW_005 :status: draft :tags: ubflow :implements: FLSP_UBFLOW_006; FLSP_UBFLOW_028 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__`` where ```` is a short, meaningful English noun in uppercase. Never use sequential numbers as the name segment. Standalone agents without a family namespace use ``AGENT_``. .. flowinst:: Verify the agent need aggregates all its instructions and skills :id: FLIN_UBFLOW_006 :status: draft :tags: ubflow :implements: FLSP_UBFLOW_007 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 --------------- .. flowinst:: Guide the user through agent creation in five confirmed steps :id: FLIN_UBFLOW_007 :status: draft :tags: ubflow :implements: FLSP_UBFLOW_008 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: 1. Identify or create the ``agentfamily`` need. 2. Author ``flowstory`` needs for 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`` bootstrap file. .. flowinst:: Run only the user-selected review modes when checking an agent :id: FLIN_UBFLOW_008 :status: draft :tags: ubflow :implements: FLSP_UBFLOW_010; FLSP_UBFLOW_011 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 ------------- .. flowinst:: Generate .agent.md as a minimal bootstrap block only :id: FLIN_UBFLOW_009 :status: draft :tags: ubflow :implements: FLSP_UBFLOW_012 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. .. flowinst:: Validate schema at startup and handle missing types contextually :id: FLIN_UBFLOW_010 :status: draft :tags: ubflow :implements: FLSP_UBFLOW_013 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 ------------------- .. flowinst:: Present an installation plan and wait for confirmation before delegating to the Installer :id: FLIN_UBFLOW_011 :status: draft :tags: ubflow :implements: FLSP_UBFLOW_015 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. .. flowinst:: Never write ubFlow-internal needs into the target project :id: FLIN_UBFLOW_012 :status: draft :tags: ubflow :implements: FLSP_UBFLOW_016 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 --------------------- .. flowinst:: Place generated .agent.md in .github/agents/ with correct name frontmatter :id: FLIN_UBFLOW_013 :status: draft :tags: ubflow :implements: FLSP_UBFLOW_019; FLSP_UBFLOW_020 When generating a ``.agent.md`` file, write it to ``.github/agents/.agent.md`` relative to the repository root, where ```` 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 ``@`` in GitHub Copilot agent mode and can be delegated to by other agents. Documentation ------------- .. flowinst:: Generate a plain-language agent summary when requested :id: FLIN_UBFLOW_014 :status: draft :tags: ubflow :implements: FLSP_UBFLOW_021 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 -------------------------------- .. flowinst:: Bootstrap full instruction set from ubCode extension on session start :id: FLIN_UBFLOW_015 :status: draft :tags: ubflow, always-load :implements: FLSP_UBFLOW_022; FLSP_UBFLOW_023 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. .. flowinst:: Deploy companion bootstrap instructions file when generating agent files :id: FLIN_UBFLOW_019 :status: draft :tags: ubflow :implements: FLSP_UBFLOW_029 When generating ``.agent.md`` files for an agent family installation, also write a ``.github/instructions/.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 --------------------- .. flowinst:: Reference the driving FLIN\_ or FLSK\_ in every decision :id: FLIN_UBFLOW_016 :status: draft :tags: ubflow, always-load :implements: FLSP_UBFLOW_024 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. .. flowinst:: Mark meaningful undocumented decisions with (NO FLOW) :id: FLIN_UBFLOW_017 :status: draft :tags: ubflow, always-load :implements: FLSP_UBFLOW_025 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 ----------------------- .. flowinst:: Keep copilot-instructions.md in sync with always-load needs :id: FLIN_UBFLOW_018 :status: draft :tags: ubflow, always-load :implements: FLSP_UBFLOW_026 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.