Change Workflows

ubFlow supports different workflow types based on the scope and nature of changes. All workflows follow ASPICE (Automotive SPICE) process structure.

ASPICE Process Levels

  • SYS.1: Stakeholder Requirements Definition (Need Analysis)

  • SYS.2: System Requirements Analysis

  • SYS.3: System Architectural Design

  • SWE.1: Software Requirements Analysis

  • SWE.2: Software Architectural Design

  • SWE.3: Software Detailed Design

  • SWE.4: Software Unit Construction & Testing

  • SWE.5: Software Integration Test

  • SWE.6: Software Qualification Test

Workflow Types

Full ASPICE Workflow

Steps: Need → System Requirements → System Architecture → Software Requirements → Software Architecture → Implementation → Test Definition → Test Execution → Verification

ASPICE Processes: SYS.1 → SYS.2 → SYS.3 → SWE.1 → SWE.2 → SWE.3 → SWE.4 → SWE.5/6

Used for: New features requiring complete requirements engineering cycle, system-level changes, features with stakeholder needs.

Example: Adding complete user authentication system with password reset, 2FA integration.

.. change:: CHG_2026_001
   :workflow: full-aspice

Typical Duration: 2-4 weeks

Agent Sequence: @need → @sysreq → @sysarch → @swreq → @swarch → @impl → @test → @testrun → @verify

Software Feature Workflow

Steps: Software Requirements → Software Architecture → Implementation → Test Definition → Test Execution → Verification

ASPICE Processes: SWE.1 → SWE.2 → SWE.3 → SWE.4 → SWE.5/6

Used for: Software features extending existing system architecture without system-level changes.

Example: Adding new API endpoint to existing service, implementing new business rule.

.. change:: CHG_2026_002
   :workflow: sw-feature

Typical Duration: 1-2 weeks

Agent Sequence: @swreq → @swarch → @impl → @test → @testrun → @verify

When to use: System architecture is stable, only software implementation changes

System Change Workflow

Steps: System Requirements → System Architecture → Software Requirements → Software Architecture → Implementation → Test Definition → Test Execution → Verification

ASPICE Processes: SYS.2 → SYS.3 → SWE.1 → SWE.2 → SWE.3 → SWE.4 → SWE.5/6

Used for: System architecture changes requiring software updates (e.g., HW/SW allocation changes).

Example: Moving functionality from software to hardware module, adding new external interface.

.. change:: CHG_2026_003
   :workflow: sys-change

Typical Duration: 2-3 weeks

Agent Sequence: @sysreq → @sysarch → @swreq → @swarch → @impl → @test → @testrun → @verify

When to use: Hardware/software allocation changes, external interface modifications

Bugfix Workflow

Steps: Implementation → Test Definition → Test Execution → Verification

ASPICE Processes: SWE.3 → SWE.4 → SWE.5/6

Used for: Bug fixes that don’t require requirement or architecture changes.

Example: Fixing null pointer exception, correcting calculation logic, fixing typo in error message.

.. change:: CHG_2026_004
   :workflow: bugfix

Typical Duration: 1-3 days

Agent Sequence: @impl → @test → @testrun → @verify

When to use: Code behaves incorrectly, no specification changes needed

Software Refactoring Workflow

Steps: Software Architecture → Implementation → Test Definition → Test Execution → Verification

ASPICE Processes: SWE.2 → SWE.3 → SWE.4 → SWE.5/6

Used for: Software refactoring with architectural impact (e.g., changing design patterns, module restructuring).

Example: Refactoring monolith to modules, introducing repository pattern, dependency injection.

.. change:: CHG_2026_005
   :workflow: refactor-sw

Typical Duration: 1-2 weeks

Agent Sequence: @swarch → @impl → @test → @testrun → @verify

When to use: Code restructuring, design pattern changes, software quality improvements

System Refactoring Workflow

Steps: System Architecture → Software Architecture → Implementation → Test Definition → Test Execution → Verification

ASPICE Processes: SYS.3 → SWE.2 → SWE.3 → SWE.4 → SWE.5/6

Used for: System architecture refactoring affecting software organization.

Example: Changing component deployment strategy, splitting monolithic system into services.

.. change:: CHG_2026_006
   :workflow: refactor-sys

Typical Duration: 2-3 weeks

Agent Sequence: @sysarch → @swarch → @impl → @test → @testrun → @verify

When to use: System-level restructuring, deployment changes, component reorganization

Test Addition Workflow

Steps: Test Definition → Test Execution

ASPICE Processes: SWE.4 → SWE.5/6

Used for: Adding tests to existing, stable functionality without code changes.

Example: Adding missing unit tests, increasing test coverage, adding regression tests.

.. change:: CHG_2026_007
   :workflow: test-addition

Typical Duration: 1-3 days

Agent Sequence: @test → @testrun

When to use: Improving test coverage for stable code, adding missing test cases

Workflow Selection Guide

Use this decision tree to select the appropriate workflow:

Does it involve stakeholder needs?
├─ Yes → full-aspice
└─ No
   ├─ Does it change system architecture (HW/SW allocation)?
   │  ├─ Yes → sys-change
   │  └─ No
   │     ├─ Does it change software architecture?
   │     │  ├─ Yes
   │     │  │  ├─ System-level impact? → refactor-sys
   │     │  │  └─ Software-only impact? → refactor-sw
   │     │  └─ No
   │     │     ├─ Does it require new software requirements?
   │     │     │  ├─ Yes → sw-feature
   │     │     │  └─ No
   │     │     │     ├─ Only adding tests? → test-addition
   │     │     │     └─ Only fixing bugs? → bugfix

Workflow Step Details

1. Need Analysis (SYS.1)

Agent: @ubflow.need

Purpose: Capture stakeholder needs from user perspective

Output: NEED_* directives with success criteria

Key Activities: Stakeholder analysis, need elicitation, prioritization

2. System Requirements (SYS.2)

Agent: @ubflow.sysreq

Purpose: Define what the system must do

Output: SYSREQ_* directives with verification methods

Key Activities: Requirements derivation, interface specification, verification planning

3. System Architecture (SYS.3)

Agent: @ubflow.sysarch

Purpose: Design system structure (hardware + software)

Output: SYSARCH_* directives with component diagrams

Key Activities: Component definition, HW/SW allocation, interface design, architectural decisions

4. Software Requirements (SWE.1)

Agent: @ubflow.swreq

Purpose: Define what software must do

Output: SWREQ_* directives with API specifications

Key Activities: Software-level requirements, API design, data models, performance specs

5. Software Architecture (SWE.2)

Agent: @ubflow.swarch

Purpose: Design software structure (modules, classes)

Output: SWARCH_* directives with module diagrams

Key Activities: Module design, class design, pattern application, detailed interfaces

6. Implementation (SWE.4)

Agent: @ubflow.impl

Purpose: Write code according to architecture

Output: Source code, unit tests, documentation

Key Activities: Coding, unit testing, code review, documentation

7. Test Definition (SWE.5/6)

Agent: @ubflow.test

Purpose: Define test cases to verify requirements

Output: TEST_* directives with test strategies

Key Activities: Unit test planning, integration test planning, test data specification

8. Test Execution (SWE.6)

Agent: @ubflow.testrun

Purpose: Execute tests and record results

Output: TESTRUN_* directives with evidence

Key Activities: Test execution, result recording, coverage analysis, defect reporting

9. Verification

Agent: @ubflow.verify

Purpose: Verify implementation against all requirements

Output: Verification report with traceability matrix

Key Activities: Requirements verification, traceability check, final approval

Proposal Branch Pattern

Each workflow step creates a proposal branch for review.

Git Branch Structure:

main
  └── changes/CHG_2026_001/          # Change namespace
      ├── change                     # Main change branch
      ├── proposal-need-1            # Proposal branches (parallel proposals)
      ├── proposal-need-2
      ├── proposal-swreq-1
      └── ...

Rationale: Git doesn’t support hierarchical branches like change/X/proposal-Y. Using changes/X/change and changes/X/proposal-{STEP}-{N} allows all branches at the same level under the changes/X/ namespace.

File Structure (in change document repository):

changes/change-001/
├── change.rst                      # Change document
├── proposal_need_1/                # Proposal content
│   └── needs.rst
├── proposal_sysreq_1/
│   └── sysreq.rst
├── proposal_swreq_1/
│   └── swreq.rst
└── proposal_impl_1/
    └── implementation notes

Review Gates

Each step requires human approval before proceeding:

  1. Proposal Creation: Agent creates proposal branch

  2. Review: Human reviews proposal using checklist

  3. Approval/Rejection:

    • Approved: Merge to change branch, proceed to next step

    • Changes Requested: Agent creates proposal_N+1

    • Blocked: Problem object created, resolution required

Problem Resolution

When problems are discovered:

.. problem:: PROB_CHG123_001
   :detected_in: swarch
   :affects_step: swreq
   :severity: blocker
   :links: ACT_CHG123_SWARCH_001

   Description of problem requiring resolution

Resolution Process:

  1. Problem object created

  2. Affected step agent creates resolution action

  3. New proposal created with fix

  4. Original step unblocked after approval

  5. Workflow proceeds

Traceability

Full traceability maintained across all levels:

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

Traceability Tools:

  • get_need_links('<ID>', max_depth=N) - Follow links with ubCode MCP

  • @ubflow.trace - Vertical traceability check

  • @ubflow.mece - Horizontal consistency check

Workflow Metrics

Typical effort distribution (full-aspice workflow):

  • Need Analysis: 5%

  • System Requirements: 10%

  • System Architecture: 15%

  • Software Requirements: 10%

  • Software Architecture: 15%

  • Implementation: 30%

  • Test Definition: 5%

  • Test Execution: 5%

  • Verification: 5%

Quality Gates:

  • 100% traceability (all requirements → tests)

  • 90%+ code coverage (unit tests)

  • 80%+ code coverage (integration tests)

  • All tests passing

  • No blocker problems

Example: Complete Workflow

# 1. Orchestrator creates change plan
@ubflow.orchestrate analyze "Add user password reset feature"

# 2. Need Analysis
@ubflow.need (creates proposal_need_1)
# Human reviews and approves

# 3. System Requirements
@ubflow.sysreq (creates proposal_sysreq_1)
# Human reviews and approves

# 4. System Architecture
@ubflow.sysarch (creates proposal_sysarch_1)
# Human reviews and approves

# 5. Software Requirements
@ubflow.swreq (creates proposal_swreq_1)
# Human reviews and approves

# 6. Software Architecture
@ubflow.swarch (creates proposal_swarch_1)
# Human reviews and approves

# 7. Implementation
@ubflow.impl (creates proposal_impl_1)
# Human reviews and approves

# 8. Test Definition
@ubflow.test (creates proposal_test_1)
# Human reviews and approves

# 9. Test Execution
@ubflow.testrun (creates proposal_testrun_1)
# Human reviews results

# 10. Verification
@ubflow.verify (creates proposal_verify_1)
# Human approves final verification

# 11. merge to main

Best Practices

  1. Choose minimal workflow: Don’t over-engineer, use shortest appropriate workflow

  2. Document decisions: Use architectural decision records (ADRs)

  3. Iterate when needed: Multiple proposals for a step are normal

  4. Maintain traceability: Always link to parent elements

  5. Use SHOULD where appropriate: Not everything is mandatory (SHALL vs SHOULD)

  6. Quantify acceptance criteria: Use measurable metrics

  7. Review carefully: Catching issues early saves time later

  8. Keep proposals focused: One concern per proposal

For detailed agent instructions, see .github/agents/ubflow.*.agent.md