[Pelis Agent Factory Advisor] Agentic Workflow Advisory — April 2026

[github-actions[bot]]

📊 Executive Summary

gh-aw-firewall has one of the most mature agentic workflow estates in the Pelis Agent Factory ecosystem — 37 agentic .md workflow files covering security, smoke testing, CI monitoring, documentation, token optimization, and issue management. The repository is an excellent reference for best practices. The top near-term opportunities are: an AWF-specific PR code reviewer that enforces firewall security boundaries, a container image security scanner (critical for a security tool that ships Docker images), and Dependabot PR bundling to reduce dependency-update noise.

---

🎓 Patterns Learned from Pelis Agent Factory

Pattern	Description	Used here?
Shared modules	Reusable .md fragments via imports:	✅ Yes — shared/gh.md, shared/reporting.md, shared/mcp-pagination.md, etc.
Cache-memory for state	Persistent key-value across runs	✅ Yes — issue-duplication-detector, pelis-agent-factory-advisor
skip-if-match guard	Prevent duplicate issues/PRs	✅ Yes — most write workflows use it
Multi-engine smoke tests	Validate Claude, Copilot, Codex, OpenCode	✅ Yes — all four engines
Token optimization loop	Analyzer → Optimizer chained via workflow_run	✅ Yes — both Claude and Copilot
CI Doctor	Automated failure investigation	✅ Yes — very complete
Contribution Guidelines Checker	Agentic PR compliance checks	❌ Missing
Dependabot PR Bundler	Group dep updates into single PR	❌ Missing
Container Security Scanner	Image vulnerability scanning agent	❌ Missing
Weekly repo status	Activity digest for maintainers	❌ Missing
PR Code Reviewer	Domain-specific agentic code review	❌ Missing (security-guard covers security changes, but not general review)
VEX Generator	OpenVEX statements for dismissed Dependabot alerts	❌ Missing
Duplicate Code Detector	Codebase refactoring opportunities	❌ Missing

---

📋 Workflow Inventory

Workflow	Purpose	Trigger	Assessment
smoke-claude	Validates Claude engine end-to-end via PR review	schedule 12h + PR + reaction	✅ Healthy — good coverage
smoke-copilot	Validates Copilot engine end-to-end	schedule 12h + PR + reaction	✅ Healthy
smoke-codex	Validates Codex engine + firewall capabilities	schedule 12h + PR + reaction	✅ Healthy
smoke-opencode	Validates OpenCode engine end-to-end	schedule 12h + PR + reaction	✅ Healthy
smoke-chroot	Validates chroot host binary access	PR (paths filter) + reaction	✅ Good path filtering
smoke-services	Validates --allow-host-service-ports (Redis/PG)	schedule 12h + PR + reaction	✅ Unique coverage
build-test	Multi-language build test suite	PR + dispatch	✅ Good multi-runtime support
security-guard	Reviews PRs for security boundary weakening	PR + dispatch	✅ Strong — 8 max turns
security-review	Daily threat modeling with evidence	schedule daily	✅ Comprehensive
secret-digger-claude	Red team secret exposure testing (Claude)	dispatch only	✅ Intentionally manual
secret-digger-codex	Red team secret exposure testing (Codex)	dispatch only	✅ Intentionally manual
secret-digger-copilot	Red team secret exposure testing (Copilot)	dispatch only	✅ Intentionally manual
dependency-security-monitor	Daily CVE monitoring + safe update PRs	schedule daily	✅ Good 24h detection SLA
ci-doctor	Automated CI failure root-cause investigation	workflow_run failed	✅ Very mature — monitors 30+ workflows
ci-cd-gaps-assessment	Daily gap analysis of CI/CD pipelines	schedule daily	✅ Meta-workflow
issue-monster	Assigns open issues to Copilot agents	issues opened + schedule 1h	✅ Active backlog burner
issue-duplication-detector	Detects duplicate issues with cache-memory	issues opened	✅ Good use of cache
firewall-issue-dispatcher	Cross-repo: gh-aw → gh-aw-firewall issue sync	schedule 6h	✅ Unique cross-repo pattern
doc-maintainer	Weekly documentation sync with code changes	schedule daily	✅ Good skip-if-match guard
test-coverage-improver	Weekly security-focused test coverage PRs	schedule weekly	✅ Security-prioritized
cli-flag-consistency-checker	Weekly CLI flag vs docs consistency	schedule weekly	✅ Good quality gate
claude-token-usage-analyzer	Daily token usage analysis (Claude)	schedule daily	✅ Good observability
claude-token-optimizer	Creates optimization recommendations	workflow_run chained	✅ Good chaining pattern
copilot-token-usage-analyzer	Daily token usage analysis (Copilot)	schedule daily	✅ Mirrors Claude pattern
copilot-token-optimizer	Creates optimization recommendations	workflow_run chained	✅ Consistent pattern
update-release-notes	Updates release notes on publish	release: published	✅ Event-driven
plan	/plan slash command for issue decomposition	slash_command	✅ Good self-service UX
pelis-agent-factory-advisor	This workflow — daily advisory	schedule daily	✅ Meta
shared/gh.md	Reusable GitHub MCP config	import	✅ DRY
shared/reporting.md	Reusable reporting helpers	import	✅ DRY
shared/mcp-pagination.md	MCP pagination pattern	import	✅ Good pattern
shared/secret-audit.md	Shared red-team audit instructions	import	✅ Good DRY for diggers
shared/version-reporting.md	Version reporting helpers	import	✅
shared/mcp/gh-aw.md	AWF MCP tool configuration	import	✅
shared/mcp/tavily.md	Tavily search MCP	import	✅

---

🚀 Recommendations

P0 — High Impact, Low Effort (Implement Now)

1. 🔍 AWF-Specific PR Code Reviewer

What: A PR-triggered agentic reviewer that goes beyond security-guard's security focus to check code quality, patterns, and AWF conventions.
Why: security-guard detects security weakening, but doesn't check: correct --allow-domains patterns in tests, proper iptables rule ordering, Docker Compose health-check patterns, or test structure. This fills the gap.
How:

on:
  pull_request:
    types: [opened, synchronize]
engine:
  id: claude
  max-turns: 6
safe-outputs:
  add-comment:
    max: 1

Check for: consistent iptables rule ordering, correct base64 config injection pattern, domain ACL format, test coverage of new features.
Effort: Low — similar to existing security-guard structure
Pelis reference: Grumpy Reviewer / PR Nitpick Reviewer patterns

---

2. 📦 Dependabot PR Bundler

What: Weekly agent that groups Dependabot PRs (especially patch-level npm and Docker base image updates) into a single bundled PR.
Why: The repo has many dependencies (package.json + container base images). Individual Dependabot PRs create review fatigue and the dependency-security-monitor already identifies safe updates. The bundler closes the loop by creating actionable PRs.
How:

on:
  schedule: weekly
  skip-if-match:
    query: 'is:pr is:open in:title "[deps bundle]"'
    max: 1
safe-outputs:
  create-pull-request:
    title-prefix: "[deps bundle] "
    labels: [dependencies, ai-generated]

Effort: Low — Pelis Agent Factory has a reference implementation
Pelis reference: Dependabot PR Bundler

---

P1 — High Impact, Medium Effort (Near-Term)

3. 🐳 Container Image Security Scanner

What: Weekly agentic workflow that runs trivy or grype against the published GHCR images (ghcr.io/github/gh-aw-firewall/squid, agent, api-proxy) and creates issues for HIGH/CRITICAL CVEs in base images.
Why: AWF ships Docker images to GHCR used in production security-sensitive environments. Base images (ubuntu/squid:latest, ubuntu:22.04) accumulate OS-level CVEs over time. The existing dependency-audit.yml and dependency-security-monitor cover npm packages — not container OS packages. This is a significant blind spot for a security firewall tool.
How:

on:
  schedule: weekly
  workflow_dispatch:
tools:
  bash:
    - "trivy:*"
    - "docker:*"
safe-outputs:
  create-issue:
    title-prefix: "[container-cve] "
    labels: [security, container]

Effort: Medium — needs Trivy setup step, GHCR pull permissions
Pelis reference: Daily Malicious Code Scan + VEX Generator patterns

---

4. 📊 Weekly Repository Status Report

What: Weekly digest of repository activity: PRs merged, issues opened/closed, agentic workflow health, token usage trends, top contributors.
Why: The repo has excellent per-topic workflows (CI Doctor, security-review, token analyzers) but no single weekly digest that synthesizes health across all dimensions. Maintainers currently must read multiple sources.
How:

on:
  schedule: weekly
safe-outputs:
  create-discussion:
    category: "general"
    title-prefix: "[Weekly Status] "

Aggregate: workflow success rates (via agentic-workflows tool), open issue counts, dependency update backlog, recent CVEs.
Effort: Medium — requires aggregating across multiple data sources
Pelis reference: Weekly Issue Summary / Daily Repo Status patterns

---

5. ✅ Contribution Guidelines Checker

What: PR-triggered agent that verifies contributions comply with CONTRIBUTING.md and AGENTS.md conventions: commit message format, test coverage for new code, documentation updates, correct copyright headers.
Why: CONTRIBUTING.md and AGENTS.md/CLAUDE.md are detailed and project-specific. Human reviewers must check these manually today. The security-guard focuses on security impact, not compliance.
How:

on:
  pull_request:
    types: [opened, synchronize, reopened]
engine: copilot
safe-outputs:
  add-comment:
    max: 1

Check: TypeScript types present, npm run build + npm test would pass for changed files, docs updated if CLI flags changed, smoke workflow .lock.yml recompiled if .md changed.
Effort: Medium — needs careful prompt engineering to avoid false positives
Pelis reference: Contribution Guidelines Checker

---

P2 — Medium Impact (Backlog)

6. 🔗 Link Fixer Agent

What: Extend the existing link-check.yml (which finds broken links) with an agentic workflow that creates PRs to fix them.
Why: The link-check.yml CI workflow finds broken links but creates no action item — someone must manually fix them. An agent could auto-update URLs or remove dead links.
Effort: Low-Medium
Pelis reference: Link Checker (auto-fix variant)

---

7. 🔍 Duplicate Code Detector

What: Monthly agent that scans src/ for duplicated logic patterns (e.g., repeated Docker Compose generation code, duplicated iptables rule patterns) and creates refactoring issues.
Why: src/docker-manager.ts is large (2000+ lines per CLAUDE.md). Regular duplicate detection prevents entropy accumulation.
Effort: Medium
Pelis reference: Duplicate Code Detector

---

8. ⚡ Agentic Performance Improver

What: Monthly agent that reads performance-monitor.yml results, identifies regressions or slow paths, and creates PRs to optimize hot code paths (e.g., Docker Compose startup time, squid config generation).
Why: performance-monitor.yml collects data but creates no action items. Closing the loop with an agent improves the "measure → act" cycle.
Effort: Medium
Pelis reference: Daily Perf Improver

---

9. 🔒 VEX Generator

What: Automated OpenVEX statement generator for dismissed Dependabot alerts, capturing security assessments in machine-readable format.
Why: AWF already has dependency-security-monitor that detects vulnerabilities. When alerts are dismissed (e.g., "not applicable in our container context"), generating OpenVEX statements documents the rationale and enables downstream tooling.
Effort: Medium
Pelis reference: VEX Generator

---

P3 — Nice to Have

10. 📅 Release Readiness Agent

What: Weekly agent that analyzes commits since last tag, checks if conventional commit messages suggest a release is warranted, and creates a "release readiness" discussion with suggested version bump and changelog draft.
Why: update-release-notes.md triggers after a release is published. A readiness agent surfaces the release decision — currently a manual judgment call.
Effort: Medium-High

---

11. 🏋️ Daily File Diet

What: Monitor source files that exceed size thresholds (e.g., src/docker-manager.ts > 2000 lines) and create tracked refactoring issues.
Why: Large files are harder to review, test, and maintain. Early warning prevents growth.
Effort: Low
Pelis reference: Daily File Diet

---

12. 🔬 Formal Verification Scout

What: Agent that identifies pure functions in src/squid-config.ts and src/host-iptables.ts suitable for property-based testing or formal verification — the security-critical ACL generation logic.
Why: AWF's domain-whitelist ACL generation and iptables rule construction are security-critical pure functions. Formal correctness guarantees here would be highly valuable.
Effort: High
Pelis reference: Lean Squad

---

📈 Maturity Assessment

Dimension	Current (1–5)	Target	Gap
Smoke / E2E Testing	5	5	✅ None — 6 smoke workflows, all 4 engines
Security Automation	4	5	Container image CVE scanning missing
CI/CD Quality	4	5	PR code review agent missing
Dependency Management	3	4	Bundling and VEX generation missing
Documentation	4	4	✅ doc-maintainer covers this well
Issue Management	5	5	✅ Monster + dedup + dispatcher
Observability	5	5	✅ Token analyzers + CI Doctor excellent
Release Automation	3	4	Release readiness agent missing
Code Quality	3	4	Duplicate detector, file diet missing

Overall: 4.0/5 → Target 4.6/5

---

🔄 Best Practice Comparison

What This Repo Does Exceptionally Well

1. Multi-engine validation — Smoke testing all four engines (Claude, Copilot, Codex, OpenCode) every 12h is industry-leading
2. Security-first mindset — Three separate secret-digger agents, daily security review, PR security guard
3. Token economics — Dual analyzer→optimizer chains for both Claude and Copilot is best-in-class
4. Shared module architecture — The shared/ folder with reusable imports is the right pattern for a large workflow estate
5. Cross-repo coordination — firewall-issue-dispatcher pulling from upstream gh-aw is a sophisticated pattern
6. CI Doctor with full workflow list — Monitoring 30+ workflows for failures is comprehensive

What Could Be Improved

1. PR review coverage — security-guard is excellent but narrow; no general quality review
2. Container security blind spot — No image-level CVE scanning despite publishing to GHCR
3. Dependabot noise — Many individual Dependabot PRs without bundling
4. Release loop — Update-release-notes exists but no release readiness signal
5. Missing ci-doctor entries — Several newer workflows not yet in CI Doctor's monitored list (e.g., Pelis Agent Factory Advisor)

---

📝 Notes

Cache update: Hash c835d85816ba5c913e7457be28bf1b55a5f2f5015298344bf3e8121250b59261 observed for Pelis docs. Cache-memory write skipped (permission denied in this run).

Priority action items:

1. Add Dependabot PR Bundler — lowest effort, clear value
2. Add container image security scanner — highest security value given the repo's purpose
3. Add AWF-specific PR reviewer — improves code quality feedback loop
4. Add newer agentic workflows to CI Doctor's monitored list

Patterns to carry forward:

• The workflow_run chaining pattern (analyzer → optimizer) works very well and should be applied to the container security scanner (scan → remediation issue)
• The shared/ module pattern should be extended with a shared/container-security.md for reusable Trivy scan instructions
• skip-if-match guards are consistently applied — maintain this discipline for all new write workflows

Generated by Pelis Agent Factory Advisor · ● 674.9K · ◷

• expires on Apr 22, 2026, 10:54 AM UTC

[github-actions[bot]]

This discussion was automatically closed because it expired on 2026-04-22T10:54:04.965Z.

Closed by Workflow