Installation¶
Bootstrap, portability, installation, adoption, and updates.
Last Updated: 2026-02-15
Level 0: Stakeholder Needs (WHY)¶
As a developer (or cloud agent), I want to have the sphinx-needs environment auto-initialize, so that I can start working without manual setup. Acceptance Scenarios:
|
As a developer, I want to use ubFlow in multiple projects, so that I have consistent requirements engineering everywhere. Acceptance Scenarios:
|
As a developer starting a new project, I want to install ubFlow from the beginning, so that I have requirements engineering built-in from day one. Acceptance Scenarios:
|
As a developer with an existing project, I want to adopt ubFlow without disrupting my current work, so that I can add requirements engineering to a project already in progress. Acceptance Scenarios:
|
As a developer using ubFlow, I want to update to the latest version, so that I benefit from new features, fixes, and improvements. Acceptance Scenarios:
|
Level 1: Requirements (WHAT)¶
Description: ubFlow SHALL be a standalone toolkit that can be used across multiple projects. Rationale: Enables ubFlow to be maintained separately and reused across multiple projects. Acceptance Criteria:
Note: Installation, update, and version tracking covered by REQ_INST_NEW_PROJECT through REQ_INST_AUTO_DETECT. |
Description: ubFlow SHALL automatically initialize the sphinx-needs environment when it is not available. Rationale: Agents running in cloud environments or fresh checkouts need to bootstrap their own dependencies without manual intervention. Acceptance Criteria:
|
Description: ubFlow SHALL be distributed via GitHub Releases with semantic versioning. Rationale: GitHub Releases provides versioned distribution with automatic archive creation, enabling users to obtain specific versions and track what they have installed. Acceptance Criteria:
|
Description: ubFlow SHALL be installable into a new project. Rationale: New projects need a straightforward path to adopt ubFlow from the beginning. Acceptance Criteria:
|
Description: ubFlow SHALL be adoptable into an existing project without data loss. Rationale: Projects already in progress need to adopt ubFlow without disrupting their existing work. Acceptance Criteria:
|
Description: ubFlow SHALL be updatable to newer versions. Rationale: Users need to benefit from new features, fixes, and improvements over time. Acceptance Criteria:
|
Description: ubFlow SHALL preserve user customizations during adoption and updates. Rationale: Users invest effort in customizing their requirements and configuration. This must not be lost during updates. Acceptance Criteria:
|
Description: ubFlow SHALL require sphinx-needs and its dependencies as mandatory components, and guide the user through installation if not available. Rationale: sphinx-needs provides the traceability infrastructure that ubFlow relies on. The setup agent assists with dependency installation. Acceptance Criteria:
|
Description: ubFlow SHALL auto-detect its own location by searching for version.json files within the project directory only. Rationale: Release ZIP structure places ubFlow in versioned folders (ubFlow-X.Y.Z/). Manual path input is error-prone and breaks user experience. Auto-detection enables seamless installation from arbitrary extraction locations. Searching above the project root is a security/correctness risk when the download location is outside the workspace. Acceptance Criteria:
|
Level 2: Design (HOW)¶
Installation¶
Design: Minimal init scripts copy only the Setup Agent to enable installation. All other setup is handled interactively by the Setup Agent. Script Locations (in ubFlow installation):
Script Behavior (minimal):
Rationale:
Usage: # Windows (from target project directory)
C:\path\to\ubFlow\scripts\powershell\init.ps1
# Unix (from target project directory)
/path/to/ubFlow/scripts/bash/init.sh
Note: This is Step 1 of the installation process.
Step 2 is invoking |
Design: Installation is a two-step process: init script, then setup agent. Step 1: Init Script (manual)
Step 2: Setup Agent (@ubFlow.setup) Section 1: Auto-Detect ubFlow Location
Section 2: Check Dependencies (Interactive) The setup agent guides the user through installing required dependencies:
Section 3: Copy Files from ubFlow Using
Section 4: Validate and Confirm
Works for both new and existing projects. Existing Project Handling:
|
File Ownership & Updates¶
Design: Clear separation between ubFlow core files and user content. UbFlow Core (with intelligent merge):
Intelligent Merge for Agent Files: When updating agent/prompt files, the setup agent SHALL:
User Content (preserved during updates):
Shared/Merged (require interactive merge):
|
Design: Update is agent-driven with backup and rollback support. Update Flow: Step 0: Find Newest ubFlow Version
Step 1: Detect Update Mode
Step 2: Backup and Update If newer version available (from Step 0):
GitHub Release Query: # Agent uses fetch_webpage or terminal curl
curl -s https://api.github.com/repos/OWNER/ubFlow/releases/latest
Rollback on Failure: If any step fails after backup:
|
Auto-Detection¶
Design: PowerShell/Bash function that finds ubFlow installation via version.json search within the project directory only. Algorithm (PowerShell): function Find-UbFlowInstallation {
# Search ONLY within the project directory (workspace root)
$projectRoot = Get-Location
$foundVersions = @()
# Find all version.json files recursively within project directory
$versionFiles = Get-ChildItem -Path $projectRoot -Filter "version.json" `
-Recurse -Depth 3 -ErrorAction SilentlyContinue
foreach ($file in $versionFiles) {
try {
$content = Get-Content $file.FullName | ConvertFrom-Json
$version = $content.version
# Skip if not ubFlow version format
if ($version -notmatch '^(\d+)\.(\d+)\.(\d+)(-\w+(\.\d+)?)?$') {
continue
}
$foundVersions += [PSCustomObject]@{
Path = $file.Directory.FullName
Version = $version
File = $file.FullName
}
} catch {
# Skip invalid JSON
continue
}
}
if ($foundVersions.Count -eq 0) {
Write-Host "No ubFlow installation found in project directory: $projectRoot"
Write-Host ""
Write-Host "Would you like to download the latest version from GitHub?"
Write-Host " The setup agent can fetch the latest release automatically."
return $null # Agent handles GitHub download interactively
}
# Sort by version (newest first)
$sorted = $foundVersions | Sort-Object {
if ($_.Version -match '^(\d+)\.(\d+)\.(\d+)(-(\w+)\.?(\d+)?)?') {
$major = [int]$matches[1]
$minor = [int]$matches[2]
$patch = [int]$matches[3]
$prerelease = $matches[5]
$prereleaseNum = if ($matches[6]) { [int]$matches[6] } else { 0 }
return @($major, $minor, $patch, $(if ($prerelease) { 0 } else { 999 }), $prereleaseNum)
}
} -Descending
# Log all found versions
Write-Host "Found ubFlow installations:"
$sorted | ForEach-Object {
Write-Host " v$($_.Version) at $($_.Path)"
}
# Return newest
$newest = $sorted[0]
Write-Host "Selected newest: v$($newest.Version)" -ForegroundColor Green
return $newest.Path
}
Bash Version: Equivalent logic in bash using find, jq, and sort. Edge Cases:
Rationale:
|
Distribution¶
Design: ubFlow releases are distributed via GitHub Releases, which automatically creates .zip and .tar.gz archives of the repository at tagged commits. Release Contents:
Version Identification:
Directory Structure in Release Archive: ubFlow-X.Y.Z/
├── .github/
│ ├── agents/ # Agent definitions (*.agent.md)
│ ├── prompts/ # Prompt files (*.prompt.md)
│ ├── skills/ # Skill files (*.skill.md)
│ └── copilot-instructions.md
├── scripts/ # Init and utility scripts
├── templates/ # Document templates
├── docs/ # Self-documentation (including releasenotes.md)
├── version.json # Release version
└── README.md # Installation instructions
GitHub Release Mechanism:
Rationale:
|
Traceability¶
Stakeholder Needs¶
ID |
Title |
Status |
Priority |
|---|---|---|---|
Adopt ubFlow in Existing Project |
implemented |
mandatory |
|
Automatic Environment Bootstrap |
implemented |
high |
|
Use ubFlow Across Projects |
implemented |
medium |
|
Install ubFlow in New Project |
implemented |
mandatory |
|
Update ubFlow to Latest Version |
implemented |
mandatory |
Requirements¶
ID |
Title |
Status |
Tags |
|---|---|---|---|
Existing Project Adoption |
implemented |
installation; install; adoption |
|
Auto-Detection of ubFlow Installation |
implemented |
installation; install; autodetect |
|
Automatic Environment Setup |
implemented |
installation; init; automation |
|
Customization Preservation |
implemented |
installation; install; update; preservation |
|
ubFlow Distribution via GitHub Releases |
implemented |
installation; install; distribution |
|
New Project Installation |
implemented |
installation; install; new-project |
|
Portable Toolkit |
implemented |
installation; portability; sync |
|
Sphinx-Needs Mandatory Dependency |
implemented |
installation; install; sphinx-needs; dependency |
|
Version Update and Migration |
implemented |
installation; update; migration |
Design Specifications¶
ID |
Title |
Status |
Links |
|---|---|---|---|
ubFlow Auto-Detection Algorithm |
implemented |
||
File Layout and Ownership |
implemented |
||
Init Scripts for Environment Setup |
implemented |
REQ_INST_AUTO_SETUP; REQ_INST_PORTABLE; REQ_INST_NEW_PROJECT; REQ_INST_ADOPT_EXISTING |
|
Release Structure |
implemented |
||
Setup Agent Design |
implemented |
REQ_INST_NEW_PROJECT; REQ_INST_ADOPT_EXISTING; REQ_INST_SPHINX_NEEDS_DEP; SPEC_INST_AUTO_DETECT; SPEC_INST_FILE_OWNERSHIP; SPEC_INST_UPDATE_PROCESS |
|
Update Process |
implemented |
REQ_INST_VERSION_UPDATE; SPEC_INST_AUTO_DETECT; SPEC_INST_FILE_OWNERSHIP |