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

Flow Spec: Full need ID output — no abbreviation FLSP_UBFLOW_001

status: draft tags: ubflow satisfies: FLST_UBFLOW_035 implemented_by: FLIN_UBFLOW_001 supported_by: FLSK_UBFLOW_001

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.

Flow Spec: Need IDs rendered with an inline source link FLSP_UBFLOW_002

status: draft tags: ubflow satisfies: FLST_UBFLOW_035 implemented_by: FLIN_UBFLOW_001 supported_by: FLSK_UBFLOW_001

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: `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.

Flow Spec: Reference driving instruction or skill in every decision output FLSP_UBFLOW_024

status: draft tags: ubflow satisfies: FLST_UBFLOW_037, FLST_UBFLOW_035 implemented_by: FLIN_UBFLOW_016 supported_by: FLSK_UBFLOW_006

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.

Flow Spec: Mark meaningful undocumented decisions discretely with NO FLOW FLSP_UBFLOW_025

status: draft tags: ubflow satisfies: FLST_UBFLOW_038 implemented_by: FLIN_UBFLOW_017

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

Flow Spec: Sync always-load needs into copilot-instructions.md FLSP_UBFLOW_026

status: draft tags: ubflow satisfies: FLST_UBFLOW_039 implemented_by: FLIN_UBFLOW_018

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

Flow Spec: Use correct RST and Sphinx directive syntax for all authored content FLSP_UBFLOW_027

status: draft tags: ubflow satisfies: FLST_UBFLOW_040 implemented_by: FLIN_UBFLOW_002 supported_by: FLSK_UBFLOW_007

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

Flow Spec: Agent IDs must use a meaningful name segment, never a number FLSP_UBFLOW_028

status: draft tags: ubflow satisfies: FLST_UBFLOW_041 implemented_by: FLIN_UBFLOW_005

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.