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
23be43f9eb4e5c4524397014accacc4b303fec29

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

249lines · 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` for non-maintainer PRs, advisory `COMMENT` only for maintainer PRs |
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<!-- markdownlint-disable-next-line MD028 -->
112
113> [!NOTE]
114> **Maintainer advisory mode.** When the PR author is a `MEMBER`, `OWNER`, or `COLLABORATOR`, the PR Review Agent switches to advisory mode: it posts a `COMMENT` review prefixed with "Advisory review …", never uses `REQUEST_CHANGES`, does not add the `needs-revision` label, and does not convert the PR to draft.
115>
116> **`skip-review` label guard.** The `skip-review` label only skips the PR Review workflow when the PR author's association is `MEMBER`, `OWNER`, or `COLLABORATOR`; PRs from other authors are reviewed normally even when the label is present.
117
118## Workflow Configuration
119
120All five workflows are defined as GitHub Agentic Workflow markdown files under `.github/workflows/` and compiled to lock files using `gh aw compile`:
121
122| Workflow File | Lock File | Trigger | Agent |
123|---------------------------|---------------------------------|----------------------------------------|------------------------|
124| `issue-triage.md` | `issue-triage.lock.yml` | Issue opened or labeled `needs-triage` | Issue Triage Agent |
125| `issue-implement.md` | `issue-implement.lock.yml` | Issue labeled `agent-ready` | Task Implementor Agent |
126| `pr-review.md` | `pr-review.lock.yml` | PR opened or marked ready for review | PR Review Agent |
127| `dependency-pr-review.md` | `dependency-pr-review.lock.yml` | Dependabot PR opened or updated | Dependency Reviewer |
128| `doc-update-check.md` | `doc-update-check.lock.yml` | Push to main | Documentation Checker |
129
130Each workflow file declares permissions, safe output limits, and activation guards that prevent unintended execution.
131
132## Label-Driven Handoffs
133
134Labels serve as the event bus connecting workflows. Each label transition triggers the next stage:
135
136```mermaid
137stateDiagram-v2
138 [*] --> needs_triage: Issue opened
139 needs_triage --> classified: Triage removes needs-triage,<br/>adds type + component labels
140 classified --> agent_ready: Triage adds agent-ready<br/>(if criteria met)
141 classified --> human_review: Criteria not met,<br/>awaits human labeling
142 agent_ready --> pr_opened: Implementation agent<br/>opens PR
143 pr_opened --> review_passed: Review agent approves
144 pr_opened --> needs_revision: Review agent requests changes
145 needs_revision --> pr_opened: Author pushes fixes
146 review_passed --> merged: Maintainer merges
147 merged --> [*]
148```
149
150## Interactive Agent Workflows
151
152Beyond 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.
153
154### RPI Orchestration
155
156The [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:
157
158| Agent | Role |
159|------------------|----------------------------------------------------------------|
160| Task Researcher | Deep codebase and domain analysis, produces research documents |
161| Task Planner | Creates phased implementation plans with validation steps |
162| Task Implementor | Executes plans through subagent delegation and tracks changes |
163| Task Reviewer | Validates completed work against plans and conventions |
164
165Each agent hands off to the next through structured artifacts stored in `.copilot-tracking/`.
166
167### Prompt Engineering
168
169The [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):
170
1711. Execute and evaluate prompt files using sandbox testing
1722. Research findings and best practices
1733. Apply modifications based on evaluation results
174
175It delegates to Prompt Tester, Prompt Evaluator, Prompt Updater, and Researcher subagents.
176
177### Security Review
178
179The [Security Reviewer](https://github.com/microsoft/hve-core/blob/main/.github/agents/security/security-reviewer.agent.md) orchestrates security skill assessment through four subagents: Codebase Profiler, Skill Assessor, Finding Deep Verifier, and Report Generator. It supports audit, diff, and plan modes across OWASP and Secure by Design frameworks.
180
181### Code Review
182
183The [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.
184
185### Documentation Operations
186
187The [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.
188
189### Backlog Management
190
191The [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.
192
193### Project Planning
194
195Five agents support upstream planning activities:
196
197| Agent | Purpose |
198|------------------------------|------------------------------------------|
199| BRD Builder | Business Requirements Documents |
200| PRD Builder | Product Requirements Documents |
201| ADR Creation | Architecture Decision Records |
202| Architecture Diagram Builder | Visual system architecture diagrams |
203| Security Plan Creator | Security assessment and mitigation plans |
204
205## How It All Connects
206
207```mermaid
208flowchart LR
209 subgraph AUTOMATED["Automated Pipeline"]
210 direction TB
211 TRIAGE["Issue Triage<br/><i>event-driven</i>"]
212 IMPL["Issue Implementation<br/><i>event-driven</i>"]
213 REVIEW["PR Review<br/><i>event-driven</i>"]
214 DEPEND["Dependabot PR Review<br/><i>event-driven</i>"]
215 DOCS["Doc Update Check<br/><i>event-driven</i>"]
216 TRIAGE -- "agent-ready label" --> IMPL
217 IMPL -- "opens PR" --> REVIEW
218 end
219
220 subgraph INTERACTIVE["Interactive Agents"]
221 direction TB
222 RPI["RPI Orchestration"]
223 PB["Prompt Builder"]
224 SR["Security Reviewer"]
225 CR["Code Review"]
226 DOC["Doc Ops"]
227 BM["Backlog Manager"]
228 PP["Project Planning"]
229 end
230
231 subgraph ARTIFACTS["Shared Artifacts"]
232 direction TB
233 INST["Instructions<br/>.github/instructions/"]
234 TRACK[".copilot-tracking/<br/>plans, research, changes"]
235 LABELS["GitHub Labels<br/>and Milestones"]
236 end
237
238 AUTOMATED --> INST
239 INTERACTIVE --> INST
240 RPI --> TRACK
241 BM --> LABELS
242 TRIAGE --> LABELS
243```
244
245The 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.
246
247---
248
249🤖 Crafted with precision by ✨Copilot following brilliant human instruction, then carefully refined by our team of discerning human reviewers.
250