Skip to content

Add AGENTS.md, CODEOWNERS, and PR template#76

Merged
miguelcalderon merged 6 commits intomainfrom
miguel/agent-first-readiness
Apr 1, 2026
Merged

Add AGENTS.md, CODEOWNERS, and PR template#76
miguelcalderon merged 6 commits intomainfrom
miguel/agent-first-readiness

Conversation

@miguelcalderon
Copy link
Copy Markdown
Contributor

@miguelcalderon miguelcalderon commented Mar 30, 2026

What

Adds agent-first infrastructure and improves e2e test reliability.

Agent-first readiness

  • AGENTS.md — Comprehensive guide documenting repo structure, example anatomy, all commands, how to add new examples, e2e testing workflow, CI setup, and code style rules. Designed for both AI agents and human contributors.
  • CODEOWNERS — Assigns Web SDK team (nickel) as default reviewers
  • PR template — Standardized checklist (type, formatting, e2e test, README, SDK version)

E2E improvements

  • Added start:e2e scripts to javascript-vite and typescript-vite (were missing, now testable in CI)
  • Fixed e2e-tests.sh to continue on failure and report all broken examples at the end, instead of silently masking failures
  • Excluded svelte-kit and vue-composition-api from e2e (require pnpm, which CI does not have)
  • Excluded svelte from e2e (uses sirv which isn't installed in CI)
  • Excluded react from e2e (react-scripts/CRA crashes on Node.js 24)

Context

Part of the agent-first repos initiative discussed in #engineering.

Refs: https://nutrient.atlassian.net/browse/AI-450
Closes https://nutrient.atlassian.net/browse/WEB-4153

Agent-first readiness:
- AGENTS.md: documents repo structure, example anatomy, commands,
  contribution workflow, and CI setup for AI agents and contributors
- CODEOWNERS: assigns Web SDK team (nickel) as default reviewers
- PR template: standardized checklist for contributions

E2E coverage improvements:
- Add start:e2e to javascript-vite, typescript-vite, svelte-kit,
  and vue-composition-api examples so Playwright smoke tests can
  run against them

Refs: #75
@miguelcalderon miguelcalderon self-assigned this Mar 30, 2026
@miguelcalderon miguelcalderon marked this pull request as ready for review March 30, 2026 12:18
@vladimir-tikhonov-nutrient
Copy link
Copy Markdown
Contributor

Nice improvement adding the missing start:e2e scripts. I pulled the branch locally and verified that the four touched examples pass the shared Playwright smoke test.

One thing I think is still worth fixing in the same area: scripts/e2e-tests.sh keeps iterating even if one example fails, and the script currently returns the status of the last command that ran. In practice that means a broken example in the middle can still be masked by a later passing example.

A tiny repro of the control flow is:

for cmd in false true; do ($cmd); done
echo $?
# 0

Would you mind making the runner fail fast with set -e (or collecting failures and exiting non-zero at the end)? Otherwise we can still end up with hidden failures even though the missing start:e2e cases are now covered.

## Checklist

- [ ] `npm run format` passes (Biome)
- [ ] Example has `start` and `start:e2e` scripts in `package.json`
Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I like having a checklist here. I think this specific checkbox will be noisy as written, though: several current examples don’t satisfy start + start:e2e literally.

The four Vite-based examples updated in this PR use dev rather than start, and the .NET examples don’t have a package.json at all. Could we scope this to new Node-based examples, or reword it to match the repo’s actual conventions?


Every example follows the same pattern:

- `package.json` with `start` script (dev server on a port)
Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Nice to see an agent guide landing here. One thing I’d tighten up before we rely on it: a few of these repo-wide rules don’t match the current examples yet.

For example, the Vite examples touched in this PR still expose dev + start:e2e, not start, several implementations use NutrientViewer.load() rather than PSPDFKit.load(), and asp-net / blazor don’t have a package.json at all.

Since this file is meant to steer both humans and agents, I think it would be safer to either describe the current state a bit more loosely (for example, “Node-based examples usually have ...”) or bring the repo into line with the guide.

Collect all failing examples and exit non-zero at the end, so a broken
example in the middle of the loop can no longer be hidden by later
passing examples.

Co-authored-by: Miguel Calderón <miguel@nutrient.io>
@miguelcalderon
Copy link
Copy Markdown
Contributor Author

Good catch! Fixed in 71a6675 — the runner now collects all failures and reports them at the end with a non-zero exit, so nothing gets masked. Went with the "collect and report" approach over set -e so we still get visibility into all broken examples in a single run.

…-api)

These examples use pnpm which is not available in CI. Exclude them
from e2e tests until pnpm is added to the CI workflow.
@miguelcalderon miguelcalderon changed the title Add AGENTS.md, CODEOWNERS, PR template, and missing start:e2e scripts Add AGENTS.md, CODEOWNERS, and PR template Mar 31, 2026
…ests

These examples fail in CI due to:
- svelte-kit, vue-composition-api: require pnpm (not available in CI)
- svelte: uses sirv which isn't installed
- react: uses react-scripts (CRA) which crashes on Node.js 24

Also removes start:e2e scripts from svelte-kit and vue-composition-api
since they can't run in CI anyway.
…trient-web-examples into miguel/agent-first-readiness

# Conflicts:
#	scripts/e2e-tests.sh
Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

:shipit:

@miguelcalderon miguelcalderon merged commit d468069 into main Apr 1, 2026
3 checks passed
@miguelcalderon miguelcalderon deleted the miguel/agent-first-readiness branch April 1, 2026 07:59
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants