Quick Start Guide

Welcome to ubFlow’s ASPICE-aligned requirements engineering workflow!

Overview

ubFlow orchestrates requirements engineering following Automotive SPICE (ASPICE) process structure. Instead of throwing your entire codebase at an AI agent, ubFlow follows traceability links to provide focused context.

Installation

# From your project directory:
/path/to/ubflow/scripts/bash/init.sh              # Linux/Mac
C:\path\to\ubflow\scripts\powershell\init.ps1     # Windows

# Then in VS Code:
@ubflow.setup

Your First Change

Understanding Git Branches

ubFlow uses a structured branching strategy to manage changes:

main
  └── changes/CHG_2026_001/          # Change namespace
      ├── change                     # Main change branch
      ├── proposal-need-1            # Proposal branches
      ├── proposal-swreq-1           # (reviewed before merging)
      └── proposal-impl-1

Why this structure? Git doesn’t support hierarchical branches like change/X with sub-branches change/X/proposal-Y. By using changes/X/change and changes/X/proposal-Y, all branches exist at the same level under the changes/X/ namespace, allowing proper branch creation, comparison, and cleanup.

Workflow:

1. Orchestrator creates changes/{CHANGE_ID}/change branch

2. Step agents create proposal branches (changes/{CHANGE_ID}/proposal-{STEP}-{N})

3. You review proposals and approve the best one

4. Approved proposal merges into changes/{CHANGE_ID}/change branch

5. After all steps, verify merges changes/{CHANGE_ID}/change into main

1. Start with the Orchestrator

@ubflow.orchestrate analyze "Add password strength validation to user registration"

The orchestrator will:

• Analyze your request

• Determine appropriate workflow type

• Create a change document (changes/change-001/change.rst)

• Assign the first agent

2. Follow the Workflow

ubFlow supports 7 workflow types based on change scope:

Workflow	Example Use Case	Steps
full-aspice	New feature with stakeholder needs	Need → SysReq → SysArch → SwReq → SwArch → Impl → Test → TestRun → Verify
sw-feature	Software-only feature	SwReq → SwArch → Impl → Test → TestRun → Verify
sys-change	System architecture change	SysReq → SysArch → SwReq → SwArch → Impl → Test → TestRun → Verify
bugfix	Bug fix	Impl → Test → TestRun → Verify
refactor-sw	Software refactoring	SwArch → Impl → Test → TestRun → Verify
refactor-sys	System refactoring	SysArch → SwArch → Impl → Test → TestRun → Verify
test-addition	Add missing tests	Test → TestRun

📖 Full details: See Change Workflows

3. Work Step-by-Step

Each agent creates a proposal branch for review:

# Example: Need analysis (SYS.1)
@ubflow.need

# Agent creates: changes/change-001/proposal_need_1/
# You review and approve

# Next: System requirements (SYS.2)
@ubflow.sysreq

# Agent creates: changes/change-001/proposal_sysreq_1/
# You review and approve

# Continue through workflow...

4. Review & Approve

After each step:

1. Review the proposal branch

2. Approve (merge to change branch) or Request Changes (agent creates proposal_N+1)

3. Proceed to next step or handle problems

5. Final Verification

@ubflow.verify

# Creates verification report with:
# - Traceability matrix
# - Coverage analysis
# - Requirements verification
# - Final approval checklist

ASPICE Agents

System Level (SYS)

• @ubflow.need (SYS.1) - Capture stakeholder needs

• @ubflow.sysreq (SYS.2) - Define system requirements

• @ubflow.sysarch (SYS.3) - Design system architecture

Software Level (SWE)

• @ubflow.swreq (SWE.1) - Define software requirements

• @ubflow.swarch (SWE.2) - Design software architecture

• @ubflow.impl (SWE.4) - Implement code and unit tests

Testing (SWE)

• @ubflow.test (SWE.5/6) - Define integration and qualification tests

• @ubflow.testrun (SWE.6) - Execute tests and record results

Supporting

• @ubflow.orchestrate - Workflow coordination

• @ubflow.verify - Final verification

• @ubflow.mece - Quality checks (gaps/redundancies)

• @ubflow.trace - Traceability analysis

• @ubflow.release - Release management

• @ubflow.setup - Installation

• @ubflow.memory - Documentation updates

Common Patterns

Bug Fix (Fastest)

@ubflow.orchestrate analyze "Fix null pointer in user profile loading"
# Workflow: bugfix (4 steps)
# Duration: 1-3 days

Software Feature

@ubflow.orchestrate analyze "Add export to CSV functionality"
# Workflow: sw-feature (6 steps)
# Duration: 1-2 weeks

Complete Feature

@ubflow.orchestrate analyze "User wants to receive email notifications for important events"
# Workflow: full-aspice (9 steps)
# Duration: 2-4 weeks

Problem Resolution

If an agent discovers issues:

.. problem:: PROB_CHG001_001
   :detected_in: swarch
   :affects_step: swreq
   :severity: blocker

   API signature incompatible with system interface requirements

The affected step’s agent is called to resolve the problem via a new proposal.

Traceability

Every element is linked:

NEED_* → SYSREQ_* → SYSARCH_* → SWREQ_* → SWARCH_* → Code → TEST_* → TESTRUN_*

Query links:

python scripts/python/get_need_links.py SWREQ_AUTH_001 --simple

Trace one element:

@ubflow.trace SWREQ_AUTH_001

Check MECE properties:

@ubflow.mece docs/requirements/sysreq_authentication.rst

Example Change Document Structure

changes/change-001/
├── change.rst                    # Change plan with all steps
├── proposal_need_1/              # Need analysis proposal
│   └── need_notifications.rst
├── proposal_sysreq_1/            # System requirements proposal
│   └── sysreq_notifications.rst
├── proposal_sysarch_1/           # System architecture proposal
│   └── sysarch_notification_service.rst
├── proposal_swreq_1/             # Software requirements proposal
│   └── swreq_notification_api.rst
├── proposal_swarch_1/            # Software architecture proposal
│   └── swarch_notification_modules.rst
├── proposal_impl_1/              # Implementation proposal
│   └── implementation_notes.md
├── proposal_test_1/              # Test definition proposal
│   └── test_notifications.rst
├── proposal_testrun_1/           # Test execution proposal
│   ├── testrun_notifications.rst
│   ├── junit-results.xml
│   └── evidence/
│       └── screenshot.png
└── proposal_verify_1/            # Verification proposal
    └── verification_report.rst

Best Practices

1. Choose minimal workflow - Bug fixes don’t need requirements

2. Review carefully - Catching issues early saves time

3. Keep proposals focused - One concern per proposal

4. Document decisions - Use ADRs for architectural choices

5. Maintain traceability - Always link to parent elements

6. Use SHALL appropriately - Not everything is mandatory

7. Quantify acceptance criteria - Use measurable metrics

Next Steps

• 📖 Read Change Workflows for detailed workflow descriptions

• 📖 Read Methodology: Specification Hierarchy & File Organization for file organization principles

• 📖 Read Naming Conventions for ID naming rules

• 🚀 Try a simple change to get familiar with the system

Getting Help

• Check agent instructions: .github/agents/ubflow.*.agent.md

• Review workflow documentation: Change Workflows

• Inspect example change: changes/change-example/

• Ask @ubflow.memory to update documentation if needed

---

Happy requirements engineering! 🎯