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.

• Generic Agents
  • Installer Agent
  • ubFlow orchestrator Agent
• Shared Needs
  • Shared Flow Stories
  • Shared Flow Specifications
  • Shared Flow Instructions
  • Shared Flow Skills
• Tools
  • Copier CLI
  • Git CLI
  • Sphinx Build
  • ubCode MCP Server

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.

Flow Story: Resolve Target Documentation Project 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.

Flow Story: Validate Documentation Project Scope 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.

Flow Story: Use ubCode MCP to Access Sphinx-Needs Objects 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.

Flow Story: Auto-Install ubCode MCP on Demand 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.

Flow Story: Fixed Execution Workflow for All Agents 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

Flow Story: Orchestrator Agent per Agent Family 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.

Flow Story: Predefined Workflow Types 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.

Flow Story: Agent Family Management 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.

Flow Story: Define Agent Family as Sphinx-Needs Object 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.

Flow Story: Agent Family Links to Its Member Agents 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.