Orchestrator Flow Stories ========================= Flow Stories specific to the **ubFlow Orchestrator** agent. Agent Authoring --------------- .. flowstory:: Guide Agent Creation :id: FLST_UBFLOW_001 :status: draft :tags: ubflow 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. .. mermaid:: 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 .. flowstory:: Describe Instructions and Skills in Sphinx :id: FLST_UBFLOW_005 :status: draft :tags: ubflow 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. .. flowstory:: Link Instructions and Skills to Needs :id: FLST_UBFLOW_006 :status: draft :tags: ubflow 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. .. flowstory:: Define Agent as Sphinx-Needs Object :id: FLST_UBFLOW_007 :status: draft :tags: ubflow 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. .. flowstory:: Agent Object Aggregates Instructions and Skills :id: FLST_UBFLOW_008 :status: draft :tags: ubflow 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 ---------------------- .. flowstory:: Review Existing Agent :id: FLST_UBFLOW_002 :status: draft :tags: ubflow 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. .. flowstory:: Control Review Depth :id: FLST_UBFLOW_003 :status: draft :tags: ubflow 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. .. flowstory:: Verify Traceability Chain :id: FLST_UBFLOW_004 :status: draft :tags: ubflow 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 ------------------------- .. flowstory:: Agent Bootstraps Itself via MCP :id: FLST_UBFLOW_009 :status: draft :tags: ubflow 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. .. flowstory:: Schema Validation via MCP at Startup :id: FLST_UBFLOW_010 :status: draft :tags: ubflow 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 ------------------- .. flowstory:: Sphinx Project Integration via Prompt :id: FLST_UBFLOW_011 :status: draft :tags: ubflow 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. .. flowstory:: No Self-Installation into Target Project :id: FLST_UBFLOW_012 :status: draft :tags: ubflow 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 ----------------------- .. flowstory:: ubCode Chat Participant :id: FLST_UBFLOW_013 :status: draft :tags: ubflow 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. .. flowstory:: Read-Only Agent After Delivery :id: FLST_UBFLOW_014 :status: draft :tags: ubflow 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. .. flowstory:: Built-in ubCode MCP Knowledge :id: FLST_UBFLOW_015 :status: draft :tags: ubflow 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 -------------------------- .. flowstory:: Human-Readable Agent Documentation :id: FLST_UBFLOW_016 :status: draft :tags: ubflow 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. .. flowstory:: Agents Callable via Copilot Prompt :id: FLST_UBFLOW_017 :status: draft :tags: ubflow As a developer, I want agents created by ubFlow to be invokable via their ``@`` prompt in GitHub Copilot so that users can call them directly without navigating the file system. .. flowstory:: ubCode Can Invoke ubFlow Agents :id: FLST_UBFLOW_018 :status: draft :tags: ubflow 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 ~~~~~~~~~~~~~~~~~~ .. flowstory:: Orchestrator Is the Family Entry Point :id: 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. .. flowstory:: Orchestrator Carries the Family Name :id: 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 ``@`` in GitHub Copilot always reaches the orchestrator without ambiguity. Workflow Routing ~~~~~~~~~~~~~~~~ .. flowstory:: Orchestrator Identifies and Routes Workflow :id: 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. .. flowstory:: Orchestrator Enforces the Five-Phase Workflow :id: 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 ~~~~~~~~~~~~~~~~~~~~~~ .. flowstory:: Orchestrator Uses ubCode MCP for All Needs Access :id: 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. .. flowstory:: Orchestrator Ensures ubCode MCP Is Available :id: 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 ------------------------------- .. flowstory:: ubFlow bootstraps its instructions from the ubCode extension :id: FLST_UBFLOW_036 :status: draft :tags: ubflow 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. .. flowstory:: Deploy companion bootstrap instructions file with every family installation :id: FLST_UBFLOW_042 :status: draft :tags: ubflow 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.