ubFlow Release Notes

v0.1.0 - 2026-02-16 (Initial Release)

Summary

ubFlow is a scalable requirements engineering toolkit designed for AI-assisted development. It uses sphinx-needs traceability links to provide focused context to AI agents - following links from Stakeholder Needs → Requirements → Design Specs to find only the affected elements.

Key Insight: AI agents need focused context, not the entire codebase. ubFlow achieves O(affected) not O(total) complexity.

✨ Core Features

Agent System

  • @ubFlow.change: Analyze change requests level-by-level with MECE validation

  • @ubFlow.implement: Execute approved changes with full traceability

  • @ubFlow.verify: Validate implementation matches Change Document

  • @ubFlow.mece: Horizontal consistency checks on any level

  • @ubFlow.trace: Vertical traceability analysis for elements

  • @ubFlow.memory: Keep copilot-instructions.md synchronized

  • @ubFlow.setup: Install/update ubFlow in projects

Three-Level Specification Hierarchy

  • Level 0: Stakeholder Needs (NEED_*) - problem domain

  • Level 1: Software Requirements (REQ_*) - detailed requirements

  • Level 2: Design Specs (SPEC_*) - solution domain

  • Full sphinx-needs traceability with :links: between all levels

Workflow System

  • Change Workflow: change → implement → verify → memory

  • Quality Workflow: Independent @mece and @trace validation

  • Release Workflow: version → validate → publish

  • Agent handoff chains documented and enforced

Installation & Updates

  • Bootstrap scripts for Windows (PowerShell) and Linux/Mac (Bash)

  • Auto-detection of ubFlow installation via version.json

  • Intelligent merge for user-modified agent files

  • Backup/rollback mechanism for safe updates

  • Single source of truth in .github/ directory

Git Branching Strategy

  • Change branches: changes/{CHANGE_ID}/change

  • Proposal branches: changes/{CHANGE_ID}/proposal-{STEP}-{N}

  • Flat namespace under changes/ (Git limitation workaround)

  • Multiple parallel proposals per change step

Documentation Framework

  • Sphinx with sphinx-needs extension for requirements traceability

  • Furo theme with light/dark mode support

  • File organization: L0/L1 by stakeholder theme, L2 by technical component

  • Descriptive ID naming: TYPE_THEME_SLUG (e.g., REQ_CHG_ANALYSIS_AGENT)

  • Methodology and naming conventions fully documented

Optional ASPICE Alignment

ubFlow supports three workflow models:

  • Full ASPICE: SYS.1/2/3 + SWE.1/2/3/4/5/6 (safety-critical systems)

  • Software Feature: SWE.1/2/3/4/5/6 (pure software projects)

  • Simplified ASPICE: NEED + REQ + SPEC (ubFlow’s own dogfooding approach)

Documentation available in docs/process/aspice_alignment.rst

📊 Specification Statistics

Level

Count

Status

Stakeholder Needs

22

21 implemented, 1 draft

Requirements

38

37 implemented, 1 approved

Design Specs

37

all implemented

🔧 Technical Dependencies

  • Python 3.10+

  • uv (Astral’s fast Python package manager)

  • sphinx >= 8.0.0

  • sphinx-needs >= 2.0.0

  • furo >= 2024.0.0

  • myst-parser >= 2.0.0

🚀 Getting Started

  1. Install uv (if not already installed):

    # Linux/Mac
curl -LsSf https://astral.sh/uv/install.sh | sh

# Windows
powershell -c "irm https://astral.sh/uv/install.ps1 | iex"

  2. Bootstrap ubFlow in your project:

    # Linux/Mac
bash <(curl -s https://raw.githubusercontent.com/danwos/ubflow/main/scripts/bash/init.sh)

# Windows
iex (irm https://raw.githubusercontent.com/danwos/ubflow/main/scripts/powershell/init.ps1)

  3. Build documentation:

    cd docs
uv venv
source .venv/bin/activate  # or .venv\Scripts\activate on Windows
uv pip install -r requirements.txt
uv run sphinx-build -b html . _build/html

  4. Start using agents in VS Code with GitHub Copilot Chat:

    • @ubFlow.change - Create a new change request

    • @ubFlow.mece - Validate level completeness

    • @ubFlow.trace - Follow traceability links

📚 Documentation

  • Full documentation: https://danwos.github.io/ubflow/

  • Quick Start: See docs/quickstart.rst

  • Methodology: See docs/methodology.rst

  • Naming Conventions: See docs/namingconventions.rst

  • ASPICE Alignment: See docs/process/aspice_alignment.rst

🙏 Acknowledgments

Built with:

  • Sphinx and sphinx-needs by useblocks

  • Furo theme by Pradyun Gedam

  • uv by Astral

  • GitHub Copilot for AI-assisted development

📝 Known Limitations

  • No automated test suite yet (coming in future releases)

  • Graphviz integration needs testing across platforms

  • Agent system requires GitHub Copilot (VS Code extension)

For detailed traceability, see the documentation