Installer Instructions ====================== .. flowinst:: Always start by loading your instructions from ubCode :id: FLIN_UBFLOW_INST_001 :status: draft :tags: ubflow, installer :implements: FLSP_UBFLOW_INST_001 At the beginning of every installation session, retrieve the ``AGENT_INSTALLER`` need from the ubCode MCP server and follow its outgoing links to load the current behavioral rules: - instructions via the ``applies`` links - skills via the ``employs`` links - tools via the ``uses`` links Never rely on cached or hardcoded rules — the linked needs are the source of truth. .. flowinst:: Always detect the repository root before asking for a target path :id: FLIN_UBFLOW_INST_002 :status: draft :tags: ubflow, installer :implements: FLSP_UBFLOW_INST_001; FLSP_UBFLOW_INST_002 Use ``git rev-parse --show-toplevel`` to locate the repository root. Abort immediately with the message ``"Not inside a Git repository. Aborting."`` if no Git repository is found. Only then prompt the developer to confirm the target documentation folder. Never accept a path outside the repository. .. flowinst:: Always verify prerequisites before writing any file :id: FLIN_UBFLOW_INST_003 :status: draft :tags: ubflow, installer :implements: FLSP_UBFLOW_INST_011; FLSP_UBFLOW_INST_012 Run the prerequisite check before any file is created or modified. Report every missing dependency with its minimum required version. Offer automatic installation for missing Python packages. Never proceed to the rendering step while any required dependency is absent. .. flowinst:: Always detect conflicts before rendering the template :id: FLIN_UBFLOW_INST_004 :status: draft :tags: ubflow, installer :implements: FLSP_UBFLOW_INST_015; FLSP_UBFLOW_INST_016 Scan the repository for Sphinx-Needs ID collisions and for file paths that would be overwritten. Never render the template while ID conflicts remain unresolved. Never overwrite an existing file without explicit per-file confirmation from the developer. .. flowinst:: Always resolve the package version from ubflow_package.json, not from git :id: FLIN_UBFLOW_INST_005 :status: draft :tags: ubflow, installer :implements: FLSP_UBFLOW_INST_009; FLSP_UBFLOW_INST_010; FLSP_UBFLOW_INST_025; FLSP_UBFLOW_INST_026 Locate the ubCode extension directory, find the package zip, extract it, and read ``ubflow_package.json`` to obtain the available package version. Display that version to the developer for confirmation. Never query a remote git server for version information. Never pass ``--vcs-ref`` to Copier. .. flowinst:: Always present epic and agent selection before rendering :id: FLIN_UBFLOW_INST_006 :status: draft :tags: ubflow, installer :implements: FLSP_UBFLOW_INST_003; FLSP_UBFLOW_INST_004; FLSP_UBFLOW_INST_005 Present all available epics and agents from the selected family to the developer. Allow individual deactivation of epics and agents. Reject an empty agent selection and re-prompt. Exclude all content belonging to deactivated epics from the generated output. .. flowinst:: Always write files atomically and roll back on failure :id: FLIN_UBFLOW_INST_007 :status: draft :tags: ubflow, installer :implements: FLSP_UBFLOW_INST_006; FLSP_UBFLOW_INST_008 Write all rendered files to a staging area first, then move them atomically to the target folder. On any failure, remove every partially written file and report: ``"Installation failed. All written files have been removed. Repository state is unchanged."`` Never leave the repository in a partially installed state. .. flowinst:: Always write an installation manifest after a successful installation :id: FLIN_UBFLOW_INST_008 :status: draft :tags: ubflow, installer :implements: FLSP_UBFLOW_INST_007 After every successful installation write ``.ubflow-manifest.json`` to the target folder containing the package source URI (``ubcode://packages/``), package version, timestamp, and a SHA-256 digest for every installed file. Never skip the manifest step. .. flowinst:: Always persist the answers file after a successful installation :id: FLIN_UBFLOW_INST_009 :status: draft :tags: ubflow, installer :implements: FLSP_UBFLOW_INST_019; FLSP_UBFLOW_INST_020 Write ``.copier-answers.yml`` with all confirmed parameters after every successful run. When the file already exists at the start of a new run, pre-populate all prompts from it so the developer only needs to confirm or change individual values. .. flowinst:: Always show a diff and require confirmation before upgrading :id: FLIN_UBFLOW_INST_010 :status: draft :tags: ubflow, installer :implements: FLSP_UBFLOW_INST_013; FLSP_UBFLOW_INST_014 Before executing an upgrade, run the template engine in pretend mode and display the resulting diff. Require the developer to enter an explicit ``y`` before modifying any file. Never perform an in-place upgrade without a preceding confirmation. .. flowinst:: Always validate the installed documentation before reporting success :id: FLIN_UBFLOW_INST_011 :status: draft :tags: ubflow, installer :implements: FLSP_UBFLOW_INST_021; FLSP_UBFLOW_INST_022 After writing all files, scan every installed RST file for undefined Sphinx-Needs references. Then invoke ``sphinx-build -b html -W`` on the target documentation project. Report the installation as incomplete if either check fails. Never declare success while validation errors are open. .. flowinst:: Use the manifest to uninstall — never delete files not listed in it :id: FLIN_UBFLOW_INST_012 :status: draft :tags: ubflow, installer :implements: FLSP_UBFLOW_INST_017; FLSP_UBFLOW_INST_018 When uninstalling, delete only files listed in ``.ubflow-manifest.json``. Skip files whose digest has changed since installation and report each skipped file to the developer. Never delete files that were not created by the installer. .. flowinst:: Always locate the family source by searching repo and extension in order :id: FLIN_UBFLOW_INST_013 :status: draft :tags: ubflow, installer :implements: FLSP_UBFLOW_INST_025 At the start of every ``install`` or ``update`` command, resolve the family source by searching the following locations in priority order: 1. ``/families//`` — directory in the repository 2. ``/families/.zip`` — zip in the repository 3. ``/families//`` — directory in the ubCode extension 4. ``/families/.zip`` — zip in the ubCode extension Use the first match found. Abort with an informative message listing all searched paths when nothing is found. Honour the optional ``--repo-root`` and ``--extension-dir`` overrides when provided. Never hard-code any search path. .. flowinst:: Always prepare the family source and clean up only what was extracted :id: FLIN_UBFLOW_INST_014 :status: draft :tags: ubflow, installer :implements: FLSP_UBFLOW_INST_026 After resolving the family source: - **Directory source**: pass the directory directly to Copier. Do not copy, extract, or modify it. No cleanup is needed after Copier exits. - **Zip source**: extract to a temporary directory before invoking Copier. Remove the temporary directory unconditionally — in both success and failure branches — as soon as Copier exits. Never leave extracted package files on disk after the command exits. Never invoke Copier against a zip path directly. .. flowinst:: Deploy the ubFlow agent stub after every install or upgrade :id: FLIN_UBFLOW_INST_015 :status: draft :tags: ubflow, installer :implements: FLSP_UBFLOW_INST_027 After completing any install or upgrade, write ``.github/agents/ubflow.agent.md`` in the target repository root using the procedure in ``FLSK_UBFLOW_INST_009``. The operation is idempotent: skip silently if the file already matches; overwrite and report if it differs. Never delete this file during uninstall of a family — ubFlow itself is not a family. .. flowinst:: Deploy companion bootstrap instructions file after every install or upgrade :id: FLIN_UBFLOW_INST_016 :status: draft :tags: ubflow, installer :implements: FLSP_UBFLOW_INST_028 After completing any install or upgrade, write ``.github/instructions/.instructions.md`` in the target repository root using the procedure in ``FLSK_UBFLOW_INST_010``. The operation is idempotent: skip silently if the file already matches; overwrite and report if it differs. Never delete this file during uninstall of a family. .. note:: The tools used by this agent (Copier CLI, ubCode MCP Server) are documented in the :doc:`Tools ` section.