Imported from ziangziangziang/waypoi (
AGENTS.md). Install upstream withnpx skills add ziangziangziang/waypoi. Copyright stays with the author.
Waypoi Contributor Guardrails
Purpose and scope:
- Applies to the entire repo.
- Preserve core functionality while evolving features.
Core invariants (must not break):
- MCP:
/mcpendpoint exists and is localhost-only.- File-first policy remains default for binary tools.
- Tool outputs remain structured as
{ ok: true|false, ... }. - File outputs must be workspace-relative (no
/tmpby default).
- Playground UI:
- Image/chat upload flows remain functional.
- Thinking/streaming behaviors are preserved.
- No regressions to basic chat/call flows.
- Reverse proxy:
/v1/*stays OpenAI-compatible.- No breaking request/response changes without migration notes.
- Providers/pools:
- Capability routing remains consistent (input/output requirements).
- Model selection logic unchanged unless updated with tests.
Change discipline:
- MCP tool contract changes must update:
docs/mcp-service.mddocs/mcp-guidelines.md- relevant tests in
tests/mcp*.test.ts
- OpenAI route changes must update relevant docs and regression tests.
- UI changes affecting chat/call/image flows must add a targeted test or a manual verification checklist in PR notes.
Default output path rule:
- Tool outputs must write under the workspace (default
./.waypoi/generated-images). - Reject
output_path/output_diroutside the workspace.
Versioning:
- Single source of truth is git tags (e.g.
v0.8.0-alpha.0). scripts/version-from-git.jsruns via npmprehooks to generatesrc/version.tsbefore build/dev/typecheck.package.jsonversion is0.0.0(placeholder — never edit manually).- To release:
git tag v<semver>&&git push origin --tags. - CI (if added) must checkout with
fetch-depth: 0and runnpm version $(git describe --tags --abbrev=0 | sed 's/^v//') --no-git-tag-versionbeforenpm publish.
Quick pointers (where to look first):
- MCP service:
src/mcp/service.ts - MCP policy:
src/mcp/policy.ts - Playground:
ui/src/pages/AgentPlayground.tsx - Reverse proxy:
src/routing/router.tsandsrc/routes/* - Providers/pools:
src/providers/*,src/pools/*
