Agentic Workflows

hve-core uses GitHub Agentic Workflows to support the journey from issue creation through implementation, code review, and dependency management. Six workflows connect specialized agents through labels, pull requests, comments, GitHub events, and manual slash commands.

NOTE

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.

End-to-End Process Flow

Workflow Details

Workflow	Trigger	Execution Owner	Key Actions
Issue Triage	Issue opened or labeled needs-triage	Issue Triage Agent	Classify, detect duplicates, assess quality, label, evaluate readiness
Issue Implementation	Issue labeled agent-ready	Workflow-owned procedure in .github/workflows/issue-implement.md	Research codebase, plan changes, implement, open PR
PR Review	User with admin, maintainer, or write access posts /review in a PR conversation or inline review comment	Code Review Agent	Add review-passed for clean reviews; request changes and add needs-revision for blocking non-maintainer findings; also convert non-maintainer PRs to draft for five or more critical findings; or submit COMMENT without an outcome label for advisory and non-blocking findings
Dependabot PR Review	Dependabot PR opened or updated	Dependency Reviewer Agent	Validate licensing, SHA pinning, and environment sync; post COMMENT or REQUEST_CHANGES; leave approval and merge to humans
Documentation Update Check	Push to main	Documentation Agent (drift mode)	Map code changes to docs, flag stale documentation for follow-up
VEX Draft	workflow_run after VEX Detection succeeds, or workflow_dispatch	SSSC Reviewer	Enrich CVEs, analyze reachability, open one PR with OpenVEX draft statements for human review

TIP

The triage agent classifies issues, applies type, area, and priority labels, detects duplicates, assesses quality, and marks qualifying issues agent-ready. It does not create sub-issues, close issues, assign users, or modify issue titles.

NOTE

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.

NOTE

Maintainer advisory mode. When the PR author is a MEMBER, OWNER, or COLLABORATOR, the Code 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.

Workflow Configuration

All six workflows are defined as GitHub Agentic Workflow markdown files under .github/workflows/ and compiled to lock files using gh aw compile:

Workflow File	Lock File	Trigger	Execution Owner
issue-triage.md	issue-triage.lock.yml	Issue opened or labeled needs-triage	Issue Triage Agent
issue-implement.md	issue-implement.lock.yml	Issue labeled agent-ready	Workflow-owned procedure
pr-review.md	pr-review.lock.yml	User with admin, maintainer, or write access posts /review in a PR comment	Code Review Agent
dependency-pr-review.md	dependency-pr-review.lock.yml	Dependabot PR opened or updated	Dependency Reviewer
doc-update-check.md	doc-update-check.lock.yml	Push to main	Documentation Agent
vex-draft.md	vex-draft.lock.yml	VEX Detection workflow_run + dispatch	SSSC Reviewer

Each workflow file declares permissions, safe output limits, and activation guards that prevent unintended execution.

Lock File Ownership

The *.lock.yml files under .github/workflows/ are generated outputs of gh aw compile. Editing them directly is not supported: the next compile overwrites the change. Edit the source .md workflow instead, then recompile.

Because these files are generated, Dependabot is configured to leave them alone. .github/dependabot.yml excludes the .github/workflows/*.lock.yml path and the github/gh-aw-actions/* action family, so action bumps inside a lock file never arrive as a pull request.

Upgrading gh-aw-actions

The gh-aw-actions version is tied to the gh aw compiler release, not set independently, and Dependabot does not manage it. Since compiler v0.85.4 the github/gh-aw-actions/* family no longer resolves through .github/aw/actions-lock.json: the compiler emits the mutable tag github/gh-aw-actions/<action>@vX.Y.Z by default, and --action-tag is written to the lock files verbatim.

No compiler flag emits both an immutable SHA and a version comment, so the repository supplies the SHA at compile time and the version comment afterward:

1. Upgrade the gh aw CLI/compiler to the target release.

2. Resolve the matching gh-aw-actions release tag to its commit SHA: gh api repos/github/gh-aw-actions/commits/vX.Y.Z --jq '.sha'.

3. Recompile every workflow against that immutable commit: gh aw compile --action-mode action --action-tag <sha>.

4. Restore the version comments that the compiler omits, so SHA-pinned actions stay traceable:

   $sha = '<sha>'
   $files = @('.github/workflows/agentics-maintenance.yml') + (Get-ChildItem .github/workflows -Filter '*.lock.yml').FullName
   foreach ($file in $files) {
       $raw = [System.IO.File]::ReadAllText($file)
       $annotated = [regex]::Replace($raw, "(github/gh-aw-actions/[^@\s]+@$sha)(?=\r?`$)", '$1 # vX.Y.Z', 'Multiline')
       [System.IO.File]::WriteAllText($file, $annotated, (New-Object System.Text.UTF8Encoding($false)))
   }

5. Run npm run lint:dependency-pinning and npm run lint:version-consistency to confirm the generated workflows satisfy both the SHA-pinning and version-comment policies.

6. Commit .github/aw/actions-lock.json, the regenerated lock files, and agentics-maintenance.yml together.

Because the pinned version is version-locked to the compiler that produces the lock files, the bump and the recompile belong in the same change.

Label-Driven Handoffs

Labels coordinate automated issue stages and review outcomes. A /review comment from a user with admin, maintainer, or write access starts the PR Review workflow after a pull request opens:

Interactive Agent Workflows

Beyond the repository-hosted GitHub workflows, hve-core provides interactive agents invoked through VS Code Copilot Chat. These agents support the manual side of the development lifecycle.

RPI Orchestration

The RPI Agent coordinates Research, Plan, Implement, Review, and Follow-up by activating four reusable phase skills:

Skill	Responsibility
rpi-research	Closes demonstrated evidence gaps and produces research evidence
rpi-plan	Creates a marker-addressed task-centered plan and independent critique
rpi-implement	Executes approved work and records changes, amendments, and validation
rpi-review	Reconciles evidence, records findings, and routes the next action

The skills coordinate through durable artifacts stored in .copilot-tracking/.

Prompt Engineering

The hve-builder skill uses one lifecycle for agents, prompts, instructions, subagents, and skills:

1. Resolve mode, targets, write boundary, architecture, and applicable conventions
2. Author or perform read-only review according to the selected mode
3. Complete all known edits, fresh-context static review, and local validation before freezing the candidate and resolving one final behavior gate. Major mutations and behavior-bearing review targets invoke HVE Builder Tester at most once; eligible no-runtime review targets and Minor or Medium mutations are satisfied-and-skipped. A behavior finding ends the current run and becomes input to a later invocation rather than a same-run edit and retest
4. Keep known target files and caller-supplied canonical references as bounded lifecycle reads; activate rpi-research for open-ended exploration and decision-critical research
5. Run non-mutating host validation and resolve one overall outcome

HVE Builder selects a reasoning profile when it delegates isolated work. Fresh-context static review uses Medium. HVE Builder Tester executes the frozen target at its own profile and grades the evidence at the higher of Medium and that target profile. The lifecycle lead keeps bounded authoring and local validation in the current context rather than creating a worker turn for each stage.

Each ordered list is an availability fallback within its selected profile. The retained prompt-builder, prompt-analyze, and prompt-refactor skills remain compatibility aliases that route legacy requests to this lifecycle.

Security Review

The Security Reviewer 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.

Code Review

The Code Review agent reviews branch diffs through one or more perspectives (functional, standards, accessibility, security, and PR-level) and merges them into a single human-gated report. It runs before code reaches a pull request and also backs the PR Review workflow after PR creation.

Documentation Operations

The Documentation agent coordinates documentation audit, drift, authoring, and validation work through its four modes, covering style compliance, accuracy against implementation, and coverage gaps.

Backlog Management

The Backlog Manager resolves the backing tracker at runtime and coordinates work discovery, triage, sprint planning, assigned-work retrieval, task planning, and execution across Azure DevOps, GitHub, and Jira. Its planning modes are read-only and produce reviewed handoffs, and a separate execution pass applies those handoffs under a three-tier autonomy model with dry-run preview.

The Functional Planner turns a PRD into a validated work item hierarchy handoff and never mutates a tracker.

Project Planning

Five agents support upstream planning activities:

Agent	Purpose
BRD Builder	Business Requirements Documents
PRD Builder	Product Requirements Documents
ADR Creation	Architecture Decision Records
Architecture Diagrams Skill	ASCII system architecture diagrams
Security Plan Creator	Security assessment and mitigation plans

How It All Connects

The repository-hosted workflows and interactive agents share instruction files for consistent coding standards. Interactive agents produce tracking artifacts that inform implementation. Repository-hosted workflows coordinate through labels, pull requests, comments, GitHub events, and manual slash commands, while interactive agents coordinate through .copilot-tracking/ files.

---

🤖 Crafted with precision by ✨Copilot following brilliant human instruction, then carefully refined by our team of discerning human reviewers.