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

Flow Skill: Decide whether content belongs in flowinst or flowskill FLSK_UBFLOW_002
status: draft
tags: ubflow
supports: FLSP_UBFLOW_004
employed_by: AGT_UBFLOW

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

Flow Skill: Execute the five-step agent creation workflow FLSK_UBFLOW_003
status: draft
tags: ubflow
supports: FLSP_UBFLOW_008, FLSP_UBFLOW_009
employed_by: AGT_UBFLOW
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.
Flow Skill: Perform syntactic, semantic, and traceability review checks FLSK_UBFLOW_004
status: draft
tags: ubflow
supports: FLSP_UBFLOW_010, FLSP_UBFLOW_011
employed_by: AGT_UBFLOW
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

Flow Skill: Cite a driving FLIN\_ or FLSK\_ with a source link FLSK_UBFLOW_006
status: draft
tags: ubflow, always-load
supports: FLSP_UBFLOW_024
employed_by: AGT_UBFLOW
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:

    `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

Flow Skill: RST and Sphinx directive syntax for common authoring patterns FLSK_UBFLOW_007
status: draft
tags: ubflow
supports: FLSP_UBFLOW_027
employed_by: AGT_UBFLOW

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

Mermaid diagram

.. mermaid::

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

Code block

.. code-block:: python

   def hello():
       return "world"

Note / warning admonition

.. note::

   This is a note.

.. warning::

   This is a warning.

List table

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

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

Cross-reference to another need

See :need:`FLIN_UBFLOW_002` for details.

Cross-reference to a section label

.. _my-label:

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

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

Inline code

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

Bold / italic inline markup

**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

Flow Skill: Query ubCode MCP schema and handle missing types FLSK_UBFLOW_005
status: draft
tags: ubflow
supports: FLSP_UBFLOW_013, FLSP_UBFLOW_014
employed_by: AGT_UBFLOW
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):

    1. Report which types are missing.

    2. Offer to run the installer workflow.

    3. 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.
Flow Skill: Author the companion bootstrap instructions file for a ubFlow agent family FLSK_UBFLOW_008
status: draft
tags: ubflow
supports: FLSP_UBFLOW_029
employed_by: AGT_UBFLOW

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:

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

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

    ## 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.