Engineering Agents Integration - One-Page Specification

This specification is a proposal to integrate Engineering Agents into HVE Core for multi-platform support and enhanced developer experience.

##UPDATE

✅ Per discussion with @WilliamBerryiii The original proposal (#63) has been split into 4 focused implementation issues to enable parallel development and clearer scope, this issue will serve as Epic:

Issue #90 : Product Manager & UX Designer Agents

Agents:

• Product Manager Advisor
• UX/UI Designer

Issue #91 : Responsible AI Agent

Agents:

• Responsible AI Specialist

Issue #92 : System Architecture Reviewer Agent
Integration Point: After @task-researcher, before @task-planner

Key Value:

• Architecture Decision Records (ADRs) preserve institutional knowledge
• Zero repeated architecture debates
• Microsoft Well-Architected Framework validation (AI-specific)
• OWASP security patterns (Top 10, LLM, ML) + Zero Trust

Agents:

• System Architecture Reviewer

Issue #93 : Code Reviewer Agent
Focus: Security validation during development

Key Value:

• OWASP Top 10, LLM Top 10, ML Security Top 10 validation

Agents:

• Code Reviewer

🎯 Overview

Integrate 6 collaborative engineering agents from engineering-team-agents into HVE Core, providing multi-platform support (GitHub Copilot + Claude Code + Agents.md) while enhancing the existing research → plan → implement workflow with quality gates that prevent common development mistakes.

1️⃣ Enhancement to Existing HVE Core

Current HVE Core Workflow

@task-researcher → @task-planner → Implementation → @pr-review

Enhanced Workflow (Agents are Optional Gates)

@product-manager (NEW) → Validates "should we build this?"
    ↓
@task-researcher (EXISTING) → Evidence-based research with clear requirements
    ↓
@architecture-reviewer (NEW) → Documents technical decisions as ADRs
    ↓
@task-planner (EXISTING) → Creates plan with architecture context
    ↓
Implementation (EXISTING) → Developer writes code
    ↓
@code-reviewer (NEW) → Security validation during development (OWASP patterns)
    ↓
@responsible-ai (NEW) → Accessibility compliance check (WCAG 2.1)
    ↓
@pr-review (EXISTING) → Final comprehensive 4-phase review
    ↓
@gitops-specialist (NEW, Optional) → Deployment optimization

Key Enhancement: Quality Gates at Right Moments

• Before Research: Validate user needs (prevent building wrong features)
• After Research: Document architecture decisions (preserve institutional knowledge)
• During Development: Security validation (catch issues early when fixes are small)
• Before PR: Accessibility check (compliance from day one)

2️⃣ Multi-Platform Support

Four Platform Formats (Maximum Compatibility)

Key Integration Principles

1. Preserve HVE Core Philosophy: Agents maintain separation of concerns (research never plans, planner never implements)
2. Additive Only: Zero modifications to existing files
3. Hybrid Documentation: .copilot-tracking/ (ephemeral) + docs/ (permanent ADRs)
4. Consistent Conventions: Follow existing HVE Core patterns (comment policy, markdown standards, commit messages)
5. Token Efficiency: Agents reference docs via file paths, not content duplication

3️⃣ Value Add to Developers (Beyond HVE Core)

Six Collaborative Agents

📊 Product Manager

• Gap Filled: No validation of "should we build this?"
• Value: Asks "Who's the user? What problem? How measure success?" before any work starts
• Outcome: 30-50% faster research (targeted, not exploratory), prevents building unwanted features
• Integration: Pre-gate for @task-researcher - provides clear requirements

🏛️ Architecture Reviewer

• Gap Filled: Technical decisions lost, new developers repeat mistakes
• Value: Creates ADRs (Architecture Decision Records) in docs/architecture/
• Outcome: Institutional knowledge preserved, zero repeated architecture debates
• Integration: Post-research documentation for @task-planner context

🔍 Code Reviewer

• Gap Filled: Security issues found too late (during @PR-Review = large refactors)
• Value: OWASP pattern validation during development (Top 10, LLM Top 10, ML Security)
• Outcome: 80% faster security fixes (caught early when context is fresh)
• Integration: During implementation, before @PR-Review final gate

🎨 UX Designer (Optional)

• Gap Filled: User workflows not validated before building
• Value: Maps user journeys, validates accessibility requirements
• Outcome: User experience validated upfront, not retrofitted
• Integration: Works with product-manager on user-facing features

🌍 Responsible AI

• Gap Filled: Accessibility as afterthought (or forgotten)
• Value: WCAG 2.1 compliance checking, bias prevention
• Outcome: Accessibility built-in from day one, no post-launch scramble
• Integration: Post-implementation gate before @PR-Review

🚀 GitOps Specialist (Optional)

• Gap Filled: Deployment issues discovered in production
• Value: CI/CD optimization, monitoring setup, runbook creation
• Outcome: Reliable deployments with proper observability
• Integration: Post-PR deployment phase

File Structure

hve-core/
├── .claude/agents/                    # Claude Code (6 agents)
│   ├── product-manager.md
│   ├── architecture-reviewer.md
│   ├── code-reviewer.md
│   ├── ux-designer.md
│   ├── responsible-ai.md
│   └── gitops-specialist.md
│
├── .github/
│   ├── agents/                        # GitHub Copilot native (6 agents) - NEW
│   │   └── [same 6 agents as Claude]
│   │
│   └── chatmodes/                     # GitHub Copilot legacy (19 total)
│       ├── [13 existing HVE modes]    # UNCHANGED
│       └── [6 new agent modes]        # NEW
│
├── AGENTS.md                          # Universal format
│
├── docs/                              # Permanent documentation (NEW)
│   ├── architecture/                  # ADRs (version controlled)
│   ├── responsible-ai/                # RAI-ADRs (compliance tracking)
│   └── templates/                     # Documentation templates
│
└── [all existing HVE Core files UNCHANGED]

Developer Experience: Same agents, different platforms, consistent behavior. Switch AI tools anytime.

4️⃣ Implementation Summary

Source Integration

From: niksacdev/engineering-team-agents (MIT License)
To: HVE Core with multi-platform enhancements

Phase 1: Foundation

# Create directory structure
mkdir -p .claude/agents
mkdir -p .github/agents
mkdir -p docs/{architecture,responsible-ai,templates}

# Port 6 agents to Claude format (.claude/agents/)
# Adapt from engineering-team-agents with HVE Core conventions
# - Follow separation of concerns (agents don't mix phases)
# - Integrate with existing .github/instructions/
# - Reference .copilot-tracking/ for ephemeral artifacts

# Port 6 agents to GitHub native format (.github/agents/)
# Standard markdown with simple YAML frontmatter

# Port 6 agents to GitHub chatmodes (.github/chatmodes/*.chatmode.md)
# Match existing HVE Core chatmode patterns

# Create AGENTS.md universal format

# Create documentation templates
# - docs/templates/adr-template.md
# - docs/templates/responsible-ai-adr-template.md

Phase 2: Integration

# Update HVE Core instructions to reference new agents
# Add workflow documentation showing when to use which agent

# Test backward compatibility
# - Verify all 13 existing chatmodes work unchanged
# - Confirm .copilot-tracking/ structure works
# - Validate no breaking changes to existing workflows

# Create setup guides
# - GitHub Copilot setup (native + chatmodes)
# - Claude Code setup
# - Universal AGENTS.md usage

Phase 3: Documentation

# Update README.md
# - Add multi-platform support section
# - Link to agent reference

# Update .github/chatmodes/README.md
# - Add 6 new agent modes to table
# - Update workflow examples

# Create agent reference guide
# - When to use each agent
# - Integration with existing HVE Core
# - Example workflows

Phase 4: Validation

# Platform testing
# - Test all agents in GitHub Copilot (both formats)
# - Test all agents in Claude Code
# - Validate AGENTS.md with other tools

# Regression testing
# - Confirm no existing HVE Core functionality broken
# - Validate all existing tests pass
# - Check all scripts still work

# User acceptance
# - Question-first workflow validated
# - ADR creation works
# - Security/accessibility checks functional

File Count Impact

Before: 13 chatmodes
After:  31 agent files total
  - .github/chatmodes/: 19 files (13 existing + 6 new)
  - .github/agents/: 6 files (NEW)
  - .claude/agents/: 6 files (NEW)
  - docs/: ~10 files (templates + READMEs)
  - AGENTS.md: 1 file

Total: ~34 new files (all additive, zero modifications)

✅ Success Criteria

Technical

• All 6 agents work in Claude Code (.claude/agents/) — .claude/agents/ does not exist
• All 6 agents work in GitHub Copilot native (.github/agents/) — 3 of 6 delivered; code-reviewer, responsible-ai, gitops-specialist not found
• All 6 agents work in GitHub Copilot legacy (.github/chatmodes/) — Architecture pivoted; .github/chatmodes/ removed
• AGENTS.md provides universal format — Not created
• No existing HVE Core functionality broken
• All existing tests pass

User Experience

• @product-manager validates requirements before research — Delivered as product-manager-advisor.agent.md
• @architecture-reviewer creates ADRs after research — Delivered as system-architecture-reviewer.agent.md
• @code-reviewer provides security validation during development — Agent not found in codebase
• @responsible-ai checks accessibility before PRs — Agent not found in codebase
• Multi-platform support confirmed (Claude + Copilot minimum) — Only GitHub Copilot native has agents

Documentation

• Setup guide for each platform
• Agent reference with integration patterns
• README updated with multi-agent capabilities
• Workflow examples showing agent usage