ubFlow Documentation

Warning

Alpha Status — This project is in active development.

Please report issues via GitHub Issues. Contributions and feedback are welcome!

AI-Assisted Requirements Engineering with ASPICE Traceability

“Safety-critical development demands traceability. AI agents need focused context, not the entire repo.”

ubFlow combines both: It uses sphinx-needs traceability links to navigate from Stakeholder Needs through Requirements down to Design Specs — exactly what ASPICE and ISO 26262 require. AI agents follow these links to find only the affected elements, making development O(affected), not O(total).

Whether you’re building automotive ECUs, medical devices, or pure software — ubFlow scales with your compliance needs.

Quick Start

1. Download & extract the latest release.

2. Run the init script from your project directory:

# Windows
C:\path\to\ubFlow\scripts\powershell\init.ps1

# Linux / Mac
/path/to/ubFlow/scripts/bash/init.sh

3. Open VS Code Copilot Chat and type @ubFlow.setup — the agent handles the rest.

That’s it. Dependencies, config, validation — all automated.

Prerequisites: VS Code + GitHub Copilot, Python 3.10+, uv package manager

How It Works

Three Levels with ASPICE Traceability

ubFlow supports three workflow models depending on your compliance needs:

Workflow Model

When to Use

Full ASPICE

Safety-critical systems (automotive ISO 26262, medical IEC 62304)

SYS.1/2/3 → SWE.1/2/3/4/5/6

Software Feature

Pure software with external system requirements

SWE.1/2/3/4/5/6 (no system level)

Simplified ASPICE

Software-only, agile teams, internal tools

NEED → REQ → SPEC (ubFlow’s own approach)

For all models, traceability links connect the levels:

Stakeholder Need   ──links──▶   Requirements   ──links──▶   Design Specs
   (WHY)                           (WHAT)                       (HOW)

When you request a change, AI agents follow these links to find only the affected elements — no searching, no scanning the entire codebase.

See Process Documentation for detailed ASPICE alignment.

Your AI Team

ubFlow provides specialized agents organized by their role in the ASPICE workflow.

Primary Entry Point

Agent

What it does

@ubflow.orchestrate

Start here! Analyzes change requests, creates Change Document, coordinates workflow through ASPICE levels

ASPICE Workflow Agents (invoked by orchestrate)

Agent

What it does

@ubflow.need

Capture stakeholder needs (SYS.1)

@ubflow.sysreq

Define system requirements (SYS.2)

@ubflow.sysarch

Design system architecture (SYS.3)

@ubflow.swreq

Define software requirements (SWE.1)

@ubflow.swarch

Design software architecture (SWE.2)

@ubflow.swdesign

Create detailed design specifications (SWE.3)

@ubflow.impl

Implement code and unit tests (SWE.4)

@ubflow.test

Define integration/qualification tests (SWE.5/6)

@ubflow.testrun

Execute tests and record results (SWE.6)

Quality & Verification

Agent

What it does

@ubflow.verify

Final verification: validates implementation against Change Document

@ubflow.mece

Horizontal validation: finds gaps and redundancies in specs

@ubflow.trace

Vertical validation: traces one element through all ASPICE levels

Support & Management

Agent

What it does

@ubflow.setup

Install or update ubFlow in your project

@ubflow.memory

Update copilot-instructions.md after changes

@ubflow.review

Review and approve proposals at any workflow step

@ubflow.release

Manage versioning, release notes, GitHub publishing

Typical workflow: orchestrate → (need/sysreq/swreq/swdesign/impl/test) → verify → memory → release

See Change Workflows for detailed workflow descriptions.

Why ubFlow?

Advantages

✅ ASPICE-Compliant AI Assistance — AI agents work within ASPICE process structure

✅ Validated Documentation — Every specification documents:

  • Input parameters and content

  • Decision-making process and rationale

  • Human review at each step

✅ Human-in-the-Loop — Reviews required after every agent step

✅ Verification Built-In — Plans are verified against actual implementation

✅ Full Traceability — Everything stored as linked sphinx-needs objects

✅ ubCode MCP Integration — Fast, validated traceability queries via MCP server

✅ Branch-Based Exploration — Test multiple alternative solutions in parallel branches

Trade-Offs

⚠️ Slower than ad-hoc development — Documentation overhead increases cycle time

⚠️ AI-Heavy Validation — Some validation steps still rely too much on AI judgment

⚠️ Verbose Reporting — Agent outputs could be more concise and precise

FAQ

Do I need to know reStructuredText?

Not really. The agents write RST for you. But understanding the basics helps — it’s just text with directives (like .. need::).

Can I use this with an existing project?

Yes. @ubFlow.setup can adopt an existing docs/ folder. Or start fresh and grow from there.

What about Markdown?

ubFlow uses myst-parser so you can mix Markdown and RST. Specs use RST (sphinx-needs requirement), but guides can be Markdown.

Is this only for automotive / ASPICE?

No. The three-level hierarchy (Stakeholder Needs → Requirements → Design) is universal. ASPICE alignment is optional and documented under Process Documentation.

How is this different from plain Copilot?

Copilot excels at writing code. But it doesn’t know which of your 500 requirements are affected by a change. ubFlow solves the navigation problem — then hands focused context to Copilot.

Why sphinx-needs?

It’s mature, extensible, and generates structured JSON for programmatic access. The ubCode MCP server reads this JSON for fast traceability queries.

Getting Started

Quick Start

Specification Modules

Specifications by Theme

Guides & Process

Guides

Release Information

Release Notes

Indices