🧠 Pull Request Creator Agent Specification¶

🎯 Agent Purpose¶

The Pull Request Creator Agent is responsible for automating the creation of trace-linked, semantically enriched pull requests in Azure DevOps, immediately after a successful code commit by the Code Committer Agent.

It acts as the bridge between automated code generation and human code review, enabling:

Policy-compliant PR formatting
Blueprint-aware context population
Event-driven collaboration
Release pipeline continuity

This agent ensures that every commit results in a reviewable, auditable, and linkable pull request — connecting architecture, engineering, and DevOps workflows.

🌐 Mission Summary¶

“Transform commit events into complete, traceable pull requests that enable human collaboration, peer review, and automated CI/CD triggers — fully aligned with ConnectSoft traceability and domain-driven principles.”

🧭 Strategic Role in Factory Flow¶

Phase	Role
🏗️ Post-Commit Automation	Converts commits into pull requests immediately
🔍 Blueprint Traceability	Attaches trace ID, scope, use case to PR metadata
🧾 Documentation + QA Input	Provides context for doc generation, test cases, release notes
🔁 Pipeline Triggering	PRs initiate CI pipelines in Azure DevOps
🧑‍🤝‍🧑 Collaboration Entry Point	Enables tech leads, QA, and reviewers to engage in the SDLC

🧠 Key Behaviors Enabled by Purpose¶

Capability	Enabled Outcome
Create PR from feature branch	Ensures GitOps readiness
Include commit summary with trace links	Ensures traceability from PR → blueprint
Notify Tech Lead or Reviewer Agent	Starts collaborative review
Enrich PR with use case, scope, domain, tags	Improves clarity and auditability
Enforce PR naming and formatting policies	Aligns with ConnectSoft standards

🧩 Alignment to ConnectSoft Core Principles¶

Principle	Alignment
Clean Architecture	PRs are scoped to single use case or feature
Traceability	PRs include trace IDs, blueprint refs, event logs
Observability-First	Emits PRCreated events and OTEL spans
Security-First	Uses scoped identity or token to create PRs securely
Automation by Default	100% event-driven — no human initiation required
Cloud-Native	Operates as a stateless, containerized agent in AKS or MCP

🧠 Summary¶

The Pull Request Creator Agent exists to connect autonomous code commits with human validation and CI/CD orchestration, ensuring every change becomes part of a secure, reviewable, and traceable software delivery flow inside the ConnectSoft factory.

📌 Core Responsibilities¶

The Pull Request Creator Agent transforms commit metadata into complete, compliant, and traceable pull requests. Its responsibilities span formatting, validation, context enrichment, and lifecycle automation.

✅ 1. Generate Pull Requests in Azure DevOps¶

Create PRs between the source (feature/hotfix) and target (main/dev) branches.
Include enriched metadata: commit hash, component scope, and trace ID.

✅ 2. Format PR Titles and Descriptions Semantically¶

PR titles must follow this structure:

feat(order): implement CreateOrderHandler [trace:ord-8128]

* PR body should include: * Use Case / Blueprint name * Trace ID and Scope * Commit summary list * Changed files table * Automation status and downstream steps

✅ 3. Attach Metadata for Traceability¶

Inject trace metadata into PR body or description fields:

trace:
  id: trace-ord-8128
  blueprint: usecase-create-order
  component: Order

* Enables QA, documentation agents, and release agents to link changes accurately.

✅ 4. Emit PR Lifecycle Events¶

Emit events such as:
- PullRequestCreated
- PullRequestFailed
- PullRequestReadyForReview
Used by: Tech Lead Agent, Observability Agent, DevOps Orchestrator

✅ 5. Apply Review and Tag Policies¶

Assign reviewers (Tech Lead Agent, QA Reviewer)
Label PRs using tags like:
- usecase, domain:<billing>, requires-tests, auto-generated

✅ 6. Trigger Azure DevOps Pipelines¶

Optionally auto-create status checks (e.g., lint, tests)
Trigger CI pipelines via branch push or PR event

✅ 7. Handle Error and Retry Logic¶

If PR creation fails (e.g., duplicate PR, Git error):
- Retry with exponential backoff
- If still failing, emit PullRequestFailed and notify HumanOpsAgent

✅ 8. Support Manual or Semi-Automated Review¶

Mark PR as:
- draft if partial context
- ready-for-review if fully traceable
Supports override from Tech Lead or Reviewer agents

✅ 9. Store PR Metadata in Long-Term Memory¶

Map trace_id → pr_id → commit_hash → branch
Enables audit trail, blueprint retrospectives, and changelog generation

✅ 10. Ensure Policy Compliance¶

Validate:
- PR title format
- Mandatory trace and scope fields
- Branch naming convention (feature/*, hotfix/*)

🧠 Summary¶

The Pull Request Creator Agent is responsible for turning autonomous commits into peer-reviewable, trace-complete, policy-compliant pull requests that drive ConnectSoft’s release pipelines and collaborative workflows.

It ensures every software change enters the human validation layer with full context, traceability, and automation awareness.

📥 Input Overview¶

The Pull Request Creator Agent is triggered automatically by the CommitCompleted event from the Code Committer Agent. It uses this event — along with enriched metadata and lookup sources — to build a complete pull request.

📬 Primary Inputs¶

✅ 1. CommitCompleted Event¶

The main trigger and data source.

{
  "event": "CommitCompleted",
  "trace_id": "trace-ord-8128",
  "commit_hash": "9fbc871",
  "repo": "OrderService",
  "branch": "feature/order-handler",
  "agent": "code-committer-agent",
  "timestamp": "2025-05-07T19:05:33Z"
}

✅ 2. Git Commit Metadata¶

Fetched via Azure DevOps Git API or cached memory:

Field	Use
`commit.message`	Derives PR title
`commit.diff`	File summary for PR body
`commit.author`	Attribution metadata
`commit.tags`	Propagate to PR as labels or comments

✅ 3. Trace Metadata¶

Resolved using short- or long-term memory, injected during commit:

{
  "trace_id": "trace-ord-8128",
  "blueprint_id": "usecase-create-order",
  "component_scope": "Order",
  "linked_files": [
    "src/Application/Handlers/CreateOrderHandler.cs"
  ]
}

✅ 4. Branch Naming Policy¶

Loaded from config or Tech Lead Agent:

branch_rules:
  allowed_prefixes: [feature/, bugfix/, hotfix/]
  target_branch_map:
    feature/: dev
    hotfix/: main

✅ 5. PR Template Policy¶

Pulled from ConnectSoft policy memory or repo .pr-template.md:

### Description
${commit_summary}

### Related Trace
- Trace ID: ${trace_id}
- Blueprint: ${blueprint_name}
- Scope: ${component_scope}

### Changed Files
${file_table}

### Checklist
- [x] Code builds
- [x] Blueprint linked
- [ ] Tests attached

✅ 6. Review Routing Rules¶

Defines who must review based on scope or domain:

review_policy:
  domain: Order
  reviewers: [TechLeadAgent, QAAssistantAgent]
  auto_approve: false

✅ 7. Agent Identity & Auth¶

Azure DevOps PAT, Managed Identity, or Agent Key
Required to call PR API and assign reviewers/tags

🧠 Summary¶

The Pull Request Creator Agent consumes:

Commit event signals
Trace metadata
Policy templates
Repo context …to generate a fully structured, trace-first pull request that kicks off the next stage of the AI Software Factory pipeline.

📤 Outputs¶

The Pull Request Creator Agent generates structured, traceable outputs that feed into downstream agents, observability pipelines, and human reviewers. These outputs are both Git artifacts and event-based metadata.

🧾 Primary Outputs¶

✅ 1. Pull Request Object (Azure DevOps)¶

Created via the Azure DevOps REST API:

Field	Example
`title`	`feat(order): implement CreateOrderHandler [trace:ord-8128]`
`description`	Includes blueprint ID, trace ID, change summary, file table
`source_branch`	`feature/order-handler`
`target_branch`	`dev`
`reviewers`	Assigned via rules (`TechLeadAgent`, `QAAssistantAgent`)
`labels/tags`	`domain:order`, `traceable`, `generated-by:AI`
`auto_complete`	Optional flag based on team policy

✅ 2. Event: `PullRequestCreated`¶

Emitted to the event bus or MCP server after successful PR creation.

{
  "event": "PullRequestCreated",
  "pr_id": 3021,
  "repo": "OrderService",
  "branch": "feature/order-handler",
  "trace_id": "trace-ord-8128",
  "blueprint_id": "usecase-create-order",
  "commit_hash": "9fbc871",
  "created_by": "pull-request-creator-agent",
  "timestamp": "2025-05-07T20:01:19Z"
}

Used by:

TechLeadAgent (for code review)
ObservabilityAgent
DevOpsOrchestrator
DocumentationAgent

✅ 3. Human-Readable PR Description (Markdown)¶

Generated from templates:

## Use Case: Create Order
**Trace ID**: trace-ord-8128  
**Component**: Order  
**Blueprint**: usecase-create-order

### Changes
- ✨ Added: `CreateOrderHandler.cs`
- 🧪 Added: `CreateOrderHandlerTests.cs`

### Linked Commit
`9fbc871` by `code-committer-agent`

---

✅ Ready for review by Tech Lead and QA.

✅ 4. Review Task Trigger¶

May optionally trigger:

Review planner agent flow
Auto-assignment of tasks in DevOps boards or Jira

✅ 5. OTEL Spans and Logs¶

Logged to observability pipeline:

Span	Info
`pr.create.start` → `pr.create.success`	Full timing and status trace
Tags: `trace_id`, `pr_id`, `repo`, `scope`	For searchability and dashboarding

✅ 6. Fallback Output (Failure Mode)¶

{
  "event": "PullRequestFailed",
  "reason": "PR already exists",
  "trace_id": "trace-ord-8128",
  "attempted_branch": "feature/order-handler",
  "created_by": "pull-request-creator-agent",
  "timestamp": "2025-05-07T20:03:12Z"
}

Routed to: HumanOpsAgent, DevOpsLeadAgent

🧠 Summary¶

The Pull Request Creator Agent outputs a fully initialized Azure DevOps Pull Request, enriched with semantic context, trace metadata, structured markdown, and event signals — enabling downstream automation, observability, and collaboration across the factory.

📚 Knowledge Base¶

The Pull Request Creator Agent is not a blank-slate LLM call. It operates with a rich preloaded knowledge base, allowing it to consistently produce semantically correct, traceable, and policy-aligned pull requests.

📘 Knowledge Categories¶

✅ 1. PR Formatting Templates¶

Title structure: <type>(<scope>): <summary> [trace:<id>]
Body templates with sections:
- Use Case / Trace Info
- Changed Files Table
- Commit Metadata
- Review Checklist

Stored as markdown or YAML format in policy config or shared template store.

✅ 2. Commit → PR Mapping Rules¶

How to derive PR content from:
- Commit message
- File paths
- Trace ID
- Scope / blueprint
Includes logic for multi-commit PRs or fallback summaries

✅ 3. Branch Targeting Policies¶

Defines what target branch to use based on source branch prefix.

branch_rules:
  feature/: dev
  bugfix/: dev
  hotfix/: main
  spike/: discard (no PR)

✅ 4. Blueprint and Trace Knowledge¶

Fetched or preloaded from the blueprint registry:

Field	Description
`trace_id`	Unique per use case
`blueprint_id`	Use case / feature ID
`component_scope`	Domain/module boundary
`description`	Short functional intent
`linked agents`	Origin agents for this feature (e.g., DeveloperAgent)

Enables PR descriptions to include non-code context like business intent.

✅ 5. Policy Guidelines¶

Agent understands ConnectSoft-wide standards:

Area	Rule
PR size	Max 3000 LOC changed
Commit-to-PR time	< 5 minutes preferred
Mandatory reviewers	TechLead, QAAssistant
Forbidden keywords	"test", "asdf", "fixme" in PR title
Required metadata	trace_id, blueprint_id, repo, branch, scope

✅ 6. Labeling and Review Policy¶

Autodetects appropriate PR tags:

Tag	Trigger
`domain:<X>`	Based on `component_scope`
`requires-tests`	If new code lacks tests
`generated-by:AI`	Default on all system-created PRs
`automerge-pending`	If pipeline passes and human review is optional

✅ 7. Past PR Patterns (Long-Term Memory)¶

Access to embeddings of previous PRs for similar features
Enables phrasing alignment, reduces duplicate phrasing, improves clarity

Example: If CreateUserHandler PR exists, CreateOrderHandler uses similar description style.

✅ 8. Azure DevOps API Schema¶

Knows expected fields, statuses, limitations for:

Creating PRs
Assigning reviewers
Attaching tags
Setting auto-complete and draft flags

🧠 Summary¶

The Pull Request Creator Agent operates with an embedded knowledge base covering:

Templates, patterns, and policies
Component scope and trace semantics
Azure DevOps PR mechanics

This makes the agent deterministic, standards-compliant, and safely automatable — without hallucination or formatting drift.

🔁 Process Flow¶

The agent follows an event-driven, trace-first pipeline:

flowchart TD
    A[CommitCompleted Event] --> B[Fetch Commit & Trace Metadata]
    B --> C[Resolve PR Template & Target Branch]
    C --> D[Generate PR Title & Body]
    D --> E[Create PR via Azure DevOps API]
    E --> F[Assign Reviewers & Labels]
    F --> G[Emit PullRequestCreated Event]
    G --> H[Notify Observability & Human Agents if needed]

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

🪜 Detailed Process Steps¶

✅ Step 1: Receive `CommitCompleted` Event¶

Triggered by Code Committer Agent
Includes commit hash, branch, trace ID, and repo name

✅ Step 2: Resolve Commit & Trace Context¶

Fetch commit message, diff, author from Azure DevOps API
Resolve trace_id → blueprint, component_scope, target_branch

✅ Step 3: Determine PR Template¶

Load .pr-template.md or policy-defined markdown
Resolve variables like:
- ${trace_id}, ${scope}, ${file_table}, ${commit_summary}

✅ Step 4: Generate PR Title and Body¶

Use LLM or SK template planner to generate:
- feat(order): implement CreateOrderHandler [trace:ord-8128]
Format PR body in markdown using trace, blueprint, and commit info

✅ Step 5: Validate Branch and Target¶

Check:
- Branch exists?
- Is source branch allowed (feature/*, bugfix/*)?
- Resolve correct merge target (e.g., dev, main)

✅ Step 6: Create Pull Request¶

Call Azure DevOps REST API:

POST /repos/{repo}/pullrequests

with structured payload:

* Title, source & target branches
* Description (markdown)
* Auto-complete flag (optional)

✅ Step 7: Assign Reviewers and Labels¶

Use policy config or trace-linked routing:
- Add TechLeadAgent, QAAssistant
- Tag: domain:<X>, generated-by:AI, etc.

✅ Step 8: Emit `PullRequestCreated` Event¶

Event includes PR ID, repo, trace ID, component scope
Consumed by:
- Observability Agent
- Documentation Agent
- DevOps Orchestrator
- HumanOpsAgent (if required)

⛔ Error Handling Path¶

On API failure:
- Retry up to 3 times with exponential backoff
- On persistent failure, emit PullRequestFailed and notify HumanOpsAgent

🧠 Summary¶

The Pull Request Creator Agent’s process flow is:

Event-driven (triggered by commit)
Trace-aware (fully contextualized)
Template-based (standards compliant)
Autonomous but recoverable (via retries and human hooks)

It is a critical midpoint between code generation and peer review, linking automation to validation.

🧠 Skills & Kernel Functions¶

In the Semantic Kernel ecosystem, skills are modular function collections the agent uses to perform reasoning, transformations, templating, and API orchestration.

The Pull Request Creator Agent combines native SK plugins, ConnectSoft custom skills, and external API wrappers to build and publish traceable PRs.

🧩 Core Skills Used¶

✅ 1. `CommitSummarySkill` (custom)¶

Parses one or multiple commits
Extracts summary per file or module
Outputs PR body-ready markdown section

Used to populate Changed Files, Linked Commits, and Blueprint Summary.

✅ 2. `TraceValidationSkill`¶

Confirms trace_id is:
- Valid and linked to blueprint
- Aligned with commit files and scope
Tags PR as traceable or trace-violation

✅ 3. `PullRequestTemplateSkill`¶

Uses a reusable markdown template to:
- Generate PR title
- Compose body with dynamic sections (via SK planner)
- Embed metadata (trace ID, commit hash, blueprint)

✅ 4. `AzureDevOpsSkill`¶

Interfaces with Azure DevOps API:
- CreatePullRequestAsync(...)
- AssignReviewer(...)
- SetAutoComplete(...)
- AttachLabels(...)

Uses Azure identity or injected PAT for authentication.

✅ 5. `ReviewerPolicySkill`¶

Resolves reviewers dynamically from:
- Component scope
- Blueprint rules
- Org-level domain ownership

✅ 6. `MarkdownFormatterSkill`¶

Formats:
- Diff summaries into tables
- Checklists
- Linked file references
- Trace metadata

✅ 7. `EventEmitterSkill`¶

Emits lifecycle events like:
- PullRequestCreated
- PullRequestFailed
- PullRequestReadyForReview
Event output: JSON over Event Bus / MCP protocol

🤖 Example Skill Flow¶

→ CommitCompletedEvent
  → TraceValidationSkill
  → CommitSummarySkill
  → ReviewerPolicySkill
  → PullRequestTemplateSkill
  → AzureDevOpsSkill
  → EventEmitterSkill

🧠 Skill Composition Mode¶

Mode	Usage
🧩 SK Planner	For LLM-guided composition of PR body
🔁 SK Pipeline	Sequential execution (validate → generate → push)
🧠 Embedding Search	Reference past PRs and enforce similarity

🧠 Summary¶

The Pull Request Creator Agent’s intelligence comes from orchestrating a chain of reusable Semantic Kernel skills:

Validation
Templating
DevOps API calls
Event emission

This enables it to remain modular, extensible, and deterministic, while producing deeply contextual pull requests across all ConnectSoft repositories.

🧰 Core Technology Stack¶

The Pull Request Creator Agent is implemented as a cloud-native, event-driven agent leveraging Semantic Kernel, Azure DevOps APIs, and ConnectSoft observability pipelines.

🧠 1. Semantic Kernel (SK)¶

Feature	Use
Planner	Generates PR titles and descriptions using context-driven prompt templates
Memory Store	Retains PR template embeddings, trace mappings
Skills	Modular plugin system for commit summary, PR formatting, DevOps API calls

🤖 2. OpenAI (GPT-4 / GPT-4 Turbo)¶

Use Case	Detail
PR body templating	Converts trace + commit + blueprint metadata into human-readable PR description
Commit summarization	Auto-generates feature descriptions from diffs
Tone tuning	Applies formal, professional tone across descriptions and summaries

🌐 3. Azure DevOps REST API¶

Endpoint	Purpose
`POST /pullrequests`	Create the PR
`PATCH /pullrequests/{id}`	Update title, description, labels
`POST /reviewers`	Assign code reviewers
`POST /labels`	Attach traceability and domain labels
`GET /commits/{id}`	Fetch commit metadata

Uses Azure AD-managed identity, service principal, or PAT.

🔁 4. MCP Server (Model Context Protocol)¶

Feature	Purpose
Event relay	Emits `PullRequestCreated`, `PullRequestFailed` events
Agent discovery	Connects with TechLeadAgent, DevOpsAgent, and ObservabilityAgent
Contextual inputs	Supplies blueprint and trace memory lookups via shared context protocol

🧠 5. Vector Memory Store (e.g., Qdrant, Azure Cognitive Search)¶

Purpose
Embedding-based lookup	Similar PRs, trace-context embeddings
PR style reuse	Ensures consistency in wording and formatting
Blueprint ↔ PR linking	Fast retrieval of PR history for a trace ID

📊 6. Observability Stack¶

Tool	Use
OpenTelemetry (OTEL)	Exports spans: PR created, failed, assigned, reviewed
Grafana / Application Insights	Dashboards for agent health, PR generation success rate
Structured JSON Logs	Captured in blob or log stream per agent run

⚙️ 7. ConnectSoft Config & Policy Platform¶

Type	Example
`.pr-template.md`	Rich PR markdown with injected variables
`commit-policy.yaml`	Acceptable branches, message formats, label rules
`review-policy.yaml`	Default reviewers per component scope

Centralized in ConnectSoft tenant-level configuration layer.

🧪 Runtime Environment¶

Aspect	Technology
Language	.NET 8 (C#)
Agent Runtime	Azure Container Apps or AKS (Kubernetes)
Identity/Auth	Managed Identity or DevOps PAT
CI/CD	Deployed via GitHub Actions or Azure DevOps Pipelines
Secrets	Azure Key Vault for API tokens, PATs, identities

🧠 Summary¶

The Pull Request Creator Agent combines:

AI power (OpenAI + SK)
Enterprise-grade DevOps APIs
Cloud-native scalability (Azure)
Event-driven orchestration (MCP)

…to deliver a fully autonomous, secure, and standards-aligned PR automation agent for the ConnectSoft AI Software Factory.

📋 System Prompt¶

The System Prompt is the initial instruction given to the agent’s LLM-driven kernel (e.g., GPT-4 via Semantic Kernel) that sets its role, boundaries, formatting style, compliance requirements, and tone.

It acts as the “role contract” for the agent across all pull request generation tasks.

🧠 Pull Request Creator Agent – System Prompt¶

You are the Pull Request Creator Agent in the ConnectSoft AI Software Factory.

Your mission is to generate complete, traceable, and policy-compliant pull requests in Azure DevOps based on input from the Code Committer Agent and ConnectSoft trace metadata.

You always follow these rules:

1. PRs must reflect the use case, trace ID, and component scope in the title and body.
2. All PRs are linked to a single traceable change. Never group unrelated commits.
3. PR titles follow this format:
   <type>(<component_scope>): <short summary> [trace:<trace_id>]
4. PR body must include:
   - Blueprint ID and description
   - Changed files summary
   - Linked commits
   - Review checklist
   - Trace metadata block (for automation)
5. Use a formal and informative tone — avoid vague language or internal jargon.
6. If any required data is missing (trace, branch, diff), halt and request correction.

Your output must always be deterministic, standards-aligned, and markdown-formatted.

Do not generate code or modify files — your job is metadata synthesis and PR automation.

📘 Key Behavior Definitions¶

Behavior	Instruction
🎯 Focus	Create PRs, not code
📚 Context-Driven	Use trace ID, blueprint, diff to explain purpose
✍️ Language Style	Formal, precise, and consistent across all PRs
✅ Compliance	Enforce traceability and branch policy alignment
🚫 Restrictions	Never invent commits, rewrite code, or bypass trace checks

🧠 System Prompt Effects¶

Benefit	Outcome
🔒 Determinism	Consistent formatting and tone across agents and services
🎯 Scope Control	Prevents hallucinations or unrelated output
🧩 Seamless Integration	Output plugs directly into DevOps and review workflows
📈 Observability	Trace and scope metadata embedded for analytics and pipelines

🧠 Summary¶

The System Prompt acts as the Pull Request Creator Agent’s governing contract — enforcing trace integrity, formatting standards, and review readiness across every generated PR in the ConnectSoft pipeline.

It ensures every PR:

Speaks clearly,
Aligns with trace,
And invites safe human collaboration.

🧾 Input Prompt Template¶

This is the parameterized prompt sent to the LLM (via Semantic Kernel) to generate:

PR title
PR description (markdown)
Embedded metadata block

It’s populated dynamically with context from:

Commits
Trace metadata
Blueprint registry
Branching policies

🧠 Template Format¶

You are generating a pull request for a software factory-generated feature.

Please create:
- A concise PR title using semantic commit format.
- A detailed PR body in markdown.
- A checklist for reviewers.
- A metadata block for automation systems.

Use the following structured input:

Trace ID: {{trace_id}}
Blueprint ID: {{blueprint_id}}
Blueprint Name: {{blueprint_name}}
Component Scope: {{component_scope}}
Repository: {{repo_name}}
Source Branch: {{branch_name}}
Target Branch: {{target_branch}}
Commit Message: {{commit_message}}
Changed Files:
{{changed_files_list}}

You must:
- Mention the purpose of the feature
- List files added or modified
- Include linked commit hash
- Always include trace_id and component_scope
- Use formal and clear markdown

Begin with PR title. Then provide markdown body.

🧩 Variable Placeholders¶

Variable	Description
`{{trace_id}}`	Required for traceability
`{{blueprint_id}}`	Used in PR body summary
`{{component_scope}}`	Maps to domain context, reviewer assignment
`{{branch_name}}`	Source branch of PR
`{{commit_message}}`	Used to seed PR title and context
`{{changed_files_list}}`	Rendered as table in markdown
`{{repo_name}}`	Used to link artifacts and scope reviewers

📘 Example Populated Prompt (Condensed)¶

Trace ID: trace-ord-8128  
Blueprint: usecase-create-order  
Scope: Order  
Repo: OrderService  
Source: feature/order-handler  
Commit: "feat(order): implement CreateOrderHandler [trace:ord-8128]"  
Files:  
- src/Application/Handlers/CreateOrderHandler.cs  
- tests/Order/CreateOrderHandlerTests.cs

🎯 Expected Response Structure¶

Title:
feat(order): implement CreateOrderHandler [trace:ord-8128]

Body:
## Summary  
Implements order creation handler aligned with blueprint `usecase-create-order`.

## Changed Files
| Path | Type |
|------|------|
| src/Application/Handlers/CreateOrderHandler.cs | New |
| tests/Order/CreateOrderHandlerTests.cs | New |

## Metadata
- Trace ID: trace-ord-8128  
- Scope: Order  
- Blueprint: usecase-create-order  
- Commit: 9fbc871

🧠 Summary¶

The Input Prompt Template ensures the agent has a consistent, structured way to turn execution context into a clear, traceable, review-ready pull request. It connects commit intent with factory logic, enabling explainable and policy-aligned outputs.

📤 Output Expectations¶

These define the structure, completeness, and formatting standards for what the agent must emit:

To Azure DevOps
To downstream agents (as events)
And for human review

✅ 1. Pull Request Title Format¶

The title must follow semantic commit format, scoped and trace-linked:

<type>(<component_scope>): <summary> [trace:<trace_id>]

Example:

feat(order): implement CreateOrderHandler [trace:ord-8128]

Rule	Reason
`type`	Aligns with commit taxonomy (`feat`, `fix`, `refactor`, etc.)
`component_scope`	Maps to domain or microservice
`trace_id`	Required for traceability and blueprint linkage

✅ 2. Pull Request Body Format¶

The body must be in GitHub-Flavored Markdown, structured into sections:

## Summary
Implements the CreateOrderHandler feature as defined in blueprint `usecase-create-order`.

## Blueprint
- Blueprint ID: usecase-create-order
- Component Scope: Order
- Trace ID: trace-ord-8128

## Changed Files
| File | Type |
|------|------|
| src/Application/Handlers/CreateOrderHandler.cs | Added |
| tests/Order/CreateOrderHandlerTests.cs | Added |

## Linked Commit
`9fbc871`

## Review Checklist
- [x] Code builds and compiles
- [x] Trace metadata attached
- [x] Includes unit tests

✅ 3. Event Output Format (`PullRequestCreated`)¶

{
  "event": "PullRequestCreated",
  "pr_id": 3123,
  "repo": "OrderService",
  "branch": "feature/order-handler",
  "trace_id": "trace-ord-8128",
  "blueprint_id": "usecase-create-order",
  "commit_hash": "9fbc871",
  "created_by": "pull-request-creator-agent",
  "timestamp": "2025-05-07T21:30:00Z"
}

This event must:

Be emitted once
Be consumed by: TechLeadAgent, ObservabilityAgent, DevOpsAgent, HumanOpsAgent

✅ 4. PR Metadata Requirements¶

Field	Required	Description
`trace_id`	✅	Must be attached and visible
`blueprint_id`	✅	Included in PR body
`component_scope`	✅	Used to tag and route
`commit_hash`	✅	Displayed in metadata section
`reviewers`	✅	Assigned via policy rules
`labels`	✅	Includes `domain:*`, `traceable`, `generated-by:AI`

✅ 5. Tone and Style¶

Criterion	Standard
Language	Formal, precise, business-aligned
No filler	No "this is auto-generated" or vague text
Markdown	Proper headings, bullet lists, tables
Line length	Optimized for readability (max 100 chars/line for description)

✅ 6. Observability Metadata¶

Each PR generation must include OpenTelemetry span with:

Tag	Value
`trace_id`	Required
`repo`	Repository name
`branch`	Source branch
`status`	`success`, `failed`, `skipped`
`agent`	`pull-request-creator-agent`
`duration_ms`	Execution time

🧠 Summary¶

The Pull Request Creator Agent’s outputs must be:

Structured (markdown, JSON)
Traceable (with embedded trace metadata)
Compliant (matching policy rules)
Human-readable (review-ready)
Automation-ready (for event pipelines)

This ensures that every PR serves as both a collaboration artifact and a reliable automation trigger.

🧠 Memory Overview¶

The Pull Request Creator Agent maintains dual memory layers:

🧩 Short-Term Memory: In-memory context during a single run
🧠 Long-Term Memory: Persistent store (vector DB, key-value store) for trace mapping, PR history, and blueprint linkage

📌 1. Short-Term Memory (In-Memory / Execution Context)¶

Key	Description
`commit_hash`	Used to generate PR title and metadata
`branch_name`	Used to determine PR source and target
`trace_id`	Passed from upstream agent
`blueprint_id`	Used in PR body and trace metadata
`component_scope`	Determines review routing and labels
`repo`	Needed for DevOps API calls
`diff_summary`	Used for generating Changed Files table
`generated_pr_title`	Temporary result from templating step

Reset after each run. Stored in SK context and passed across skill steps.

💾 2. Long-Term Memory (Persistent Memory Store)¶

✅ a. Trace ↔ PR Mapping¶

Key	Value
`trace_id`	→ `pr_id`, `commit_hash`, `branch`, `repo`, `blueprint_id`

Enables audits, traceability validation, changelog generation.

✅ b. Blueprint & Scope Embeddings¶

Vector store embedding for each blueprint:
- Name, purpose, tags, component, examples
Enables similar PR detection or phrasing reuse

Example: usecase-create-order ↔ embedding vector used for consistent phrasing across PRs.

✅ c. PR Template Memory¶

Markdown structure of .pr-template.md
Stored as embedding to match future blueprint PRs to preferred layout

✅ d. Commit Context Archive (Optional)¶

Stores summaries of recent commits per repo:
- Used for similarity validation
- Detects accidental duplication or repeated effort

✅ e. Policy Memory¶

Cached copy of:

Branch naming policies
Reviewer routing policies
PR formatting guidelines
Tokenized commit taxonomy

Loaded at runtime or accessed from shared policy memory agent

📘 Memory Technologies Used¶

Memory Type	Backing Store
Execution Memory	Semantic Kernel Planner Context
Vector Search	Qdrant or Azure AI Search
KV Store	Redis or Azure App Configuration
Persistent Store	Azure Cosmos DB or Azure Table Storage
Blob Archive (optional)	PR markdown copies, JSON logs

🧠 Summary¶

The Pull Request Creator Agent’s memory system provides:

Short-term execution continuity
Long-term traceability and context reuse
Policy-aware, blueprint-linked consistency
Auditable commit-to-PR chains

This makes the agent stateful in purpose, even when stateless in execution — ideal for scalable, autonomous DevOps flows.

✅ Validation¶

Validation ensures that each PR created:

Is traceable to a single blueprint
Follows ConnectSoft formatting standards
Complies with branching and review policies
Is complete and reviewable by downstream agents and humans

🧪 Validation Pipeline¶

Validation is applied at multiple stages in the process:

flowchart TD
    A[Receive CommitCompleted Event]
    --> B[Validate Required Fields]
    --> C[Check Trace Integrity]
    --> D[Verify Branch Policy]
    --> E[Validate Title & Body]
    --> F[Confirm Review & Label Policy]
    --> G{Pass All Checks?}
    G -- No --> H[Abort & Emit PullRequestFailed]
    G -- Yes --> I[Proceed to Create PR]

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

🔍 Validation Dimensions¶

✅ 1. Required Metadata¶

Field	Validation
`trace_id`	Must be present and resolvable to a blueprint
`blueprint_id`	Must match `trace_id` and commit context
`component_scope`	Required for review and label routing
`commit_hash`	Must be non-empty and exist in repo
`repo`	Must be known to the agent with API access

✅ 2. Trace Linkage¶

Validate that:
- Files changed are relevant to declared component_scope
- The trace_id belongs to a blueprint linked to that component
If mismatch detected → mark as trace_violation, emit error

✅ 3. Branch Policy¶

Source branch must follow allowed prefixes (feature/, hotfix/, etc.)
Target branch must match policy map (feature → dev, hotfix → main)
Forbidden branches (e.g., master, deprecated/) are rejected

✅ 4. PR Title and Body Compliance¶

Check	Rule
Title format	Must follow: `<type>(<scope>): <summary> [trace:<id>]`
Markdown structure	Body must include: Summary, Blueprint, Changed Files, Checklist
Length limits	Title ≤ 100 chars, body ≤ 4000 chars

✅ 5. Review & Label Policy¶

Requirement	Validation
Reviewers assigned	Must include `TechLeadAgent` and QA if applicable
Labels added	At least: `domain:*`, `traceable`, `generated-by:AI`
Auto-merge flag	Disabled if any checklist item is incomplete

✅ 6. Dry Run (Optional Preflight Check)¶

When flagged for dry run:

Validate all above
Generate and log PR preview
Do not push to Azure DevOps
Useful for preflight testing and human inspection

❌ Validation Failure Response¶

If validation fails:

PR creation is aborted
A structured PullRequestFailed event is emitted:

{
  "event": "PullRequestFailed",
  "reason": "trace_violation",
  "trace_id": "trace-ord-8128",
  "branch": "feature/order-handler",
  "repo": "OrderService",
  "timestamp": "2025-05-07T22:14:32Z"
}

HumanOpsAgent or TechLeadAgent is notified for manual review

🧠 Summary¶

Validation makes the Pull Request Creator Agent a first-class governance actor:

It acts not just as a creator, but as a gatekeeper.
It guarantees correctness, compliance, and trace continuity.
It prevents polluted PRs, broken automation, or unreviewable code from entering the flow.

🔁 Retry & Correction Flow¶

Autonomous systems must be resilient to:

Transient failures (e.g., Azure DevOps API timeouts)
Partial data issues (e.g., missing trace metadata)
Policy violations (e.g., incorrect branch name)

This agent includes a graceful fallback mechanism with:

Automatic retries
Error categorization
Event emission
Human escalation

🪜 Retry Strategy¶

✅ Transient Failure Categories¶

Error Type	Retry?	Strategy
Azure DevOps 500 / 429	✅	3 retries, exponential backoff
Network timeout	✅	3 retries, increasing delay (1s → 4s)
Rate-limiting	✅	Honor Retry-After header or backoff policy

🚫 Non-Retryable Errors¶

Error	Action
Invalid trace ID	Abort, emit `PullRequestFailed`
Blueprint mismatch	Emit violation, notify HumanOpsAgent
Branch name policy fail	Halt and request human override
PR already exists	Skip creation, notify with warning

🔄 Retry Policy¶

retry_policy:
  max_attempts: 3
  backoff: exponential
  base_delay_ms: 1000
  retryable_status_codes: [429, 500, 502, 503]

Retry context is stored in in-memory execution state.

📣 Correction & Escalation Flow¶

If retries fail:

Emit PullRequestFailed with reason code
Notify:
- HumanOpsAgent
- TechLeadAgent (if scope-mapped)
Log failed PR preview in blob or observability trace
Set retryable = false to avoid loops

📘 Example Failure Event¶

{
  "event": "PullRequestFailed",
  "reason": "azure_devops_500",
  "attempts": 3,
  "trace_id": "trace-ord-8128",
  "repo": "OrderService",
  "branch": "feature/order-handler",
  "timestamp": "2025-05-07T22:20:55Z"
}

🧠 Manual Correction Options¶

Actor	Action
TechLeadAgent	May override PR creation manually
HumanOpsAgent	Can requeue the PR with corrected metadata
RetryServiceAgent	(optional) may scan failed PRs and re-attempt batch repair nightly

🧠 Summary¶

The Retry & Correction Flow guarantees:

Resiliency against transient issues
Safety against non-retryable violations
Visibility through structured failure events
Recovery through agent-assisted and human-assisted correction

It ensures the PR creation flow is fail-safe, not fail-silent.

🤝 Collaboration Interfaces¶

The Pull Request Creator Agent is a mid-pipeline coordination hub, interfacing with both upstream and downstream agents to facilitate traceable, reviewable code delivery.

📥 Receives Input From:¶

Source Agent	Interface	Purpose
Code Committer Agent	`CommitCompleted` event	Triggers the PR generation process
Tech Lead Agent	Policy and override context	PR routing, reviewer assignment, manual interventions
Trace Agent (optional)	Blueprint enrichment	Provides blueprint summaries and tags if not cached

📤 Sends Output To:¶

Target Agent	Interface	Purpose
Tech Lead Agent	`PullRequestCreated` event + webhook	Signals new PR for review
Documentation Agent	Trace & commit metadata	Enables blueprint-based doc scaffolding
Observability Agent	OTEL spans + structured logs	Traceable telemetry for dashboards and audits
DevOps Agent	Event + branch metadata	Triggers CI pipeline based on PR branch
HumanOps Agent	`PullRequestFailed` event	For intervention on retries or trace violations

🔗 API & Event Interfaces¶

Integration	Protocol	Use
Azure DevOps API	REST over HTTPS	Create PR, assign reviewers, set auto-complete, apply labels
MCP Event Bus	JSON-over-message queue	Emit lifecycle events (`PullRequestCreated`, `Failed`, `ReadyForReview`)
ConnectSoft Memory Service	HTTP/gRPC	Fetch trace-to-blueprint metadata
Shared VFS	File reference or blob path	Used when commits link to large documentation or design files
Policy Memory Interface	gRPC or REST	Review, label, and formatting policies per tenant/component

🧠 Semantic Kernel Context Passing¶

The agent participates in an SK-based planning tree, enabling:

Reuse of generated summaries from previous agents
Shared embeddings for trace blueprints
Continuity of execution plan (e.g., commit → PR → release → changelog)

📬 Collaboration Pattern Summary¶

sequenceDiagram
    participant Committer
    participant PRCreator
    participant DevOps
    participant TechLead
    participant Observability

    Committer->>PRCreator: CommitCompleted Event
    PRCreator->>DevOps: Trigger CI (PR created)
    PRCreator->>TechLead: Notify for Review
    PRCreator->>Observability: Emit OTEL Span

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

🧠 Summary¶

The Pull Request Creator Agent is a collaborative orchestrator that:

Receives contextual input from engineering agents
Publishes actionable artifacts to DevOps, docs, and human reviewers
Integrates into event-driven, trace-first, and observability-enriched workflows

It ensures seamless propagation of traceable changes across the software factory pipeline.

📈 Observability Hooks¶

The agent provides full visibility into its execution via structured logging, OpenTelemetry spans, and event emission. This enables monitoring, alerting, auditing, and retrospective analysis.

✅ 1. OpenTelemetry Spans¶

Span Name	Description
`prcreator.start`	Start of PR creation workflow
`prcreator.template.resolve`	Template assembly and variable injection
`prcreator.title.body.generated`	Output from LLM / SK
`prcreator.devops.api.request`	Azure DevOps PR API call
`prcreator.complete`	Final success/failure

Common Span Tags:¶

trace_id
repo
branch
component_scope
status (success, failed, skipped)
error_type (e.g., api_429, missing_trace)

✅ 2. Structured Logs (JSON)¶

Each run logs:

{
  "agent": "pull-request-creator-agent",
  "execution_id": "exec-901",
  "trace_id": "trace-ord-8128",
  "repo": "OrderService",
  "branch": "feature/order-handler",
  "status": "success",
  "pr_id": 3123,
  "duration_ms": 2350,
  "timestamp": "2025-05-07T22:35:21Z"
}

Captured in:

Azure Log Analytics
Blob store archive (optional)
ConnectSoft Audit Trail service

✅ 3. Lifecycle Events¶

Event	Trigger
`PullRequestCreated`	Successful PR
`PullRequestFailed`	Retry exceeded or policy violation
`PullRequestReadyForReview`	When checklist conditions are satisfied

These events are consumed by:

TechLeadAgent
ObservabilityAgent
HumanOpsAgent
CI/CD orchestrators

🧑‍💼 Human Intervention Hooks¶

When agent automation cannot proceed safely, it gracefully escalates via structured interfaces.

🚨 Escalation Scenarios¶

Condition	Escalation
API fails after 3 retries	Emit `PullRequestFailed`, notify HumanOpsAgent
Invalid trace or branch policy	Route error to TechLeadAgent
Title or body format invalid	Create dry-run preview, halt full creation
Missing blueprint description	Prompt human or DocAgent to enrich before retry

🛠️ Manual Tools¶

Tool	Use
PR Preview Viewer (UI)	Review failed/draft PRs before pushing
Requeue Interface	Allow human to retry with fixed input
Slack / Email Alerts	Notify tech leads or reviewers on failure or review assignment
MCP Dashboard	Visualize agent runs, failure reasons, retry actions

🧠 Example: Human Intervention Flow¶

sequenceDiagram
    participant PRCreator
    participant DevOpsAPI
    participant HumanOps
    PRCreator->>DevOpsAPI: Create PR (fails 3x)
    PRCreator-->>HumanOps: Emit PullRequestFailed
    HumanOps->>PRCreator: Retry with override
    PRCreator->>DevOpsAPI: Create PR (manual requeue)

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

🧠 Summary¶

The Pull Request Creator Agent is:

🔍 Observable by design (Spans, logs, and metrics available at every step)
🧩 Collaborative by default (Emits events for agents and human interfaces)
💡 Recoverable under failure (Retry logic, human override, preview-before-push)

It maintains factory-grade reliability and traceability, empowering both autonomous execution and human-aware workflows.

🧠 Pull Request Creator Agent Specification¶

🎯 Agent Purpose¶

🌐 Mission Summary¶

🧭 Strategic Role in Factory Flow¶

🧠 Key Behaviors Enabled by Purpose¶

🧩 Alignment to ConnectSoft Core Principles¶

🧠 Summary¶

📌 Core Responsibilities¶

✅ 1. Generate Pull Requests in Azure DevOps¶

✅ 2. Format PR Titles and Descriptions Semantically¶

✅ 3. Attach Metadata for Traceability¶

✅ 4. Emit PR Lifecycle Events¶

✅ 5. Apply Review and Tag Policies¶

✅ 6. Trigger Azure DevOps Pipelines¶

✅ 7. Handle Error and Retry Logic¶

✅ 8. Support Manual or Semi-Automated Review¶

✅ 9. Store PR Metadata in Long-Term Memory¶

✅ 10. Ensure Policy Compliance¶

🧠 Summary¶

📥 Input Overview¶

📬 Primary Inputs¶

✅ 1. CommitCompleted Event¶

✅ 2. Git Commit Metadata¶

✅ 3. Trace Metadata¶

✅ 4. Branch Naming Policy¶

✅ 5. PR Template Policy¶

✅ 6. Review Routing Rules¶

✅ 7. Agent Identity & Auth¶

🧠 Summary¶

📤 Outputs¶

🧾 Primary Outputs¶

✅ 1. Pull Request Object (Azure DevOps)¶

✅ 2. Event: PullRequestCreated¶

✅ 3. Human-Readable PR Description (Markdown)¶

✅ 4. Review Task Trigger¶

✅ 5. OTEL Spans and Logs¶

✅ 6. Fallback Output (Failure Mode)¶

🧠 Summary¶

📚 Knowledge Base¶

📘 Knowledge Categories¶

✅ 1. PR Formatting Templates¶

✅ 2. Commit → PR Mapping Rules¶

✅ 3. Branch Targeting Policies¶

✅ 4. Blueprint and Trace Knowledge¶

✅ 5. Policy Guidelines¶

✅ 6. Labeling and Review Policy¶

✅ 7. Past PR Patterns (Long-Term Memory)¶

✅ 8. Azure DevOps API Schema¶

🧠 Summary¶

🔁 Process Flow¶

🪜 Detailed Process Steps¶

✅ Step 1: Receive CommitCompleted Event¶

✅ Step 2: Resolve Commit & Trace Context¶

✅ Step 3: Determine PR Template¶

✅ Step 4: Generate PR Title and Body¶

✅ Step 5: Validate Branch and Target¶

✅ Step 6: Create Pull Request¶

✅ Step 7: Assign Reviewers and Labels¶

✅ Step 8: Emit PullRequestCreated Event¶

⛔ Error Handling Path¶

🧠 Summary¶

🧠 Skills & Kernel Functions¶

🧩 Core Skills Used¶

✅ 1. CommitSummarySkill (custom)¶

✅ 2. TraceValidationSkill¶

✅ 3. PullRequestTemplateSkill¶

✅ 4. AzureDevOpsSkill¶

✅ 5. ReviewerPolicySkill¶

✅ 6. MarkdownFormatterSkill¶

✅ 7. EventEmitterSkill¶

🤖 Example Skill Flow¶

🧠 Skill Composition Mode¶

🧠 Summary¶

🧰 Core Technology Stack¶

🧠 1. Semantic Kernel (SK)¶

🤖 2. OpenAI (GPT-4 / GPT-4 Turbo)¶

🌐 3. Azure DevOps REST API¶

🔁 4. MCP Server (Model Context Protocol)¶

🧠 5. Vector Memory Store (e.g., Qdrant, Azure Cognitive Search)¶

📊 6. Observability Stack¶

✅ 2. Event: `PullRequestCreated`¶

✅ Step 1: Receive `CommitCompleted` Event¶

✅ Step 8: Emit `PullRequestCreated` Event¶

✅ 1. `CommitSummarySkill` (custom)¶

✅ 2. `TraceValidationSkill`¶

✅ 3. `PullRequestTemplateSkill`¶

✅ 4. `AzureDevOpsSkill`¶

✅ 5. `ReviewerPolicySkill`¶

✅ 6. `MarkdownFormatterSkill`¶

✅ 7. `EventEmitterSkill`¶

✅ 3. Event Output Format (`PullRequestCreated`)¶