GitVita
New repositoryImport repositoryNew issue
Your repositories Your dashboard Sign in

microsoft/hve-core

Public

mirrored fromhttps://github.com/microsoft/hve-coreAvailable

Watch0Fork0Star0
CodeCommitsIssuesPull requestsActionsInsightsSecurity
a3acef32dec8d8ac8051793df3686007a92266cd

Branches

Tags

  • No tags available.
0Branches0Tags
Go to file
Add file
Code

Clone

HTTPS

Download ZIP

hve-core/docs/architecture

docs/architecture/agentic-workflows.md

242lines · modecode

RawDownload
Latest commit unavailable.
1---
2title: Agentic Workflows
3description: End-to-end process flow for AI-driven issue triage, implementation, and review workflows in hve-core
4author: HVE Core Team
5ms.date: 2026-03-27
6ms.topic: concept
7sidebar_position: 4
8keywords:
9 - agentic workflows
10 - issue triage
11 - automated implementation
12 - pr review
13 - github copilot
14 - process flow
15---
16
17hve-core uses GitHub Agentic Workflows to automate the journey from issue creation through implementation, code review, and dependency management. Five event-driven workflows connect specialized agents into a pipeline where each stage triggers the next through labels, pull requests, and GitHub events.
18
19> [!NOTE]
20> GitHub Agentic Workflows is an experimental/beta feature. The workflows described here represent hve-core's early experiments with the technology and may evolve as the platform matures.
21
22## End-to-End Process Flow
23
24```mermaid
25flowchart TD
26 subgraph TRIGGER["Issue Created or Labeled"]
27 A["New issue opened<br/>or labeled needs-triage"]
28 end
29
30 subgraph TRIAGE["Issue Triage Workflow"]
31 B["Read issue title, body,<br/>and template metadata"]
32 C["Classify by type<br/>and component"]
33 D["Detect duplicates<br/>via keyword search"]
34 E["Assess issue quality"]
35 F{"Scope too broad<br/>for single deliverable?"}
36 G["Decompose into<br/>sub-issues"]
37 H{"Passes all<br/>agent-ready criteria?"}
38 I["Apply labels,<br/>remove needs-triage"]
39 J["Add agent-ready label"]
40 K["Leave for human<br/>review"]
41 end
42
43 subgraph IMPLEMENT["Issue Implementation Workflow"]
44 L["Read issue and<br/>acceptance criteria"]
45 M["Research codebase:<br/>files, patterns, conventions"]
46 N["Plan minimal<br/>change set"]
47 O["Implement changes"]
48 P["Verify against<br/>acceptance criteria"]
49 Q["Open pull request<br/>referencing the issue"]
50 end
51
52 subgraph REVIEW["PR Review Workflow"]
53 R["Detect PR opened<br/>or ready for review"]
54 S["Analyze diff against<br/>coding standards"]
55 T["Check conventions,<br/>security, quality"]
56 U{"Review passed?"}
57 V["Add review-passed label"]
58 W["Add needs-revision label<br/>with inline comments"]
59 end
60
61 subgraph HUMAN["Human Review"]
62 X["Maintainer reviews<br/>and merges"]
63 end
64
65 A --> B
66 B --> C
67 C --> D
68 D --> E
69 E --> F
70 F -- Yes --> G
71 G --> I
72 F -- No --> H
73 H -- Yes --> I
74 I --> J
75 H -- No --> I
76 I --> K
77 J --> L
78 L --> M
79 M --> N
80 N --> O
81 O --> P
82 P --> Q
83 Q --> R
84 R --> S
85 S --> T
86 T --> U
87 U -- Yes --> V
88 V --> X
89 U -- No --> W
90 W -.-> O
91```
92
93## Workflow Details
94
95| Workflow | Trigger | Agent | Key Actions |
96|----------------------|----------------------------------------|----------------------------------------------------------------------------------------------------------------------------------|--------------------------------------------------------------------------------------|
97| Issue Triage | Issue opened or labeled `needs-triage` | [Issue Triage Agent](https://github.com/microsoft/hve-core/blob/main/.github/agents/issue-triage.agent.md) | Classify, detect duplicates, assess quality, decompose, label, evaluate readiness |
98| Issue Implementation | Issue labeled `agent-ready` | [Task Implementor Agent](https://github.com/microsoft/hve-core/blob/main/.github/agents/hve-core/task-implementor.agent.md) | Research codebase, plan changes, implement, open PR |
99| PR Review | PR opened or marked ready for review | [PR Review Agent](https://github.com/microsoft/hve-core/blob/main/.github/agents/hve-core/pr-review.agent.md) | Review correctness, conventions, security; label `review-passed` or `needs-revision` |
100| Dependabot PR Review | Dependabot PR opened or updated | [Dependency Reviewer Agent](https://github.com/microsoft/hve-core/blob/main/.github/agents/dependency-reviewer.agent.md) | Validate licensing, SHA pinning, environment sync; approve safe bumps |
101| Documentation Update | Push to main | [Documentation Update Checker Agent](https://github.com/microsoft/hve-core/blob/main/.github/agents/doc-update-checker.agent.md) | Map code changes to docs, create issues for stale documentation |
102
103> [!TIP]
104> The triage agent only classifies, labels, and optionally decomposes issues. It does not close issues, assign users, or modify issue titles.
105
106<!-- markdownlint-disable-next-line MD028 -->
107
108> [!NOTE]
109> The implementation agent keeps PRs small and focused. If the issue is ambiguous or too large, it posts a comment requesting clarification instead of guessing.
110
111## Workflow Configuration
112
113All five workflows are defined as GitHub Agentic Workflow markdown files under `.github/workflows/` and compiled to lock files using `gh aw compile`:
114
115| Workflow File | Lock File | Trigger | Agent |
116|---------------------------|---------------------------------|----------------------------------------|------------------------|
117| `issue-triage.md` | `issue-triage.lock.yml` | Issue opened or labeled `needs-triage` | Issue Triage Agent |
118| `issue-implement.md` | `issue-implement.lock.yml` | Issue labeled `agent-ready` | Task Implementor Agent |
119| `pr-review.md` | `pr-review.lock.yml` | PR opened or marked ready for review | PR Review Agent |
120| `dependency-pr-review.md` | `dependency-pr-review.lock.yml` | Dependabot PR opened or updated | Dependency Reviewer |
121| `doc-update-check.md` | `doc-update-check.lock.yml` | Push to main | Documentation Checker |
122
123Each workflow file declares permissions, safe output limits, and activation guards that prevent unintended execution.
124
125## Label-Driven Handoffs
126
127Labels serve as the event bus connecting workflows. Each label transition triggers the next stage:
128
129```mermaid
130stateDiagram-v2
131 [*] --> needs_triage: Issue opened
132 needs_triage --> classified: Triage removes needs-triage,<br/>adds type + component labels
133 classified --> agent_ready: Triage adds agent-ready<br/>(if criteria met)
134 classified --> human_review: Criteria not met,<br/>awaits human labeling
135 agent_ready --> pr_opened: Implementation agent<br/>opens PR
136 pr_opened --> review_passed: Review agent approves
137 pr_opened --> needs_revision: Review agent requests changes
138 needs_revision --> pr_opened: Author pushes fixes
139 review_passed --> merged: Maintainer merges
140 merged --> [*]
141```
142
143## Interactive Agent Workflows
144
145Beyond the automated GitHub event-driven pipeline, hve-core provides interactive agents invoked through VS Code Copilot Chat. These agents support the manual side of the development lifecycle.
146
147### RPI Orchestration
148
149The [RPI Agent](https://github.com/microsoft/hve-core/blob/main/.github/agents/hve-core/rpi-agent.agent.md) runs a five-phase iterative cycle: Research, Plan, Implement, Review, and Discover. It delegates to four specialized subagents:
150
151| Agent | Role |
152|------------------|----------------------------------------------------------------|
153| Task Researcher | Deep codebase and domain analysis, produces research documents |
154| Task Planner | Creates phased implementation plans with validation steps |
155| Task Implementor | Executes plans through subagent delegation and tracks changes |
156| Task Reviewer | Validates completed work against plans and conventions |
157
158Each agent hands off to the next through structured artifacts stored in `.copilot-tracking/`.
159
160### Prompt Engineering
161
162The [Prompt Builder](https://github.com/microsoft/hve-core/blob/main/.github/agents/hve-core/prompt-builder.agent.md) orchestrates a three-phase workflow for creating and refining AI artifacts (agents, prompts, instructions, skills):
163
1641. Execute and evaluate prompt files using sandbox testing
1652. Research findings and best practices
1663. Apply modifications based on evaluation results
167
168It delegates to Prompt Tester, Prompt Evaluator, Prompt Updater, and Researcher subagents.
169
170### Security Review
171
172The [Security Reviewer](https://github.com/microsoft/hve-core/blob/main/.github/agents/security/security-reviewer.agent.md) orchestrates OWASP-based vulnerability assessment through four subagents: Codebase Profiler, Skill Assessor, Finding Deep Verifier, and Report Generator. It supports audit, diff, and plan modes.
173
174### Code Review
175
176The [Functional Code Review](https://github.com/microsoft/hve-core/blob/main/.github/agents/code-review/functional-code-review.agent.md) agent analyzes branch diffs for logic errors, edge case gaps, and error handling deficiencies before code reaches a pull request. The [PR Review](https://github.com/microsoft/hve-core/blob/main/.github/agents/hve-core/pr-review.agent.md) agent provides comprehensive review after PR creation.
177
178### Documentation Operations
179
180The [Doc Ops](https://github.com/microsoft/hve-core/blob/main/.github/agents/hve-core/doc-ops.agent.md) agent audits documentation for style compliance, accuracy against implementation, and coverage gaps.
181
182### Backlog Management
183
184The [GitHub Backlog Manager](https://github.com/microsoft/hve-core/blob/main/.github/agents/github/github-backlog-manager.agent.md) coordinates five workflows (discovery, triage, sprint planning, execution, and quick add) for managing issue lifecycles. The [ADO Backlog Manager](https://github.com/microsoft/hve-core/blob/main/.github/agents/ado/ado-backlog-manager.agent.md) provides equivalent capabilities for Azure DevOps work items.
185
186### Project Planning
187
188Five agents support upstream planning activities:
189
190| Agent | Purpose |
191|------------------------------|------------------------------------------|
192| BRD Builder | Business Requirements Documents |
193| PRD Builder | Product Requirements Documents |
194| ADR Creation | Architecture Decision Records |
195| Architecture Diagram Builder | Visual system architecture diagrams |
196| Security Plan Creator | Security assessment and mitigation plans |
197
198## How It All Connects
199
200```mermaid
201flowchart LR
202 subgraph AUTOMATED["Automated Pipeline"]
203 direction TB
204 TRIAGE["Issue Triage<br/><i>event-driven</i>"]
205 IMPL["Issue Implementation<br/><i>event-driven</i>"]
206 REVIEW["PR Review<br/><i>event-driven</i>"]
207 DEPEND["Dependabot PR Review<br/><i>event-driven</i>"]
208 DOCS["Doc Update Check<br/><i>event-driven</i>"]
209 TRIAGE -- "agent-ready label" --> IMPL
210 IMPL -- "opens PR" --> REVIEW
211 end
212
213 subgraph INTERACTIVE["Interactive Agents"]
214 direction TB
215 RPI["RPI Orchestration"]
216 PB["Prompt Builder"]
217 SR["Security Reviewer"]
218 CR["Code Review"]
219 DOC["Doc Ops"]
220 BM["Backlog Manager"]
221 PP["Project Planning"]
222 end
223
224 subgraph ARTIFACTS["Shared Artifacts"]
225 direction TB
226 INST["Instructions<br/>.github/instructions/"]
227 TRACK[".copilot-tracking/<br/>plans, research, changes"]
228 LABELS["GitHub Labels<br/>and Milestones"]
229 end
230
231 AUTOMATED --> INST
232 INTERACTIVE --> INST
233 RPI --> TRACK
234 BM --> LABELS
235 TRIAGE --> LABELS
236```
237
238The automated pipeline and interactive agents share instruction files for consistent coding standards. Interactive agents produce tracking artifacts that inform implementation. The automated pipeline uses GitHub labels as its coordination mechanism, while interactive agents coordinate through `.copilot-tracking/` files.
239
240---
241
242🤖 Crafted with precision by ✨Copilot following brilliant human instruction, then carefully refined by our team of discerning human reviewers.
243