project_human AGENTS.md

AGENTS.md — Agentic Coding Guidelines

---

CRITICAL: All compute in GitHub Codespaces

NEVER run compilation, testing, builds, linting, or installs on the local machine. These operations are blocked in opencode.json and must run in a GitHub Codespace.

gh cs ssh <name> -- "cd /workspaces/project_human && pnpm check"
gh cs cp <changed-file> remote:/workspaces/project_human/<path>

Sync files to your codespace after making edits, then run verification there.

---

Commands (Codespace only)

pnpm monorepo. Two packages: @humanity4ai/mcp-servers (publishable) and @humanity4ai/evals (private).

pnpm check          # tsc --noEmit across all packages
pnpm start          # MCP server via tsx (stdio transport)
pnpm test           # vitest run (both packages)
pnpm test:coverage  # vitest --coverage
pnpm evals          # skill eval harness (10 checks: 9 skills + contract-consistency)
pnpm build          # compile mcp-servers → dist/

Single test / single package:

pnpm --filter @humanity4ai/mcp-servers test -- --test-name-pattern "H-1"
pnpm --filter @humanity4ai/mcp-servers test -- src/__tests__/handlers.test.ts
pnpm --filter @humanity4ai/mcp-servers check
pnpm --filter @humanity4ai/evals test

Pre-commit (run in codespace): pnpm check && pnpm evals && pnpm test. CI order: check → build → EVAL_REPORT=1 pnpm evals → test:coverage (both packages).

---

Coverage Thresholds

Package	Stmts	Branch	Funcs	Lines
mcp-servers	90%	83%	90%	90%
evals	78%	65%	80%	78%

Excluded from coverage (vitest.config.ts): bin.ts, accessibility-engine.ts, server-factory.ts. wcag-criteria.ts included (96% covered by modules.test.ts). New conditionals → new tests in __tests__/modules.test.ts.

---

Architecture

Package layout

• mcp-servers/src/server-factory.ts — shared createServer() → registers all 9 tools on an McpServer. Used by both stdio (mcp-server.ts) and HTTP (api/mcp.ts) transports.
• mcp-servers/src/mcp-server.ts — thin stdio wrapper: imports factory, connects StdioServerTransport. Re-exports handlers + VERSION for test compatibility.
• mcp-servers/api/mcp.ts — Vercel serverless function using StreamableHTTPServerTransport in stateless mode. Imports factory + handlers from npm package.
• mcp-servers/src/schemas-data.ts — auto-generated at build time: all 18 JSON schemas as inline JS objects. validate.ts imports this instead of readFileSync — zero file I/O, works in all bundler environments (Vercel, Cloudflare).
• mcp-servers/src/validate.ts — input validation against inline SCHEMA_REGISTRY. No node:fs dependency. Called by invokeAction at handler dispatch time.
• mcp-servers/src/handlers.ts — 9 private handler functions + invokeAction(action, input) dispatcher.
• knowledge-core/taxonomy.ts — canonical CATEGORY_SLUGS + ESCALATION_REQUIRED_SKILLS (typed const arrays). taxonomy.md is the human-readable reference.
• evals/src/run-evals.ts — parses VALID_CATEGORIES from knowledge-core/taxonomy.md at runtime (no hardcoded duplicate). 10 checks: 9 skills + contract-consistency.