ai-workflows copilot-instructions.md

GitHub Copilot Instructions — ai-workflows

Repository Purpose

Reusable GitHub Actions workflows for AI-assisted automation. Consumer repos call these with thin callers (~10-20 lines). This is the single source of truth for CI/CD automation workflows.

Build & Test

• Package manager: bun (not npm or node)
• Run tests: bun test
• Watch mode: bun test --watch
• bun is globally available; no install step needed

File Structure Rules

Each file must contain a single language — never mix:

• .yml files: YAML only (workflow configuration)
• .js files: JavaScript only (logic — one script per purpose)
• .md files: prompts with ${VAR} placeholders for dynamic values
• .json files: configuration only

Inline threshold: Scripts of 5 lines or fewer may be embedded in YAML run: steps. Scripts exceeding 5 lines must be extracted to .github/scripts/<workflow-name>/<script>.js.

JavaScript Script Pattern

All scripts use this module pattern:

module.exports = async ({ github, context, core }) => {
  // logic here
};

Pass GitHub Actions expression values (${{ }}) via env: on the step, then read with process.env in the script. Never interpolate expressions inside .js files.

Invoke extracted scripts in YAML:

- uses: actions/github-script@v8
  env:
    MY_VAR: ${{ steps.prev.outputs.value }}
  with:
    script: |
      const run = require('./.ai-workflows/.github/scripts/<dir>/<name>.js');
      await run({ github, context, core });

Testing Requirements

• Framework: bun:test (built-in globals: describe, it, expect, beforeEach)
• One test file per script: tests/<script-name>.test.js
• Mock factories in tests/helpers.js — use createMockCore, createMockContext, createMockGithub
• Use mock() from bun:test for mock functions
• Every new script must include a test: happy path + key failure modes

Prompt Files

Prompts live in dryvist/ai-llm-prompts under automation/ with ${VAR} placeholders. Workflows pin an immutable catalog commit and render with .github/scripts/render-prompt.sh, which strips OKF frontmatter before envsubst.