Orchestrator Flow Stories

Flow Stories specific to the ubFlow Orchestrator agent.

Agent Authoring

Flow Story: Guide Agent Creation FLST_UBFLOW_001

status: draft tags: ubflow satisfied_by: FLSP_UBFLOW_008, FLSP_UBFLOW_009

As a developer, I want to be guided step-by-step through authoring User Stories, Specifications, and an .agent.md file so that I can create a new agent that fully complies with the ubFlow process. sequenceDiagram User->>Project_Docs: Writes down Agent Sphinx-Needs object with name "AgentX" User->>Project_Docs: Writes down Instructions, Skills for agent User->>ubFlow: Create new agent "AgentX" ubFlow->>ubCode MCP: Request Sphinx-Needs agent object for "AgentX" ubCode MCP ->>ubFlow: Send back "AgentX" information ubFlow->>.github: Create "Agent.md" file ubFlow-->User: all done

Flow Story: Describe Instructions and Skills in Sphinx FLST_UBFLOW_005

status: draft tags: ubflow satisfied_by: FLSP_UBFLOW_003, FLSP_UBFLOW_004

As a developer, I want to describe every agent instruction and skill as a structured RST object in the Sphinx-Needs project so that they are versioned, searchable, and traceable alongside other needs.

Flow Story: Link Instructions and Skills to Needs FLST_UBFLOW_006

status: draft tags: ubflow satisfied_by: FLSP_UBFLOW_005

As a developer, I want each instruction and skill object to be linked to the needs (UST/SPEC) that motivate them so that the full traceability chain from user goal to agent behavior is always visible.

Flow Story: Define Agent as Sphinx-Needs Object FLST_UBFLOW_007

status: draft tags: ubflow satisfied_by: FLSP_UBFLOW_006

As a developer, I want to define a new agent by authoring a single .. agent:: need object in Sphinx so that the agent’s identity and its linked instructions and skills are managed in one traceable place.

Flow Story: Agent Object Aggregates Instructions and Skills FLST_UBFLOW_008

status: draft tags: ubflow satisfied_by: FLSP_UBFLOW_007

As a developer, I want the agent need object to reference all its instructions and skills via Sphinx-Needs links so that the complete agent definition can be queried and rendered from the documentation project alone.

Agent Review & Quality

Flow Story: Review Existing Agent FLST_UBFLOW_002

status: draft tags: ubflow satisfied_by: FLSP_UBFLOW_010

As a developer or quality manager, I want to request a review of an existing .agent.md file so that I can identify and fix non-compliance with ubFlow rules.

Flow Story: Control Review Depth FLST_UBFLOW_003

status: draft tags: ubflow satisfied_by: FLSP_UBFLOW_010

As a user, I want to choose which review checks ubFlow applies (syntactic, semantic, traceability) so that I get exactly the feedback depth I need for my current task.

Flow Story: Verify Traceability Chain FLST_UBFLOW_004

status: draft tags: ubflow satisfied_by: FLSP_UBFLOW_011

As a quality manager, I want ubFlow to verify that every instruction in an agent file references an existing FLSP_ ID in /docs so that the traceability chain is always intact.

Agent Runtime & Bootstrap

Flow Story: Agent Bootstraps Itself via MCP FLST_UBFLOW_009

status: draft tags: ubflow satisfied_by: FLSP_UBFLOW_012

As a developer, I want the .agent.md file to contain only a bootstrap instruction that loads the agent’s instructions and skills at runtime via the ubCode MCP server so that the agent file stays minimal and the documentation is the single source of truth.

Flow Story: Schema Validation via MCP at Startup FLST_UBFLOW_010

status: draft tags: ubflow satisfied_by: FLSP_UBFLOW_013

As a developer, I want the agent to verify at startup via get_schema (MCP) that the Sphinx-Needs schema contains the required object types for instructions and skills so that a missing or misconfigured schema is detected before any operation is attempted.

Project Integration

Flow Story: Sphinx Project Integration via Prompt FLST_UBFLOW_011

status: draft tags: ubflow satisfied_by: FLSP_UBFLOW_015

As a developer, I want to integrate ubFlow into a new or existing Sphinx project via a single prompt so that the required schema, need types, and link definitions are configured automatically without manual setup.

Flow Story: No Self-Installation into Target Project FLST_UBFLOW_012

status: draft tags: ubflow satisfied_by: FLSP_UBFLOW_016

As a developer, I want ubFlow to never install its own instructions or skills into a target project so that the target project remains clean and ubFlow’s internals stay encapsulated.

Identity & Distribution

Flow Story: ubCode Chat Participant FLST_UBFLOW_013

status: draft tags: ubflow satisfied_by: FLSP_UBFLOW_017

As a developer, I want ubFlow to be available as a ubCode chat participant so that its instructions and skills remain hidden from the user and are not exposed in the target project.

Flow Story: Read-Only Agent After Delivery FLST_UBFLOW_014

status: draft tags: ubflow satisfied_by: FLSP_UBFLOW_018

As a product owner, I want the ubFlow agent to be non-editable by the end user so that behavioral updates are exclusively delivered via the ubFlow repository and ubCode distribution.

Flow Story: Built-in ubCode MCP Knowledge FLST_UBFLOW_015

status: draft tags: ubflow satisfied_by: FLSP_UBFLOW_014

As a developer, I want ubFlow to have built-in knowledge of ubCode and its MCP server so that it can query needs, schemas, and project structure without additional setup instructions.

Documentation & Visibility

Flow Story: Human-Readable Agent Documentation FLST_UBFLOW_016

status: draft tags: ubflow satisfied_by: FLSP_UBFLOW_021

As a developer, I want ubFlow to generate human-readable documentation of agent structure, process relationships, and responsibilities in the target project so that team members can understand the agent ecosystem beyond raw traceability data.

Flow Story: Agents Callable via Copilot Prompt FLST_UBFLOW_017

status: draft tags: ubflow satisfied_by: FLSP_UBFLOW_019

As a developer, I want agents created by ubFlow to be invokable via their @<name> prompt in GitHub Copilot so that users can call them directly without navigating the file system.

Flow Story: ubCode Can Invoke ubFlow Agents FLST_UBFLOW_018

status: draft tags: ubflow satisfied_by: FLSP_UBFLOW_020

As a developer, I want ubCode to be able to delegate to ubFlow-created agents via their prompt (e.g. @ubcode swarch) so that ubCode workflows can hand off to domain-specific agents without breaking the ubCode interface.

Generic Orchestrator

These Flow Stories apply to every orchestrator in every family created by ubFlow, regardless of domain.

Single Entry Point

Flow Story: Orchestrator Is the Family Entry Point FLST_UBFLOW_029

status: draft tags: ubflow, generic-orchestrator

As a developer, I want the orchestrator agent to be the only agent in a family that is directly addressable by the user so that all communication flows through one well-known interface and domain agents remain internal implementation details.

Flow Story: Orchestrator Carries the Family Name FLST_UBFLOW_030

status: draft tags: ubflow, generic-orchestrator

As a developer, I want the orchestrator agent to carry the exact name of its agent family so that invoking @<family-name> in GitHub Copilot always reaches the orchestrator without ambiguity.

Workflow Routing

Flow Story: Orchestrator Identifies and Routes Workflow FLST_UBFLOW_031

status: draft tags: ubflow, generic-orchestrator

As a developer, I want the orchestrator to identify which workflow type (e.g. SW Change, Bugfix) matches the user’s request and then invoke the corresponding domain agents in the correct sequence so that the user does not need to know which sub-agents exist or in what order to call them.

Flow Story: Orchestrator Enforces the Five-Phase Workflow FLST_UBFLOW_032

status: draft tags: ubflow, generic-orchestrator

As a developer, I want the orchestrator to enforce the mandatory five-phase execution model — (1) Plan & Explain, (2) Human Approval, (3) Execute, (4) Human Review, (5) Merge — for every workflow it coordinates so that no change is applied without explicit human sign-off at the critical checkpoints.

ubCode MCP Integration

Flow Story: Orchestrator Uses ubCode MCP for All Needs Access FLST_UBFLOW_033

status: draft tags: ubflow, generic-orchestrator

As a developer, I want the orchestrator to use the ubCode MCP server exclusively for reading and querying Sphinx-Needs objects so that its access to requirements, specifications, and agent definitions is consistent and auditable.

Flow Story: Orchestrator Ensures ubCode MCP Is Available FLST_UBFLOW_034

status: draft tags: ubflow, generic-orchestrator

As a developer, I want the orchestrator to verify that the ubCode MCP server is available before starting any operation and to offer installation from the VS Code Marketplace upon explicit user confirmation if it is missing so that the family can recover from a missing dependency without manual setup instructions.

Extension-Bundled Instructions

Flow Story: ubFlow bootstraps its instructions from the ubCode extension FLST_UBFLOW_036

status: draft tags: ubflow satisfied_by: FLSP_UBFLOW_022, FLSP_UBFLOW_023

As a developer, I want the ubFlow agent to be deployable as a minimal stub .agent.md that contains no visible instructions, so that the target repository stays clean while the full, versioned instruction set is fetched at runtime from the ubCode extension via MCP. The stub bootstraps itself by calling the ubCode MCP server with agent="ubflow"; the server resolves this magic word to its internally bundled ubFlow documentation project and returns the current FLIN_ and FLSK_ needs — without any of those needs ever being written into the user’s repository. Re-bootstrapping must also happen immediately after any change to the ubFlow instruction set within a session, so that the active rules always reflect the latest written state.

Flow Story: Deploy companion bootstrap instructions file with every family installation FLST_UBFLOW_042

status: draft tags: ubflow satisfied_by: FLSP_UBFLOW_029

As a developer installing a ubFlow agent family, I want a workspace .instructions.md file to be deployed alongside the family so that GitHub Copilot enforces the MCP bootstrap step for every agent in the family, regardless of whether the agent’s .agent.md file is loaded first. Without this companion file the applyTo-less .agent.md bootstrap block may be silently skipped when the agent is invoked through the agent picker, leaving the agent without its full instruction set.