From cc72042964f2da4669b367a87624289c58591e87 Mon Sep 17 00:00:00 2001 From: don-petry <36422719+don-petry@users.noreply.github.com> Date: Mon, 2 Feb 2026 05:36:03 +0000 Subject: [PATCH 1/6] docs: add agents guide (docs/agents.md) --- docs/agents.md | 0 1 file changed, 0 insertions(+), 0 deletions(-) create mode 100644 docs/agents.md diff --git a/docs/agents.md b/docs/agents.md new file mode 100644 index 00000000..e69de29b From e939d3ae4b21d2d1b259cc1a9bf6b443da3dc62a Mon Sep 17 00:00:00 2001 From: don-petry <36422719+don-petry@users.noreply.github.com> Date: Mon, 2 Feb 2026 05:39:53 +0000 Subject: [PATCH 2/6] docs: make agents guide prescriptive (docs/agents.md) --- docs/agents.md | 112 +++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 112 insertions(+) diff --git a/docs/agents.md b/docs/agents.md index e69de29b..e01cbb3f 100644 --- a/docs/agents.md +++ b/docs/agents.md @@ -0,0 +1,112 @@ +# Agents Development Guide (Rules & Conventions) + +This document provides explicit rules, conventions, and examples for implementing agents in this repository. Follow these guidelines to ensure consistency, testability, security, and maintainability. + +--- + +## 1) Agent structure (required) +Every agent MUST live under the top-level `agents/` folder and follow this layout: + +- agents// + - README.md # Purpose, configuration, runtime requirements (required) + - src/ # Implementation files (required) + - tests/ # Unit and integration tests (required) + - package.json # If the agent has dependencies or needs its own scripts (optional) + - Dockerfile # Only if containerized (optional) + - .github/workflows/ # Optional per-agent workflows (name clearly) + +Notes: +- Keep pure logic inside `src/` so unit tests can run without platform dependencies. +- Agent code SHOULD avoid using global state; prefer explicit inputs/outputs and dependency injection. + +--- + +## 2) Naming convention (required) +- Agent directory: `agents/` (lowercase, hyphen separated, e.g. `agent-cleanup-archives`). +- Branches: `feat/agent--` (e.g., `feat/agent-cleanup-archives-schedule`). +- PR title: `feat(agent): ` (e.g., `feat(agent): add scheduled cleanup agent`). +- Files: use `kebab-case` or `camelCase` consistently; prefer `kebab-case` for filenames and directories. + +--- + +## 3) Unit testing strategy (required) +- Unit tests MUST reside in `agents//tests/` and use Jest (project default). +- Tests should only cover deterministic, pure logic in `src/`. Any platform integrations (Google services, HTTP calls) MUST be mocked. +- Use the repo's `test-utils/` helpers for common mocks (e.g., Google Apps Script mocks) — extend these helpers rather than duplicating logic. +- Each agent MUST have tests that assert: + - Core logic correctness for edge cases (e.g., empty inputs, error conditions). + - Failure handling and retry/backoff logic. + - Deduplication or idempotency behavior where applicable. + +Test strategy details: +- Unit tests: fast, no network, use mocks. +- Integration tests: optional, keep them isolated and mark with `@integration` or similar tag. CI should be able to skip them unless explicitly enabled. +- Coverage: each agent should aim for reasonable coverage; add coverage thresholds at repo-level later (optional enhancement). + +--- + +## 4) CI & workflows (required) +- All agents with `tests/` will be discovered by the repository-level `Node.js Tests` job. Ensure tests pass locally with `npm test` or `npx jest "agents//tests"`. +- If an agent requires additional verification (container build, release), include a `.github/workflows/agent-.yml` workflow in the agent folder or in `.github/workflows/`. +- Workflow files that run in PRs must be added through a branch with workflow permission (GitHub may require `workflow` scope to push them). If you cannot push the workflow, add it via the PR UI or ask a maintainer. + +--- + +## 5) Security and secrets (required) +- Do not store secrets in code. Use GitHub Actions secrets or an external secret manager. +- Limit secrets to the narrowest scope needed and document which secrets are required in the agent `README.md`. +- Agents running with elevated permissions require explicit approval from a maintainer and a short security plan in the PR description. + +--- + +## 6) Observability, retries, and idempotency (required) +- Agents MUST log key lifecycle events and errors with enough context to debug (timestamp, job id, inputs sanitized). +- Implement retries with exponential backoff for transient errors. Fail after a bounded number of attempts and surface errors to monitoring. +- Agents must be idempotent: repeated executions with the same input should not cause duplicate side effects. Tests must cover idempotency behavior. + +--- + +## 7) Pull Request rules (required) +When opening a PR for an agent change, include the following in the PR description: +- Short summary of what the agent does. +- How it will be triggered (schedule / webhook / manual / workflow). +- What permissions or secrets it requires. +- Test plan and how to run tests locally (commands). +- A short security and data-retention note (where data is stored, who can access it). + +Checklist in PR description (use as a template): +- [ ] README.md exists and documents configuration and secrets +- [ ] Unit tests added and passing +- [ ] Integration tests added (if applicable) and marked/skippable +- [ ] CI workflow included or verification that repo-level CI runs tests +- [ ] Security review notes included and maintainer approval requested (if required) + +--- + +## 8) Code quality & review (required) +- Keep functions small and focused. +- Add JSDoc comments for exported functions and complex logic. +- Avoid side effects in module initialization. +- Add meaningful unit tests that validate behavior, not implementation details. + +--- + +## 9) Example: Agent scaffold (recommended) +Create the following files to scaffold a new agent: + +- agents/agent-cleanup-archives/README.md +- agents/agent-cleanup-archives/src/index.js +- agents/agent-cleanup-archives/tests/index.test.js +- agents/agent-cleanup-archives/.github/workflows/agent-cleanup-archives.yml (optional) + +Quick test commands: +- Run unit tests: npx jest "agents/agent-cleanup-archives/tests" + +--- + +## 10) Maintainers & contact +- Tag `@petry-projects` or open an issue/PR and request a review from a maintainer for agent changes requiring infra or security approval. + +--- + +If you'd like, I can scaffold an example agent (implementation + tests + optional workflow) in a new branch following these rules. Should I create that scaffold now? From abb826601cc3c976374076eae60fd7811b437272 Mon Sep 17 00:00:00 2001 From: don-petry <36422719+don-petry@users.noreply.github.com> Date: Mon, 2 Feb 2026 05:43:50 +0000 Subject: [PATCH 3/6] docs: add root AGENTS.md and point docs/agents.md to canonical file --- AGENTS.md | 93 +++++++++++++++++++++++++++++++++++++++ docs/agents.md | 116 ++++--------------------------------------------- 2 files changed, 101 insertions(+), 108 deletions(-) create mode 100644 AGENTS.md diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 00000000..51846372 --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,93 @@ +# 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 +- All agents MUST live under `agents/` at the repo root. + +Recommended layout: + +- agents// + - 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 -- "agents//tests" (or run `npx jest "agents//tests"`) +- Run the repository test suite locally before opening a PR: + - npm test + +--- + +## 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 `agents//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 `agents//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 agents/agent-cleanup/src agents/agent-cleanup/tests +2. Add implementation to `src/` and tests to `tests/` +3. Run tests: `npx jest "agents/agent-cleanup/tests"` +4. Add `README.md` and open a PR with the PR checklist above + +--- + +## 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 index e01cbb3f..e2dcccd6 100644 --- a/docs/agents.md +++ b/docs/agents.md @@ -1,112 +1,12 @@ -# Agents Development Guide (Rules & Conventions) +# Agents Development Guide — short pointer -This document provides explicit rules, conventions, and examples for implementing agents in this repository. Follow these guidelines to ensure consistency, testability, security, and maintainability. +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: -## 1) Agent structure (required) -Every agent MUST live under the top-level `agents/` folder and follow this layout: +- Canonical file: `/AGENTS.md` ✅ +- Agents live under: `agents//` ✅ +- Run tests locally: `npm test` (or `npx jest "agents//tests"`) ✅ +- CI: `Node.js Tests` job (repository-level) runs tests for any package that contains `tests/` ✅ -- agents// - - README.md # Purpose, configuration, runtime requirements (required) - - src/ # Implementation files (required) - - tests/ # Unit and integration tests (required) - - package.json # If the agent has dependencies or needs its own scripts (optional) - - Dockerfile # Only if containerized (optional) - - .github/workflows/ # Optional per-agent workflows (name clearly) - -Notes: -- Keep pure logic inside `src/` so unit tests can run without platform dependencies. -- Agent code SHOULD avoid using global state; prefer explicit inputs/outputs and dependency injection. - ---- - -## 2) Naming convention (required) -- Agent directory: `agents/` (lowercase, hyphen separated, e.g. `agent-cleanup-archives`). -- Branches: `feat/agent--` (e.g., `feat/agent-cleanup-archives-schedule`). -- PR title: `feat(agent): ` (e.g., `feat(agent): add scheduled cleanup agent`). -- Files: use `kebab-case` or `camelCase` consistently; prefer `kebab-case` for filenames and directories. - ---- - -## 3) Unit testing strategy (required) -- Unit tests MUST reside in `agents//tests/` and use Jest (project default). -- Tests should only cover deterministic, pure logic in `src/`. Any platform integrations (Google services, HTTP calls) MUST be mocked. -- Use the repo's `test-utils/` helpers for common mocks (e.g., Google Apps Script mocks) — extend these helpers rather than duplicating logic. -- Each agent MUST have tests that assert: - - Core logic correctness for edge cases (e.g., empty inputs, error conditions). - - Failure handling and retry/backoff logic. - - Deduplication or idempotency behavior where applicable. - -Test strategy details: -- Unit tests: fast, no network, use mocks. -- Integration tests: optional, keep them isolated and mark with `@integration` or similar tag. CI should be able to skip them unless explicitly enabled. -- Coverage: each agent should aim for reasonable coverage; add coverage thresholds at repo-level later (optional enhancement). - ---- - -## 4) CI & workflows (required) -- All agents with `tests/` will be discovered by the repository-level `Node.js Tests` job. Ensure tests pass locally with `npm test` or `npx jest "agents//tests"`. -- If an agent requires additional verification (container build, release), include a `.github/workflows/agent-.yml` workflow in the agent folder or in `.github/workflows/`. -- Workflow files that run in PRs must be added through a branch with workflow permission (GitHub may require `workflow` scope to push them). If you cannot push the workflow, add it via the PR UI or ask a maintainer. - ---- - -## 5) Security and secrets (required) -- Do not store secrets in code. Use GitHub Actions secrets or an external secret manager. -- Limit secrets to the narrowest scope needed and document which secrets are required in the agent `README.md`. -- Agents running with elevated permissions require explicit approval from a maintainer and a short security plan in the PR description. - ---- - -## 6) Observability, retries, and idempotency (required) -- Agents MUST log key lifecycle events and errors with enough context to debug (timestamp, job id, inputs sanitized). -- Implement retries with exponential backoff for transient errors. Fail after a bounded number of attempts and surface errors to monitoring. -- Agents must be idempotent: repeated executions with the same input should not cause duplicate side effects. Tests must cover idempotency behavior. - ---- - -## 7) Pull Request rules (required) -When opening a PR for an agent change, include the following in the PR description: -- Short summary of what the agent does. -- How it will be triggered (schedule / webhook / manual / workflow). -- What permissions or secrets it requires. -- Test plan and how to run tests locally (commands). -- A short security and data-retention note (where data is stored, who can access it). - -Checklist in PR description (use as a template): -- [ ] README.md exists and documents configuration and secrets -- [ ] Unit tests added and passing -- [ ] Integration tests added (if applicable) and marked/skippable -- [ ] CI workflow included or verification that repo-level CI runs tests -- [ ] Security review notes included and maintainer approval requested (if required) - ---- - -## 8) Code quality & review (required) -- Keep functions small and focused. -- Add JSDoc comments for exported functions and complex logic. -- Avoid side effects in module initialization. -- Add meaningful unit tests that validate behavior, not implementation details. - ---- - -## 9) Example: Agent scaffold (recommended) -Create the following files to scaffold a new agent: - -- agents/agent-cleanup-archives/README.md -- agents/agent-cleanup-archives/src/index.js -- agents/agent-cleanup-archives/tests/index.test.js -- agents/agent-cleanup-archives/.github/workflows/agent-cleanup-archives.yml (optional) - -Quick test commands: -- Run unit tests: npx jest "agents/agent-cleanup-archives/tests" - ---- - -## 10) Maintainers & contact -- Tag `@petry-projects` or open an issue/PR and request a review from a maintainer for agent changes requiring infra or security approval. - ---- - -If you'd like, I can scaffold an example agent (implementation + tests + optional workflow) in a new branch following these rules. Should I create that scaffold now? +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 From 1a644c57f8954f229fa9c3b950d40a1386086e53 Mon Sep 17 00:00:00 2001 From: don-petry <36422719+don-petry@users.noreply.github.com> Date: Mon, 2 Feb 2026 05:46:33 +0000 Subject: [PATCH 4/6] chore(agents): add label-check workflow, agent workflow template, and repo-level rules (AGENTS.md) --- .github/workflows/agent-workflow-template.yml | 37 +++++++++++++++++++ .github/workflows/require-agent-label.yml | 34 +++++++++++++++++ AGENTS.md | 15 ++++++++ 3 files changed, 86 insertions(+) create mode 100644 .github/workflows/agent-workflow-template.yml create mode 100644 .github/workflows/require-agent-label.yml 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 index 51846372..424f75cb 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -84,6 +84,21 @@ Include short notes about how to trigger the agent (schedule, manual, webhook) a --- +## Repo-level rules & enforcement (required) +To keep agent contributions consistent and safe, this repository applies the following required rules: + +- **PR label**: Any PR that modifies files under `agents/` MUST include the **`agent`** label. The repo includes a check workflow at `.github/workflows/require-agent-label.yml` that will fail the check if the label is not present. + +- **Coverage threshold**: Agents 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 `agents//.github/workflows/` using the template above. + +Notes: +- Maintainers may adjust thresholds per-agent via PR discussion; the default baseline is 80% global coverage. +- The label check only applies when files under `agents/` are modified; general PRs are not affected. + +--- + ## Where to learn more - AGENTS.md reference: https://agents.md/ - Agent ecosystem examples: https://github.com/search?q=path%3AAGENTS.md+NOT+is%3Afork From cf015b0c6ebaaf50f73f6b51025099076e3f818e Mon Sep 17 00:00:00 2001 From: don-petry <36422719+don-petry@users.noreply.github.com> Date: Mon, 2 Feb 2026 05:49:31 +0000 Subject: [PATCH 5/6] docs(agents): align AGENTS.md with canonical guidance and add agent operation rules --- AGENTS.md | 10 ++++++++++ 1 file changed, 10 insertions(+) diff --git a/AGENTS.md b/AGENTS.md index 424f75cb..46a7b036 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -36,6 +36,16 @@ For monorepos or nested projects, you MAY place an `AGENTS.md` inside a package --- +## 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 `agents//README.md`. + +--- + ## Tests & CI conventions - Use Jest (the repo default) for unit tests. - Unit tests MUST be fast, deterministic, and not access external networks. From 6342f629ab14b429ef5363623e79877ba625e878 Mon Sep 17 00:00:00 2001 From: don-petry <36422719+don-petry@users.noreply.github.com> Date: Mon, 2 Feb 2026 05:53:41 +0000 Subject: [PATCH 6/6] docs: remove explicit 'agents/' path references and generalize to '' --- AGENTS.md | 25 +++++++++++-------------- docs/agents.md | 4 ++-- 2 files changed, 13 insertions(+), 16 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index 46a7b036..ab07f02f 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -11,11 +11,11 @@ This file follows the AGENTS.md conventions (see https://agents.md/) and provide --- ## Project layout & where to put agent code -- All agents MUST live under `agents/` at the repo root. +- Agent code should be placed in a clearly documented folder; record its path in `AGENTS.md` or the agent's `README.md`. -Recommended layout: +Recommended layout example: -- agents// +- / - README.md # purpose, configuration, secrets required - src/ # implementation (keep pure logic testable) - tests/ # unit and optional integration tests @@ -30,7 +30,7 @@ For monorepos or nested projects, you MAY place an `AGENTS.md` inside a package - Install repository dependencies (root): - npm install - Run tests for an agent: - - npm test -- "agents//tests" (or run `npx jest "agents//tests"`) + - npm test -- "/tests" (or run `npx jest "/tests"`) - Run the repository test suite locally before opening a PR: - npm test @@ -42,7 +42,7 @@ These short rules reflect the canonical AGENTS.md guidance and are adapted for t - 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 `agents//README.md`. +- Document project-specific commands and any environment variables/secrets needed in `/README.md`. --- @@ -51,7 +51,7 @@ These short rules reflect the canonical AGENTS.md guidance and are adapted for t - 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 `agents//tests` passes on CI. +- Agent tests are discovered by the repository-level `Node.js Tests` job; ensure `/tests` passes on CI. --- @@ -62,7 +62,7 @@ These short rules reflect the canonical AGENTS.md guidance and are adapted for t --- ## Security & secrets -- Never store secrets in the repo. Use GitHub Secrets or an external secret manager and document required secrets in `agents//README.md`. +- 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. --- @@ -87,9 +87,9 @@ Include short notes about how to trigger the agent (schedule, manual, webhook) a --- ## Example scaffold -1. mkdir -p agents/agent-cleanup/src agents/agent-cleanup/tests +1. mkdir -p /src /tests 2. Add implementation to `src/` and tests to `tests/` -3. Run tests: `npx jest "agents/agent-cleanup/tests"` +3. Run tests: `npx jest "/tests"` 4. Add `README.md` and open a PR with the PR checklist above --- @@ -97,15 +97,12 @@ Include short notes about how to trigger the agent (schedule, manual, webhook) a ## Repo-level rules & enforcement (required) To keep agent contributions consistent and safe, this repository applies the following required rules: -- **PR label**: Any PR that modifies files under `agents/` MUST include the **`agent`** label. The repo includes a check workflow at `.github/workflows/require-agent-label.yml` that will fail the check if the label is not present. +- **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`. -- **Coverage threshold**: Agents 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 `agents//.github/workflows/` using the template above. +- **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. -- The label check only applies when files under `agents/` are modified; general PRs are not affected. --- diff --git a/docs/agents.md b/docs/agents.md index e2dcccd6..7282308d 100644 --- a/docs/agents.md +++ b/docs/agents.md @@ -5,8 +5,8 @@ This project's canonical agent guidance is now the repository-level `AGENTS.md` Quick references: - Canonical file: `/AGENTS.md` ✅ -- Agents live under: `agents//` ✅ -- Run tests locally: `npm test` (or `npx jest "agents//tests"`) ✅ +- 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