Orchestrator Flow Skills
========================

Skills specific to the **ubFlow Orchestrator** agent.
Each ``FLSK_`` links to the ``FLSP_`` it supports via ``:supports:``.

.. note::

   Shared skills (available to all agents) live in
   ``shared/flow_skills.rst``.


Needs Authoring
---------------

.. flowskill:: Decide whether content belongs in flowinst or flowskill
   :id: FLSK_UBFLOW_002
   :status: draft
   :tags: ubflow
   :supports: FLSP_UBFLOW_004

   Apply the following decision rule when authoring or reviewing a need:

   1. **Ask**: Does the text state an obligation without describing steps?
      → It belongs in a ``flowinst``. Example: *"The agent shall never
      abbreviate a need ID."*

   2. **Ask**: Does the text describe a repeatable procedure with discrete
      steps (numbered list, command sequences, conditionals)?
      → It belongs in a ``flowskill``. Example: *"1. Call
      get_data_for_single_need. 2. Extract origin.path …"*

   3. **Mixed content**: If a draft contains both obligation and procedure,
      split it: keep the obligation sentence in a ``flowinst`` and move the
      procedure into a new or existing ``flowskill``. Link them via
      ``:implements:`` / ``:supports:`` to the same ``flowspec``.

   4. **Stub rule**: If the procedure is non-trivial but not yet written,
      create a ``flowskill`` stub with ``:status: draft`` and a
      ``TODO: describe procedure`` body. Notify the user.


Agent Lifecycle
---------------

.. flowskill:: Execute the five-step agent creation workflow
   :id: FLSK_UBFLOW_003
   :status: draft
   :tags: ubflow
   :supports: FLSP_UBFLOW_008; FLSP_UBFLOW_009
   :linked_tool: FLTL_UBCODE_MCP

   1. **agentfamily**: Query ubCode MCP for an existing ``agentfamily`` need
      in the target project. If none exists, draft a new one and ask the user
      to confirm before writing.
   2. **flowstory**: Present a numbered list of proposed flow stories based on
      the user's description. Ask for confirmation or edits. Write confirmed
      stories to the appropriate ``flow_stories/`` RST file.
   3. **flowspec**: For each confirmed story, propose one or more ``flowspec``
      needs. Ask for confirmation. Write to ``core/orchestrator/flow_specs.rst``.
   4. **flowinst / flowskill**: For each confirmed spec, propose instructions
      and skills applying the what/how separation rule (see ``FLSK_UBFLOW_002``).
      Ask for confirmation. Write to ``instructions.rst`` and ``skills.rst``.
   5. **bootstrap file**: Retrieve the ``agent`` need via ubCode MCP and verify
      every ``:applies:`` and ``:employs:`` ID resolves. Generate a minimal
      ``.agent.md`` that contains only a bootstrap block referencing the agent
      ID. Report any unresolvable IDs and abort if any are found.

.. flowskill:: Perform syntactic, semantic, and traceability review checks
   :id: FLSK_UBFLOW_004
   :status: draft
   :tags: ubflow
   :supports: FLSP_UBFLOW_010; FLSP_UBFLOW_011
   :linked_tool: FLTL_UBCODE_MCP

   **Syntactic check**:

   1. Parse the YAML frontmatter — report any YAML syntax errors.
   2. Verify required sections are present (e.g. a bootstrap block or
      ``applyTo`` pattern).
   3. Check heading hierarchy for consistency.

   **Semantic check**:

   1. Locate all prose blocks that appear to be behavioral rules.
   2. Apply the flowinst/flowskill decision rule (``FLSK_UBFLOW_002``) to each.
   3. Flag any rule that mixes obligation and procedure in the same block.

   **Traceability check**:

   1. Extract every ``FLIN_`` and ``FLSK_`` ID mentioned in the file using
      the pattern ``r'\bF(?:LIN|LSK)_[A-Za-z0-9_.]+\b'``.
   2. For each ID call ``get_data_for_single_need(need_id=<id>)``.
   3. Collect all IDs where the call returns no result or raises an error.
   4. Report each unresolvable ID with the line number in the agent file
      and one of: *"Create the missing need"* or *"Correct the ID"*.
   5. Exit the traceability check with a PASS / FAIL summary.


Decision Transparency
---------------------

.. flowskill:: Cite a driving FLIN\_ or FLSK\_ with a source link
   :id: FLSK_UBFLOW_006
   :status: draft
   :tags: ubflow, always-load
   :supports: FLSP_UBFLOW_024
   :linked_tool: FLTL_UBCODE_MCP

   Use this procedure every time a decision is driven by a ``FLIN_`` or
   ``FLSK_`` and must be cited in output.

   1. **Identify the ID** — note the full, unabbreviated need ID that governs
      the decision (e.g. ``FLIN_UBFLOW_016``).
   2. **Call ubCode MCP** — execute
      ``get_data_for_single_need(need_id="<ID>", file_path=<ubproject.toml>)``.
   3. **Extract origin** — read ``result.origin.Directive.path`` (absolute file
      path) and ``result.origin.Directive.line`` (1-based line number).
   4. **Compute workspace-relative path** — strip the repository root prefix
      from the absolute path (e.g.
      ``/home/.../ubflow/docs/core/.../flow_instructions.rst``
      → ``docs/core/.../flow_instructions.rst``).
   5. **Format the citation** — render as:

      .. code-block:: text

         `ID` ([source](workspace-relative/path.rst#LNNN))

      Example: ``FLIN_UBFLOW_016`` ([source](docs/core/agents/ubflow/flow_instructions.rst#L223))

   6. **Fallback** — if the MCP call fails or ``origin`` is absent, render
      the ID as inline code only (no link). Never omit the ID itself.

   **Do not** use the ID as the Markdown link label — VS Code Copilot chat
   overrides link display text with the target file path, making the ID
   invisible.


RST Authoring Reference
------------------------

.. flowskill:: RST and Sphinx directive syntax for common authoring patterns
   :id: FLSK_UBFLOW_007
   :status: draft
   :tags: ubflow
   :supports: FLSP_UBFLOW_027

   Consult this reference when writing content inside RST files for any
   Sphinx-Needs project. All examples are valid reStructuredText.

   **Mermaid diagram**

   .. code-block:: rst

      .. mermaid::

         flowchart TD
             A[Start] --> B{Decision}
             B --> |yes| C[Action]
             B --> |no| D[End]

   **Code block**

   .. code-block:: rst

      .. code-block:: python

         def hello():
             return "world"

   **Note / warning admonition**

   .. code-block:: rst

      .. note::

         This is a note.

      .. warning::

         This is a warning.

   **List table**

   .. code-block:: rst

      .. list-table::
         :header-rows: 1
         :widths: 30 70

         * - Column A
           - Column B
         * - value 1
           - value 2

   **Cross-reference to another need**

   .. code-block:: rst

      See :need:`FLIN_UBFLOW_002` for details.

   **Cross-reference to a section label**

   .. code-block:: rst

      .. _my-label:

      Section Title
      -------------

      See :ref:`my-label` for details.

   **Inline code**

   .. code-block:: rst

      Use ``sphinx-build`` to build the project.

   **Bold / italic inline markup**

   .. code-block:: rst

      **bold text** and *italic text*

   **Key constraint**: Markdown syntax (fenced code blocks with triple
   backticks, ``#`` headings, ``**bold**`` outside RST context) must never
   appear in RST files. Always use the RST/Sphinx equivalent.


MCP Bootstrap
-------------

.. flowskill:: Query ubCode MCP schema and handle missing types
   :id: FLSK_UBFLOW_005
   :status: draft
   :tags: ubflow
   :supports: FLSP_UBFLOW_013; FLSP_UBFLOW_014
   :linked_tool: FLTL_UBCODE_MCP

   1. Call the ubCode MCP schema tool (e.g. ``get_needs_schema()``) and collect
      the list of registered need type directives.
   2. Check that all of the following are present:
      ``flowinst``, ``flowskill``, ``flowspec``, ``flowstory``, ``agent``,
      ``agentfamily``.
   3. **All types present** → continue normally.
   4. **Types missing, installer workflow active** (user asked to install or
      set up ubFlow for the first time):

      a. Report which types are missing.
      b. Offer to run the installer workflow.
      c. Wait for explicit user confirmation before proceeding.

   5. **Types missing, no installer context** → halt with a clear error
      message listing the missing types and instructing the user to run
      the ubFlow installer first.

.. flowskill:: Author the companion bootstrap instructions file for a ubFlow agent family
   :id: FLSK_UBFLOW_008
   :status: draft
   :tags: ubflow
   :supports: FLSP_UBFLOW_029

   Use this procedure when creating the companion bootstrap instructions file
   for any ubFlow agent family.

   1. **Determine the family name** — use the orchestrator agent's ``name:``
      frontmatter value in lowercase with hyphens (e.g. ``agile``, ``aspice``).
   2. **Create the file** at
      ``.github/instructions/<family>.instructions.md``.
   3. **Write the YAML frontmatter**:

      .. code-block:: yaml

         ---
         applyTo: '**'
         ---

   4. **Write the bootstrap body** using the following template, substituting
      the family's orchestrator agent ID and ``ubproject.toml`` path:

      .. code-block:: markdown

         ## ubFlow Bootstrap — <FAMILY> family

         When operating as `@<family>`:

         1. Call `mcp_ubcode_get_schema_for_need_filter` with
            `file_path: <path/to/ubproject.toml>`.
         2. Call `mcp_ubcode_get_data_for_single_need` with
            `id: <AGT_FAMILY_ORCHESTRATOR>`.
         3. Load every need linked via `:applies:` (all `FLIN_*`)
            and `:employs:` (all `FLSK_*`).
         4. Only then respond to the user request.

         Do **not** skip these steps. If any MCP call fails, halt and ask the
         user to check the ubCode extension.

   5. **Verify** the file is present at the correct path and the frontmatter
      is valid YAML before reporting completion.