.coderabbit.yaml

# yaml-language-server: $schema=https://coderabbit.ai/integrations/schema.v2.json
# CodeRabbit configuration for ai-workflows
#
# This repo contains structured Markdown workflows and simple skills that AI
# agents read and execute. The configuration has two layers:
#
#   1. Domain-specific rules — enforce the project's own quality standards
#      (skill-reviewer dimensions, CONTRIBUTING.md conventions, AGENTS.md
#      architecture). These are the primary value-add for this repo.
#
#   2. Inherited security rules (prodsec-skills) — retained for future-
#      proofing. They activate only when matching file patterns exist.
#      Currently most patterns (*.go, Dockerfile, etc.) match few or no
#      files in this markdown-centric repository.
#
# Schema:   https://coderabbit.ai/integrations/schema.v2.json
# Validate: comment "@coderabbitai configuration" on any PR
#
language: "en-US"
tone_instructions: >-
  Review workflows and simple skills for structural correctness, clear
  instructions, and cross-file consistency. Apply a security lens to scripts
  and CI. Flag ambiguity likely to make an AI agent produce incorrect output.
early_access: true

reviews:
  profile: "assertive"
  request_changes_workflow: false
  high_level_summary: true
  high_level_summary_instructions: >-
    Summarize changes in terms of which packages are affected, what
    structural or behavioral changes were made to skills/commands/guidelines,
    and whether the changes affect shared resources (_shared/) or
    cross-package conventions.
  collapse_walkthrough: false
  sequence_diagrams: false
  review_details: true
  suggested_labels: true
  auto_apply_labels: false

  path_filters:
    - "!vendor/**"
    - "!node_modules/**"
    - "!dist/**"
    - "!*.min.js"
    - "!yarn.lock"
    - "!.artifacts/**"

  auto_review:
    enabled: true
    auto_incremental_review: true
    drafts: false
    base_branches:
      - "main"
      - "release/.*"
    ignore_title_keywords:
      - "[skip-review]"
      - "WIP"

  labeling_instructions:
    - label: "workflow-structure"
      instructions: >-
        Apply when the PR changes SKILL.md, guidelines.md, controller.md,
        dispatch.md, completion.md, or adds/removes/renames files in skills/
        or commands/ directories. Structural changes affect how AI agents
        discover and execute workflows.

    - label: "new-workflow"
      instructions: >-
        Apply when the PR adds a new top-level directory containing a SKILL.md.
        New workflows require AGENTS.md and README.md cross-reference updates.

    - label: "new-simple-skill"
      instructions: >-
        Apply when the PR adds skills/*/SKILL.md. Simple skills require
        AGENTS.md and README.md cross-reference updates, but do not require
        workflow phases, commands, guidelines.md, or a package README.

    - label: "shared-resources"
      instructions: >-
        Apply when the PR modifies files in _shared/. Changes here affect
        multiple workflows — review for cross-cutting impact.

    - label: "ci-validation"
      instructions: >-
        Apply when the PR modifies .github/ files (workflows, scripts, configs)
        or linter/checker configuration files (.markdownlint-cli2.yaml,
        .lychee.toml, .coderabbit.yaml).

    - label: "documentation"
      instructions: >-
        Apply when the PR primarily modifies README.md files, AGENTS.md,
        CONTRIBUTING.md, or other human-facing documentation without changing
        skill logic.

    - label: "scripts"
      instructions: >-
        Apply when the PR modifies Python or shell scripts in scripts/
        directories, install.sh, or uninstall.sh.

    - label: "templates"
      instructions: >-
        Apply when the PR modifies files in templates/ or prompts/ directories.
        Template changes affect generated artifacts and sub-agent behavior.

  path_instructions:

    # ══════════════════════════════════════════════════════════════
    # Domain-specific rules (ai-workflows)
    #
    # These enforce the project's own quality standards derived from
    # the skill-reviewer's 8 evaluation dimensions, CONTRIBUTING.md
    # conventions, and AGENTS.md architecture.
    # ══════════════════════════════════════════════════════════════

    # ── SKILL.md entry points ───────────────────────────────────
    - path: "*/SKILL.md"
      instructions: |
        SKILL.md review (ai-workflows conventions):
        - YAML frontmatter required: opening/closing --- delimiters
        - Required fields: name (lowercase, hyphens only, max 64 chars),
          description (third person, includes trigger terms and
          activated-by commands)
        - Total file length must be under 30 lines (progressive
          disclosure rule — details belong in guidelines.md or skills/)
        - Must reference guidelines.md for principles/limits/safety/quality
        - Must NOT duplicate content from guidelines.md or controller.md
        - Should list all phases with references to skills/ or commands/
        - No IDE-specific syntax — plain markdown only
        - Verify every file path reference resolves to an existing file

    - path: "skills/*/SKILL.md"
      instructions: |
        Simple-skill SKILL.md review (ai-workflows conventions):
        - YAML frontmatter is required with name, version, and a concise
          discovery description that says what the skill does and when to use it
        - Total file length must be under 30 lines, including frontmatter
        - Keep the entry point focused; put conditional detail in references/
        - Verify relative resource references resolve from the skill directory
        - Do not require phases, commands, a controller, guidelines.md, a README,
          slash-command activation, or artifact persistence
        - External mutations must have explicit approval and bounded scope
        - No IDE-specific syntax

    # ── Command wrappers ────────────────────────────────────────
    - path: "*/commands/*.md"
      instructions: |
        Command file review (ai-workflows conventions):
        - YAML frontmatter required with name and description fields
        - name field must use colon notation: {workflow-name}:{phase-name}
          (e.g., bugfix:assess, design:ingest)
        - Commands must be thin wrappers — they dispatch to a skill,
          not implement logic themselves. Flag commands that contain
          step-by-step instructions or decision logic
        - Must include $ARGUMENTS placeholder to pass user context
        - Path references must be relative to the command file's location:
          use ../skills/controller.md, ../skills/dispatch.md, ../SKILL.md,
          or a direct phase-skill path; do not use absolute paths or omit
          the required ../ prefix
        - Every command must route to its corresponding phase, either through
          a direct file reference or an explicit phase parameter passed to a
          dispatcher (for example, PHASE=assess)
        - No IDE-specific syntax

    # ── Workflow skill files ────────────────────────────────────
    - path: "*/skills/*.md"
      instructions: |
        Workflow skill review (ai-workflows conventions):
        - First classify the file as a phase implementation, controller,
          dispatcher, completion guide, or other support file. Apply
          phase-specific rules only to phase implementations.
        - Maximum 10 steps per skill invocation — flag if exceeded
          (cognitive load / context window risk for AI agents)
        - Main steps must be numbered sequentially: no gaps, no
          duplicates. Sub-steps (e.g., Step 1a) are allowed ONLY for
          conditional branches off a parent step — never as a way to
          insert a new main step without renumbering
        - Internal cross-references (e.g., "see Step 4") must point to
          correct step numbers
        - No step should depend on output from a later step
        - Synthesis tasks (summarization, assessment, verdict) must NOT
          be buried after heavy per-item processing — they degrade in
          long contexts
        - controller.md, dispatch.md, and completion.md must reference sibling
          skill files as file-name.md (not skills/file-name.md) — relative to
          their own directory
        - A controller may centrally dispatch phases and own transitions, or
          limit itself to discovery and ambiguous-input routing when explicit
          commands use a lightweight dispatcher
        - A dispatcher must remain a thin router: resolve the requested phase,
          preserve override behavior and context, and delegate transition
          decisions rather than implementing phase logic
        - A completion guide may centralize next-step recommendations so phase
          files do not duplicate the workflow transition model
        - Skills referencing _shared/ resources must use the correct
          relative path depth (e.g., ../../_shared/recipes/self-review-gate.md
          from skills/)
        - Failure modes must be documented: what to do when prerequisites
          are missing, when zero results are returned, when tools are
          unavailable
        - Escalation criteria must be clear: when to stop and ask the user
        - Instructions must be unambiguous — an AI agent reading
          top-to-bottom should produce correct output on the first try
        - If the file has YAML frontmatter, name and description are required

    # ── Guidelines files ────────────────────────────────────────
    - path: "*/guidelines.md"
      instructions: |
        Guidelines review (ai-workflows conventions):
        - Must contain: Principles, Hard Limits, Safety, Quality, and
          Escalation sections (or equivalent coverage)
        - Content must NOT duplicate SKILL.md or controller.md — each
          file has a distinct role
        - Escalation criteria must be specific and actionable (not vague
          "when things go wrong")
        - Hard limits must be concrete prohibitions, not suggestions
        - All phase references should use consistent naming matching
          the workflow's actual phase names

    # ── Workflow README files ───────────────────────────────────
    - path: "*/README.md"
      instructions: |
        Workflow README review (ai-workflows conventions):
        - Must document .artifacts/ output path for the workflow
        - Phase descriptions must match what SKILL.md and skills/
          actually implement — flag any documentation drift
        - Features mentioned in README must exist in the skill files;
          features implemented in skills must be documented in README
        - Prerequisites (required tools, environment, integrations)
          must be listed
        - Usage examples should show actual command invocations
          (e.g., /workflow:phase)

    # ── Shared resources (_shared/) ─────────────────────────────
    - path: "_shared/**"
      instructions: |
        Shared resource review (ai-workflows conventions):
        - Shared resources may be referenced by multiple packages —
          changes here have cross-cutting impact. Verify that all
          consuming workflows and simple skills are identified
        - Recipes must be self-contained and parameterized (using
          uppercase PLACEHOLDER names for caller-provided values)
        - References TO shared resources from workflow skills must use
          correct relative depth (../../_shared/ from skills/ directories)
        - No workflow-specific logic — shared resources must be generic
          enough for all consumers

    # ── Templates and prompts ───────────────────────────────────
    - path: "*/{templates,prompts}/*.md"
      instructions: |
        Template/prompt review (ai-workflows conventions):
        - Templates use {placeholder} syntax for caller-filled values —
          verify all placeholders are documented
        - Prompt templates must be self-contained: the sub-agent receives
          only the prompt, not the caller's context
        - Prompts must instruct output to .artifacts/, not inline return
        - Templates must work when the workflow is installed via symlink
        - No absolute paths in templates

    # ── Workflow scripts ────────────────────────────────────────
    - path: "*/scripts/*.py"
      instructions: |
        Workflow script review (ai-workflows conventions):
        - Scripts must be invoked by skill files, not by users directly
        - Must work when the workflow is installed via symlink
        - Exit code conventions must be documented in docstring:
          Report scripts: 0 = informational, 1 = halt
          Search/query scripts: define semantics in docstring
        - Python 3 required; no Python 2 compatibility needed
        - No hardcoded absolute paths — derive paths relative to
          script location

    - path: "skills/*/references/*.md"
      instructions: |
        Simple-skill reference review (ai-workflows conventions):
        - References contain focused, conditionally loaded instructions
        - Contracts, terminology, permissions, and failure behavior must remain
          consistent across the entry point and other referenced files
        - Package-resource references must be relative and resolve; runtime data
          paths such as user-selected attachments may be absolute
        - State-changing operations require an exact preview and explicit approval

    - path: "skills/*/templates/*.md"
      instructions: |
        Simple-skill template review (ai-workflows conventions):
        - Follow the placeholder grammar documented by the owning skill; do not
          assume workflow {placeholder} syntax or .artifacts/ output
        - Verify required placeholders and omission behavior against the renderer
        - Templates for embedded content may intentionally begin below H1

    - path: "skills/*/scripts/*.py"
      instructions: |
        Simple-skill script review (ai-workflows conventions):
        - Treat scripts as maintained code: deterministic behavior, validated
          inputs, clear failures, documented CLI/exit status, and unit tests
        - Scripts must work through symlinked installations and avoid hardcoded
          installation paths
        - A script may be invoked by the skill and exposed as a documented CLI
          helper; do not require workflow phase dispatch

    # ── Shell scripts ───────────────────────────────────────────
    - path: "**/*.sh"
      instructions: |
        Shell script review (ai-workflows conventions):
        - Follow the repository's established error-handling mode; quote variable
          expansions and handle pipeline/unset-variable risks where they occur
        - install.sh and uninstall.sh: verify auto-discovery logic
          (scanning for */SKILL.md and skills/*/SKILL.md) is correct
        - validate-structure.sh: verify checks match current
          CONTRIBUTING.md conventions
        - No hardcoded workflow lists — rely on SKILL.md auto-discovery

    # ── Cross-workflow markdown consistency ──────────────────────
    - path: "**/*.md"
      instructions: |
        Cross-package consistency (ai-workflows conventions):
        - Package-resource references that an agent follows must be relative for
          symlink compatibility. Do not apply this to runtime/user data paths,
          URLs, issue keys, or illustrative attachment manifests
        - No IDE-specific syntax (Cursor-specific, VS Code-specific, etc.)
        - Consistent terminology within a workflow: pick one term, stick
          with it
        - Schema field names and types must match between producer and
          consumer files (e.g., if a field is defined in one phase skill
          and consumed in another, names and types must agree)
        - No verbatim duplication of multi-line instruction blocks
          across workflow SKILL.md, guidelines.md, and controller.md — each has
          a distinct role (shared phase names and brief references are
          expected cross-referencing, not duplication)

    # ── CI/CD configuration ─────────────────────────────────────
    - path: ".github/**"
      instructions: |
        CI configuration review (ai-workflows conventions):
        - validate-structure.sh must stay in sync with CONTRIBUTING.md
          conventions — if a convention changes, the validation script
          must be updated to match
        - markdownlint config (.markdownlint-cli2.yaml) disabled rules
          must have comments explaining why
        - lychee config must exclude {placeholder} template URLs
        - New validation checks should complement, not duplicate, what
          CodeRabbit already checks via path_instructions

    # ══════════════════════════════════════════════════════════════
    # Inherited security rules (prodsec-skills)
    #
    # These blocks are retained for future-proofing. They activate
    # only when files matching their path patterns exist in the repo.
    # Currently, most patterns (*.go, Dockerfile, K8s manifests, etc.)
    # match few or no files in this markdown-centric repository.
    # ══════════════════════════════════════════════════════════════

    # ── Injection & input validation (inherited — prodsec-skills) ─
    # Skills: input-validation-injection, web-application-security
    - path: "**/*.{py,js,ts,go,rs,java,rb,php,kt,swift,cs}"
      instructions: |
        Injection prevention (prodsec-skills):
        - SQL: parameterized queries only; no string concatenation
        - Command: no shell=True, os.system, or backtick exec with user input
        - LDAP/XPath: escape special characters in filters
        - Path traversal: canonicalize paths, reject ../
        - Deserialization: no pickle/yaml.load()/eval on untrusted data
        - Prototype pollution: no recursive merge of untrusted objects
        - Validate at trust boundaries with allow-lists, not deny-lists
        - Normalize Unicode and anchor regexes (^$); watch for ReDoS

    # ── Web & frontend security (inherited — prodsec-skills) ─────
    # Skills: react-security, client-side-security, http-security-headers,
    #         graphql-security, session-management-cookies, file-handling-uploads,
    #         xml-serialization-security
    - path: "**/*.{html,jsx,tsx,vue,svelte}"
      instructions: |
        Web security (prodsec-skills):
        - No dangerouslySetInnerHTML or v-html with user data
        - CSP: no unsafe-inline, no unsafe-eval
        - CSRF tokens on state-changing requests
        - Cookies: Secure, HttpOnly, SameSite=Strict
        - No document.write, eval, new Function with user input
        - GraphQL: depth/complexity limits, disable introspection in prod
        - File uploads: validate by content magic, cap size, server-generate names
        - XML: disable external entities (XXE), reject DTDs from untrusted sources

    # ── Cryptography (inherited — prodsec-skills) ────────────────
    # Skills: algorithm-selection, constant-time-analysis, zeroize-audit,
    #         wycheproof, crypto-protocol-diagram, mermaid-to-proverif,
    #         constant-time-testing
    - path: "**/*{crypt,cipher,sign,hash,tls,ssl,cert,key,token}*"
      instructions: |
        Cryptographic security (prodsec-skills):
        - Banned: MD5, SHA1, DES, RC4, 3DES, Blowfish, ECB mode
        - Symmetric: AES-256-GCM or ChaCha20-Poly1305
        - Passwords: Argon2id (not bcrypt/scrypt for new code)
        - Signing: Ed25519 or ECDSA P-256+
        - Key exchange: X25519 or ECDH P-256+
        - Constant-time comparison for all secret/token data
        - Zeroize key material after use (no garbage-collector reliance)
        - No custom crypto; use vetted libraries only
        - Post-quantum: flag if protecting long-lived secrets

    # ── Container & image hardening (inherited — prodsec-skills) ──
    # Skills: container-hardening, isolation-sandboxing
    - path: "**/{Dockerfile,Containerfile}*"
      instructions: |
        Container security (prodsec-skills):
        - Base image: UBI minimal or distroless from catalog.redhat.com
        - Red Hat images: use floating tags (Red Hat manages updates);
          non-RH images: pin by digest
        - Multi-stage builds; no build tools in final image
        - USER non-root; never run as root
        - COPY specific files, not entire context
        - No secrets in ENV, ARG, or COPY
        - Read-only rootfs where possible
        - No package manager cache in final layer
        - HEALTHCHECK defined

    # ── Kubernetes & OpenShift (inherited — prodsec-skills) ──────
    # Skills: scc-security, operator-security, helm-chart-security,
    #         container-hardening, health-probes
    - path: "**/*.{yaml,yml}"
      instructions: |
        If this is a Kubernetes/OpenShift manifest or Helm template:
        - securityContext: runAsNonRoot, readOnlyRootFilesystem,
          allowPrivilegeEscalation: false
        - Drop ALL capabilities, add only what is required
        - Resource limits (cpu, memory) on every container
        - No hostPID, hostNetwork, hostIPC, privileged: true
        - NetworkPolicy defined for the namespace
        - OpenShift: SCC must be restricted or custom-scoped
        - Liveness + readiness probes defined
        - automountServiceAccountToken: false unless needed
        - RBAC: least privilege; no cluster-admin for workloads
        - Helm: no .Values interpolation in shell commands

    # ── MCP server security (inherited — prodsec-skills) ─────────
    # Skills: hardening-local, hardening-remote, oauth21-resource-server,
    #         rbac, input-output-sanitization, secure-token-handling,
    #         containerization, tool-server-injection-prevention,
    #         no-credential-forwarding, roots-support, sampling-controls,
    #         logging-and-observability, runtime-restrictions, os-tool-security,
    #         reject-api-keys, token-exchange-for-tools
    - path: "**/{mcp,tool_server,toolserver}/**/*"
      instructions: |
        MCP server review (prodsec-skills):
        - OAuth 2.1 resource server: validate tokens per RFC 9068
        - Enforce scope-based access per tool; no default-allow
        - RBAC: per-tool permissions mapped to token scopes/roles
        - Sanitize all tool inputs against declared schemas
        - Reject path traversal in file-accessing tools
        - No credential forwarding to downstream services
        - Tool injection: validate registry integrity, reject dynamic
          tool loading from untrusted sources
        - Container isolation: unprivileged, read-only rootfs
        - Audit log all tool invocations with caller identity
        - Rate limiting per client/scope
        - Reject API keys; require IdP-issued tokens

    # ── MCP client (inherited — prodsec-skills) ──────────────────
    # Skills: mcp-client-client-metadata-support,
    #         mcp-client-dynamic-client-registration,
    #         mcp-client-protected-resource-metadata,
    #         consent-and-scoping, discovery-mechanisms
    - path: "**/{mcp_client,mcp-client}/**/*"
      instructions: |
        MCP client review (prodsec-skills):
        - OAuth client metadata: register with minimal scopes
        - Dynamic registration: validate server response, store
          client_id/secret securely
        - Protected resource metadata: discover before token request
        - Consent: prompt user before granting tool access
        - Discovery: validate .well-known endpoints over HTTPS only

    # ── Inference engine & model serving (inherited — prodsec-skills)
    # Skills: isolation-sandboxing, jwt-token-enforcement,
    #         model-security-scanning, model-signature-verification,
    #         oidc-integration, token-lifecycle, external-idp-integration
    - path: "**/{inference,model,serving,predict}/**/*"
      instructions: |
        Inference engine review (prodsec-skills):
        - Process isolation: container or microVM per model
        - JWT/OIDC on all inference endpoints; no unauthenticated access
        - Model provenance: verify signatures before loading
        - Scan models for embedded payloads (pickle, arbitrary code)
        - Token lifecycle: short-lived, secure storage, revocation
        - No direct filesystem access from inference process
        - Resource limits to prevent DoS via large inputs

    # ── Agent security (inherited — prodsec-skills) ──────────────
    # Skills: agent-identity, agent-to-agent-auth, agent-to-mcp-server-auth
    - path: "**/{agent,agents,agentic}/**/*"
      instructions: |
        Agent security (prodsec-skills):
        - Unique, verifiable identity per agent instance
        - Agent-to-agent auth: SPIFFE/mTLS, not shared secrets
        - Agent-to-MCP auth: OAuth 2.1 client credentials flow
        - No ambient authority; agents present credentials per call
        - Audit trail for all inter-agent communication

    # ── LLM interaction (inherited — prodsec-skills) ─────────────
    # Skills: prompt-injection-mitigation, file-protection,
    #         third-party-model-security, bidirectional-filtering,
    #         output-validation-sandbox
    - path: "**/{llm,prompt,chat,completion}/**/*"
      instructions: |
        LLM security (prodsec-skills):
        - Prompt injection: separate system/user content; never
          interpolate untrusted input into system prompts
        - Output filtering: validate LLM output before execution
        - File protection: restrict file access to declared paths
        - Third-party models: evaluate trust, scan artifacts
        - Guardrails: bidirectional filtering on prompts and responses

    # ── Supply chain & dependencies (inherited — prodsec-skills) ──
    # Skills: supply-chain-risk-auditor, sbom-provenance,
    #         software-signing, secure-pipeline, vulnerability-management
    - path: "**/{requirements*.txt,Pipfile*,pyproject.toml,package*.json,package-lock.json,go.mod,go.sum,Cargo.toml,Cargo.lock,Gemfile*,Gemfile.lock,pom.xml,build.gradle*}"
      instructions: |
        Supply chain security (prodsec-skills):
        - New deps: justify need, check license compatibility
        - Pin exact versions; verify hashes where supported
        - Flag known CVEs (cross-ref osv.dev)
        - No pre-release or yanked versions in production
        - SBOM: ensure build produces provenance attestations
        - Signing: artifacts signed with Sigstore/cosign

    # ── CI/CD & GitHub Actions (inherited — prodsec-skills) ──────
    # Skills: secure-pipeline, build-yaml-misconfiguration,
    #         agentic-actions-auditor
    - path: ".github/workflows/**/*"
      instructions: |
        CI/CD security (prodsec-skills):
        - GitHub-owned actions (actions/*) use tag refs (e.g., @v4)
          for readability — do NOT flag these for missing SHA pins.
          Third-party actions must be pinned by full SHA with a
          trailing version comment (e.g., @<sha> # v1.2.3).
        - No secrets in logs; mask sensitive outputs
        - Least privilege: minimize GITHUB_TOKEN permissions
        - No pull_request_target with checkout of PR head
        - SAST/SCA steps in pipeline
        - Sign artifacts with Sigstore/cosign
        - Agentic CI actions: audit for prompt injection via
          issue/PR title/body flowing into LLM prompts

    # ── Authentication & OAuth (inherited — prodsec-skills) ──────
    # Skills: oauth21-implementation, authentication, authorization,
    #         session-management-cookies, avoid-api-keys,
    #         service-to-service-mtls
    - path: "**/{auth,oauth,oidc,login,session,saml}/**/*"
      instructions: |
        Authentication review (prodsec-skills):
        - OAuth 2.1: PKCE required; no implicit grant
        - JWT: verify signature, issuer, audience, expiry, nbf
        - Sessions: secure cookie flags, regenerate ID on login
        - Passwords: Argon2id; never plaintext or weak hashes
        - Rate limit login attempts; account lockout policy
        - MFA: support and encourage; never bypass silently
        - Service-to-service: SPIFFE/mTLS, not shared secrets
        - Avoid API keys; prefer IdP-issued short-lived tokens

    # ── API gateway & rate limiting (inherited — prodsec-skills) ──
    # Skills: authentication-enforcement, internal-application-routing,
    #         rate-limiting, request-validation
    - path: "**/{gateway,proxy,ingress,route}/**/*"
      instructions: |
        API gateway review (prodsec-skills):
        - Auth enforcement at gateway, not just downstream
        - Rate limiting per client/endpoint; fail closed
        - Request validation: size limits, content-type checks
        - No internal-only routes exposed externally
        - TLS termination with strong cipher suites

    # ── Go (inherited — prodsec-skills) ──────────────────────────
    # Skills: go-security
    - path: "**/*.go"
      instructions: |
        Go security (prodsec-skills):
        - Never ignore error returns
        - database/sql with placeholders; no fmt.Sprintf in queries
        - Use stdlib crypto/* and golang.org/x/crypto (Go team maintained);
          avoid third-party crypto libraries
        - Integer overflow: bounds-check user-supplied sizes
        - context.Context for cancellation and timeouts

    # ── C/C++ (inherited — prodsec-skills) ───────────────────────
    # Skills: safe-c-functions, compiler-hardening
    - path: "**/*.{c,cpp,cc,h,hpp}"
      instructions: |
        C/C++ security (prodsec-skills):
        - Banned: gets, sprintf, strcpy, strcat, strtok
        - Use strlcpy, snprintf, bounded APIs
        - Compile: -fstack-protector-strong -fPIE -pie
          -D_FORTIFY_SOURCE=2 -Wformat-security
        - Nullify pointers after free; no use-after-free
        - Integer overflow: check arithmetic on untrusted sizes

    # ── Database & external data (inherited — prodsec-skills) ────
    # Skills: database-security, authentication (external-data-source),
    #         encrypted-communication, redis-elasticache-security
    - path: "**/{db,database,redis,cache,storage}/**/*"
      instructions: |
        Data store security (prodsec-skills):
        - Auth: no default credentials; use IAM or IdP tokens
        - Encryption: TLS in transit, encryption at rest
        - Least privilege: app user has minimal grants
        - Redis/ElastiCache: AUTH required, no KEYS in prod,
          rename dangerous commands (FLUSHALL, CONFIG)
        - Connection strings: no embedded credentials

    # ── Messaging (inherited — prodsec-skills) ───────────────────
    # Skills: kafka-amq-security, mqtt-security
    - path: "**/{kafka,amq,mqtt,messaging,broker}/**/*"
      instructions: |
        Messaging security (prodsec-skills):
        - Kafka/AMQ: TLS, SASL auth, per-topic ACLs
        - MQTT: auth required, topic ACLs, payload encryption
        - No anonymous access in production

    # ── Model registry (inherited — prodsec-skills) ──────────────
    # Skills: model-registry-*, admin-interface-security,
    #         model-registry-secure-storage
    - path: "**/{model_registry,model-registry,registry}/**/*"
      instructions: |
        Model registry review (prodsec-skills):
        - Admin interface: auth + RBAC, no public exposure
        - Model scanning: check for malicious payloads before publish
        - Model signing: verify signatures on pull
        - Audit logging: who uploaded/downloaded/deleted what
        - Secure storage: encrypted at rest, access-controlled

  # ── Tools ─────────────────────────────────────────────────────
  tools:
    # Markdown & prose
    markdownlint:
      enabled: true
    languagetool:
      enabled: true
      level: "picky"
      disabled_categories:
        - "TYPOS"
        - "CASING"
    yamllint:
      enabled: true

    # Security scanners (inherited — prodsec-skills)
    gitleaks:
      enabled: true
    semgrep:
      enabled: true
    checkov:
      enabled: true
    hadolint:
      enabled: true
    trivy:
      enabled: true
    osvScanner:
      enabled: true
    actionlint:
      enabled: true
    ast-grep:
      essential_rules: true

  # ── Pre-merge checks ─────────────────────────────────────────
  pre_merge_checks:
    description:
      mode: "warning"
    custom_checks:

      - name: "ai-attribution"
        instructions: |
          If AI tools were used (mentioned in PR or commits), verify
          attribution trailers: Assisted-by, Generated-by, or
          Made-with (e.g., Made-with: Cursor) are acceptable.
          Flag use of Co-Authored-By for AI tools.
        mode: "error"

      # ── Domain-specific gates (ai-workflows) ──────────────────

      - name: "no-absolute-paths-in-skills"
        instructions: |
          Flag any absolute filesystem path in markdown files within
          workflow directories (*/SKILL.md, */skills/*.md, */commands/*.md,
          */guidelines.md). Paths like /home/, /Users/, /tmp/, /var/,
          /opt/ are prohibited because workflows are installed via symlink
          and must use relative paths only. Paths inside fenced code
          blocks that are clearly examples (containing "example", "e.g.",
          or placeholder usernames like /home/user/) are exempt.
          This check does not apply to runtime/user data paths in simple-skill
          references, such as an attachment selected for upload.
        mode: "error"

      - name: "skill-md-under-30-lines"
        instructions: |
          For any SKILL.md file changed in this PR, verify it is under
          30 lines total (including frontmatter). SKILL.md must be thin
          entry points using progressive disclosure. If a SKILL.md
          exceeds 30 lines, flag it with the count and suggest moving
          content to guidelines.md or skills/ files.
        mode: "warning"

      - name: "command-colon-notation"
        instructions: |
          For any top-level workflow file matching */commands/*.md, verify the YAML
          frontmatter name field uses colon notation matching the
          pattern {workflow-name}:{phase-name} (e.g., bugfix:assess,
          design:ingest). The workflow-name must match the parent
          workflow directory name. Flag any command whose name field
          is missing, does not contain a colon, or has a prefix that
          doesn't match its workflow directory.
        mode: "error"

      - name: "no-orphaned-references"
        instructions: |
          For any changed markdown file in a top-level workflow directory, verify
          that file path references (backtick-quoted paths like
          `../skills/controller.md` or `guidelines.md`) point to files
          that exist. Flag references to files that don't exist (dangling
          references). Also flag skill or command files that exist but
          are never referenced from SKILL.md, controller.md, or any
          command file (orphaned files). Treat an explicit dispatcher parameter
          such as PHASE=assess as a reference to skills/assess.md when the
          dispatcher documents that mapping. Treat files referenced by a
          reachable dispatcher or completion guide as reachable. For skills/*
          simple skills, require
          only that supporting resources are reachable from SKILL.md or another
          reachable reference; do not require workflow-specific files.
        mode: "warning"

      - name: "no-content-duplication"
        instructions: |
          When any of SKILL.md, guidelines.md, controller.md, dispatch.md, or
          completion.md in a workflow is changed, compare it against the other
          architectural files that are present and check for duplication of
          multi-line instruction blocks or paragraphs. Each has a distinct
          role: SKILL.md is
          the thin entry point, guidelines.md holds principles/limits/
          safety/quality/escalation. A controller may own centralized phase
          routing and transitions; in a demand-loaded design it handles
          discovery and ambiguous routing, dispatch.md handles explicit phase
          routing, and completion.md may hold the authoritative transition
          model.
          Phase names and brief one-line descriptions appearing in
          multiple files is EXPECTED (cross-referencing, not duplication)
          — only flag substantial blocks of identical prose or
          step-by-step instructions that are copied between files.
        mode: "warning"

      - name: "step-sequencing"
        instructions: |
          For any changed top-level workflow file matching */skills/*.md, verify
          that main steps are
          numbered sequentially (Step 1, Step 2, Step 3... or ## Step 1,
          ## Step 2...). Flag: gaps in numbering (1, 2, 4), duplicate
          numbers (two Step 3s), and any skill with more than 10 main
          steps (cognitive load risk for AI agents). Sub-steps (Step 1a,
          Step 3b) are acceptable ONLY when they represent conditional
          branches off the parent step (e.g., "Step 1a: If <condition>,
          do X"). Flag sub-steps that are actually new main steps
          inserted to avoid renumbering — those should be promoted to
          full steps with the sequence renumbered.
        mode: "warning"

# ── Knowledge base ──────────────────────────────────────────
knowledge_base:
  code_guidelines:
    enabled: true
    filePatterns:
      - "**/AGENTS.md"
      - "**/REDHAT.md"
      - "**/CLAUDE.md"
      - "**/CONTRIBUTING.md"
      - "_shared/review-protocol.md"
      - "_shared/recipes/self-review-gate.md"
      - "skill-reviewer/skills/review.md"

  issues:
    scope: "auto"
  pull_requests:
    scope: "auto"
  learnings:
    scope: "auto"