diff --git a/.github/workflows/agent-workflow-template.yml b/.github/workflows/agent-workflow-template.yml new file mode 100644 index 00000000..43639029 --- /dev/null +++ b/.github/workflows/agent-workflow-template.yml @@ -0,0 +1,37 @@ +name: "Agent: Test + Coverage Template" + +on: + workflow_dispatch: + pull_request: + paths: + - 'agents/**' + push: + paths: + - 'agents/**' + +jobs: + test: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v4 + + - name: Setup Node.js + uses: actions/setup-node@v4 + with: + node-version: '20' + cache: 'npm' + + - name: Install dependencies + run: npm ci + + - name: Run tests with coverage + run: npx jest --coverage --testPathPattern="agents/.*/tests" + + - name: Check coverage threshold (global >= 80%) + run: | + if [ ! -f coverage/coverage-summary.json ]; then echo "coverage report not found"; exit 1; fi + node -e "const fs=require('fs');const s=JSON.parse(fs.readFileSync('coverage/coverage-summary.json'));const g=s.total;const min=80;const ok=g.lines.pct>=min&&g.statements.pct>=min&&g.branches.pct>=min&&g.functions.pct>=min; if(!ok){console.error('Coverage below threshold', g); process.exit(1)} console.log('Coverage OK', g);" + +# NOTES: +# - This is a template you can copy into an agent's folder or use as-is for repository-level checks. +# - Adjust the node version, cache strategy, or coverage threshold to meet your project's needs. \ No newline at end of file diff --git a/.github/workflows/require-agent-label.yml b/.github/workflows/require-agent-label.yml new file mode 100644 index 00000000..cd3bc41e --- /dev/null +++ b/.github/workflows/require-agent-label.yml @@ -0,0 +1,34 @@ +name: "Require 'agent' label for agent changes" + +on: + pull_request: + +jobs: + require-agent-label: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v4 + + - name: Check PR files and labels + uses: actions/github-script@v7 + with: + script: | + const pr = context.payload.pull_request; + const files = await github.paginate(github.rest.pulls.listFiles, { + owner: context.repo.owner, + repo: context.repo.repo, + pull_number: pr.number, + }); + + const changedAgentFile = files.some(f => f.filename.startsWith('agents/')); + if (!changedAgentFile) { + core.info('No changes under agents/; skipping label check.'); + return; + } + + const labels = pr.labels.map(l => l.name); + if (!labels.includes('agent')) { + core.setFailed("PR modifies files under 'agents/' and must include the 'agent' label. Please add the label to the PR."); + } else { + core.info("'agent' label found on PR."); + } \ No newline at end of file diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 00000000..ab07f02f --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,115 @@ +# AGENTS.md — Agent Guidance for this Repository + +This file follows the AGENTS.md conventions (see https://agents.md/) and provides agent-focused, machine- and human-readable instructions for implementing, testing, and operating agents in this repository. + +--- + +## Why this file exists +- Use AGENTS.md for agent-specific developer instructions (build, test, run, configuration) that complement `README.md` files. +- Agents and automation tools will read the nearest `AGENTS.md` to decide how to build and test a package. + +--- + +## Project layout & where to put agent code +- Agent code should be placed in a clearly documented folder; record its path in `AGENTS.md` or the agent's `README.md`. + +Recommended layout example: + +- / + - README.md # purpose, configuration, secrets required + - src/ # implementation (keep pure logic testable) + - tests/ # unit and optional integration tests + - package.json # optional, only if agent has separate deps or scripts + - .github/workflows/ # optional per-agent workflows + +For monorepos or nested projects, you MAY place an `AGENTS.md` inside a package—agents will prefer the nearest file. + +--- + +## Quick start (dev environment) +- Install repository dependencies (root): + - npm install +- Run tests for an agent: + - npm test -- "/tests" (or run `npx jest "/tests"`) +- Run the repository test suite locally before opening a PR: + - npm test + +--- + +## Agent operation guidance (adopted from https://agents.md/) +These short rules reflect the canonical AGENTS.md guidance and are adapted for this repository so agent-driven tooling behaves predictably: + +- Use interactive/dev commands or test commands during agent sessions; avoid running destructive or production-only workflows from an interactive agent session. +- Keep dependencies in sync: update the lockfile (`package-lock.json`/`pnpm-lock.yaml`/`yarn.lock`) when adding or changing dependencies and restart any local dev/test servers. +- Prefer small, focused commands for iterative work (e.g., run the specific agent tests instead of the full suite). +- Document project-specific commands and any environment variables/secrets needed in `/README.md`. + +--- + +## Tests & CI conventions +- Use Jest (the repo default) for unit tests. +- Unit tests MUST be fast, deterministic, and not access external networks. +- Mock external services (Google Apps Script, HTTP calls) using `test-utils/` helpers. +- Integration tests are allowed but MUST be clearly marked (e.g., `@integration`) and skippable in CI. +- Agent tests are discovered by the repository-level `Node.js Tests` job; ensure `/tests` passes on CI. + +--- + +## Code style and types +- Follow repo conventions (JavaScript, tests with Jest). If an agent uses TypeScript, add tsconfig and keep strict typing. +- Keep module initialization free of side effects for testability. + +--- + +## Security & secrets +- Never store secrets in the repo. Use GitHub Secrets or an external secret manager and document required secrets in `/README.md`. +- Limit permissions and document the minimal scope required. Anything that requires elevated permissions must be reviewed by maintainers. + +--- + +## Observability, retries, and idempotency +- Agents MUST log lifecycle events and errors with enough context for debugging. +- Implement retries for transient errors with exponential backoff and a bounded retry count. +- Design agents to be idempotent and add tests to cover repeated runs. + +--- + +## PR checklist for agent changes +Add the following to your PR description or use it as a template: +- [ ] Agent `README.md` included and documents config + secrets +- [ ] Unit tests added and passing +- [ ] Integration tests added only if required and marked/skippable +- [ ] CI workflow included (if agent needs extra verification) or note that repo-level CI runs the tests +- [ ] Security notes and required maintainer approval if running with elevated permissions + +Include short notes about how to trigger the agent (schedule, manual, webhook) and how to run tests locally. + +--- + +## Example scaffold +1. mkdir -p /src /tests +2. Add implementation to `src/` and tests to `tests/` +3. Run tests: `npx jest "/tests"` +4. Add `README.md` and open a PR with the PR checklist above + +--- + +## Repo-level rules & enforcement (required) +To keep agent contributions consistent and safe, this repository applies the following required rules: + +- **Coverage threshold**: Agent code SHOULD meet a minimum **global coverage of 80%** (lines, statements, branches, functions). A template workflow `.github/workflows/agent-workflow-template.yml` demonstrates running tests and enforcing the coverage threshold via `coverage/coverage-summary.json`. + +- **Per-agent workflows**: If your agent needs extra verification (container build, release, or scheduled triggers), add a per-agent workflow in `/.github/workflows/` using the template above. + +Notes: +- Maintainers may adjust thresholds per-agent via PR discussion; the default baseline is 80% global coverage. + +--- + +## Where to learn more +- AGENTS.md reference: https://agents.md/ +- Agent ecosystem examples: https://github.com/search?q=path%3AAGENTS.md+NOT+is%3Afork + +--- + +If you'd like, I can scaffold a concrete example agent (code + tests + optional workflow) that follows this `AGENTS.md`. Reply with the agent name and trigger type (scheduled / manual / webhook) and I’ll create the scaffold in a new branch. \ No newline at end of file diff --git a/docs/agents.md b/docs/agents.md new file mode 100644 index 00000000..7282308d --- /dev/null +++ b/docs/agents.md @@ -0,0 +1,12 @@ +# Agents Development Guide — short pointer + +This project's canonical agent guidance is now the repository-level `AGENTS.md` at the repo root. That file follows the AGENTS.md convention (https://agents.md/) and contains machine- and human-oriented instructions for building, testing, and operating agents in this repo. + +Quick references: + +- Canonical file: `/AGENTS.md` ✅ +- Agent code should be placed in a documented folder (e.g., `tools/`, `scripts/`, or similar); record the path in `AGENTS.md` ✅ +- Run tests locally: `npm test` (or `npx jest "/tests"`) ✅ +- CI: `Node.js Tests` job (repository-level) runs tests for any package that contains `tests/` ✅ + +If you prefer, I can convert this short doc into a full `AGENTS.md` at the project root (I already added one) or scaffold a sample agent (implementation + tests + optional workflow) in a new branch — tell me the agent name and trigger type (scheduled / webhook / manual) and I’ll create a scaffold. \ No newline at end of file