Core Objects 
=============

This section documents the **generic agents** that ubFlow always creates as
part of every agent family. These agents need no user customization — their
behavior is fully defined here and applies universally.

Every ubFlow family MUST contain at least the agents listed in this section.
ubFlow SHALL include the corresponding Flow Stories and Specifications from
this section when authoring a new family.

.. toctree::
   :maxdepth: 2

   agents/index
   shared/index
   tools/index



Shared Behavior
---------------

.. note::

   These stories apply to **every agent created by ubFlow**, not just ubFlow
   itself. Rules derived from them MUST be included in every generated agent.

.. flowstory:: Resolve Target Documentation Project
   :id: FLST_UBFLOW_019
   :status: draft
   :tags: ubflow, shared

   As a developer, I want every ubFlow-created agent to resolve its target
   Sphinx-Needs project before performing any operation, with priority:
   explicit parameter > workspace context (``ubproject.toml``) > interactive
   prompt, so that agents always operate on the correct documentation project
   without ambiguity.

.. flowstory:: Validate Documentation Project Scope
   :id: FLST_UBFLOW_020
   :status: draft
   :tags: ubflow, shared

   As a developer, I want every ubFlow-created agent to validate that the
   resolved documentation project is a valid ubFlow Sphinx-Needs project before
   proceeding so that operations on wrong or incompatible projects are prevented.

.. flowstory:: Use ubCode MCP to Access Sphinx-Needs Objects
   :id: FLST_UBFLOW_021
   :status: draft
   :tags: ubflow, shared

   As a developer, I want every ubFlow-created agent to exclusively use the
   ubCode MCP server to read and query Sphinx-Needs objects so that all access
   to requirements, specifications, instructions, and skills is consistent,
   auditable, and independent of local file parsing.

.. flowstory:: Auto-Install ubCode MCP on Demand
   :id: FLST_UBFLOW_022
   :status: draft
   :tags: ubflow, shared

   As a developer, I want a ubFlow-created agent to detect when the ubCode MCP
   server is not available and offer to install the ubCode extension from the
   VS Code Marketplace after explicit user confirmation so that the agent can
   recover from a missing dependency without manual setup instructions.

.. flowstory:: Fixed Execution Workflow for All Agents
   :id: FLST_UBFLOW_023
   :status: draft
   :tags: ubflow, shared

   As a developer, I want every ubFlow-created agent to follow a fixed
   five-phase execution workflow — (1) Plan & Explain, (2) Human Approval,
   (3) Execute, (4) Human Review, (5) Merge — so that no change is applied
   without explicit human sign-off at the critical checkpoints.


Agent Families & Orchestration
-------------------------------

.. flowstory:: Orchestrator Agent per Agent Family
   :id: FLST_UBFLOW_024
   :status: draft
   :tags: ubflow

   As a developer, I want ubFlow to always generate an orchestrator agent that
   carries the name of the agent family and serves as the single entry point
   for all communication so that users interact with the family through one
   well-known interface and the orchestrator routes tasks to the appropriate
   domain agents.

.. flowstory:: Predefined Workflow Types
   :id: FLST_UBFLOW_025
   :status: draft
   :tags: ubflow

   As a developer, I want the orchestrator to support predefined workflow types
   — such as *SW Change* (requirements, architecture, test cases, code
   implementation) and *Bugfix* (code only) — so that the correct sequence of
   domain agents is automatically composed when a workflow is triggered.

.. flowstory:: Agent Family Management
   :id: FLST_UBFLOW_026
   :status: draft
   :tags: ubflow

   As a developer, I want ubFlow to always create and maintain a coherent
   agent family — a named group of agents with a designated orchestrator —
   so that the full set of agents for a domain is versioned, discoverable,
   and maintained as a unit rather than as isolated files.

.. flowstory:: Define Agent Family as Sphinx-Needs Object
   :id: FLST_UBFLOW_027
   :status: draft
   :tags: ubflow

   As a developer, I want every agent family to be defined by exactly one
   ``.. agentfamily::`` need object in its Sphinx-Needs documentation project
   so that the family's identity, purpose, and membership are versioned and
   queryable alongside all other needs.

.. flowstory:: Agent Family Links to Its Member Agents
   :id: FLST_UBFLOW_028
   :status: draft
   :tags: ubflow

   As a developer, I want the ``agentfamily`` need object to reference all
   its member agents via a ``:has_agents:`` link so that the complete family
   composition can be determined by querying the documentation project alone,
   without reading individual ``.agent.md`` files.