ubFlow Documentation ==================== | **Traceable, auditable AI agents for regulated software development.** | *Engineers decide. AI delivers.* Software in safety-critical systems — automotive (ASPICE, ISO 26262), aerospace (DO-178C), or medical (IEC 62304) — is developed under strict process obligations: bidirectional traceability, peer reviews with explicit disposition, configuration baselines, tool qualification, and audit trails. These obligations apply equally whether a human engineer or an AI agent produces the artifact. ubFlow is a **needs-driven agent design system** for GitHub Copilot. It provides the infrastructure to build, deploy, and operate AI agents that are natively compliant with regulated development processes: * **Every agent rule is traceable** — instructions are derived from Sphinx-Needs specifications and linked back to their motivating requirements. * **Every agent action is auditable** — execution records capture prompts, tool calls, and touched artifacts for ASPICE SUP.8 / ISO 26262 tool qualification. * **Every output passes a review gate** — structured Sphinx-Needs review objects, linked by content hash, provide the same evidence as a traditional peer review. * **Domain knowledge is packaged as agent families** — a single install brings all instructions, skills, and process knowledge required for a given domain (e.g., ASPICE SYS/SWE) into the project's own documentation. The result is an agentic development workflow where the AI is not a black box but a qualified, traceable contributor — one whose work can be assessed, approved, and integrated with the same rigour expected of any human engineer on the team. .. warning:: This Agentic worklfow and the tools are under heavy development and some parts are just concepts yet. Current project status is **alpha**. .. grid:: 1 2 2 3 :gutter: 3 .. grid-item-card:: Traceable Instructions :link: concept-traceability :link-type: ref Agent instructions loaded live from Sphinx-Needs docs — full traceability to requirements, as mandated by ASPICE, ISO 26262, and DO-178C. .. grid-item-card:: Agent Families :link: concept-agent-families :link-type: ref Deploy domain-specific agent sets (e.g., ASPICE SYS/SWE) into your project with a single command. Each family is independently customizable. .. grid-item-card:: Change Branches :link: concept-change-branches :link-type: ref Run parallel agentic proposals, compare outcomes, and merge only the approved result — aligned with ASPICE CHG.1 baseline management. .. grid-item-card:: Quality Assurance :link: concept-quality :link-type: ref Automated rubric-based quality scoring for any Sphinx-Needs object — configurable per need type with adjustable thresholds. .. grid-item-card:: Audit Trail :link: concept-tracking :link-type: ref Full audit record per run — prompts, tool calls, and touched artifacts, ready for ASPICE SUP.8 / ISO 26262 tool qualification. .. grid-item-card:: Structured Reviews :link: concept-reviews :link-type: ref Reviews are Sphinx-Needs objects cryptographically linked to the exact artifact version — machine-generated, human-approved, standards-compliant. .. grid-item-card:: Optimized Workflows :link: concept-workflows :link-type: ref Gate-driven V-model workflows — reviewed output of one step becomes the controlled input to the next, per ASPICE and DO-178C phase gates. .. grid-item-card:: Knowledge Access :link: concept-chatbots :link-type: ref Agents query a structured knowledge graph built from framework and project documentation. Focused retrieval delivers exactly the right context. .. grid-item-card:: Documentation Model :link: concept-docmodel :link-type: ref A compact metamodel mapping agent artifacts to standard-required work products in ASPICE, ISO 26262, IEC 62304, and DO-178C. .. _concept-traceability: Core concept: Traceable, on-the-fly Agent instructions ------------------------------------------------------ **Status**: :bdg-primary:`Implemented` Agents obtain their instructions directly from the Sphinx-based project documentation, which allows to have the full traceability between agent instructions and their motivation in terms of requirements and specifications. Bi-directional traceability between requirements, design, and verification artifacts is a mandatory obligation in regulated domains — ASPICE (SWE.1–SWE.6), ISO 26262-8 §6, IEC 62304 §5.7, and DO-178C §11 all require it explicitly. .. image:: _static/ubflow_trace_prompt.png :align: center The above image shows a CoPilot prompt answer snippet with Sphinx-Needs references for instructions and skills. It is referencing :need:`FLIN_UBFLOW_INST_002` and :need:`FLSK_UBFLOW_INST_001`. This works by letting the ubFlow agents read their instructions via ubCode MCP from the Sphinx-Needs project: .. mermaid:: flowchart LR user(User) copilot(CoPilot) agent(agent.md) ubcode(ubCode MCP) subgraph docs["Project documentation"] inst(Instruction
& skills) req(Requirements) code(Source Code) end inst -. links .-> req code -. links .-> req user -- 1. asks --> copilot copilot -- 2. reads --> agent copilot -- 3. asks --> ubcode -- 4. collects --> inst inst -- 5. enhances agent --> copilot copilot -- 6. works on --> req copilot -- 7. works on --> code copilot -- 8. asks for approval --> user A single agent instructions looks like this in the project documentation: .. code-block:: rst .. flowinst:: Always print need IDs in full and link to their source :id: FLIN_UBFLOW_001 :status: draft :tags: ubflow :implements: FLSP_UBFLOW_001; FLSP_UBFLOW_002 Whenever a need ID (instruction, skill, specification, flow story, agent, or tool) is mentioned in any output or explanation, always use the full, unabbreviated identifier. Never shorten IDs. [...] And the traceability of such an instruction looks like: .. needflow:: :root_id: FLIN_UBFLOW_001 :root_depth: 2 :root_direction: outgoing The rst command for such a traceability view of an instruction is: .. code-block:: rst .. needflow:: :root_id: FLIN_UBFLOW_001 :root_depth: 2 :root_direction: outgoing .. _concept-always-load: Always-Load Rules — resilient instruction delivery --------------------------------------------------- **Status**: :bdg-primary:`Implemented` The MCP bootstrap that loads an agent's instructions at session start is the primary delivery channel — but it can fail: the ubCode extension may not yet be installed, the index may be stale, or the session may have started before the bootstrap completed. For the majority of instructions this is acceptable: they will be loaded on the first explicit action. A small number of meta-rules, however, must be available *unconditionally* — rules about transparency, citation of driving instructions, and maintenance of the instruction set itself. A session that progresses without these rules produces output that is hard to audit and may silently violate process obligations. The ``always-load`` tag solves this. Any ``FLIN_`` or ``FLSK_`` tagged ``always-load`` is mirrored as a one-line entry in the ``## Always-Active Rules`` section of ``.github/copilot-instructions.md``. Because that file is loaded automatically by GitHub Copilot on every session start — before any MCP call — the rules it contains are always in effect. Key properties: * **Self-maintaining** — ``FLIN_UBFLOW_018`` requires the ``Always-Active Rules`` table to be updated immediately whenever an ``always-load`` need is created or modified. * **Minimal footprint** — only genuinely session-critical rules receive the tag; the copilot-instructions.md stays concise. * **Traceable** — every entry in the table links to a fully-specified ``FLIN_`` or ``FLSK_`` need with a ``FLSP_`` and ``FLST_`` chain. .. _concept-agent-families: ubFlow based Agent Families --------------------------- **Status**: :bdg-primary:`Implemented` To support comprehensive workflows in system and software development, multiple specialized agents are required. While these agents share common rules, each is tailored for distinct tasks. ubFlow streamlines the creation and management of agent families by providing standardized mechanisms and domain knowledge for their development and integration. An agent family is installed into the user's documentation project and repository, providing all definitions, data, and tooling required for operation. This enables independent, project-specific customization of agent behavior. The family model directly reflects how regulated projects are structured: ASPICE mandates separate process areas for system requirements (SYS.2), software requirements (SWE.1), architecture (SWE.2), and testing (SWE.4–SWE.6) — each with defined work products and entry/exit criteria. Equivalent role separations exist in DO-178C and IEC 62304. .. mermaid:: flowchart LR user(User) subgraph ubcode["ubCode"] ubflow(ubFlow) subgraph ubflow_docs[Docs & Traceability] ubflow_common(ubFlow Common Knowledge) ubflow_aspice(ubFlow ASPICE Family) end end subgraph github["github Config"] agent0(ASPICE Orchestration) agent1(Agent SYS.2) agent2(Agent SWE.1) agent3(Agent ...) end subgraph project["Project Docs"] docs(Documentation) process("Process Artifacts
(Reqs,Specs,Test cases)") inst("Agent
Instructions") skills("Agent
Skills") inst -- links --> process skills -- links --> process linkStyle 0,1 stroke:#d4ff3e,stroke-width:2px, stroke-dasharray:5 5 end user -- "1. Create and install ASPICE agents" --> ubflow ubflow_common -- 2. Retrieve needed
agent information --> ubflow ubflow_aspice -- 3. Retrieve needed
ASPICE information --> ubflow ubflow -- 4. Install instructions --> inst ubflow -- 5. Install skills --> skills ubflow -- 6. Update process artifacts --> process ubflow -- 7. Install agent definitions --> github agent1 -. uses .-> inst agent1 -. uses .-> skills classDef ub_new stroke:#d4ff3e,stroke-width:2px,color:#fff classDef ub_update stroke:#d4ff3e,stroke-width:2px,color:#fff,stroke-dasharray: 5 5 classDef ub fill:#d4ff3e,color:#333 class inst,skills,agent0,agent1,agent2,agent3 ub_new class process ub_update class ubflow ub .. _concept-change-branches: ubFlow Change branches ---------------------- **Status**: :bdg-primary:`Prototype` ubFlow separates agent work by integrating results only after thorough reviews and approvals. By supporting change proposals, multiple agentic runs with similar configurations can be executed in parallel, enabling comparison of outcomes and selection of the optimal result for final integration. This directly implements the change-request lifecycle required by ASPICE CHG.1 and the configuration baseline management of ISO 26262-8 §7 and DO-178C §7: parallel proposals are developed in isolation, reviewed, and only then merged into the controlled baseline. .. mermaid:: /_mermaid/git_branch_concept.mmd .. _concept-quality: Quality assurance for Sphinx-Needs objects ------------------------------------------- **Status**: :bdg-primary:`In Progress` ubFlow embeds a quality agent that evaluates Sphinx-Needs objects against defined quality criteria — regardless of whether the object belongs to ubFlow itself or is a project-specific artifact such as a system requirement or software specification. Quality checks are based on a weighted rubric: each category yields a score and an improvement proposal; the aggregated result is a single overall quality score. Criteria are configurable per Sphinx-Needs type, support project-specific measurement rules, and allow threshold adjustment per project context. By default, ubFlow Quality agents checks for: * Clarity & wording * Atomicity * Context & Conditions * Measurability / Acceptance Criteria * Testability * Interfaces & Data (I/O) * Safety / Risk / Degradation (ADAS) * Solution Neutrality .. figure:: /_static/ubcode_quality.png :align: center Example result of a quality check for one object. Presented in the ubCode Needs Tree. .. _concept-tracking: Agent usage tracking and reporting ---------------------------------- **Status**: :bdg-primary:`Open` In safety-critical and regulated projects, an AI agent is a **development tool** in the sense of functional-safety standards such as ASPICE or ISO 26262 — and like any tool, it must be qualified and its usage must be auditable. Without a structured record of what the agent did, which instructions it followed, and which artifacts it produced or modified, neither process compliance nor tool qualification can be demonstrated. ubFlow captures a full execution record for every agentic run: * **Prompt and agent configuration** — exact instruction set and parameters in effect at execution time * **Tool calls with inputs and outputs** — every MCP query, file read, and external API call * **Touched artifacts** — all files and need objects created or modified This audit trail directly supports three compliance objectives: * **Process compliance** — demonstrate that prescribed development steps were executed and traceable to project artifacts * **Tool qualification** — provide the evidence required by standards such as ASPICE SUP.8 or ISO 26262 Part 8 to qualify the AI agent as a trusted development tool * **AI transparency** — automatically mark commits and pull requests as AI-assisted, enabling downstream review and accountability ubFlow collects this data transparently, with no instrumentation effort required from the user, by leveraging the `VS Code Copilot OpenTelemetry support `_: .. mermaid:: sequenceDiagram Participant User Participant ubFlow Participant CoPilot box darkgreen Agent stuff Participant Agent Participant ubCode MCP Participant File X Participant Tool A Participant Subagent end User->>CoPilot : Invokes agent CoPilot->>ubFlow: Starts on-the-fly reporting
via OpenTelemetry par Agent actions CoPilot->> Agent: Executes Agent Agent<<->>ubCode MCP: Gets Instructions Agent<<->>File X: Changes file Agent<<->>Tool A: Calls tool Agent<<->>Subagent: Triggers a subagent end ubFlow ->> ubFlow: Analyses Agent events ubFlow ->> User: Presents usage report .. _concept-scoped-environment: Scoped Agent Environment ------------------------ **Status**: :bdg-primary:`Open` Agents execute inside a controlled environment whose boundaries are defined entirely by Sphinx-Needs objects in the project documentation. Three mechanisms enforce this scope: * **Dev Container** — a declarative container definition pins the exact toolchain, extensions, and MCP servers available to the agent. No tool outside the declared set can be invoked. * **VS Code Settings** — workspace settings restrict the active MCP servers to the project-approved list. No undeclared server endpoint is exposed to the agent. * **ubCode MCP Server** — server-side access control ensures that only features explicitly enabled in the project's Sphinx-Needs configuration are surfaced. Agents cannot query or modify data outside their designated scope. This containment is paired with the :ref:`agent usage tracking and reporting ` capability: adherence to the scoped environment can be verified and demonstrated as part of a tool-qualification audit trail, as required by ASPICE SUP.8 and ISO 26262-8 §11. .. _concept-reviews: Sphinx-Needs based Review concept --------------------------------- **Status**: :bdg-primary:`Open` Documented peer reviews with explicit disposition are a mandatory verification activity in regulated development — required by ASPICE SWE.3/SWE.4, ISO 26262-6 §8, IEC 62304 §5.5, and DO-178C §11.9. Traditionally, these are separate review documents with manual author signatures tied to a specific document version. ubFlow agents document reviews as Sphinx-Needs objects, hard-linked to the exact artifact version via content hash — providing equivalent evidence automatically. Example:: .. req:: Park Assist distance range :id: REQ_PARK The park assist must work in the range of 50cm down to 5cm. .. review:: Functional Review :by: Max Mustermann :for: REQ_PARK[hash=ADEF3] :status: change_required The max. distance is too low, it must be at least 200cm .. review:: Agentic Quality Review :by: Quality Agent :for: REQ_PARK[hash=ADEF3] :status: change_required The requirement is not atomic. It should be split into two requirements, one for max and one for min distance. .. review:: Testing team :by: Peter Tester :for: REQ_PARK[hash=ADEF3] :status: approved All good, can be tested. .. _concept-process: Processes description for humans and agents ------------------------------------------- **Status**: :bdg-primary:`Open` In regulated development, a process is not just documentation — it is a contract: it defines what steps must be performed, in what order, by whom, and with what entry and exit criteria. Both human engineers and AI agents must understand this contract to act correctly inside a complex process landscape. ubFlow represents process knowledge as first-class Sphinx-Needs objects. Process definitions, phases, activities, roles, and work products are all structured, queryable, and traceable — not buried in unstructured text. Agents query these objects at runtime via the ubCode MCP server, giving them precise, up-to-date process context without prompt engineering overhead. Key capabilities: * **Process phases** — define lifecycle phases (e.g., requirements, architecture, testing) with entry and exit criteria, responsible roles, and linked work products. * **Process activities** — break phases into discrete, actionable steps. Each activity carries a description, inputs, outputs, and the agent or role responsible. * **Work products** — declare the expected artifacts (documents, models, code) produced or consumed by each activity, and link them to Sphinx-Needs requirements. * **Role assignments** — specify whether a step is performed by a human engineer, an AI agent, or both — enabling hybrid human/agent workflows. * **Traceability to instructions** — every agent instruction (``FLIN_``) and skill (``FLSK_``) can be linked to the process activity it implements, providing end-to-end traceability from process obligation to agent behaviour. .. _concept-workflows: Optimized workflows ------------------- **Status**: :bdg-primary:`Open` Combined with the review concept described above, each agentic workflow step is optimized for concise, quality-driven execution. Reviews serve both as validation and as gatekeepers: the output of one agent becomes the input for the next. Review tasks are performed in parallel by human engineers and agentic AI, ensuring robust and efficient quality assurance. This gate-driven structure mirrors the V-model entry/exit criteria of ASPICE and the phase-review requirements of ISO 26262 and DO-178C: the verified output of one process step becomes the controlled input to the next. .. mermaid:: flowchart TD prompt("User prompt") prompt -- triggers --> agent1 agent1 -. requests update .-> prompt subgraph a1["Agentic Step 1"] agent1("Agent 1") agent2r("Agent 2 Review") result1("Agent 1 Result") reviews1("Reviews 1") eng("Engineer") agent1 -- produces --> result1 result1 -- requests reviews --> eng result1 -- requests reviews --> agent2r eng -- creates --> reviews1 agent2r -- creates --> reviews1 reviews1 -. requests changes .-> agent1 end subgraph a2["Agentic Step 2"] agent2("Agent 2") result2("Agent 2 Result") agent3r("Agent 3 Review") reviews2("Reviews 2") eng2("Engineer") reviews1 -- triggers --> agent2 agent2 -- produces --> result2 result2 -- requests reviews --> eng2 result2 -- requests reviews --> agent3r eng2 -- creates --> reviews2 agent3r -- creates --> reviews2 reviews2 -. requests changes .-> agent2 end classDef ag1 fill:#d4ff3e,color:#333 classDef ag2 fill:#3ed43e,color:#333 classDef ag3 fill:#d43e3e,color:#333 class agent1,result1,reviews1 ag1 class agent2,result2,reviews2,agent2r ag2 class agent3r ag3 .. _concept-chatbots: Project- and Workflow-specific Support Chatbots ----------------------------------------------- **Status**: :bdg-primary:`In Progress` ubFlow equips agents with structured access to framework documentation (Sphinx, Sphinx-Needs) and project-specific content. It indexes and classifies the available documentation so that agents can retrieve precisely the knowledge relevant to a given task — without noise from unrelated content. The underlying knowledge graph is built from multiple source layers and made queryable via the ubCode MCP server: .. mermaid:: flowchart LR subgraph sources["ubFlow Knowledge Sources"] sphinx("Sphinx &
Sphinx-Needs Docs") ubflow_docs("ubFlow
Documentation") project("Project
Documentation") proc("Process Artifacts
(Reqs, Specs, Tests)") end subgraph kg["Knowledge Graph (ubCode)"] index("Indexed &
Classified Content") end subgraph agents["Agents"] agent1("Agent A") agent2("Agent B") end sphinx --> index ubflow_docs --> index project --> index proc --> index index -- "focused query
via MCP" --> agent1 index -- "focused query
via MCP" --> agent2 .. _concept-docmodel: Documentation model ------------------- **Status**: :bdg-primary:`Implemented` The Sphinx-Needs object model used by ubFlow has the following elements: * **Flow Story** (``FLST_``): Describes the motivation of an agentic feature * **Flow Spec** (``FLSP_``): Describes the technical realisation of a flow story. * **Flow Inst** (``FLIN_``): A set of instructions for the final agent, related to the flow spec. * **Flow Skill** (``FLSK_``): A specific process and tool description for a specific problem. * **Flow Tool** (``FLTL_``): A tool or script description, which can be used by an agent. The need types map to standard-required work products: Flow Stories → stakeholder needs (ASPICE SYS.1 / ISO 26262-3 / IEC 62304 §5.2); Flow Specs → software requirements (ASPICE SWE.1 / ISO 26262-6 §6); Flow Insts/Skills → work instructions and process knowledge (ASPICE SUP.8 / ISO 26262-8 §11); Flow Tools → qualified tool descriptions (ASPICE SUP.8 BP6 / ISO 26262-8 §11). Flow Stories can also be bundled into **Epics**, which can be used by agents like the Installer to categorize use cases for their work. .. mermaid:: flowchart TD epic["Epic"] -.-> us["Flow Story"] --> spec["Flow Spec"] style epic stroke-dasharray: 5 5 subgraph col["Information for Agents"] direction LR inst["Flow Inst"] --> skill["Flow Skill"] --> tool["Flow Tool"] end spec --> col ubFlow Presentation ------------------- A concise slide deck for managers and team leads — covering the core concepts and value proposition of ubFlow without deep technical detail. .. raw:: html
↓ Download PDF
Table of contents ----------------- .. toctree:: :maxdepth: 2 core/index families/index flow_traceability contribute todo Table of objects ---------------- .. needtable:: :columns: id, title, type