Installer Flow Stories ====================== .. flowstory:: Installer target location :id: FLST_UBFLOW_INST_01 :covered_by: AGENT_INSTALLER :status: approved :tags: ubflow, installer As an installing developer, I want to confirm the installation target location within my repository, because multiple documentation projects may coexist. .. flowstory:: Installer epic approvals :id: FLST_UBFLOW_INST_02 :covered_by: AGENT_INSTALLER :status: approved :tags: ubflow, installer As an installing developer, I want to select which epics (use-case collections) are activated for the installed agent family, so that I can exclude epics that require custom implementation — for example, a project-specific branching strategy. .. flowstory:: Epics :id: FLST_UBFLOW_INST_03 :covered_by: AGENT_INSTALLER :links: FLST_UBFLOW_INST_02 :status: approved :tags: ubflow, installer As a ubFlow developer, I want to group flow stories into epics so that epics serve as coarse-grained interaction units during the installation dialogue. .. flowstory:: Deterministic installation :id: FLST_UBFLOW_INST_04 :covered_by: AGENT_INSTALLER :status: approved :tags: ubflow, installer As an installing developer, I want the installation process to be deterministic and its output to be verifiable against the installation specification, so that I can confirm the installation is complete and matches the requested configuration. .. flowstory:: Single target folder :id: FLST_UBFLOW_INST_05 :covered_by: AGENT_INSTALLER :status: approved :tags: ubflow, installer As an installing developer, I want all installed agent family documentation placed under a single target folder (with optional sub-folders and files), so that the documentation can be relocated as a unit and reviewed in one place. .. flowstory:: Template and version selection :id: FLST_UBFLOW_INST_06 :covered_by: AGENT_INSTALLER :status: draft :tags: ubflow, installer As an installing developer, I want to select the agent family template and its version before installation, so that I have full control over which template revision is deployed and can reproduce the same installation at a later point. .. flowstory:: Partial agent selection :id: FLST_UBFLOW_INST_07 :covered_by: AGENT_INSTALLER :status: draft :tags: ubflow, installer As an installing developer, I want to select a subset of agents from the chosen family for installation, so that I can omit agents that are not relevant to my project and keep the installed documentation lean. .. flowstory:: Prerequisite and dependency check :id: FLST_UBFLOW_INST_08 :covered_by: AGENT_INSTALLER :status: draft :tags: ubflow, installer As an installing developer, I want the installer to verify all required tools and dependencies (e.g. sphinx-needs, ubproject.toml) before starting, and to offer automatic installation of any missing prerequisites, so that the target environment is ready before any files are written. .. flowstory:: Update and upgrade :id: FLST_UBFLOW_INST_09 :covered_by: AGENT_INSTALLER :status: draft :tags: ubflow, installer As an installing developer, I want to upgrade an existing installation to a newer template version, so that I can adopt improvements and fixes without manually merging changes into the installed documentation. .. flowstory:: Conflict detection :id: FLST_UBFLOW_INST_10 :covered_by: AGENT_INSTALLER :status: draft :tags: ubflow, installer As an installing developer, I want the installer to detect conflicts — such as duplicate need IDs or file path collisions — with content already present in the target repository, and report them before writing any files, so that existing work is not silently overwritten. .. flowstory:: Rollback and uninstall :id: FLST_UBFLOW_INST_11 :covered_by: AGENT_INSTALLER :status: draft :tags: ubflow, installer As an installing developer, I want to uninstall a previously installed agent family or roll back a failed installation, so that the repository is returned to its prior state without manual cleanup. .. flowstory:: Installation configuration persistence :id: FLST_UBFLOW_INST_12 :covered_by: AGENT_INSTALLER :status: draft :tags: ubflow, installer As an installing developer, I want the installer to persist the chosen configuration (template, version, selected agents, target path, activated epics) to an answers file, so that the same installation can be reproduced or updated without re-entering all parameters. .. flowstory:: Post-install validation :id: FLST_UBFLOW_INST_13 :covered_by: AGENT_INSTALLER :status: draft :tags: ubflow, installer As an installing developer, I want the installer to run automated validation after completing the installation — including RST syntax checks and a Sphinx build — so that I receive an immediate confirmation that the installed documentation is well-formed and buildable. .. flowstory:: Local family source bundled with ubCode :id: FLST_UBFLOW_INST_14 :covered_by: AGENT_INSTALLER :status: approved :tags: ubflow, installer As an installing developer, I want agent-family packages to be available locally — as a directory or zip bundled with the ubCode VS Code extension, or as a directory directly in the repository — so that installation works offline and I never depend on network access to a remote git repository. .. flowstory:: Package manifest declaration :id: FLST_UBFLOW_INST_15 :covered_by: AGENT_INSTALLER :status: approved :tags: ubflow, installer As a package author, I want to declare package metadata, the set of installable directories, and the available epics in a ``ubflow_package.json`` file at the package root, so that the installer can present the correct configuration options to the developer without inspecting template internals. .. flowstory:: Merge ubFlow configuration into existing ubproject.toml :id: FLST_UBFLOW_INST_16 :covered_by: AGENT_INSTALLER :status: draft :tags: ubflow, installer As a developer, I want the installer to detect an existing ``ubproject.toml`` in the target directory and merge the required ubFlow sections (need types, link definitions) into it without overwriting existing project-specific configuration, so that projects that already have a Sphinx-Needs setup can adopt ubFlow without losing their custom need types or link rules. ubFlow Agent Stub ----------------- .. flowstory:: Installer deploys the ubFlow agent stub :id: FLST_UBFLOW_INST_17 :status: draft :tags: ubflow, installer As a developer, I want the installer to automatically create the ubFlow agent stub file (``.github/agents/ubflow.agent.md``) in the target repository during every install or upgrade, so that the ubFlow agent is immediately available in GitHub Copilot without any manual setup. .. flowstory:: Installer deploys the companion bootstrap instructions file :id: FLST_UBFLOW_INST_18 :status: draft :tags: ubflow, installer As a developer installing a ubFlow agent family, I want the installer to automatically create a ``.github/instructions/.instructions.md`` file with ``applyTo: '**'`` in the target repository during every install or upgrade, so that GitHub Copilot enforces the MCP bootstrap step for every agent in the family without any manual setup and regardless of whether the ``.agent.md`` file is read first.