Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
47 lines (41 loc) · 1.97 KB

CONTRIBUTING.md

File metadata and controls

47 lines (41 loc) · 1.97 KB
Raw

Contributing

Thanks for your interest. This repo is the reference implementation of the Agent App Framework and the A2App protocol (v0.1). It is a spec-first, pnpm TypeScript monorepo; the conformance suite is the source of truth for behavior, not code review.

Prerequisites

  • Node ≥ 20, pnpm 9 (corepack enable)
  • Python ≥ 3.9 (only for the Python SDK)

Set up & verify (from source)

pnpm install
pnpm -r build
pnpm -r typecheck
pnpm -r test            # runs the conformance suite (classes A/B/C + Toolkit)

Run the conformance suite alone: pnpm --filter @a2app/conformance test.

Try it

# scaffold and gate an app from a blueprint:
node framework/cli/dist/agent-app.js scaffold ./my-app --blueprint blueprint-react-node
node framework/cli/dist/agent-app.js validate ./my-app --no-build
# launch it and operate it over A2App:
node framework/cli/dist/agent-app.js serve ./my-app
node framework/cli/dist/a2app.js data ./my-app schema
node framework/cli/dist/agent-app.js stop ./my-app

Ground rules

  • Spec + schema move together. The JSON Schemas in spec/v0_1/schema/ are the machine contract and win over prose. Change both, and add a conformance check.
  • A change is proven by the conformance suite, not by assertion. New protocol behavior needs a suite entry; new framework behavior needs a test.
  • Respect the layering. @a2app/rules is pure (no I/O). Adapters implement a Binding; they never fork the rules. Toolkits are NOT part of the framework — nothing in framework/ may require one. Hosts are optional.
  • No secrets in code, manifests, skills, toolkits, or examples. Credentials are runtime artifacts, never committed.
  • Keep every package green: pnpm -r build && pnpm -r typecheck && pnpm -r test.

PRs

Small, focused PRs with tests. Describe the behavior change and point at the conformance/test coverage that proves it. CI (build · typecheck · test · conformance · Python · npm pack) must be green.