feat: add AgentShield CI standard and agent-shield.yml workflow template

standards/agent-standards.md

@@ -0,0 +1,94 @@
+# Agent Configuration Standards
+
+Standards for repositories that use AI agent configurations (CLAUDE.md,
+AGENTS.md, BMAD modules, Claude plugins, MCP server configs).
+
+---
+
+## Required Files
+
+Every repository MUST have:
+
+| File | Purpose | Compliance Check |
+|------|---------|-----------------|
+| `CLAUDE.md` | Project-level instructions for Claude Code | error if missing |
+| `AGENTS.md` | Development standards for AI agents | error if missing |
+
+### CLAUDE.md Requirements
+
+- MUST reference `AGENTS.md` for development standards
+- MUST NOT contain secrets, API keys, or credentials
+- MUST NOT contain overly permissive tool authorization (e.g., `dangerouslySkipPermissions`)
+- SHOULD define project-specific context (tech stack, conventions, key files)
+
+### AGENTS.md Requirements
+
+- MUST reference the org-level standards: `petry-projects/.github/AGENTS.md`
+- MUST define project-specific development standards (testing, code style, architecture)
+- MUST NOT override org-level security policies
+
+## Agent Configuration Security
+
+The workflow uses a **two-layer** approach:
+
+### Layer 1: AgentShield Action (deep security scan)
+
+The [`affaan-m/agentshield`](https://github.com/affaan-m/agentshield) GitHub
+Action performs a comprehensive security scan with **102 rules** across 5
+categories:
+
+| Category | Rules | Coverage |
+|----------|------:|----------|
+| Secrets Detection | 10 rules, 14 patterns | API keys, tokens, credentials, env leaks |
+| Permission Audit | 10 rules | Wildcard access, missing deny lists, dangerous flags |
+| Hook Analysis | 34 rules | Command injection, data exfiltration, silent errors |
+| MCP Server Security | 23 rules | High-risk servers, supply chain, hardcoded secrets |
+| Agent Config Review | 25 rules | Prompt injection, auto-run, hidden instructions |
+
+The action produces a graded security report (A–F, 0–100 score) and fails
+the build if findings at or above `high` severity are detected.
+
+**CLI reference (used via `npx` in CI — no install required):**
+
+```yaml
+- name: AgentShield Security Scan
+  run: |
+    npx ecc-agentshield@1.4.0 scan \
+      --path . \
+      --min-severity high \
+      --format terminal
+```
+
+### Layer 2: Org-specific structural checks
+
+Custom checks that enforce petry-projects conventions not covered by the
+generic AgentShield scanner:
+
+| Rule | Severity | Description |
+|------|----------|-------------|
+| `required-files` | error | CLAUDE.md and AGENTS.md must exist |
+| `claude-reference` | error | CLAUDE.md must reference AGENTS.md |
+| `org-reference` | error | AGENTS.md must reference `petry-projects/.github/AGENTS.md` |
+| `valid-frontmatter` | error | All SKILL.md files must have YAML frontmatter with `name` and `description` |
+
+## AgentShield CI Workflow
+
+Every repository MUST include `.github/workflows/agent-shield.yml`.
+See [`workflows/agent-shield.yml`](workflows/agent-shield.yml) for the
+standard template.
+
+**Standard triggers:** push to main, pull requests to main.
+
+The workflow runs both the AgentShield action and the org structural checks.
+Either layer failing causes the build to fail.
+
+## Agent Ecosystem in Dependabot
+
+Repositories with BMAD modules or Claude plugins should track agent
+dependencies. While Dependabot does not have a native "agents" ecosystem,
+the AgentShield CI workflow performs equivalent version and security checks
+on agent configuration files.
+
+For repos with `package.json` referencing BMAD modules (e.g., `bmad-method`,
+`bmad-bgreat-suite`), the `npm` ecosystem already covers version tracking.
+The AgentShield action adds the agent-specific security layer on top.

standards/ci-standards.md

@@ -8,10 +8,10 @@ repository must implement.
 
 ## Required Workflows
 
-Every repository MUST have these workflows. Reusable templates for Dependabot
-workflows are in [`standards/workflows/`](workflows/). The CI, CodeQL,
-SonarCloud, and Claude Code workflows are documented as patterns below — copy
-and adapt the examples to each repo's tech stack.
+Every repository MUST have these 7 workflows. Reusable templates for Dependabot
+and AgentShield workflows are in [`standards/workflows/`](workflows/). The CI,
+CodeQL, SonarCloud, and Claude Code workflows are documented as patterns
+below — copy and adapt the examples to each repo's tech stack.
 
 ### 1. CI Pipeline (`ci.yml`)
 
@@ -205,6 +205,14 @@ Vulnerability scanning for all package ecosystems.
 See [`workflows/dependency-audit.yml`](workflows/dependency-audit.yml)
 and the [Dependabot Policy](dependabot-policy.md).
 
+### 7. AgentShield (`agent-shield.yml`)
+
+Agent configuration security validation. Checks that CLAUDE.md and
+AGENTS.md exist and follow standards, scans for secrets in agent config
+files, validates SKILL.md frontmatter, and detects permission bypasses.
+See [`workflows/agent-shield.yml`](workflows/agent-shield.yml) and the
+[Agent Configuration Standards](agent-standards.md) for full details.
+
 ---
 
 ## Workflow Patterns by Tech Stack
@@ -454,9 +462,10 @@ autofix:
 6. **Add `dependabot.yml`** from the appropriate template in [`standards/dependabot/`](dependabot/)
 7. **Add `dependabot-automerge.yml`** from [`standards/workflows/`](workflows/)
 8. **Add `dependency-audit.yml`** from [`standards/workflows/`](workflows/)
-9. **Configure secrets** in the repository settings
-10. **Set required status checks** in branch protection (see [GitHub Settings](github-settings.md))
-11. **Pin all action references** to commit SHAs
+9. **Add `agent-shield.yml`** from [`standards/workflows/`](workflows/)
+10. **Configure secrets** in the repository settings
+11. **Set required status checks** in branch protection (see [GitHub Settings](github-settings.md))
+12. **Pin all action references** to commit SHAs
 
 ---
 

standards/workflows/agent-shield.yml

@@ -0,0 +1,103 @@
+# AgentShield — Agent configuration security validation
+# See: standards/agent-standards.md
+#
+# Two-layer approach:
+#   1. affaan-m/agentshield action — deep security scan (102 rules across
+#      secrets, permissions, hooks, MCP servers, and agent config)
+#   2. Org-specific structural checks — required files, cross-references,
+#      SKILL.md frontmatter validation
+
+name: AgentShield
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+permissions:
+  contents: read
+
+jobs:
+  agent-shield:
+    name: AgentShield
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+
+      # --- Deep security scan via AgentShield CLI ---
+      # Uses ecc-agentshield (https://github.com/affaan-m/agentshield)
+      # 102 rules: secrets, permissions, hooks, MCP servers, agent config
+      - name: AgentShield Security Scan
+        run: |
+          npx ecc-agentshield@1.4.0 scan \
+            --path . \
+            --min-severity high \
+            --format terminal
+
+      # --- Org-specific structural checks ---
+      - name: Check required agent files exist
+        run: |
+          status=0
+
+          if [ ! -f "CLAUDE.md" ]; then
+            echo "::error::Missing CLAUDE.md"
+            status=1
+          fi
+
+          if [ ! -f "AGENTS.md" ]; then
+            echo "::error::Missing AGENTS.md"
+            status=1
+          fi
+
+          exit $status
+
+      - name: Validate cross-references
+        run: |
+          status=0
+
+          if [ -f "CLAUDE.md" ] && \
+             ! grep -qi 'AGENTS.md' CLAUDE.md; then
+            echo "::error file=CLAUDE.md::Must reference AGENTS.md"
+            status=1
+          fi
+
+          if [ -f "AGENTS.md" ] && \
+             ! grep -qi 'petry-projects/\.github' AGENTS.md; then
+            echo "::error file=AGENTS.md::Must reference org standards"
+            status=1
+          fi
+
+          exit $status
+
+      - name: Validate SKILL.md frontmatter
+        run: |
+          status=0
+
+          while IFS= read -r file; do
+            frontmatter=$(awk \
+              '/^---$/{n++; next} n==1{print} n>=2{exit}' \
+              "$file")
+
+            if [ -z "$frontmatter" ]; then
+              echo "::error file=$file::Missing YAML frontmatter"
+              status=1
+              continue
+            fi
+
+            if ! echo "$frontmatter" | grep -q '^name:'; then
+              echo "::error file=$file::Missing 'name' field"
+              status=1
+            fi
+            if ! echo "$frontmatter" | grep -q '^description:'; then
+              echo "::error file=$file::Missing 'description' field"
+              status=1
+            fi
+          done < <(find . -name 'SKILL.md' \
+            -not -path '*/node_modules/*' \
+            -not -path '*/.git/*')
+
+          if [ "$status" -eq 0 ]; then
+            echo "All SKILL.md frontmatter validated."
+          fi
+          exit $status