Software engineering workflows (software-engineering-workflows).
Vision and product planning workflows (vision-and-product-planning-workflows).

Sprint Execution Coordinator¶

Target

This page describes intended behaviour or structure. No implementation is claimed unless a section is explicitly marked Current implementation or Evidence.

Overview and Role in the Factory¶

The SprintExecutionCoordinator is a core orchestrator in the ConnectSoft AI Software Factory. It is responsible for managing the lifecycle of sprints, ensuring that feature execution is scoped, traceable, and milestone-aligned.

It orchestrates agents such as the ProductOwnerAgent, BackendDeveloperAgent, TestGeneratorAgent, QAAgent, and DevOpsAgent — but only within the context of an active sprint. Its design enforces execution windows, gate-based progression, and trace-linked output verification.

In the ConnectSoft Factory, a sprint is not a date range — it’s a controlled execution boundary, defined by traceable artifacts and driven by logical FSM transitions.

🎯 Core Purpose¶

Enforce scoped execution of features and agents during a sprint
Emit lifecycle events: SprintPlanned, SprintStarted, SprintCheckpoint, SprintClosed
Ensure only agents tagged to the current sprint are activated
Link all generated artifacts (code, tests, metrics) to a sprint_id and trace_id
Track progress and gate transitions against milestone_id targets

📦 Key Capabilities¶

Capability	Description
Sprint Lifecycle FSM	Defines logical states: `Planned`, `Active`, `Checkpoint`, `Closed`, `Blocked`
Agent Activation Filter	Activates only agents associated with features in current sprint
Trace Injection	Ensures all artifacts and metrics include `sprint_id`, `milestone_id`, and `trace_id`
Gate Enforcement	Blocks `SprintClosed` until required outputs (e.g., tests, PRs, CI runs) are complete
Retry and Resume	Supports `PlanningResumed`, partial reruns, and failure correction flows

🧬 Sprint Metadata Structure¶

{
  "sprint_id": "sprint-2025-05-MVP1",
  "milestone_id": "mvp-core",
  "features": ["BookingFlow", "Notification.Email.Send"],
  "agents": ["ProductOwnerAgent", "BackendDeveloperAgent", "TestGeneratorAgent"],
  "status": "Planned",
  "trace_id": "trace-abc123"
}

🧠 Why This Coordinator Matters¶

Without the SprintExecutionCoordinator, the factory would risk:

Unscoped agent activation
Feature execution without QA enforcement
Milestone advancement without artifact validation
Lack of sprint-aware dashboards or Studio visualization
Poor traceability across thousands of services

It serves as the governor and scheduler of AI execution cycles, balancing speed with structure.

Position in the Execution Flow¶

The SprintExecutionCoordinator operates in the middle phase of the Factory lifecycle, directly after milestone planning and before CI/CD orchestration. It is triggered when:

A milestone becomes ready for execution
A SprintPlanned event is emitted by the ProductOwnerAgent or MilestoneLifecycleCoordinator

It marks the beginning of a bounded, traceable execution window, during which features are implemented, validated, and linked to milestone goals.

🔁 Execution Phase¶

Phase	Position
Project Initialization	❌ Before
Milestone Planning	✅ Precursor
Sprint Execution	✅ Active Phase
CI/CD & Deployment	🔄 Triggered After
Release Management	❌ Follows Output

📌 Dependencies¶

Upstream Coordinators/Agents	Required Outputs
`ProjectBootstrapOrchestrator`	`DevOpsArtifactsReady`
`MilestoneLifecycleCoordinator`	`MilestoneReadyForExecution`, `MilestoneScopeLocked`
`ProductOwnerAgent`	`SprintPlanned`, `sprint-definition.json`

🚀 What It Unlocks¶

Once the SprintExecutionCoordinator is triggered, it enables:

Activation of scoped AI agents (execution is no longer global)
Generation of trace-linked artifacts (code, tests, diagrams)
Emission of SprintStarted, SprintCheckpoint, and SprintClosed events
Enforcement of milestone gates via sprint-trace-matrix.json
Integration with CI/CD pipeline emitters and QA validation routines

🧬 Execution Timeline Diagram¶

flowchart TD
    MilestonePlanning -->|SprintPlanned| SprintExecutionCoordinator
    SprintExecutionCoordinator --> AgentCluster
    AgentCluster -->|ArtifactReady| SprintExecutionCoordinator
    SprintExecutionCoordinator -->|SprintClosed| MilestoneLifecycleCoordinator
    SprintExecutionCoordinator -->|ArtifactsTagged| CICD["CI/CD Orchestrators"]

Hold "Alt" / "Option" to enable pan & zoom

🧠 Summary¶

The SprintExecutionCoordinator serves as the execution gateway between planning and delivery — ensuring that all actions performed during a sprint are:

✅ Scoped
✅ Traceable
✅ Testable
✅ Governed

Responsibilities¶

The SprintExecutionCoordinator is responsible for managing the entire lifecycle of a sprint, ensuring that agents operate only within the authorized scope and that all outputs are trace-linked, quality-checked, and milestone-aligned.

It acts as a gatekeeper, scheduler, and validator for sprint execution, providing both structure and resilience for fast-paced, multi-agent orchestration.

✅ Core Responsibilities¶

Responsibility	Description
Activate Sprint	React to `SprintPlanned` event and transition sprint to `Active` state
Enable Agents by Scope	Only activate agents for features explicitly assigned to the current sprint
Manage Sprint FSM	Handle state transitions (`Planned → Active → Checkpoint → Closed`)
Track Progress	Monitor agent activity, artifact readiness, and test pass status
Emit Lifecycle Events	`SprintStarted`, `SprintCheckpoint`, `SprintClosed`, `SprintBlocked`
Enforce Completion Gates	Validate `sprint-trace-matrix.json` against expected features and tests
Support Recovery and Retry	Allow safe re-execution or continuation after failure (`SprintResumed`, `RetrySprintExecution`)

📦 Additional Outputs Controlled¶

SprintStartedEvent — activates agents and enables log traces
sprint-trace-matrix.json — artifact-to-feature map
qa-validation-report.md — optional, links QA status per feature
SprintClosedEvent — unlocks CI/CD and milestone transitions

🧠 Sprint FSM States (Internal)¶

State	Description
`Planned`	Sprint has been scoped and planned but not yet active
`Active`	Agents are currently working; outputs are being generated
`Checkpoint`	Optional mid-sprint pause to validate progress or perform manual review
`Blocked`	Execution halted due to failure, missing artifact, or unmet gate
`Closed`	Sprint successfully completed and outputs validated

🔁 Coordinated Domains¶

Domain	Coordination Role
Features	Assign agents and track story delivery
Tests	Link generated tests to feature IDs and verify pass rate
CI/CD	Prepare tagging and artifact linkage based on sprint completion
Security	Validate that generated code includes tracing, auth policies, and observability hooks

MilestoneLifecycleCoordinator (for milestone advancement)
CI/CD ArtifactCoordinator (for version tagging and deployment triggers)
QAOrchestrator (for test coverage enforcement)

🎯 Summary¶

The SprintExecutionCoordinator is the central timing and scope enforcement unit in the Factory’s orchestration layer.
It ensures that everything generated during a sprint is intentional, traceable, and governed.

Triggering Events¶

The SprintExecutionCoordinator is fully event-driven, activated by upstream planning components and controlling downstream agent execution and milestone progression through structured lifecycle events.

It listens for well-defined events to begin execution and emits events to signal sprint state changes, progress checkpoints, and completion status.

🚦 Primary Triggering Events¶

Event	Emitted By	Description
`SprintPlanned`	`ProductOwnerAgent` or `MilestoneLifecycleCoordinator`	Indicates that sprint scope, agents, and features are defined. Triggers coordinator startup.
`PlanningResumed`	Manual or automatic resume	Re-initializes a previously paused or blocked sprint. May include additional features or agent instructions.
`RetrySprintExecution`	Factory FSM or Studio UI	Used to restart execution flow after partial or failed sprint attempt.

🔁 Re-Entry / Update Events¶

Event	Description
`SprintCheckpointRequested`	Triggers a pause to inspect progress before sprint closure.
`SprintExtended`	Updates current sprint to include new features or scope (e.g., after blueprint update).
`SprintBlocked`	Internal state — signals unmet gate condition (e.g., missing artifacts, failed QA).

📤 Events Emitted by the Coordinator¶

Event	Triggered When
`SprintStarted`	Sprint scope is loaded and agent activation begins.
`SprintCheckpoint`	Mid-sprint progress inspection triggered.
`SprintClosed`	All artifacts validated, test coverage met, CI/CD ready.
`SprintFailed`	Sprint terminated due to critical blocking failure.
`SprintEscalated`	Human intervention requested (e.g., QA rejection, scope misalignment).

🧠 Event Payload Structure: `SprintStarted`¶

{
  "event": "SprintStarted",
  "sprint_id": "sprint-2025-06-notification",
  "milestone_id": "mvp-ready",
  "trace_id": "trace-xyz789",
  "features": ["SendEmail", "ScheduleRetry"],
  "agents": ["BackendDeveloperAgent", "TestGeneratorAgent", "QAAgent"],
  "status": "Active",
  "started_at": "2025-05-13T08:00:00Z"
}

This event is consumed by:

Activated agents (to determine their scope)
Studio for real-time visualization
Observability dashboards
Milestone FSM controllers

📡 Observability Integration¶

All events include:

trace_id
sprint_id
milestone_id
agent_roles
Timestamps (started_at, completed_at)
status

→ Enables fine-grained time-to-execute metrics, agent success rates, and traceback across CI/CD.

✅ Summary¶

The SprintExecutionCoordinator is fully reactive, responding to factory planning decisions and emitting structured events to:

Activate execution
Gate milestone progression
Enable traceable delivery
Trigger downstream automation

Inputs¶

The SprintExecutionCoordinator requires a structured set of inputs to launch, monitor, and complete a sprint. These inputs define what should be executed, by whom, and under which milestone and trace context.

Inputs are derived from upstream planning events and artifacts, especially those emitted by the ProductOwnerAgent, MilestoneLifecycleCoordinator, and Studio interface.

📥 Required Inputs¶

Input	Type	Description
`sprint_id`	string	Unique identifier for the sprint (e.g., `sprint-2025-06-MVP2`)
`milestone_id`	string	Milestone this sprint contributes to (e.g., `mvp-ready`)
`features[]`	string[]	List of feature IDs assigned to the sprint (e.g., `BookingFlow`, `SendNotification`)
`agents[]`	string[]	Agent types expected to be active during the sprint (e.g., `TestGeneratorAgent`, `BackendDeveloperAgent`)
`trace_id`	string	Execution trace anchor used for observability and artifact correlation
`scope_definition_file`	file	File or pointer to the sprint plan (`sprint-definition.json`) containing scope metadata
`execution_window`	object	Optional logical timing constraints (e.g., max retries, max duration, checkpoint frequency)

🧬 `sprint-definition.json` Sample¶

{
  "sprint_id": "sprint-2025-06-MVP2",
  "milestone_id": "mvp-ready",
  "features": [
    { "id": "BookingFlow", "priority": "P1", "estimation": 5 },
    { "id": "SendConfirmationEmail", "priority": "P2", "estimation": 3 }
  ],
  "agents": [
    "BackendDeveloperAgent",
    "TestGeneratorAgent",
    "QAAgent"
  ],
  "trace_id": "trace-abc-123",
  "checkpoints": 1,
  "retryPolicy": { "maxAttempts": 2 }
}

This document is validated on startup and persisted alongside trace metadata for auditability.

🔍 Optional / Contextual Inputs¶

Input	Type	Description
`manual_override`	boolean	Allows sprint execution to proceed even if some gates are unmet
`resumption_context`	object	Used if sprint is resuming from a paused or checkpointed state
`security_profile`	object	Indicates if any endpoint/auth observability is required by agents
`testCoverageThreshold`	number	Required percent test coverage (e.g., `85`) enforced at sprint close

🧠 Configuration Source Options¶

These inputs can be injected via:

SprintPlanned event payload
Files in the planning workspace (/planning/sprint-definition.json)
Studio UI input (via sprint planning dashboard)
SprintResumed or SprintRetry payloads

✅ Summary¶

The SprintExecutionCoordinator requires:

A clearly scoped sprint plan
A list of features and agents
A trace ID for audit and observability
Optional execution controls (duration, retries, checkpoints)

These inputs enable the coordinator to run a fully traceable, scoped, and validated execution window aligned to sprint goals and milestone gates.

Outputs¶

The SprintExecutionCoordinator produces a set of traceable, event-driven outputs that represent the state, results, and compliance of a sprint. These outputs serve as:

Activation signals for downstream agents
Gate triggers for milestones and deployments
Observability inputs for dashboards and auditors
Artifacts consumed by QA and CI/CD components

📤 Primary Outputs¶

Output	Type	Description
`SprintStarted`	Event	Indicates sprint has begun and agent execution is permitted
`SprintCheckpoint`	Event	Optional progress checkpoint for QA and trace analysis
`SprintClosed`	Event	Signals all execution and validation steps for this sprint are complete
`SprintFailed`	Event	Indicates a blocking issue or unmet gate prevented sprint closure
`SprintEscalated`	Event	Sent if manual intervention is required (e.g., failed validation)
`sprint-trace-matrix.json`	Artifact	JSON artifact linking features, agents, artifacts, tests, and trace IDs
`qa-validation-report.md`	Artifact	Optional summary of test coverage and QA metrics per feature
`execution-metadata.json[]`	Artifact	Agent-generated trace files during sprint execution

📘 `sprint-trace-matrix.json` Example¶

{
  "sprint_id": "sprint-2025-06-MVP2",
  "milestone_id": "mvp-ready",
  "trace_id": "trace-abc-123",
  "features": [
    {
      "id": "BookingFlow",
      "artifacts": ["BookingHandler.cs", "booking-api.feature"],
      "tests": ["BookingFlowTests.cs"],
      "agent": "BackendDeveloperAgent",
      "status": "complete"
    }
  ],
  "coverage": "92%"
}

✅ This artifact is required to pass milestone gate checks and close the sprint.

📦 File Output Paths¶

File	Location
`sprint-trace-matrix.json`	`/execution/sprints/{sprint_id}/`
`qa-validation-report.md`	`/execution/sprints/{sprint_id}/qa/`
`execution-metadata.json`	One per agent → `/execution/agents/`

🧠 Event Payload: `SprintClosed`¶

{
  "event": "SprintClosed",
  "sprint_id": "sprint-2025-06-MVP2",
  "milestone_id": "mvp-ready",
  "trace_id": "trace-abc-123",
  "status": "complete",
  "artifacts_validated": true,
  "coverage": "92%",
  "timestamp": "2025-05-13T16:32:00Z"
}

This output is consumed by:

MilestoneLifecycleCoordinator
PipelineGenerator
Studio Sprint Tracker
CI/CD Tagging System

📊 Observability Metrics Emitted¶

Metric	Description
`sprint_execution_duration_ms`	Time from `SprintStarted` to `SprintClosed`
`sprint_feature_completion_rate`	% of scoped features completed
`sprint_test_coverage_percent`	Final test coverage from QA report
`agent_execution_success_rate`	Agent success/failure ratio during sprint

✅ Summary¶

The SprintExecutionCoordinator produces:

Structured events to track sprint state
Artifact matrices for traceability and QA
Metrics and logs for audit, observability, and milestone promotion

These outputs make every sprint measurable, auditable, and automatically promotable.

Collaborating Agents¶

The SprintExecutionCoordinator serves as the execution gateway for a select group of AI agents during each sprint. It activates, supervises, and validates their contributions within a clearly scoped window of time and trace.

These agents are chosen based on the sprint plan and are limited to executing within the assigned sprint_id, milestone_id, and feature_id[] context.

🤖 Core Collaborating Agents¶

Agent	Role in Sprint
`ProductOwnerAgent`	Finalizes sprint plan, monitors backlog shifts, emits checkpoints
`BackendDeveloperAgent`	Implements service logic, commands, and use case handlers
`TestGeneratorAgent`	Generates Reqnroll/BDD artifacts and unit tests for each feature
`QAAgent`	Validates trace-test linkage, executes test cases, enforces coverage gates
`DevOpsAgent`	Applies CI/CD pipeline updates or release plan tags (post-sprint)
`GitCommitAgent`	Commits all sprint-generated artifacts to their respective Git repositories

🔁 Agent Activation Flow¶

SprintExecutionCoordinator receives SprintPlanned
Loads allowed agents[] and features[] for the sprint
For each feature:
- Activates the corresponding agent with feature + trace context
- Tracks ArtifactReady and AgentExecutionCompleted events
- Collects execution-metadata.json from each agent
QAAgent and DevOpsAgent are activated after all other agents complete their traceable steps.

🧠 Agent Execution Context Injected¶

Each agent receives:

{
  "sprint_id": "sprint-2025-06-MVP2",
  "milestone_id": "mvp-ready",
  "trace_id": "trace-abc-123",
  "feature_id": "BookingFlow",
  "agent_role": "BackendDeveloperAgent",
  "allowed_skills": ["GenerateHandler", "EmitCommand", "PushCode"]
}

✅ Ensures agents cannot operate outside of their assigned feature and sprint scope.

📎 Optional/Conditional Agents¶

Agent	Activation Criteria
`FeatureToggleInjectionAgent`	Only if `featureFlags[]` present in sprint plan
`SecurityEngineerAgent`	Enabled for regulated sprints or security milestone alignment
`ObservabilityAgent`	Injects OpenTelemetry hooks based on trace config
`HumanApprovalEscalator`	Triggered only if `SprintEscalated` event is emitted

🧩 Agent Interaction Model¶

sequenceDiagram
  SprintCoordinator->>BackendDev: Execute BookingFlow
  SprintCoordinator->>TestGenerator: Create tests for BookingFlow
  SprintCoordinator->>QAAgent: Validate artifacts and coverage
  SprintCoordinator->>DevOpsAgent: Inject pipeline tags
  SprintCoordinator->>GitAgent: Commit artifacts to repo

Hold "Alt" / "Option" to enable pan & zoom

Each agent emits trace-tagged events that SprintExecutionCoordinator collects to verify sprint completion.

✅ Summary¶

The SprintExecutionCoordinator orchestrates only the agents needed for the sprint’s scope, tracks their outputs, and validates their contributions.

This scoped agent activation model enables:

High concurrency
Governance per sprint
Traceable execution per artifact

System Prompt¶

The SprintExecutionCoordinator constructs and dispatches structured prompts to activate agents within the current sprint context. These prompts include sprint-level metadata, assigned feature scope, traceability anchors, and skill constraints — ensuring agents behave deterministically and securely within sprint boundaries.

Each prompt is agent-type specific, but always includes the sprint scope and trace envelope.

🧠 Example System Prompt (Generic Template)¶

You are the {{agent_role}} participating in a sprint inside the ConnectSoft AI Software Factory.

Your current sprint context is:

- sprint_id: {{sprint_id}}
- milestone_id: {{milestone_id}}
- trace_id: {{trace_id}}
- feature_id: {{feature_id}}
- runtime_environment: {{environment}}

Your responsibilities are:

- Execute only tasks defined for your agent type
- Ensure all outputs are trace-tagged with `sprint_id` and `trace_id`
- Do not operate outside your assigned `feature_id`
- Emit all results in structured form (file, event, or trace log)

You may use the following skills:
{{allowed_skills}}

Respond with:
{
  "agent_role": "...",
  "feature_id": "...",
  "files_emitted": [...],
  "status": "completed",
  "trace_id": "...",
  "duration_ms": ...
}

🔧 Dynamic Prompt Variables¶

Placeholder	Description
`{{agent_role}}`	Agent type (e.g., `TestGeneratorAgent`)
`{{sprint_id}}`	Sprint this agent is operating under
`{{milestone_id}}`	Associated milestone for trace validation
`{{trace_id}}`	Root trace for observability correlation
`{{feature_id}}`	Single feature the agent is responsible for
`{{environment}}`	Current runtime tier (`dev`, `test`, etc.)
`{{allowed_skills}}`	Specific skills enabled for the agent

📦 Example Prompt (for `TestGeneratorAgent`)¶

You are the TestGeneratorAgent assigned to sprint `sprint-2025-06-MVP2`.

Feature: `BookingFlow`
Trace ID: `trace-abc123`
Milestone: `mvp-ready`

Use your BDD and Reqnroll generation skills to create:

- 1 feature file (`BookingFlow.feature`)
- 1 unit test class (`BookingFlowTests.cs`)

Tag all outputs with trace metadata and respond with file paths.

🧠 Prompt Delivery Methods¶

Inline Agent Framework tool invocations
Azure Function trigger calls
Remote task queue (via Event Grid or Azure Service Bus)
Studio “Manual Agent Re-Activation” interface

✅ Summary¶

System prompts dispatched by the SprintExecutionCoordinator ensure:

Agents operate only within sprint boundaries
Outputs are traceable and auditable
Prompt behavior is role-specific and policy-compliant

This prompt model enables safe, autonomous, scoped execution per sprint-feature-agent combination.

Execution Flow (Steps)¶

The SprintExecutionCoordinator follows a well-defined, stateful execution process. This flow governs how the sprint begins, activates agents, tracks progress, validates outputs, and emits terminal events.

Each step is event-driven, traceable, and scoped to the active sprint and milestone context.

🔁 Step-by-Step Execution Flow¶

1. Wait for `SprintPlanned` Event¶

Load sprint_id, milestone_id, features[], agents[], and trace_id
Validate sprint-definition.json exists and passes schema checks

2. Initialize Execution Context¶

Inject trace and sprint metadata into observability layer
Persist sprint metadata to /execution/sprints/{sprint_id}/sprint-context.json
Transition FSM state to Planned → Active

3. Activate Agents by Feature¶

For each feature_id: - Activate corresponding agents from the agents[] list - Inject system prompt and execution scope - Monitor emitted events: ArtifactReady, SkillExecutionCompleted

4. Track Agent Outputs¶

Collect execution-metadata.json per agent
Build sprint-trace-matrix.json incrementally
If enabled: perform mid-sprint checkpoint (SprintCheckpoint)

5. Validate Completion Conditions¶

Confirm each feature_id has:
- At least one code artifact (ArtifactReady)
- At least one test case or coverage report (qa-validation-report.md)
Confirm test coverage meets threshold if defined
Validate trace metadata integrity

6. Emit `SprintClosed`¶

Persist final sprint-trace-matrix.json
Emit SprintClosed event with validation summary
Update observability spans with duration, status, and metrics

7. Forward Control to MilestoneCoordinator / CI/CD¶

Trigger MilestoneLifecycleCoordinator to evaluate milestone gates
Trigger PipelineGenerator to begin artifact tagging or release promotion

📂 Generated Artifacts¶

Artifact	Created At Step
`sprint-context.json`	Step 2
`execution-metadata.json[]`	Step 4
`sprint-trace-matrix.json`	Step 5
`qa-validation-report.md`	Step 5
`SprintClosed` event	Step 6

🧠 FSM Transitions (Logical)¶

From → To	Trigger
`Planned → Active`	`SprintPlanned` validated
`Active → Checkpoint`	Progress threshold met
`Active → Blocked`	Failed validation / missing artifact
`Active → Closed`	All completion conditions met

✅ Summary¶

This execution process ensures that every sprint is:

Trace-anchored
Feature-scoped
Agent-driven
Artifact-verified

…and ends only when traceable, testable, CI/CD-ready output exists.

Execution Flow (Diagram)¶

The following Mermaid sequenceDiagram illustrates the runtime flow of sprint execution, showing how the SprintExecutionCoordinator interacts with upstream planners, downstream validators, and per-sprint agents.

This diagram emphasizes trace propagation, FSM transitions, and coordinated agent activation across a defined sprint boundary.

🧬 Mermaid Diagram: Sprint Execution Lifecycle¶

sequenceDiagram
    participant Planner as ProductOwnerAgent
    participant Coordinator as SprintExecutionCoordinator
    participant Agent1 as BackendDeveloperAgent
    participant Agent2 as TestGeneratorAgent
    participant QA as QAAgent
    participant DevOps as DevOpsAgent
    participant Milestone as MilestoneLifecycleCoordinator

    Planner->>Coordinator: Emit SprintPlanned
    Coordinator->>Coordinator: Validate sprint-definition.json
    Coordinator->>Coordinator: Transition to Active
    Coordinator->>Agent1: Execute BookingFlow
    Coordinator->>Agent2: Generate BookingFlow Tests
    Agent1-->>Coordinator: Emit ArtifactReady
    Agent2-->>Coordinator: Emit TestCasesGenerated
    Coordinator->>QA: Validate coverage, trace links
    QA-->>Coordinator: Emit QAValidationReport
    Coordinator->>DevOps: Tag CI pipeline, inject sprint metadata
    DevOps-->>Coordinator: Confirm CI Ready
    Coordinator->>Coordinator: Validate trace matrix
    Coordinator-->>Milestone: Emit SprintClosed

Hold "Alt" / "Option" to enable pan & zoom

🧠 Key Execution Highlights¶

Phase	Description
Activation	Coordinator receives `SprintPlanned`, validates scope, and transitions FSM to `Active`
Scoped Agent Execution	Agents only act on their assigned `feature_id`, using injected system prompts
Observability	Every interaction is trace-tagged (`sprint_id`, `trace_id`, `milestone_id`)
QA Enforcement	QAAgent validates artifact-to-feature mappings and test thresholds
Completion	Once validated, `SprintClosed` is emitted and `sprint-trace-matrix.json` is finalized

🧩 FSM Path Summary¶

stateDiagram-v2
    [*] --> Planned
    Planned --> Active: SprintPlanned
    Active --> Checkpoint: MidSprintReview
    Active --> Blocked: MissingArtifact
    Active --> Closed: AllConditionsMet
    Blocked --> Active: PlanningResumed
    Closed --> [*]

Hold "Alt" / "Option" to enable pan & zoom

✅ Summary¶

This flow and diagram provide a visual representation of how the SprintExecutionCoordinator:

Activates only the necessary agents
Enforces trace-linked execution
Ensures QA coverage and trace matrix completeness
Interfaces with CI/CD and milestone governance

Required Blueprints and Artifacts¶

The SprintExecutionCoordinator operates based on a set of structured, declarative blueprints and configuration files. These inputs define the sprint’s scope, traceability anchors, execution constraints, and success criteria.

By formalizing these artifacts, the Factory ensures repeatable, auditable, and governable sprint execution cycles.

📘 Required Blueprints¶

Artifact	Description
`sprint-definition.json`	Core sprint execution plan: defines `sprint_id`, `milestone_id`, `features`, `agents`, `trace_id`, execution rules
`features.yaml`	Contains definitions for all blueprint-derived features, including priorities, dependencies, and agents assigned
`milestones.yaml`	Maps each milestone to expected features and sprint(s), used to gate sprint closure and milestone progression
`execution-timeline.mmd`	Optional visual timeline of planned sprint phases (used in Studio dashboards)

📂 Example: `sprint-definition.json`¶

{
  "sprint_id": "sprint-2025-07-userauth",
  "milestone_id": "auth-stable-v1",
  "trace_id": "trace-7482bfa3",
  "features": [
    "LoginHandler",
    "TokenValidation",
    "UserProfileQuery"
  ],
  "agents": [
    "BackendDeveloperAgent",
    "TestGeneratorAgent",
    "QAAgent"
  ],
  "checkpoints": 1,
  "testCoverageThreshold": 90
}

📂 Example: `features.yaml`¶

features:
  - id: LoginHandler
    assignedSprint: sprint-2025-07-userauth
    priority: P1
    requiredBy: milestone:auth-stable-v1
    agents:
      - BackendDeveloperAgent
      - TestGeneratorAgent
  - id: TokenValidation
    assignedSprint: sprint-2025-07-userauth
    priority: P1
    requires: [LoginHandler]
    agents: [BackendDeveloperAgent]

📦 Resolved Inputs (During Startup)¶

Artifact / Field	Purpose
`trace_id`	Injected into all events, logs, commits
`sprint_id`	Used in all prompt injections and logs
`feature_id[]`	Drives agent activation map
`milestone_id`	Used for gate checks at close
`testCoverageThreshold`	Enforced before emitting `SprintClosed`
`allowed_agents[]`	Whitelist for which agents may run during sprint

🔐 Observability Integration Files¶

sprint-context.json — context snapshot of all sprint metadata
execution-metadata.json[] — per-agent records of file generation, success/failure
sprint-trace-matrix.json — feature-to-artifact validation report
qa-validation-report.md — optional, for manual milestone review

✅ Summary¶

The SprintExecutionCoordinator requires and consumes:

Structured sprint blueprints
Fully traceable feature plans
Milestone-aligned scoping rules
Agent-bound execution constraints

These artifacts ensure the Factory executes sprints safely, consistently, and transparently across thousands of services.

AI Skills and Plugins Used¶

The SprintExecutionCoordinator uses Agent Framework skills and plugins to activate agents, orchestrate their behavior, enforce scope constraints, and track outputs. It does not generate content itself — instead, it delegates responsibilities to trace-aware agents configured for the current sprint.

These skills allow the coordinator to operate in a modular, policy-compliant, and parallelized manner.

🧠 Core Semantic Skills Utilized¶

Skill / Plugin	Purpose
`AgentActivationSkill.ActivateByScope`	Activates a specific agent with trace + sprint scope
`TraceabilitySkill.InjectSprintTrace`	Adds `trace_id`, `sprint_id`, `milestone_id` into logs, commits, events
`ValidationSkill.CheckAgentOutput`	Confirms agent outputs meet expected test or coverage thresholds
`QAValidationSkill.CompileTraceMatrix`	Builds the `sprint-trace-matrix.json` from agent outputs
`StateMachineSkill.AdvanceSprintState`	Transitions internal FSM between sprint states
`CheckpointSkill.EmitMidSprintReview`	Emits a checkpoint summary for Studio or agents

📘 Example: Agent Activation Skill Call¶

{
  "agent": "TestGeneratorAgent",
  "feature_id": "LoginHandler",
  "trace_id": "trace-7482bfa3",
  "sprint_id": "sprint-2025-07-userauth",
  "milestone_id": "auth-stable-v1",
  "skills_allowed": ["GenerateReqnrollFeature", "EmitTestClass"]
}

This is sent to the AgentActivationSkill, which prepares the system prompt, routes the call to the selected AI agent, and logs the result for post-sprint analysis.

🧩 Optional / Conditional Skills¶

Skill / Plugin	Trigger
`FeatureToggleSkill.InjectFlags`	If `featureFlags[]` is defined in sprint
`EditionSkill.OverrideAgentBehavior`	If the sprint is part of an edition-specific milestone
`ObservabilitySkill.InjectSpans`	If OpenTelemetry is enabled in project config
`SecuritySkill.AnnotateTraceSpan`	If security policy integration is enabled

🔧 Plugin Execution Context¶

All plugins receive:
trace_id
sprint_id
milestone_id
feature_id
agent_role
Execution parameters (e.g., skills allowed, coverage gates)
All responses are logged in:
execution-metadata.json
sprint-trace-matrix.json

📦 Plugin Source and Extensibility¶

Plugin Type	Hosted By	Scope
Microsoft Agent Framework Plugins	AI Orchestration Layer	Agent activation, trace injection, skill filtering
Azure Functions	For durable state machines or skill expansion
Local Plugins (if self-hosted)	Custom sprint-specific CI/CD or QA validation logic

✅ Summary¶

The SprintExecutionCoordinator doesn’t write code — it activates and governs the agents that do.

Through use of AI plugins and skills, it enables:

Controlled, repeatable, parallel agent execution
Sprint-bounded trace injection
Observability-compliant behavior across roles

Human Intervention Hooks¶

While the SprintExecutionCoordinator is designed to operate autonomously, there are strategic points in the sprint lifecycle where manual approval, override, or escalation may be necessary.

These hooks allow the Factory to pause, review, or adjust sprint execution in response to failures, policy gates, or incomplete agent outputs — without compromising traceability or consistency.

🧑‍💼 Manual Review Scenarios¶

Hook Point	Description
`SprintApprovalRequired`	Before starting sprint, Studio user must confirm scope, agents, or milestone alignment
`CoverageBelowThreshold`	QA coverage fails below required percent (e.g., 85%); human reviewer must approve continuation
`ManualGateOverride`	Allows Studio user to approve `SprintClosed` even if one or more completion gates are unmet
`SprintPausedByStudio`	Studio UI triggers a deliberate pause in sprint execution for strategy or dependency reasons
`AgentFailureRequiresReview`	A critical agent fails to emit valid outputs (e.g., missing test cases or trace linkage)

🆘 Escalation Triggers¶

Condition	Result
Repeated failure of an agent (e.g., >3 retries)	Escalation to `HumanApprovalEscalator`
Incomplete trace matrix after sprint timeout	Sprint flagged for manual review
Security policy violation in output	Studio and Compliance Officer notified
Sprint scope mismatch with milestone	Block further progression without manual resolution

🛑 Studio Overrides (UI Buttons)¶

Control	Effect
🛑 Pause Sprint	Halts all downstream agent execution
✅ Approve Sprint Start	Signals coordinator to activate FSM
🔁 Retry Agent	Resubmits prompt/task to failed agent
🔓 Close Sprint (Manual)	Forces `SprintClosed` emission
✏️ Edit Sprint Scope	Updates `sprint-definition.json` before reactivation

🔐 Controlled Bypass Flags¶

Injected into sprint-definition.json or Studio form:

{
  "manual_override": true,
  "allow_unmet_gates": true,
  "approver": "studio-admin"
}

This allows authorized users to bypass automated failure stops with full trace logging.

📊 Audit Logging¶

All manual interventions are recorded in:

intervention-events.json
Studio audit logs (with user ID, action, reason, timestamp)
Sprint FSM history for compliance reporting

✅ Summary¶

Human intervention hooks provide:

🧭 Governance without disruption
🔍 Control without removing automation
🧾 Full auditability of manual decisions

The SprintExecutionCoordinator supports enterprise-grade trust and transparency while maintaining agentic speed and autonomy.

Observability & Traceability¶

The SprintExecutionCoordinator is deeply integrated with the Factory’s observability-first architecture.
It emits structured telemetry, traceable logs, and sprint-level execution metrics to ensure real-time visibility, cross-agent correlation, and audit-ready histories.

“Every sprint execution step, agent action, and artifact must be traceable to a sprint and milestone.”

📡 Trace Context Fields¶

All events, artifacts, logs, and metrics include the following:

Field	Description
`sprint_id`	Unique sprint execution ID (e.g., `sprint-2025-06-MVP2`)
`milestone_id`	Parent milestone ID (e.g., `mvp-ready`)
`trace_id`	Global orchestration trace ID for observability
`feature_id`	Feature executed by an agent
`agent_id`	Agent type (e.g., `BackendDeveloperAgent`)
`skill_id`	Skill invoked (e.g., `GenerateHandler`)
`status`	`success`, `error`, `pending`, `blocked`, `manual_override`
`duration_ms`	Total execution time (per agent or per feature)

📊 Metrics Emitted¶

Metric Name	Type	Description
`sprint_execution_duration_ms`	Timer	Total time from `SprintStarted` to `SprintClosed`
`agent_execution_count`	Counter	Number of agents executed during sprint
`feature_completion_percent`	Gauge	% of planned features completed
`qa_coverage_percent`	Gauge	Final test coverage percent
`trace_matrix_validation_passed`	Boolean	Whether the sprint-trace-matrix is complete and valid
`manual_interventions_count`	Counter	How many times humans paused or intervened

These are pushed to: - Prometheus / Grafana dashboards - Azure Monitor / Application Insights - Studio execution dashboards

🧵 Observability Spans¶

Each agent execution step includes a span:

{
  "span": "AgentExecution",
  "trace_id": "trace-abc123",
  "sprint_id": "sprint-2025-06-MVP2",
  "feature_id": "BookingFlow",
  "agent": "TestGeneratorAgent",
  "skill": "GenerateReqnrollFeature",
  "duration_ms": 1142,
  "status": "success"
}

Spans are emitted through:

OpenTelemetry instrumentation
Structured logs
CI/CD trace pipelines

📁 Logged Artifacts¶

Artifact File	Description
`sprint-trace-matrix.json`	Links features → agents → artifacts/tests
`execution-metadata.json[]`	Per-agent execution logs
`qa-validation-report.md`	Optional test coverage summary
`intervention-events.json`	Human overrides and escalation logs

📊 Studio Sprint Visualization¶

The coordinator integrates with the Studio’s visual layer:

Sprint Timeline: real-time execution view
Agent Activity Table: who did what, when, with trace links
QA Coverage Grid: feature × test matrix per sprint
Intervention Log: review and audit manual decisions

✅ Summary¶

Through structured telemetry, span injection, and trace-anchored outputs, the SprintExecutionCoordinator makes every sprint step observable and explainable — enabling real-time tracking, post-mortem analysis, and compliance audits.

Configuration¶

The behavior of the SprintExecutionCoordinator is configurable to adapt to different governance models, execution environments, and project maturity levels.

These configuration settings can be defined:

Per project (e.g., in orchestration-config.yaml)
Globally across the Factory
Dynamically via SprintPlanned event payload

⚙️ YAML Configuration Example¶

SprintExecutionCoordinator:
  enableCheckpoint: true
  defaultCoverageThreshold: 90
  retryLimitPerAgent: 2
  allowManualOverrides: true
  requireSprintApproval: false
  autoCloseSprint: true
  observability:
    emitSpans: true
    logLevel: info
    metricsEnabled: true
  escalationPolicy:
    enabled: true
    notifyRoles: [ "product-owner", "qa-lead" ]
    fallbackCoordinator: "HumanApprovalEscalator"

🧩 Key Configuration Fields¶

Field	Description
`enableCheckpoint`	Enables mid-sprint checkpoint event/validation
`defaultCoverageThreshold`	QA coverage gate (%); required to emit `SprintClosed`
`retryLimitPerAgent`	Maximum number of retries per agent per feature
`allowManualOverrides`	Allows Studio users to bypass failed gates (logged)
`requireSprintApproval`	Prevents sprint activation until manually approved
`autoCloseSprint`	Automatically emits `SprintClosed` if all gates pass
`observability.emitSpans`	Enables OpenTelemetry tracing for each agent skill call
`escalationPolicy.enabled`	Enables intervention flow if blockers are encountered

🧠 Runtime Config Injection¶

Config values may also be injected via:

The SprintPlanned event payload
A global environment preset
Overrides stored in sprint-definition.json (for sprint-specific behavior)

This allows both global policies and context-aware sprint tuning.

📁 File Location and Inheritance¶

Source	Scope
`/config/orchestration-config.yaml`	Global defaults for all sprints
`/planning/sprint-definition.json`	Sprint-specific overrides
Studio UI (editable fields)	For manual configuration in real-time

✅ Summary¶

Configuration allows the SprintExecutionCoordinator to adapt to:

🎛️ Different governance levels (from autonomous to human-reviewed)
📈 Varying QA maturity (strict vs. flexible coverage gates)
🔁 Retry and resilience policies
🔐 Security and observability controls

This flexibility ensures the Factory can operate at scale while staying policy-aligned and team-appropriate.

Error Handling & Resilience¶

The SprintExecutionCoordinator is built with robust error handling and resilience mechanisms to ensure sprint execution can continue — or recover — even in the presence of partial failures, agent misbehavior, or environmental issues.

Its design embraces idempotency, structured retries, and graceful escalation.

🛠 Error Categories and Recovery Strategies¶

Error Type	Handling Strategy
Agent Execution Failure	Retry up to `retryLimitPerAgent`, then escalate
Missing Artifact	Transition to `Blocked`, notify QA and Studio
Test Coverage Below Threshold	Pause or require manual approval to continue
Trace Mismatch or Invalid Output	Reject sprint close, emit validation error
Observability Failure	Retry span injection; escalate if telemetry fails
CI/CD Pipeline Tagging Error	Defer handoff to `PipelineGenerator`, retry if possible

🔁 Retry Behavior¶

Trigger	Configurable?	Retry Default
Agent failure (`status: error`)	✅ via `retryLimitPerAgent`	2 attempts
Span injection or trace write	✅	3 attempts
Invalid artifact (e.g., file missing fields)	✅	1 attempt, else manual review

Retry actions are logged in execution-metadata.json and Studio dashboards for traceability.

⏸ Sprint FSM State Transitions on Error¶

stateDiagram-v2
    Active --> Blocked: MissingArtifact or FailedValidation
    Blocked --> Active: ManualFix or RetryTrigger
    Active --> Checkpoint: MidSprintPause
    Blocked --> Escalated: HumanInterventionRequired
    Escalated --> Active: ResumedAfterApproval

Hold "Alt" / "Option" to enable pan & zoom

🧠 Internal State Flags¶

Flag	Meaning
`isBlocked`	True if sprint FSM moved to Blocked state
`hasEscalated`	True if manual review was triggered
`agentRetryHistory[]`	Stores retry attempts per agent/feature/skill
`overrideRequested`	True if Studio user manually forced continuation

🧾 Error Artifacts¶

File	Contents
`execution-errors.json`	List of failed agents, retry attempts, and resolution status
`intervention-events.json`	Records of human approvals, manual transitions
`blocked-sprint-summary.md`	Summary of blockers, missing outputs, test gaps

📣 Studio and Alerting¶

🟠 Warnings shown in Sprint Dashboard
🔴 Blockers emit real-time notification to approver roles
🔁 Retry buttons available per agent in UI
✏️ Manual fix injection (e.g., fix trace metadata or retry coverage analysis)

✅ Summary¶

The SprintExecutionCoordinator is designed to:

Retry safely when possible
Block progression when required
Escalate only with full trace context
Log and visualize every failure for diagnosis and governance

This ensures resilient, traceable, sprint execution — even in imperfect conditions.

Integration with MilestoneLifecycleCoordinator¶

The SprintExecutionCoordinator operates in close alignment with the MilestoneLifecycleCoordinator, ensuring that sprints contribute toward milestone progression, and that no milestone can be completed unless all of its sprints have been validated and trace-complete.

This coordination ensures both execution granularity (sprint) and delivery alignment (milestone).

🔁 Communication Between Coordinators¶

Direction	Trigger / Event	Payload
Milestone → Sprint	`SprintPlanned`, `MilestoneReady`	Sprint scope, trace ID, milestone goal
Sprint → Milestone	`SprintClosed`	Feature completion, coverage %, trace matrix
Sprint → Milestone	`SprintBlocked`, `SprintEscalated`	Error reason, retry history, manual approval request

📘 Sprint Contribution to Milestone Gates¶

Each milestone in milestones.yaml lists required features:

milestones:
  - id: mvp-ready
    requiredFeatures:
      - BookingFlow
      - Notification.Send
      - Auth.Login
    gateConditions:
      - allSprintsClosed
      - sprintTraceMatrixComplete
      - testCoverageAbove: 90

The MilestoneLifecycleCoordinator checks:

Has every required feature_id been completed in one or more sprints?
Are all associated sprints closed and QA-verified?
Does the aggregated sprint-trace-matrix.json cover milestone scope?

🧠 Trace Propagation Model¶

Level	Trace Field
Sprint	`sprint_id`, `trace_id`, `milestone_id`
Agent Output	Includes all above fields + `feature_id`, `skill_id`
Milestone	Aggregates sprint closures and matrix validation reports

This enables full backward tracing: Milestone → Sprint(s) → Feature → Artifact → Agent

📤 Event Example: `SprintClosed`¶

{
  "event": "SprintClosed",
  "sprint_id": "sprint-2025-07-MVP2",
  "milestone_id": "mvp-ready",
  "trace_id": "trace-xyz-456",
  "features": ["BookingFlow", "Notification.Send"],
  "qa_coverage": 91.3,
  "status": "complete"
}

Consumed by:

MilestoneLifecycleCoordinator
Studio dashboards
CI/CD pipeline stage gates

🔐 Coordinated Compliance¶

Test coverage gates enforced at sprint level
Artifact tagging linked to both sprint and milestone IDs
CI/CD stages for release promotion gated by MilestoneReached only after all dependent SprintClosed events pass

✅ Summary¶

The SprintExecutionCoordinator and MilestoneLifecycleCoordinator work together to:

Maintain modular execution via sprints
Guarantee delivery integrity via milestone gates
Provide end-to-end traceability from feature to release

This layered coordination ensures scale without chaos and speed with structure.

CI/CD Trace Injection: Tagging and Artifact Metadata¶

The SprintExecutionCoordinator plays a key role in preparing all generated artifacts — including code, tests, containers, and release manifests — for CI/CD alignment and traceability.

By injecting trace metadata at the sprint level, it ensures that every artifact is linked to a sprint, milestone, and feature, enabling:

🧾 Auditable releases
🔁 Reproducible builds
📦 Tagged Docker images and Git commits
📊 Build pipeline trace dashboards

🧬 Metadata Fields Injected¶

Field	Where Injected
`sprint_id`	Git commit messages, image tags, execution logs
`trace_id`	`execution-metadata.json`, logs, observability spans
`milestone_id`	Deployment manifests, trace matrix
`feature_id`	Artifact file headers, test annotations
`agent_id`	Skill logs and telemetry entries

📁 Artifacts with Trace Tags¶

Artifact Type	Injection Point
Git Commit	`commit-msg: "[sprint:sprint-06] [trace:xyz] Add BookingHandler"`
Docker Image	`booking-service:1.0.3-sprint06-mvp-v1`
Pipeline Logs	Includes `trace_id`, `sprint_id`, and `agent_id`
Release Notes / Markdown	Includes footer block with trace context
Test Cases	Gherkin/Reqnroll tag: `@SprintId(sprint-2025-07)`

📦 CI/CD Pipeline Integration¶

Once the SprintClosed event is emitted and validated:

PipelineGenerator picks up sprint-trace-matrix.json
Builds and releases are tagged using values from:
sprint_id
milestone_id
trace_id

✅ Example:

variables:
  sprint_id: sprint-2025-07
  milestone_id: mvp-ready
  trace_id: trace-7482bfa3

steps:
  - task: Docker@2
    inputs:
      tags: |
        $(sprint_id)
        $(milestone_id)
        trace:$(trace_id)

🔐 Deployment Trace Anchoring¶

Deployed artifacts (e.g., Helm charts, ARM templates) include metadata annotations:

metadata:
  labels:
    sprint: sprint-2025-07
    milestone: mvp-ready
    trace: trace-7482bfa3

→ Enables reverse tracing from production environment back to the planning intent.

📊 Studio Build Trace View¶

Artifact	Sprint	Milestone	Image Tag	CI/CD Status
Booking API	sprint-2025-07	mvp-ready	`booking:1.0.3-sprint07`	✅ Passed
Auth Service	sprint-2025-06	auth-preview	`auth:0.9.1-sprint06`	⚠️ Retrying

✅ Summary¶

The SprintExecutionCoordinator guarantees that every artifact generated during a sprint is trace-linked, tagged, and CI/CD-compatible.

This enables:

🔗 End-to-end traceability from blueprint to deployment
🚦 Milestone-driven promotion gates
📦 Artifact governance across environments

Studio Visualizations: Sprint Cards, Dashboards, and Trace Matrix¶

The ConnectSoft Studio provides a rich set of visualizations to monitor, validate, and govern sprint execution.
These views are powered directly by outputs from the SprintExecutionCoordinator — including events, trace files, QA reports, and observability metrics.

Sprint execution becomes observable, navigable, and actionable via Studio’s sprint dashboards.

🧩 Sprint Overview Card¶

Each active or completed sprint is shown as a card in the Studio UI:

Field	Source
Sprint ID	`sprint-definition.json`
Milestone Link	`milestone_id` from sprint
Feature Count	Number of scoped `feature_id[]`
QA Status	From `qa-validation-report.md`
Coverage %	Calculated from trace matrix
Duration	Time between `SprintStarted` and `SprintClosed`
Agent Health	Aggregated from `execution-metadata.json`
Progress	Derived from trace and artifact readiness

📊 Sprint Trace Matrix View¶

Interactive table populated from sprint-trace-matrix.json:

Feature	Agents Executed	Artifacts	Tests	Status
BookingFlow	BackendDev, QAAgent	3 files	2 test cases	✅ Done
SendEmail	TestGenAgent	2 files	1 test case	⚠️ Incomplete
RetryMechanism	BackendDev	0	0	❌ Blocked

🟢 Rows link to logs, trace IDs, and file diffs

📈 Sprint Timeline¶

gantt
    title Sprint Timeline — sprint-2025-07-MVP2
    dateFormat  YYYY-MM-DD
    section Sprint Phases
    Planning           :done,    s0, 2025-05-12,1d
    Active Execution   :active,  s1, 2025-05-13,2d
    QA Validation      :         s2, 2025-05-15,1d
    Sprint Closure     :         s3, 2025-05-16,0.5d

Hold "Alt" / "Option" to enable pan & zoom

→ Annotated with failure/retry markers, manual interventions, and trace logs

📍 Agent Activity Breakdown¶

Bar chart per agent:

Total skills invoked
Avg duration
Success/failure ratio
Linked trace ID count

Filtered by:

Sprint
Feature
Milestone

🧯 Intervention Panel¶

Shows manual approvals, blocked states, retry attempts:

Event Type	Agent	Timestamp	Outcome
Retry Request	QAAgent	2025-05-14T10:32Z	✅ Passed
Manual Close Override	Studio Admin	2025-05-15T17:04Z	🟡 Partial Trace
Agent Failure	TestGenAgent	2025-05-14T08:23Z	❌ No Output

📎 Trace Explorer Integration¶

From any sprint card or row, user can launch:

Trace-to-Code Path: trace → agent → skill → file → commit
Trace-to-Test: trace → feature → test → coverage
Trace-to-Artifact: trace → build → image → CI/CD result

✅ Summary¶

Studio visualizations powered by the SprintExecutionCoordinator provide:

🧠 Real-time sprint monitoring
✅ Visual validation of gates, coverage, and agent activity
🔍 Trace-aware diagnostics for debugging or compliance

Real-World Example Sprint: Notification Service MVP Sprint¶

This example illustrates how the SprintExecutionCoordinator orchestrated a real sprint for the Notification Service, demonstrating full traceable execution — from sprint planning to milestone completion.

📘 Sprint Overview¶

Property	Value
`sprint_id`	`sprint-2025-05-notify-mvp`
`milestone_id`	`mvp-ready`
`trace_id`	`trace-d56a12fa`
`features`	`SendEmail`, `RetryNotification`, `SendPush`
`agents`	`BackendDeveloperAgent`, `TestGeneratorAgent`, `QAAgent`
`coverageThreshold`	90%
`checkpointEnabled`	✅ Yes

🧩 Inputs¶

sprint-definition.json:

{
  "sprint_id": "sprint-2025-05-notify-mvp",
  "milestone_id": "mvp-ready",
  "features": ["SendEmail", "RetryNotification", "SendPush"],
  "agents": ["BackendDeveloperAgent", "TestGeneratorAgent", "QAAgent"],
  "trace_id": "trace-d56a12fa",
  "checkpoints": 1,
  "testCoverageThreshold": 90
}

🔁 Execution Flow¶

SprintPlanned event triggered by ProductOwnerAgent
SprintExecutionCoordinator loaded plan, transitioned to Active
Agents activated:
- BackendDeveloperAgent created handlers
- TestGeneratorAgent emitted Reqnroll BDD and unit tests
- QAAgent validated artifacts and generated coverage report
All agents' outputs linked via trace_id and written to:
- execution-metadata.json
- sprint-trace-matrix.json
Mid-sprint checkpoint passed without intervention
SprintClosed emitted after 92.1% test coverage achieved

📦 Outputs¶

execution/BookingHandler.cs
tests/NotificationFlow.feature
sprint-trace-matrix.json
qa-validation-report.md
SprintClosed event emitted
Tagged image: notification-service:1.0.0-sprint05

📊 Studio View Snapshot¶

Feature	Artifacts	Tests	QA Status	Result
SendEmail	`EmailHandler.cs`	✅ 3 test cases	✅ Pass	✅ Done
RetryNotification	`RetryHandler.cs`	✅ 2 test cases	✅ Pass	✅ Done
SendPush	`PushHandler.cs`	✅ 2 test cases	✅ Pass	✅ Done

📈 Metrics Summary¶

Total agent executions: 9
Average agent duration: 1.28 sec
QA coverage: 92.1%
Manual interventions: 0
Status: ✅ Sprint success
Time-to-completion: 4m 17s

🎯 Outcome¶

MilestoneLifecycleCoordinator received SprintClosed
PipelineGenerator triggered build and release tagging
Sprint artifacts were promoted to staging via mvp-ready milestone gate

✅ Summary¶

This real-world sprint demonstrated:

🔄 Coordinated agent execution per feature
🧪 Enforced QA validation gates
🔗 End-to-end traceability via sprint_id and trace_id
📦 Deployment-ready CI/CD handoff

The SprintExecutionCoordinator enabled structured, observable, and governable delivery from intent to artifact — all in minutes.

Related workflows¶

Sprint Execution Coordinator¶

Overview and Role in the Factory¶

🎯 Core Purpose¶

📦 Key Capabilities¶

🧬 Sprint Metadata Structure¶

🧠 Why This Coordinator Matters¶

Position in the Execution Flow¶

🔁 Execution Phase¶

📌 Dependencies¶

🚀 What It Unlocks¶

🧬 Execution Timeline Diagram¶

🧠 Summary¶

Responsibilities¶

✅ Core Responsibilities¶

📦 Additional Outputs Controlled¶

🧠 Sprint FSM States (Internal)¶

🔁 Coordinated Domains¶

🧩 Related Coordinators It Interacts With¶

🎯 Summary¶

Triggering Events¶

🚦 Primary Triggering Events¶

🔁 Re-Entry / Update Events¶

📤 Events Emitted by the Coordinator¶

🧠 Event Payload Structure: SprintStarted¶

📡 Observability Integration¶

✅ Summary¶

Inputs¶

📥 Required Inputs¶

🧬 sprint-definition.json Sample¶

🔍 Optional / Contextual Inputs¶

🧠 Configuration Source Options¶

✅ Summary¶

Outputs¶

📤 Primary Outputs¶

📘 sprint-trace-matrix.json Example¶

📦 File Output Paths¶

🧠 Event Payload: SprintClosed¶

📊 Observability Metrics Emitted¶

✅ Summary¶

Collaborating Agents¶

🤖 Core Collaborating Agents¶

🔁 Agent Activation Flow¶

🧠 Agent Execution Context Injected¶

📎 Optional/Conditional Agents¶

🧩 Agent Interaction Model¶

✅ Summary¶

System Prompt¶

🧠 Example System Prompt (Generic Template)¶

🔧 Dynamic Prompt Variables¶

📦 Example Prompt (for TestGeneratorAgent)¶

🧠 Prompt Delivery Methods¶

✅ Summary¶

Execution Flow (Steps)¶

🔁 Step-by-Step Execution Flow¶

1. Wait for SprintPlanned Event¶

2. Initialize Execution Context¶

3. Activate Agents by Feature¶

4. Track Agent Outputs¶

5. Validate Completion Conditions¶

6. Emit SprintClosed¶

7. Forward Control to MilestoneCoordinator / CI/CD¶

📂 Generated Artifacts¶

🧠 FSM Transitions (Logical)¶

✅ Summary¶

Execution Flow (Diagram)¶

🧬 Mermaid Diagram: Sprint Execution Lifecycle¶

🧠 Key Execution Highlights¶

🧩 FSM Path Summary¶

✅ Summary¶

Required Blueprints and Artifacts¶

📘 Required Blueprints¶

📂 Example: sprint-definition.json¶

📂 Example: features.yaml¶

📦 Resolved Inputs (During Startup)¶

🔐 Observability Integration Files¶

✅ Summary¶

AI Skills and Plugins Used¶

🧠 Core Semantic Skills Utilized¶

📘 Example: Agent Activation Skill Call¶

🧠 Event Payload Structure: `SprintStarted`¶

🧬 `sprint-definition.json` Sample¶

📘 `sprint-trace-matrix.json` Example¶

🧠 Event Payload: `SprintClosed`¶

📦 Example Prompt (for `TestGeneratorAgent`)¶

1. Wait for `SprintPlanned` Event¶

6. Emit `SprintClosed`¶

📂 Example: `sprint-definition.json`¶

📂 Example: `features.yaml`¶

📤 Event Example: `SprintClosed`¶