Shared Flow Specifications
==========================

Specifications in this section are **cross-cutting** — they apply to every
agent created by ubFlow. Each ``FLSP_`` links back to one or more ``FLST_``
via ``:satisfies:``.

Need ID Output
--------------

.. flowspec:: Full need ID output — no abbreviation
   :id: FLSP_UBFLOW_001
   :status: draft
   :satisfies: FLST_UBFLOW_035
   :tags: ubflow

   Every ubFlow agent shall never abbreviate, truncate, or shorten any
   Sphinx-Needs ID in its output, commentary, or progress reports.
   Every referenced need (instruction, skill, specification, flow story,
   agent, tool) shall be displayed using its full registered identifier
   exactly as returned by the ubCode MCP server.

.. flowspec:: Need IDs rendered with an inline source link
   :id: FLSP_UBFLOW_002
   :status: draft
   :satisfies: FLST_UBFLOW_035
   :tags: ubflow

   When any ubFlow agent references a need ID in its output, it shall
   attempt to resolve the need's source location via
   ``get_data_for_single_need(need_id=<id>)``. When the result contains an
   ``origin.path`` (absolute file path) and ``origin.line`` (1-based line
   number), the agent shall render the reference as inline code followed by
   a parenthesised Markdown source link:

   .. code-block:: text

      `FULL_ID` ([source](workspace-relative/path/to/file.rst#LNNN))

   where:

   - ``FULL_ID`` is the complete, unabbreviated need ID, rendered as
     inline code so it is always visible regardless of link rendering.
   - ``workspace-relative/path`` is the path from the repository root to
     the RST source file (computed via ``os.path.relpath``).
   - ``LNNN`` is the 1-based line number of the need directive.

   The ID itself must never be the label of the Markdown link, because
   VS Code Copilot chat overrides link display text with the target file
   path, which would make the ID invisible to the developer.

   If the origin is unavailable or the MCP call fails, the ID shall still
   be printed in full as inline code. No ID shall ever be silently omitted.

.. flowspec:: Reference driving instruction or skill in every decision output
   :id: FLSP_UBFLOW_024
   :status: draft
   :satisfies: FLST_UBFLOW_037; FLST_UBFLOW_035
   :tags: ubflow

   When an agent makes a decision driven by a ``FLIN_`` or ``FLSK_``, it
   must reference the full ID of that need in its output. The ID must be
   displayed according to ``FLSP_UBFLOW_001`` and ``FLSP_UBFLOW_002`` —
   full and unabbreviated, with a source link where origin data is available.

.. flowspec:: Mark meaningful undocumented decisions discretely with NO FLOW
   :id: FLSP_UBFLOW_025
   :status: draft
   :satisfies: FLST_UBFLOW_038
   :tags: ubflow

   When an agent makes a **meaningful** decision (routing, content choice,
   ordering, delegation, acceptance or rejection of input) that is not governed
   by any ``FLIN_`` or ``FLSK_``, it must append ``(NO FLOW)`` discretely
   after that decision in its output.

   The following are **exempt** and must not be marked:

   - Formatting choices (markdown structure, use of tables, lists, headings,
     code blocks)
   - Phrasing choices (word choice, sentence structure, tone)


Always-Load Rules
-----------------

.. flowspec:: Sync always-load needs into copilot-instructions.md
   :id: FLSP_UBFLOW_026
   :status: draft
   :satisfies: FLST_UBFLOW_039
   :tags: ubflow

   Any ``FLIN_`` or ``FLSK_`` tagged ``always-load`` MUST have a one-line
   summary entry in the ``## Always-Active Rules`` section of
   ``.github/copilot-instructions.md``. The agent MUST add or update this
   entry immediately after the tagged need is created or modified, before
   continuing with any other work.


RST Authoring
-------------

.. flowspec:: Use correct RST and Sphinx directive syntax for all authored content
   :id: FLSP_UBFLOW_027
   :status: draft
   :satisfies: FLST_UBFLOW_040
   :tags: ubflow

   All content written into RST files — need bodies, diagrams, code examples,
   tables, and admonitions — MUST use syntactically correct reStructuredText
   and valid Sphinx directives. The agent MUST consult ``FLSK_UBFLOW_007``
   when authoring any non-trivial RST construct. No Markdown-only syntax
   (fenced code blocks, ``#`` headings, ``**bold**`` outside inline markup
   context) may appear inside RST files.


Agent Naming
------------

.. flowspec:: Agent IDs must use a meaningful name segment, never a number
   :id: FLSP_UBFLOW_028
   :status: draft
   :satisfies: FLST_UBFLOW_041
   :tags: ubflow

   Every ``agent`` need ID MUST follow the pattern ``AGT_<NS>_<NAME>``
   where ``<NAME>`` is a short, meaningful English noun or noun phrase in
   uppercase (e.g. ``ORCHESTRATOR``, ``STORY``, ``DEV``, ``TEST``).
   Sequential numbers (``001``, ``002``, …) are not permitted as the name
   segment. Standalone agents without a family namespace MAY use the
   ``AGENT_<NAME>`` pattern.