🧠 Product Manager Agent Specification¶
🎯 Purpose¶
The Product Manager Agent is a strategic and operational bridge between business vision and technical realization inside the ConnectSoft AI Software Factory.
Its core purpose is to:
-
Transform Business Requirements Documents (BRDs) created by the Business Analyst Agent
into well-structured Product Plans — including feature maps, release strategies, MVP scoping, backlog planning, and business goal alignment. -
Prioritize and structure features to ensure business value delivery across iterations.
-
Define Minimum Viable Products (MVPs), editions, feature sets, and roadmaps aligned with business priorities, target personas, and market opportunities.
-
Generate AI-ready artifacts that enable smooth continuation of the autonomous development process — triggering Product Owner Agent, Enterprise Architect Agent, UX/UI Agents, and Engineering Agents downstream.
🚀 In Short:¶
The Product Manager Agent transforms raw vision into structured, prioritized, and validated product plans —
ensuring that the entire ConnectSoft Software Factory can build what matters first, align with business goals, and move efficiently towards launch.
🏛️ Position in the ConnectSoft AI Software Factory Lifecycle¶
flowchart TD
VisionArchitectAgent -->|Structured Vision Document| BusinessAnalystAgent
BusinessAnalystAgent -->|Business Requirements Document| ProductManagerAgent
ProductManagerAgent -->|Product Planning Artifacts| ProductOwnerAgent
ProductManagerAgent -->|Feature Maps, MVP Scope| EnterpriseArchitectAgent
ProductManagerAgent -->|Feature Backlog| UXDesignerAgent
ProductManagerAgent -->|Release Strategy| DevOpsEngineerAgent
Hold "Alt" / "Option" to enable pan & zoom
- Upstream Input: Business Requirements Document (BRD), Business Rules, Process Models, and traceability metadata produced by the Business Analyst Agent.
- Downstream Outputs:
- Product Plans (Roadmaps, MVP definitions, Backlogs, Feature Maps)
- Events:
ProductPlanCreated,MVPDefined,FeatureBacklogReady - Triggers for multiple agents across product, architecture, UX/UI, and DevOps tracks.
🧭 Strategic Importance¶
| Aspect | Product Manager Agent Contribution |
|---|---|
| Vision Realization | Converts high-level vision into actionable product definitions. |
| Business Alignment | Prioritizes features that maximize business value and market fit. |
| MVP Focus | Ensures lean, fast-to-market product launches. |
| Edition Strategy | Supports multi-tenant SaaS needs: free, pro, enterprise, customized editions. |
| Observability and Governance | Embeds traceability, versioning, and event-driven notifications from the start. |
| Elastic Scaling | Supports branching and parallel execution paths for multi-product SaaS factories. |
📚 Example Use Cases¶
| Scenario | Supported? | Notes |
|---|---|---|
| Defining MVP for a new healthcare SaaS platform | ✅ | Aligns minimal launch scope to key medical workflows. |
| Planning Editions (Basic, Premium, Enterprise) for a CRM SaaS | ✅ | Segments feature sets by tier, prepares edition boundaries. |
| Building a Feature Backlog for an AI chatbot solution | ✅ | Prioritizes core conversation flows, learning models, integrations. |
| Rapid pivot to a new market (e.g., retail loyalty mobile app) | ✅ | Adjusts feature roadmap, trims or reorders backlog automatically. |
🏷️ ConnectSoft Platform Alignment¶
-
📚 Domain-Driven Design (DDD):
Product decomposition aligns with bounded contexts and ubiquitous language. -
🛜 Event-Driven Architecture (EDA):
EmitsProductPlanCreated,FeatureBacklogReady,MVPDefinedevents for downstream collaboration. -
🧱 Cloud-Native Scalability:
Product plans generated to support cloud-native, SaaS-first deployment models. -
🤖 AI-First Modularization:
Features modularized early to support agentic decomposition and microservices templates.
📋 Responsibilities¶
The Product Manager Agent is responsible for producing high-fidelity, structured deliverables that drive the transition from Vision to Engineering Execution inside the ConnectSoft AI Software Factory.
Each responsibility ensures that downstream agents (Product Owner, Enterprise Architect, UX Designer, Engineering Clusters) can work efficiently, guided by clear, validated, and AI-ready artifacts.
| Responsibility | Description |
|---|---|
| Vision Decomposition | Analyze the Vision Document and extract core product goals, modules, and high-level features. |
| Feature Catalog Definition | Create a structured catalog of features, grouped by business domain and functional areas. |
| MVP (Minimum Viable Product) Identification | Define a minimal set of features needed for the first public release, focusing on fast business validation. |
| Edition Mapping | Propose how features will be distributed across product editions (e.g., Free, Professional, Enterprise). |
| Product Roadmap Planning | Draft phased releases (MVP, Phase 2, Phase 3...) aligned with business priorities and technical feasibility. |
| Persona Alignment | Map features to target personas (e.g., "Admin", "End User", "Customer Success Manager") defined earlier. |
| Business Objectives Mapping | Align features with business KPIs and strategic goals identified in the Vision Document (e.g., "Reduce churn by 15%"). |
| Feature Prioritization | Apply scoring models (e.g., MoSCoW, RICE) to prioritize feature delivery based on impact, effort, risk. |
| Traceability Embedding | Embed trace IDs, version numbers, artifact references in all produced documents for full lifecycle traceability. |
| Event Emission | Emit system events like ProductPlanCreated, MVPDefined, FeatureBacklogReady to activate downstream agents. |
| Collaboration Readiness | Ensure all outputs are modular, structured, and documented for seamless collaboration with Product Owner Agent, UX Designer, and Architects. |
🏛️ Visual: Product Manager Agent Responsibilities Overview¶
flowchart TB
VisionDocument -->|Analyze| ProductManagerAgent
ProductManagerAgent -->|FeatureCatalog| FeatureCatalogArtifact
ProductManagerAgent -->|MVP Definition| MVPArtifact
ProductManagerAgent -->|Roadmap| RoadmapArtifact
ProductManagerAgent -->|Edition Plan| EditionsArtifact
ProductManagerAgent -->|Feature Backlog| FeatureBacklogArtifact
ProductManagerAgent -->|Emit Events| EventBus
Hold "Alt" / "Option" to enable pan & zoom
📚 Example Outputs per Responsibility¶
| Responsibility | Example Output |
|---|---|
| Vision Decomposition | "Customer Onboarding", "User Profile Management", "Billing Integration" modules |
| Feature Catalog | Table listing 50+ features with descriptions, priorities, and mappings |
| MVP Identification | MVP Feature List: 8 critical features for first launch |
| Edition Mapping | Free Edition: Basic Access; Pro Edition: Extended Integrations; Enterprise Edition: Multi-Tenant Management |
| Roadmap | Q1: MVP Launch; Q2: Analytics & Reporting Additions; Q3: Advanced Integrations |
| Persona Alignment | Feature X targeted at "Billing Admin"; Feature Y targeted at "End Customer" |
| Business Objectives Mapping | Feature A tied to "Increase Retention"; Feature B tied to "Increase Revenue Per User" |
| Prioritization | RICE Scoring Table for all proposed features |
| Traceability Embedding | All artifacts include project_id, trace_id, vision_version, plan_version metadata |
| Event Emission | Emit ProductPlanCreatedEvent JSON message with attached artifact URIs |
🧩 Cross-Link to ConnectSoft Principles¶
| Platform Principle | Responsibility Mapping |
|---|---|
| Domain-Driven Design (DDD) | Vision decomposition into functional bounded contexts. |
| Event-Driven Architecture (EDA) | Structured event emissions after artifact creation. |
| Cloud-Native Design | Modular feature prioritization enabling microservices decomposition. |
| Clean Architecture | Separation between business feature definition and technical realization. |
| Multi-Tenant SaaS | Editions mapping to free/pro/enterprise tenant models. |
📥 Inputs¶
The Product Manager Agent requires a rich set of structured inputs to accurately decompose visions into actionable product plans.
It consumes both artifact-based and event-based inputs,
ensuring that every product planning decision is contextual, traceable, and aligned with ConnectSoft's platform standards.
| Input Type | Description | Example |
|---|---|---|
| Vision Document | The core structured document produced by the Vision Architect Agent, containing problem definition, opportunity framing, initial feature set, personas, and success criteria. | Markdown + JSON Vision Artifact linked via URI. |
| Vision Metadata | Trace IDs, vision version, timestamps, software type classifications, domain tags. | trace_id: vision-2025-04-27-001, domain: healthcare |
| VisionDocumentCreated Event | Event emitted by Vision Architect Agent signaling availability of a new vision to process. | Event payload containing links to artifacts and context. |
| Business Requirements Document (BRD) | Structured requirements, rules, process models produced by the Business Analyst Agent. | Markdown + JSON artifact linked via URI. |
| BRD Metadata | Trace ID, project ID, domain context, compliance tags, etc. | trace_id: brd-2025-04-27-001, domain: healthcare, regulatory: HIPAA |
| BusinessRequirementsReady Event | Event emitted by the Business Analyst Agent signaling BRD readiness for product planning. | Payload with BRD URI and traceability context. |
| Strategic Objectives Context | Business KPIs, goals, success metrics embedded in the Vision Document. | "Reduce customer churn by 15%", "Launch by Q2 2026" |
| Persona Definitions | List of target users, stakeholders, external systems defined in the Vision Artifact. | ["Admin User", "End Customer", "Support Agent"] |
| Initial Feature Map | Early, unprioritized list of major capabilities suggested by the Vision Architect. | Appointments Management, Billing and Invoicing, Profile Settings |
| Software Type Classification | Type of system envisioned: SaaS Platform, API Platform, Mobile App, Embedded System, etc.. | "SaaS Platform" + "Mobile App Extension" |
| Market/Domain Constraints (optional) | Specific domain knowledge or regulatory frameworks relevant to the product. | "HIPAA Compliance required", "Supports B2B workflows" |
| Semantic Memory Retrieval (Optional) | Previous similar product plans, editions definitions, roadmaps retrieved from internal vector memory or MCP Servers. | Past project plans, feature scoring templates, edition matrices. |
| Execution Constraints (optional) | Special instructions regarding MVP size, initial go-to-market requirements, launch urgency. | "MVP must launch within 4 months" |
🏗️ Visual: Product Manager Agent Input Sources¶
flowchart TD
VisionArchitectAgent -->|VisionDocument + Metadata| ProductManagerAgent
BusinessAnalystAgent -->|BRD + Business Rules| ProductManagerAgent
EventBus -->|VisionDocumentCreatedEvent + BusinessRequirementsReadyEvent| ProductManagerAgent
SemanticMemory -->|Similar Past Artifacts| ProductManagerAgent
InternalPolicies -->|Business/Compliance Constraints| ProductManagerAgent
Hold "Alt" / "Option" to enable pan & zoom
📜 Example VisionDocumentCreated Event Payload¶
{
"event_type": "VisionDocumentCreated",
"artifact_uri": "https://connectsoft.blob.core.windows.net/visions/vision-2025-04-27-001.md",
"trace_id": "vision-2025-04-27-001",
"vision_version": "1.0",
"software_type": ["SaaS", "Mobile App"],
"domain": "Healthcare",
"persona_list": ["Doctor", "Admin Staff", "Patient"],
"strategic_goals": ["Reduce appointment no-shows by 25%", "Increase patient engagement"]
}
✅ Product Manager Agent consumes this event and downloads the referenced artifact before starting processing.
📚 Source of Inputs¶
| Source | Inputs Provided |
|---|---|
| Vision Architect Agent | Vision Document, Vision Metadata |
| Event Bus | VisionDocumentCreated Event |
| ConnectSoft Artifact Storage | Vision Document file, semantic memories |
| Business Analyst Agent | Business Requirements Document, BRD Metadata |
| Internal Knowledge Base | Domain rules, compliance standards |
| Semantic Memory, Data Storage, Azure Devops/Git platforms, MCP Servers integrations | Past product plans, feature prioritizations, editions structures |
🧩 Alignment to ConnectSoft Principles¶
| Principle | Input Relationship |
|---|---|
| Event-Driven Architecture | All actions start based on structured system events. |
| Domain-Driven Design | Vision artifacts map to initial bounded contexts. |
| Cloud-Native Storage | Artifact storage on cloud-native, observable systems. |
| Semantic Memory Augmentation | Retrieve reusable knowledge to boost product plan quality. |
📤 Outputs¶
The Product Manager Agent produces a set of structured, AI-ready artifacts and event emissions,
enabling the seamless activation of downstream agents across product management, architecture, UX, and engineering tracks.
Each output is carefully structured to support:
- Clear decomposition of work across bounded contexts.
- Observable and versioned handoff.
- Validation-first workflows for downstream consumption.
📋 Main Outputs¶
| Output Type | Description | Format |
|---|---|---|
| Product Plan Document | Structured description of the product, including feature catalog, MVP, editions, and roadmap. | Markdown + JSON |
| Feature Catalog Artifact | Table of all proposed features, mapped to personas, business goals, and priorities. | Markdown Table + JSON List |
| MVP Feature Set | Defined list of minimum features required for first launch. | JSON Object |
| Editions Mapping | Mapping of features to product editions (Free, Pro, Enterprise, Custom). | JSON Mapping + Markdown |
| Product Roadmap | Phased release plan showing the evolution from MVP to full system. | Markdown Timeline + JSON |
| Feature Backlog | Prioritized list of features prepared for Product Owner Agent backlog refinement. | JSON List with RICE/MoSCoW scores |
| Event Emissions | System events emitted to notify downstream agents about artifact readiness. | JSON Event Payloads |
🏗️ Visual: Product Manager Agent Output Flows¶
flowchart TD
ProductManagerAgent -->|ProductPlanCreatedEvent| ProductOwnerAgent
ProductManagerAgent -->|MVPDefinedEvent| EnterpriseArchitectAgent
ProductManagerAgent -->|FeatureBacklogReadyEvent| UXDesignerAgent
ProductManagerAgent -->|EditionsDefinedEvent| PlatformIntegratorAgent
Hold "Alt" / "Option" to enable pan & zoom
📄 Example: Product Plan Document Structure¶
# Product Plan: Healthcare Appointment Management SaaS
## Vision Summary
(Reference Vision ID: vision-2025-04-27-001)
## MVP Scope
- Patient Registration
- Appointment Scheduling
- Notifications
## Feature Catalog
| Feature | Persona | Priority | Strategic Goal |
|:--------|:--------|:---------|:---------------|
| Appointment Scheduling | Patient, Doctor | High | Increase engagement |
| Billing Module | Admin | Medium | Improve revenue tracking |
## Editions Plan
- Free: Appointment Scheduling, Basic Notifications
- Pro: Advanced Notifications, Billing Integration
- Enterprise: Multi-Clinic Management, Analytics Dashboard
## Product Roadmap
- Q1 2026: MVP Launch
- Q2 2026: Billing & Payments
- Q3 2026: Analytics and Reporting
📦 Example: Event Emissions¶
| Event | Triggered After | Payload Content |
|---|---|---|
ProductPlanCreated |
Product Plan Document completion | Artifact URI, version, trace ID, vision reference |
MVPDefined |
MVP Feature List validation | Feature list, context metadata |
FeatureBacklogReady |
Feature Catalog prioritization complete | Backlog URI, priorities, RICE scores |
EditionsDefined |
Editions Mapping finalization | Editions artifact URI, feature mappings |
Example Payload:
{
"event_type": "ProductPlanCreated",
"trace_id": "vision-2025-04-27-001",
"product_plan_uri": "https://connectsoft.blob.core.windows.net/products/product-plan-2025-04-27-001.md",
"version": "1.0",
"vision_reference": "vision-2025-04-27-001",
"timestamp": "2025-04-27T20:00:00Z"
}
🧩 Output Quality Standards¶
| Attribute | Expectation |
|---|---|
| Traceability | All artifacts must embed trace_id, vision_reference, version. |
| Validation-First | All outputs must pass structural, semantic, and context validations. |
| Event-Driven | Every major artifact creation triggers a corresponding event. |
| Semantic Alignment | Outputs must align with business goals, personas, and domains specified in Vision Document. |
| Multi-Agent Ready | Outputs must be modular and consumable by Product Owner, Architect, UX, and Engineering Agents without rework. |
📚 Knowledge Base¶
The Product Manager Agent operates based on a rich internal Knowledge Base,
which empowers it to reason, plan, prioritize, and structure products effectively —
without needing constant human supervision.
This Knowledge Base is made up of static templates, semantic memories, domain expertise, and strategic business mappings, allowing the agent to:
- Decompose complex visions into structured plans.
- Prioritize features based on business value.
- Design editions strategies aligned with SaaS best practices.
- Map features to personas and strategic goals intelligently.
- Support multi-tenant SaaS and cloud-native architectural expectations.
📋 Core Areas of the Knowledge Base¶
| Knowledge Area | Description |
|---|---|
| Product Planning Templates | Standardized templates for product plans, roadmaps, MVP definitions, and feature backlogs (Markdown and JSON formats). |
| Feature Prioritization Models | Built-in understanding of RICE Scoring, MoSCoW Method, Weighted Shortest Job First (WSJF). |
| Strategic Objectives Mapping | Models for aligning features to business KPIs: engagement, retention, revenue, churn reduction, etc. |
| Persona-Feature Mapping Principles | Methods for assigning features to target personas based on needs and workflows. |
| SaaS Editions Strategy Models | Patterns for defining Free, Pro, Enterprise, and Custom SaaS editions with feature segregation. |
| Product Roadmap Phasing Techniques | Models for planning MVP → Phase 2 → Phase 3 evolutions in cloud-native SaaS products. |
| Multi-Tenant SaaS Best Practices | Awareness of tenancy boundaries, feature scoping by tenant class, and upgrade paths. |
| Domain Knowledge and Industry Context | Understands nuances for common industries (Healthcare, Fintech, Retail, EdTech, AI SaaS, etc.). |
| ConnectSoft Modular Platform Standards | Knowledge of ConnectSoft's architectural modularity (bounded contexts, DDD aggregates, event-driven flows). |
| Semantic Memory of Past Projects | Access to similar project structures, successful MVPs, backlog templates, edition matrices from previous ConnectSoft builds. |
🧠 Internal Diagrams: Knowledge Base Components¶
flowchart TD
KnowledgeBase --> ProductPlanningTemplates
KnowledgeBase --> PrioritizationModels
KnowledgeBase --> StrategicObjectivesMapping
KnowledgeBase --> SaaSEditionPatterns
KnowledgeBase --> DomainKnowledge
KnowledgeBase --> SemanticMemory
KnowledgeBase --> ConnectSoftPlatformStandards
Hold "Alt" / "Option" to enable pan & zoom
✅ These components are dynamically consulted during reasoning and artifact generation.
🗂️ Example Internal Assets Stored in Knowledge Base¶
| Asset | Description | Example |
|---|---|---|
standard-product-plan.md |
Markdown template for Product Plan documents. | Placeholder structure with feature catalog, MVP, editions, roadmap sections. |
feature-prioritization-rules.json |
JSON rules for RICE scoring model. | Impact weight = 0.4, Confidence = 0.3, Effort = 0.3 |
editions-mapping-patterns.md |
Heuristics for defining SaaS editions boundaries. | Core → Free, Integrations → Pro, Customizations → Enterprise |
personas-industry-mapping.json |
Default mappings of personas to industries. | Healthcare: Patient, Doctor, Admin |
roadmap-phasing-patterns.md |
Guidelines for incremental feature rollouts. | MVP (Core features) → Phase 2 (Advanced modules) → Phase 3 (Optimizations) |
🧩 Knowledge Base Access Mechanisms¶
| Source | Access Mode |
|---|---|
| Internal ConnectSoft Artifact Storage | Static templates and modular knowledge artifacts. |
| Azure Storage types, Azure DevOps, blob storage, MCP Servers (Azure, PostgreSQL, MinIO) | Semantic memory search and retrieval. |
| ConnectSoft SDKs and Libraries | DDD, messaging, persistence model libraries used for reasoning support. |
| Runtime Event Bus | Access traceability data, upstream vision metadata. |
📜 Example Retrieval Flow (Semantic Memory)¶
flowchart TD
ProductManagerAgent -->|Semantic Query: Healthcare SaaS MVPs| SemanticMemoryMCP
SemanticMemory-->|Return Past Project| ProductManagerAgent
ProductManagerAgent -->|Incorporate Best Practices| ArtifactGeneration
Hold "Alt" / "Option" to enable pan & zoom
✅ Agent dynamically improves outputs based on previous successful strategies.
🧠 ConnectSoft Platform Alignment¶
| Principle | Knowledge Base Use |
|---|---|
| Cloud-Native & Distributed | Memory and knowledge distributed across Azure Storage types, Azure DevOps, blob storage, MCP Servers. |
| Event-Driven | Artifact and version metadata retrieved from event triggers. |
| Domain-Driven | Decomposition maps cleanly to bounded contexts. |
| Extensible by Design | New knowledge (templates, patterns) can be plugged into the agent without changing core logic. |
🔄 Process Flow¶
The Product Manager Agent follows a structured, modular, and observable execution flow inside the ConnectSoft AI Software Factory.
Every task assigned to the agent moves through a predictable lifecycle, ensuring:
- 🔵 Consistency
- 🟢 Traceability
- 🟠 Recoverability
- 🟣 Scalability
- 🟤 Observability
The agent operates event-driven and artifact-centric,
transforming input Vision Documents into validated Product Planning Artifacts and structured downstream events.
🧩 High-Level Phases of the Process Flow¶
| Phase | Description |
|---|---|
| 1. Task Assignment | Triggered by a VisionDocumentCreated event. Receives assignment metadata and artifact references. |
| 2. Information Intake | Downloads the Vision Document, parses metadata, retrieves semantic memories if needed. |
| 3. Vision Decomposition | Analyzes business goals, personas, success criteria, and initial features. |
| 4. Product Structuring | Creates structured artifacts: Feature Catalog, MVP Definition, Editions Mapping, Roadmap Planning. |
| 5. Prioritization | Applies prioritization models (RICE, MoSCoW) to feature lists. |
| 6. Validation | Runs structural, semantic, and compliance validation on all artifacts. |
| 7. Correction (if needed) | Auto-corrects or retries artifact generation if validation fails. |
| 8. Artifact Storage | Stores artifacts in ConnectSoft Artifact Storage / MCP Servers / Azure DevOps/Git, blobs. |
| 9. Event Emission | Emits structured events: ProductPlanCreated, MVPDefined, FeatureBacklogReady, EditionsDefined. |
| 10. Observability Recording | Captures telemetry (logs, traces, metrics) across the entire flow. |
🏗️ Visual Diagram: Product Manager Agent Internal Execution Flow¶
flowchart TD
TaskAssignment["Task Assignment from EventBus"]
--> Intake["Information Intake: Download Vision, Metadata, Semantic Context"]
--> Decomposition["Vision Decomposition"]
--> Structuring["Product Structuring (Feature Catalog, MVP, Editions, Roadmap)"]
--> Prioritization["Feature Prioritization"]
--> Validation["Artifact Validation"]
Validation -->|Pass| Storage["Artifact Storage to ConnectSoft Artifact Storage / MCP Servers / Azure DevOps/Git, blobs"]
Validation -->|Fail| Correction["Auto-Correction and Retry"]
Correction -->|Retry| Validation
Storage --> EventEmission["Event Emission"]
EventEmission --> Observability["Telemetry Emission (Logs, Traces, Metrics)"]
Hold "Alt" / "Option" to enable pan & zoom
🧠 Detailed Steps Inside Each Phase¶
📥 1. Task Assignment¶
- Listen for
VisionDocumentCreatedevents. - Extract artifact URIs, trace IDs, project IDs, version info.
📚 2. Information Intake¶
- Download Vision Document (Markdown/JSON).
- Fetch any domain-specific rules if domain constraints are tagged.
- Query semantic memory for similar product plans.
🧠 3. Vision Decomposition¶
- Parse problem statement, opportunity framing, personas, success metrics.
- Map early feature candidates.
🏗️ 4. Product Structuring¶
- Build Product Plan document.
- Create Feature Catalog Artifact.
- Define MVP.
- Map Editions boundaries.
- Plan Roadmap phases.
🔢 5. Prioritization¶
- Score all features (RICE, MoSCoW).
- Attach priority metadata to the backlog.
✅ 6. Validation¶
- Validate:
- Traceability (trace ID, project linkage).
- Structure compliance (required sections exist).
- Semantic consistency (e.g., every feature linked to persona or goal).
🔁 7. Correction¶
- Retry generation for missing or incomplete sections.
- Log auto-correction attempts.
💾 8. Artifact Storage¶
- Upload artifacts to ConnectSoft Artifact Storage, Azure DevOps/Git, blobs, MCP-connected cloud storage (Azure Blob, MinIO, etc.).
📣 9. Event Emission¶
- Emit:
ProductPlanCreatedMVPDefinedFeatureBacklogReadyEditionsDefined
- Each event includes full context and artifact references.
📈 10. Observability Recording¶
- Emit:
- Structured logs
- Distributed traces (OpenTelemetry spans)
- Metrics (artifact generation time, validation retries, event emission success)
🧩 ConnectSoft Platform Principles Alignment¶
| Principle | Process Step Mapping |
|---|---|
| Event-Driven Activation | Task triggered via EventBus. |
| Cloud-Native Artifact Storage | Artifacts stored in scalable cloud-native systems. |
| Resilience and Recoverability | Built-in retries and auto-correction loops. |
| Observability First | OpenTelemetry traces, structured logs, metrics emitted for every execution. |
| Modular Autonomy | Each artifact and event is a modular, consumable unit for downstream agents. |
🛠️ Technologies¶
The Product Manager Agent leverages a cloud-native, AI-augmented, and event-driven technology stack,
aligned with ConnectSoft platform-wide standards for scalability, observability, resilience, and modularity.
Its architecture integrates Semantic Kernel orchestration, OpenAI models, ConnectSoft internal and MCP-based artifact management, and distributed eventing systems to operate autonomously inside the ConnectSoft AI Software Factory.
🧩 Core Technology Stack¶
| Technology | Purpose | Example Usage |
|---|---|---|
| Semantic Kernel (.NET) | AI skill orchestration, planner execution, function composition. | Dynamically invokes planning, prioritization, decomposition skills. |
| OpenAI Models (Azure OpenAI) | LLMs for natural language understanding, structured reasoning, drafting product plans. | GPT-4-Turbo models for feature catalog drafting, MVP identification. |
| Azure Blob Storage | Artifact storage for Product Plans, Feature Catalogs, Roadmaps, MVP definitions. | Saves markdown and JSON artifacts per project trace ID. |
| Azure blobs/Azure DevOps, MCP Servers (Azure MCP, MinIO MCP, PostgreSQL MCP) | Standardized artifact addressing, semantic memory retrieval, structured metadata handling. | Access prior successful plans and templates from PostgreSQL MCP server/Azure blobs/Azure DevOps etc. |
| Azure Event Grid (or Kafka) | Event-driven activation and downstream agent triggering. | Publishes ProductPlanCreated, FeatureBacklogReady events. |
| ConnectSoft Observability Stack (OpenTelemetry + Serilog) | Full tracing, metrics collection, structured JSON logging for every execution. | Emits execution spans, validation retries, artifact upload telemetry. |
| Azure Cognitive Search (optional) | Semantic search over previous Product Plans and industry patterns. | Retrieves best practices when structuring new product features. |
| Redis (optional) | Short-lived context caching for fast access during multi-phase executions. | Caches semantic search results across multiple skill invocations. |
📂 Technology Diagram: Agent Component Stack¶
flowchart TD
SemanticKernel -->|Skill Orchestration| OpenAIModels
SemanticKernel -->|Artifact Management| AzureBlobStorage
SemanticKernel -->|Memory Search| StorageServers
SemanticKernel -->|Task Trigger| EventGrid
SemanticKernel -->|Telemetry Emission| OpenTelemetry
SemanticKernel -->|Local Context Cache| Redis
OpenAIModels -->|LLM Responses| SemanticKernel
StorageServers -->|Artifact Metadata| SemanticKernel
Hold "Alt" / "Option" to enable pan & zoom
✅ Every integration is cloud-native, scalable, secure, and aligned with Clean Architecture principles.
📜 Example: Storage Architecture¶
| Storage Need | Technology | Details |
|---|---|---|
| Artifact Storage (Markdown, JSON) | Azure Blob Storage | Versioned by trace ID, artifact type, and timestamps. |
| Artifact Metadata | PostgreSQL MCP Server/Blobs/Azure DevOps | Semantic memory of artifact versions and project lineage. |
| Semantic Search of Past Plans | Azure Cognitive Search (optional) | Embeds prior plans for similarity search in long-term memory. |
📣 Example: Event Emission Stack¶
| Emitted Event | Routed Through | Consumed By |
|---|---|---|
ProductPlanCreated |
Azure Event Grid | Product Owner Agent, Enterprise Architect Agent |
FeatureBacklogReady |
Azure Event Grid | UX Designer Agent |
EditionsDefined |
Azure Event Grid | Platform Integrator Agent |
Each event includes trace IDs, artifact URIs, plan version, and semantic tags.
🧩 Platform Principles Alignment¶
| Principle | Technology Mapping |
|---|---|
| Cloud-Native | Azure Blob Storage, Redis, Azure Event Grid. |
| Event-Driven Architecture | Event Grid, Kafka topics. |
| Clean Architecture Separation | Semantic Kernel for domain orchestration vs. external infra. |
| Observability First | OpenTelemetry traces, Serilog structured logging. |
| Semantic Extensibility | MCP Servers + Semantic Search augmentations. |
📝 System Prompt (Initialization Instruction)¶
At runtime, when the Product Manager Agent is bootstrapped by the ConnectSoft AI Software Factory,
it loads a structured system prompt that sets its role, expectations, behavioral guardrails, and output requirements.
This system prompt is critical — it ensures the agent operates predictably, following ConnectSoft's standards of:
- Modular decomposition
- Traceable artifact production
- Event-driven collaboration
- Business alignment
- SaaS and cloud-native practices
📋 Full System Prompt Text¶
🧠 You are a Product Manager Agent inside the ConnectSoft AI Software Factory.
Your mission is to transform a structured Vision Document into a fully actionable, structured Product Plan aligned with ConnectSoft platform principles.
You must decompose the vision into:
- A full Feature Catalog, mapped to personas and strategic goals.
- A clearly defined MVP (Minimum Viable Product) feature set.
- An Editions Plan for Free, Pro, Enterprise tiers (if applicable).
- A Product Roadmap broken into logical phases.
📋 Rules and Expectations:
- Embed traceability metadata (trace_id, vision_reference, version) into every artifact.
- Prioritize features using RICE or MoSCoW models.
- Align features with business KPIs and personas defined in the Vision Document.
- Structure outputs in both Markdown and JSON formats for downstream agents.
- Validate your own outputs for structural completeness before emitting events.
- Operate cloud-native, multi-tenant SaaS by default unless otherwise specified.
- Emit events (
ProductPlanCreated,MVPDefined,FeatureBacklogReady,EditionsDefined) when artifacts are ready.🚀 Style and Quality:
- Outputs must be modular, consumable, and AI-ready.
- Follow ConnectSoft observability-first, event-driven, cloud-native architecture.
🧩 Semantic Principles:
- Preserve and extend original business vision integrity.
- Anticipate downstream agent needs (Product Owner Agent, UX Designer Agent, Solution Architect Agent).
🧠 Purpose of System Prompt¶
| Objective | Why It's Important |
|---|---|
| Set Role and Responsibility | Guarantees the agent understands it must build a Product Plan, not code or design directly. |
| Enforce ConnectSoft Standards | Embeds Clean Architecture, Event-Driven, Cloud-Native, SaaS-first assumptions. |
| Require Structured Outputs | Ensures artifacts are modular, machine-readable (Markdown + JSON), traceable. |
| Embed Observability and Validation | Makes validation, traceability, and event emission first-class responsibilities. |
| Align Outputs to Business Goals | Guarantees feature planning is business-driven, not random. |
| Prepare for Multi-Agent Collaboration | Creates predictable, structured artifacts for the next agents (Product Owner, Architect, UX). |
📋 Example: Embedded Behavioral Instructions (Quick View)¶
| Rule | Embedded In Prompt? | Example |
|---|---|---|
| Always output traceability metadata | ✅ | "trace_id": "vision-2025-04-27-001" |
| MVP must be minimal and goal-aligned | ✅ | Only 5–8 core features in MVP definition |
| Editions must reflect SaaS multi-tier models | ✅ | Free = Basic access; Enterprise = Advanced analytics, integrations |
| Modular and structured output | ✅ | Separate sections for each artifact, both Markdown and JSON |
| Emit correct system events | ✅ | ProductPlanCreated, MVPDefined after validation |
📥 Input Prompt Template¶
When the Product Manager Agent is assigned a task (triggered by VisionDocumentCreated event),
it formulates an internal structured prompt that transforms the incoming information (Vision Document, metadata, context)
into a clear, focused instruction for the Semantic Kernel and LLM skills.
This input prompt template ensures that:
- The agent understands all context.
- Outputs are modular, structured, and business-aligned.
- It can reason consistently and reproducibly across thousands of executions.
📋 Standard Input Prompt Template¶
## Input Information
Vision Document Summary:
{vision_summary}
Strategic Objectives:
{strategic_objectives_list}
Personas Identified:
{persona_list}
Initial Feature Suggestions:
{initial_feature_list}
Domain/Industry:
{domain_context}
Urgency or Constraints:
{execution_constraints}
Traceability Metadata:
- Project ID: {project_id}
- Vision Trace ID: {vision_trace_id}
- Vision Version: {vision_version}
---
## Task for Product Manager Agent
Using the above context:
1. Decompose the vision into a **complete Feature Catalog**, with mappings:
- Feature Name
- Target Personas
- Linked Strategic Objectives
2. Define the **Minimum Viable Product (MVP)** — the minimal feature set required to validate core business hypotheses.
3. Create an **Editions Plan**:
- Free Edition
- Pro Edition
- Enterprise Edition
(Optional: Custom Editions if domain requires.)
4. Draft a **Product Roadmap**:
- MVP Phase (short-term)
- Phase 2 Expansion
- Phase 3 Optimization
5. Prioritize features using **RICE** or **MoSCoW** methods.
6. Embed **traceability metadata** in all outputs.
7. Validate structural completeness before finalizing.
8. Output in:
- Markdown format (primary artifact)
- Compact JSON structure (secondary artifact)
---
## Style Guide
- Clear modular sections.
- Business and persona alignment is mandatory.
- Output should be autonomous and directly consumable by downstream agents.
- Follow ConnectSoft product planning standards.
🧠 Example Parameterized Values at Runtime¶
| Placeholder | Example |
|---|---|
{vision_summary} |
"A SaaS platform for healthcare appointment management." |
{strategic_objectives_list} |
"Reduce missed appointments by 25%; Improve patient engagement." |
{persona_list} |
"Doctor, Administrative Staff, Patient." |
{initial_feature_list} |
"Appointment Scheduling, Patient Profile Management, Billing Integration." |
{domain_context} |
"Healthcare / HIPAA Compliance." |
{execution_constraints} |
"MVP launch required within 4 months." |
{project_id} |
"healthcare-saas-2025" |
{vision_trace_id} |
"vision-2025-04-27-001" |
{vision_version} |
"1.0" |
🏗️ Visual Diagram: Input Prompt Building Blocks¶
flowchart TD
VisionDocument -->|Parse Vision Summary| InputPrompt
Metadata -->|Attach Traceability| InputPrompt
StrategicGoals -->|Instruct on Business Alignment| InputPrompt
Personas -->|Persona Mapping| InputPrompt
Constraints -->|Execution Constraints| InputPrompt
Hold "Alt" / "Option" to enable pan & zoom
🧩 Alignment to ConnectSoft Platform Principles¶
| Principle | Input Prompt Impact |
|---|---|
| Event-Driven Context Injection | Inputs are populated from event payloads. |
| Modularity | Prompts request discrete modular outputs (Catalog, MVP, Editions, Roadmap). |
| Business-Driven Reasoning | Business goals and personas guide all decomposition. |
| Traceability | Every artifact output links back to the Vision Document via metadata. |
| Cloud-Native SaaS Orientation | Editions mapping assumes multi-tenant SaaS models. |
📤 Output Expectations¶
The Product Manager Agent must produce outputs that are:
- Structured,
- Traceable,
- Validated,
- Modular,
- Cloud-Native SaaS Ready,
- AI-Ready (easy to consume by downstream agents).
Each artifact must comply with strict format, structure, and metadata standards to guarantee observability, reusability, and composability across the ConnectSoft AI Software Factory.
📋 Primary Output Artifacts and Their Expectations¶
| Artifact | Format | Key Sections and Validation Rules |
|---|---|---|
| Product Plan Document | Markdown + JSON | Vision summary, MVP scope, full feature catalog, editions mapping, roadmap. |
| Feature Catalog | Table (Markdown) + JSON Array | Each feature must include name, persona(s), strategic goal(s), priority score. |
| MVP Feature List | JSON Object + Markdown List | 5–10 minimal features, each traced to personas and goals. |
| Editions Mapping | JSON Object + Markdown Table | Free/Pro/Enterprise mapping of features, must have edition-specific notes. |
| Product Roadmap | Markdown Timeline + JSON | Phased delivery plan: MVP, Phase 2 Expansion, Phase 3 Optimization. |
| Event Emissions | JSON | Must include artifact URIs, trace IDs, timestamps, versions. |
🏗️ Example: Product Plan Markdown Skeleton¶
# 📋 Product Plan: Healthcare SaaS Appointment Management
## 🧠 Vision Summary
Trace ID: vision-2025-04-27-001
Domain: Healthcare SaaS
Strategic Objectives:
- Reduce appointment no-shows by 25%
- Improve patient engagement rates
## 🎯 MVP Scope
- Patient Registration
- Appointment Scheduling
- Notifications System
## 🧩 Feature Catalog
| Feature | Target Persona | Priority | Strategic Goal |
|:--------|:----------------|:---------|:---------------|
| Appointment Scheduling | Doctor, Patient | High | Engagement Increase |
| Notifications | Patient | High | Reduce No-Shows |
| Billing Management | Admin | Medium | Revenue Tracking |
## 🗂️ Editions Mapping
| Edition | Features Included |
|:--------|:-------------------|
| Free | Appointment Scheduling, Basic Notifications |
| Pro | Advanced Notifications, Billing Integration |
| Enterprise | Multi-Clinic Management, Analytics |
## 🗺️ Roadmap
- **Q2 2026** - MVP Launch
- **Q3 2026** - Billing and Advanced Notifications
- **Q4 2026** - Enterprise Analytics and Integrations
✅ Artifacts must include traceability metadata embedded in headings and content.
📦 Example: JSON Structure Expectations¶
{
"trace_id": "vision-2025-04-27-001",
"product_plan_version": "1.0",
"vision_summary": "SaaS for healthcare appointment management",
"strategic_objectives": ["Reduce no-shows by 25%", "Improve patient engagement"],
"feature_catalog": [
{
"feature_name": "Appointment Scheduling",
"personas": ["Doctor", "Patient"],
"priority_score": 9,
"strategic_goals": ["Engagement Increase"]
}
],
"mvp_features": ["Appointment Scheduling", "Patient Registration", "Notifications"],
"editions_mapping": {
"Free": ["Appointment Scheduling", "Basic Notifications"],
"Pro": ["Advanced Notifications", "Billing Integration"],
"Enterprise": ["Multi-Clinic Management", "Analytics"]
},
"roadmap": {
"MVP": "Q2 2026",
"Phase 2": "Q3 2026",
"Phase 3": "Q4 2026"
}
}
✅ JSON must be machine-readable, versioned, and include all mandatory fields.
📣 Event Emissions Expectations¶
Each event (ProductPlanCreated, MVPDefined, FeatureBacklogReady, EditionsDefined) must:
| Field | Description |
|---|---|
event_type |
e.g., ProductPlanCreated |
trace_id |
Same as originating Vision Document |
artifact_uri |
Blob Storage URI or MCP artifact reference |
version |
Plan version (e.g., 1.0) |
timestamp |
UTC ISO8601 timestamp |
additional_context |
Optional fields like personas, domain tags, urgency |
Example Event Payload:
{
"event_type": "ProductPlanCreated",
"trace_id": "vision-2025-04-27-001",
"artifact_uri": "https://connectsoft.blob.core.windows.net/products/product-plan-2025-04-27-001.md",
"version": "1.0",
"timestamp": "2025-04-27T22:00:00Z"
}
🧩 Validation Checklist Before Finalizing Outputs¶
| Check | Must Pass |
|---|---|
| Artifact contains full traceability (trace_id, vision_reference) | ✅ |
| All required sections exist (Vision Summary, MVP, Feature Catalog, Editions, Roadmap) | ✅ |
| Feature Catalog contains persona mappings and goal mappings | ✅ |
| MVP Feature Set contains minimum viable subset | ✅ |
| Editions Mapping aligns with SaaS multi-tenant best practices | ✅ |
| Roadmap is phased and incremental | ✅ |
| Artifacts are both Markdown and JSON formatted | ✅ |
| Corresponding events emitted successfully | ✅ |
| All outputs observable and linkable via telemetry traces | ✅ |
📜 Platform Principles Reinforced by Output Expectations¶
| Principle | How It's Reinforced |
|---|---|
| Traceability | Every artifact linked back to originating vision. |
| Modularity | Discrete, composable artifacts for downstream agents. |
| Observability | Structured events, logs, and OpenTelemetry traces on each emission. |
| Cloud-Native Ready | Artifacts addressable via cloud storage and MCP servers. |
| Business Goal Alignment | Features, MVPs, roadmaps are business-driven, not tech-driven. |
🧠 Memory Strategy¶
The Product Manager Agent leverages both short-term and long-term memory systems to:
- Maintain context across a task lifecycle
- Retrieve relevant historical knowledge and best practices
- Improve consistency, reusability, and quality of output artifacts
Memory is a first-class design feature —
ensuring the agent reasons effectively even in multi-step, multi-agent, multi-version factory pipelines.
📋 Memory Types and Purposes¶
| Memory Type | Purpose | Storage |
|---|---|---|
| Short-Term Memory (Context Window) | Hold the active Vision Document, traceability metadata, decomposed goals, initial features during task execution. | In-process memory (Semantic Kernel session context) |
| Long-Term Memory (Semantic Memory) | Retrieve similar past Product Plans, Feature Catalogs, Editions Definitions, and best practices for cross-referencing and enrichment. | MCP Servers (PostgreSQL MCP, MinIO MCP, Azure Blob) |
| Artifact Memory | Access and manage the specific artifacts the agent generates for traceability and handoff. | Azure Blob Storage + Artifact URIs embedded into events |
| Event Lineage Memory | Recall emitted events, project execution lineage for full lifecycle tracking. | Event Bus + Artifact metadata linkage |
🧩 Short-Term Memory (Context Window)¶
| Aspect | Details |
|---|---|
| Storage Mode | In-memory per Semantic Kernel execution session |
| Content | Vision summary, strategic objectives, personas, feature list, project metadata |
| Capacity | Single project execution scope (usually one vision decomposition task at a time) |
| Expiry | Cleared after successful artifact storage and event emissions |
✅ Enables the agent to reason effectively without overloading LLM token limits.
📂 Long-Term Memory (Semantic Vector Database)¶
| Aspect | Details |
|---|---|
| Storage | MCP Servers — PostgreSQL MCP Server or Azure Cognitive Search |
| Content | Embeddings of past Product Plans, MVPs, Editions Models, SaaS Blueprints, Roadmaps |
| Retrieval Mechanism | Similarity search during the Information Intake phase |
| Access Frequency | Optional: triggered if the agent detects low confidence in decomposition or missing domain-specific patterns. |
| Update Policy | After every successfully validated Product Plan, embeddings are created and stored back into semantic memory for future retrieval. |
✅ Supports learning across projects — enables self-optimizing agentic behaviors.
📜 Example Memory Usage Flow¶
flowchart TD
VisionDocumentIntake --> MemoryCheck{"Is this domain or pattern known?"}
MemoryCheck -- No --> SemanticSearch["Query Semantic Memory MCP"]
SemanticSearch --> BestPracticeRetrieval["Retrieve similar Product Plan structures"]
BestPracticeRetrieval --> PlanningProcess
MemoryCheck -- Yes --> PlanningProcess
Hold "Alt" / "Option" to enable pan & zoom
✅ Dynamically enriches outputs with historical best practices when needed.
🧠 Artifact and Event Lineage Memory¶
| Storage | Purpose |
|---|---|
| Azure Blob Storage | Store finalized Markdown and JSON artifacts; provide versioned, traceable URIs. |
| Event Bus (Event Grid, Kafka) | Maintain event lineage across the factory: VisionDocumentCreated → ProductPlanCreated → MVPDefined → FeatureBacklogReady |
✅ Guarantees every piece of the production line is traceable, auditable, and recoverable.
🧩 ConnectSoft Platform Alignment¶
| Principle | Memory Implementation |
|---|---|
| Semantic Continuity | Retrieval and learning from prior artifacts. |
| Observability and Traceability | Trace IDs, project lineage embedded in events and artifacts. |
| Cloud-Native Storage | Blob Storage and MCP Servers guarantee distributed, scalable memory. |
| Resilience and Recoverability | Ability to retry planning based on memory searches if initial output is incomplete. |
✅ Validation Strategy¶
Before finalizing outputs and emitting any event,
the Product Manager Agent must perform internal validation to ensure artifacts are:
- Structurally complete
- Semantically aligned with the Vision Document
- Cloud-native SaaS compliant
- Traceable and observable
- Ready for autonomous downstream consumption
Validation is mandatory —
no artifact is allowed to proceed without successful internal validation.
📋 Validation Types and Their Purpose¶
| Validation Type | Purpose |
|---|---|
| Structural Validation | Ensure all required sections (Vision Summary, MVP, Feature Catalog, Editions Mapping, Roadmap) exist and are non-empty. |
| Semantic Validation | Ensure every feature is mapped to at least one persona and linked to a business goal. |
| Traceability Validation | Ensure all artifacts embed trace_id, project_id, version fields. |
| Prioritization Validation | Ensure feature prioritization scores (RICE or MoSCoW) exist and are logical. |
| Edition Strategy Validation | Ensure Editions Mapping is aligned with SaaS multitenancy principles (Free/Pro/Enterprise tiers). |
| Event Completeness Validation | Ensure that after each artifact storage, corresponding system events are properly emitted and populated. |
| Observability Validation | Ensure all critical steps (artifact creation, validation success/failure, event emission) emit OpenTelemetry traces. |
🏗️ Validation Flow Diagram¶
flowchart TD
DraftArtifacts --> StructuralValidation
StructuralValidation -->|Pass| SemanticValidation
SemanticValidation -->|Pass| TraceabilityValidation
TraceabilityValidation -->|Pass| PrioritizationValidation
PrioritizationValidation -->|Pass| EditionStrategyValidation
EditionStrategyValidation -->|Pass| EventEmissionValidation
EventEmissionValidation -->|Pass| MarkArtifactsAsValid
EventEmissionValidation -->|Fail| CorrectionAttempt
AnyFail --> CorrectionAttempt
CorrectionAttempt -->|Retry| FullValidationAgain
Hold "Alt" / "Option" to enable pan & zoom
✅ Artifacts must pass all validations sequentially before considered complete.
📄 Example: Structural Validation Rules¶
| Section | Must Exist? | Min Length |
|---|---|---|
| Vision Summary | ✅ | 100 characters |
| MVP Features | ✅ | 5–10 features |
| Feature Catalog | ✅ | At least 10 entries |
| Editions Mapping | ✅ | Free, Pro, Enterprise tiers defined |
| Product Roadmap | ✅ | 3 Phases: MVP, Expansion, Optimization |
📄 Example: Semantic Validation Rules¶
| Item | Rule |
|---|---|
| Feature Persona Mapping | Every feature must have at least one linked persona. |
| Feature Strategic Alignment | Every feature must contribute to at least one business goal. |
| MVP Integrity | MVP features must map to core goals — cannot include low-priority features. |
📦 Example: Traceability Metadata Validation¶
| Field | Validation Rule |
|---|---|
| trace_id | Must match assigned vision_trace_id. |
| project_id | Must match originating project_id. |
| artifact_version | Must be initialized to 1.0, incremented if retried. |
📣 Example: Event Completeness Validation¶
Each emitted event (ProductPlanCreated, MVPDefined, FeatureBacklogReady, EditionsDefined) must:
- Reference the correct artifact URI.
- Include matching trace_id.
- Include artifact version.
- Have timestamp in UTC ISO 8601 format.
✅ Otherwise, a correction attempt is triggered before event emission.
🧩 ConnectSoft Platform Alignment¶
| Principle | Validation Enforcement |
|---|---|
| Observability First | Validation steps emit traces, metrics. |
| Recoverability | Correction and retry flow on validation failure. |
| Cloud-Native SaaS Standards | Editions Validation guarantees SaaS-tier compliance. |
| Traceability | Artifact linkage guaranteed at every phase. |
| Resilient Autonomous Execution | Agent self-validates before affecting downstream flows. |
🔁 Retry and Correction Flow¶
If the Product Manager Agent detects invalid, incomplete, or inconsistent artifacts during the Validation Phase,
it triggers an autonomous Retry and Correction Mechanism to:
- Self-correct minor or recoverable issues
- Revalidate corrected artifacts
- Escalate to human intervention only when absolutely necessary
This mechanism ensures the ConnectSoft AI Software Factory remains:
- Resilient
- Self-healing
- Minimally disruptive
- Highly reliable across autonomous multi-agent workflows
📋 Correction Strategy Overview¶
| Error Type | Correction Attempt | Retry Behavior |
|---|---|---|
| Missing Section | Auto-generate missing section based on context memory. | Immediate retry of validation. |
| Incomplete MVP Features | Re-scan Feature Catalog, select critical features again. | Retry validation after update. |
| Incorrect Traceability Metadata | Regenerate correct trace_id, project_id, artifact_version from memory context. | Retry event preparation and emission. |
| Prioritization Missing | Re-apply RICE or MoSCoW models to the feature list automatically. | Retry feature prioritization validation. |
| Invalid Editions Mapping | Re-map features according to SaaS standard templates (Free, Pro, Enterprise). | Retry Editions Mapping validation. |
| Event Emission Failure | Retry event construction and submission up to 3 times with exponential backoff. | If failure persists, trigger human escalation. |
🏗️ Retry Flow Diagram¶
flowchart TD
ValidationFailure --> AutoCorrectionAttempt
AutoCorrectionAttempt --> CorrectionSuccess
CorrectionSuccess --> RetryValidation
RetryValidation -->|Pass| EventEmission
RetryValidation -->|Fail| HumanIntervention
Hold "Alt" / "Option" to enable pan & zoom
✅ Minor errors are fixed without human involvement.
❗ Persistent critical errors escalate to human operators.
🧠 Correction Attempt Techniques¶
| Technique | Description |
|---|---|
| Context Rehydration | Rebuild prompt context by re-fetching Vision Document and metadata if inconsistencies detected. |
| Fallback Templates | Use pre-approved ConnectSoft standard templates for missing structures. |
| Semantic Retry | Re-ask internal Semantic Kernel skills to regenerate missing sections intelligently. |
| Memory Hints | Leverage semantic memory snapshots from similar past projects to auto-fill missing components. |
| Event Emission Retries | Use exponential backoff strategy for event retries (e.g., retry after 5s, 15s, 45s). |
📜 Human Intervention Trigger Rules¶
| Situation | Immediate Escalation? |
|---|---|
| Retry failure after 2 full correction cycles | ✅ |
| Critical failure in semantic decomposition (e.g., missing MVP logic after corrections) | ✅ |
| Artifact storage failure despite retries | ✅ |
| EventBus unavailable after 3 retries | ✅ |
| Severe semantic inconsistency detected (e.g., features contradict business goals) | ✅ |
📣 Example: Correction and Retry Metrics Tracked¶
| Metric Name | Purpose |
|---|---|
product_manager_agent_validation_failures_total |
Total validation failures detected. |
product_manager_agent_corrections_attempted_total |
Total auto-corrections initiated. |
product_manager_agent_successful_retries_total |
Successful corrections without human intervention. |
product_manager_agent_escalations_total |
Number of human escalations triggered. |
✅ All retries and correction attempts are observable through OpenTelemetry traces and Prometheus metrics.
🧩 ConnectSoft Platform Principles Alignment¶
| Principle | Retry and Correction Mapping |
|---|---|
| Resilience First | Built-in retries and fallback corrections. |
| Autonomous Recovery | Minimal human involvement unless critical. |
| Observability | Tracing and metrics for all retries and corrections. |
| Semantic Continuity | Memory-driven intelligent self-healing. |
| Governed Escalation | Only escalate after structured, tracked recovery attempts fail. |
🛠️ Skills Overview¶
The Product Manager Agent is equipped with a set of modular, dynamic Skills
implemented as Semantic Kernel Functions.
Each Skill performs a focused, specialized operation inside the Product Planning lifecycle:
allowing the agent to compose, validate, correct, and emit product artifacts in a resilient, observable, and autonomous way.
📋 Full Skills Catalog¶
| Skill Name | Description | Example Internal Prompt |
|---|---|---|
| Vision Decomposer | Breaks down Vision Document into clear domains, modules, and initial features. | "Analyze the provided vision summary and list functional areas and high-level features." |
| Feature Catalog Creator | Creates a full structured catalog of features, linking them to personas and strategic goals. | "Generate a feature table, each feature linked to personas and goals." |
| MVP Selector | Selects a minimal viable set of features that deliver core value and business goals. | "From the feature catalog, select the 5–8 features needed to achieve MVP success." |
| Editions Mapper | Proposes how features should be distributed into Free, Pro, and Enterprise editions. | "Map features to appropriate SaaS editions following standard patterns." |
| Product Roadmap Planner | Creates a phased timeline plan for MVP → Phase 2 → Phase 3 releases. | "Generate a 3-phase product roadmap aligned with strategic objectives." |
| Prioritization Scorer | Scores features using RICE or MoSCoW prioritization models. | "Apply RICE scoring to the feature catalog." |
| Validation Checker | Inspects artifact structures to ensure completeness, consistency, and SaaS compliance. | "Validate that the feature catalog covers personas, goals, and has traceability." |
| Correction Synthesizer | Automatically repairs missing or incorrect artifact sections. | "Detect missing sections and regenerate based on initial vision and context." |
| Event Preparer | Packages finalized artifacts into structured event payloads for emission. | "Prepare a ProductPlanCreated event with artifact URI, version, trace ID." |
| Semantic Memory Retriever | Searches semantic memory (MCP servers) for similar past projects to inform planning. | "Retrieve 3 closest previous product plans related to healthcare SaaS." |
| Trace Metadata Enricher | Ensures every output includes full traceability info. | "Embed project ID, trace ID, vision version into all outputs." |
🧠 Skill Categories¶
| Category | Skills |
|---|---|
| Decomposition and Planning | Vision Decomposer, Feature Catalog Creator, MVP Selector, Editions Mapper, Roadmap Planner |
| Prioritization and Optimization | Prioritization Scorer |
| Validation and Correction | Validation Checker, Correction Synthesizer |
| Memory and Enrichment | Semantic Memory Retriever, Trace Metadata Enricher |
| Emission and Collaboration | Event Preparer |
✅ Skills are modular — individually evolvable without impacting the entire agent.
🏗️ Skills Orchestration Diagram¶
flowchart TD
Intake["Information Intake"]
--> DecompositionSkills["Vision Decomposer -> Feature Catalog Creator -> MVP Selector"]
--> PlanningSkills["Editions Mapper -> Roadmap Planner"]
--> PrioritizationSkills["Prioritization Scorer"]
--> ValidationSkills["Validation Checker"]
--> CorrectionSkills["Correction Synthesizer"]
--> MemoryEnrichment["Semantic Memory Retriever"]
--> EmissionSkills["Event Preparer -> Trace Metadata Enricher"]
Hold "Alt" / "Option" to enable pan & zoom
✅ Skills are dynamically composed during execution depending on context, task complexity, and prior validation results.
📚 Example: Vision Decomposer Internal Skill Prompt¶
"You are tasked with decomposing the following Vision Document:
- Identify key business domains (e.g., Scheduling, Billing, Notifications).
- List high-level features proposed in the vision.
- Return the results in Markdown and JSON formats.Context:
- Industry: Healthcare SaaS
- Goal: Reduce appointment no-shows by 25%."
🧩 ConnectSoft Platform Alignment¶
| Principle | Skills Impact |
|---|---|
| Clean Modularity | Every skill is independently maintainable and extendable. |
| Event-Driven Collaboration | Skills prepare artifacts for clean downstream handoffs. |
| Resilience and Recovery | Correction Skills handle retry flows automatically. |
| Traceability | Metadata Enricher Skill guarantees full auditability. |
| Continuous Improvement | Skills evolve over time without disrupting the platform. |
🔗 Collaboration Interfaces¶
The Product Manager Agent collaborates within the ConnectSoft AI Software Factory through:
- Event-Driven Communication (primary mode)
- Artifact Sharing via MCP-backed storage
- Indirect Memory Hand-offs (semantic references to previous artifacts)
This guarantees modularity, loose coupling, and high resilience —
even across large, parallel, multi-agent execution trees.
📋 Collaboration Methods¶
| Interface Type | Purpose | Downstream Consumer |
|---|---|---|
| Event Emission | Notify other agents that artifacts are ready. | Product Owner Agent, Enterprise Architect Agent, UX Designer Agent |
| Artifact Storage | Save structured Markdown/JSON artifacts accessible via MCP URIs. | Artifact Service, other agents' Information Intake |
| Event Bus Subscription | Publish events (ProductPlanCreated, MVPDefined, FeatureBacklogReady, EditionsDefined). | Event Grid / Kafka Topics |
| Traceability Injection | Embed trace IDs and project IDs into artifacts for lifecycle correlation. | Observability Tools, Control Plane Governance |
| Semantic Memory Update | After finalization, update vectorized semantic memory with new project knowledge. | Internal memory augmentation for future planning agents |
🏗️ Event Emission Diagram¶
flowchart TD
ProductManagerAgent -->|ProductPlanCreated| ProductOwnerAgent
ProductManagerAgent -->|FeatureBacklogReady| UXDesignerAgent
ProductManagerAgent -->|MVPDefined| EnterpriseArchitectAgent
ProductManagerAgent -->|EditionsDefined| PlatformIntegratorAgent
Hold "Alt" / "Option" to enable pan & zoom
✅ No direct synchronous calls —
✅ All communication is event-driven and observable.
📈 Observability Hooks¶
The Product Manager Agent is deeply observable —
it emits logs, traces, and metrics at every critical execution step.
| Observability Layer | Details | Example |
|---|---|---|
| Logs | Structured JSON logs via Serilog, enriched with trace_id, project_id, skill_name. | "Creating MVP Feature Set | TraceId: vision-2025-04-27-001" |
| Traces | OpenTelemetry Spans for each skill execution, validation, correction, and event emission. | Trace spans grouped under ProductPlanningFlow. |
| Metrics | Prometheus counters, histograms, gauges. | product_manager_agent_validation_failures_total, product_manager_agent_event_emissions_total |
📦 Example Metrics Exposed¶
| Metric Name | Purpose |
|---|---|
product_manager_agent_tasks_started_total |
Number of tasks assigned and accepted. |
product_manager_agent_artifacts_validated_total |
Number of artifacts passing internal validation. |
product_manager_agent_validation_failures_total |
Number of artifacts requiring correction. |
product_manager_agent_event_emissions_total |
Number of successful events emitted. |
product_manager_agent_human_escalations_total |
Number of tasks requiring manual intervention. |
✅ Metrics are exposed on /metrics Prometheus scrape endpoints.
🧠 Observability Flows Example¶
flowchart TD
SkillExecution -->|Trace Emission| OpenTelemetryCollector
ArtifactStorage -->|Structured Log| SerilogSink
EventEmission -->|Metrics Update| PrometheusGateway
Hold "Alt" / "Option" to enable pan & zoom
✅ Every Skill, Validation Attempt, Correction, Event Emission, and Memory Access is observable.
🧩 ConnectSoft Platform Alignment¶
| Principle | Collaboration & Observability Mapping |
|---|---|
| Loose Coupling | Event-driven handoff — no tight binding between agents. |
| Observability-First Design | Logs, traces, metrics integrated natively. |
| Cloud-Native Scalability | Event-driven communication and Prometheus metrics expose scalability health. |
| Governed Execution | Full traceability across multi-agent workflows. |
| Elastic Multi-Agent Flows | Event emissions trigger parallel agent activations without bottlenecks. |
🛡️ Human Intervention Hooks¶
Although the Product Manager Agent is designed to be fully autonomous,
it supports controlled human intervention in exceptional cases when autonomous correction fails.
This guarantees reliability, governance, and high-quality artifact production without unnecessary blocking.
📋 When Human Intervention is Triggered¶
| Situation | Reason for Escalation | Example |
|---|---|---|
| Persistent Validation Failure | Agent cannot auto-correct artifacts after 2 correction attempts. | MVP definition missing despite retries. |
| Semantic Inconsistency Detected | Major misalignment between features and strategic goals detected. | Features contradict "reduce churn" objective. |
| Storage System Unavailable | Artifact cannot be stored after multiple retries. | Azure Blob Storage or MCP failure. |
| Event Bus Communication Failure | Events cannot be emitted after retry backoffs. | Kafka or Event Grid downtime. |
| Critical Missing Inputs | Vision Document lacks critical data and cannot proceed. | No personas defined for feature mapping. |
🛠️ Human Escalation Workflow¶
flowchart TD
ValidationFailure --> AutoCorrection
AutoCorrection -->|Fails| EscalationTrigger
EscalationTrigger --> HumanNotification
HumanNotification --> OperatorIntervention
OperatorIntervention -->|Resolve Issue| RetryExecution
Hold "Alt" / "Option" to enable pan & zoom
✅ All escalations are observable via events, logs, and metrics.
✅ Human intervention logs include cause, attempted corrections, and recommended next steps.
📈 Escalation Metrics Emitted¶
| Metric Name | Purpose |
|---|---|
product_manager_agent_escalations_total |
Total number of human escalations triggered. |
product_manager_agent_failed_retries_total |
Total retries failed before escalation. |
🧩 Human Intervention Points in Platform¶
| Platform Layer | Hook |
|---|---|
| Observability UI (Grafana / Kibana) | Displays agent escalation alerts. |
| Artifact Service | Marks incomplete artifacts for human review. |
| Event Bus | Posts escalation events with task IDs and trace links. |
| Control Plane Governance | Logs escalation reasons for auditability. |
🏗️ Final Flow Diagram: Product Manager Agent Positioning¶
flowchart TD
VisionArchitectAgent -->|VisionDocumentCreated| ProductManagerAgent
ProductManagerAgent -->|ProductPlanCreated| ProductOwnerAgent
ProductManagerAgent -->|FeatureBacklogReady| UXDesignerAgent
ProductManagerAgent -->|MVPDefined| EnterpriseArchitectAgent
ProductManagerAgent -->|EditionsDefined| PlatformIntegratorAgent
Hold "Alt" / "Option" to enable pan & zoom
✅ Ensures modular, traceable, business-driven software creation.
📈 C1: System Context Diagram¶
flowchart TB
VisionArchitect["Vision Architect Agent"]
EventBus["ConnectSoft Event Bus (Event Grid/Kafka)"]
ProductManagerAgent["Product Manager Agent"]
ArtifactStorage["ConnectSoft Artifact Storage (Azure Blob + MCP Servers)"]
ProductOwnerAgent["Product Owner Agent"]
UXDesignerAgent["UX Designer Agent"]
EnterpriseArchitectAgent["Enterprise Architect Agent"]
PlatformIntegratorAgent["Platform Integrator Agent"]
ObservabilityStack["ConnectSoft Observability Stack (OpenTelemetry, Prometheus)"]
VisionArchitect -->|VisionDocumentCreated Event| EventBus
EventBus -->|Task Assignment| ProductManagerAgent
ProductManagerAgent -->|ProductPlanCreated Event| EventBus
ProductManagerAgent -->|MVPDefined Event| EventBus
ProductManagerAgent -->|FeatureBacklogReady Event| EventBus
ProductManagerAgent -->|EditionsDefined Event| EventBus
ProductManagerAgent -->|Store Artifacts| ArtifactStorage
ProductManagerAgent -->|Emit Traces, Logs, Metrics| ObservabilityStack
EventBus --> ProductOwnerAgent
EventBus --> UXDesignerAgent
EventBus --> EnterpriseArchitectAgent
EventBus --> PlatformIntegratorAgent
Hold "Alt" / "Option" to enable pan & zoom
✅ Shows external system interactions
✅ Highlights agent's autonomous operation
🛠️ C2: Container Diagram (Inside the Agent)¶
flowchart TB
APIController["Task Intake Controller (Event Listener)"]
PlannerEngine["Planner Engine (Semantic Kernel Orchestrator)"]
SkillSet["Skills (Vision Decomposer, MVP Selector, etc.)"]
Validator["Validation Engine"]
StorageManager["Artifact Storage Manager"]
EventEmitter["Event Emission Manager"]
MemoryManager["Memory Manager (Short-Term + Semantic Memory MCP Access)"]
ObservabilityAgent["Observability Hooks (Tracing, Metrics, Logs)"]
APIController --> PlannerEngine
PlannerEngine --> SkillSet
PlannerEngine --> MemoryManager
SkillSet --> Validator
Validator --> StorageManager
StorageManager --> EventEmitter
AllSteps -.-> ObservabilityAgent
Hold "Alt" / "Option" to enable pan & zoom
✅ Internal components modular
✅ Orchestration flows clearly visible
✅ Observability hooks everywhere
🧠 C3: Component Diagram (Key Skills and Flows)¶
flowchart TB
VisionDecomposerSkill["Vision Decomposer Skill"]
FeatureCatalogSkill["Feature Catalog Creator Skill"]
MVPSelectorSkill["MVP Selector Skill"]
EditionsMapperSkill["Editions Mapper Skill"]
RoadmapPlannerSkill["Product Roadmap Planner Skill"]
PrioritizationSkill["Prioritization Scorer Skill"]
ValidationSkill["Validation Checker Skill"]
CorrectionSkill["Correction Synthesizer Skill"]
MemoryRetrieverSkill["Semantic Memory Retriever Skill"]
TraceEnricherSkill["Trace Metadata Enricher Skill"]
PlannerEngine --> VisionDecomposerSkill
VisionDecomposerSkill --> FeatureCatalogSkill
FeatureCatalogSkill --> MVPSelectorSkill
MVPSelectorSkill --> EditionsMapperSkill
EditionsMapperSkill --> RoadmapPlannerSkill
RoadmapPlannerSkill --> PrioritizationSkill
PrioritizationSkill --> ValidationSkill
ValidationSkill --> CorrectionSkill
CorrectionSkill --> EventEmitter
MemoryManager --> MemoryRetrieverSkill
AllSkills -.-> TraceEnricherSkill
Hold "Alt" / "Option" to enable pan & zoom
✅ Clear modular skill pipeline
✅ Memory retrieval embedded dynamically