docs: add agent definition spike and ADR-0004

[XxHugheadxX]

Refs #33

Draft. Question 5 (who signs the agent-wallet steps of a deploy) is left pending ADR-0003 (#7) on purpose. #33 is assigned to @TOMOKI977; I asked on the issue to take it so it can move in parallel with #7 (comment). This becomes Closes #33 once #7 decides custody and step 5 is aligned with it.

Summary

• docs/spikes/agent-definition.md: answers the 7 questions of spike: agent definition (manifest) and deployment model for Agent Studio #33, with sources
• docs/adr/0004-agent-manifest-and-deployment.md: the decision, alternatives, and impact on feat: Agent Identity Registry contract #13, chore: deploy contracts to testnet and seed demo agents #15, feat: register agent flow (wallet and on-chain identity) #18, feat: agent runtime executing deployed manifests #20, feat: AgentManifest domain model and validation #34, feat: Agent Studio endpoints (drafts, test run, deploy) #35, feat: Agent Studio UI (builder, playground, deploy) #37
• docs/architecture/examples/agent-manifest.example.json: the manifest of the Copy Forge demo agent

Key decisions:

• An agent is a manifest (puls3.agent-manifest/v1): name, description, skills (A2A skill shape), model, system prompt, input/output contract, and price as an integer in USDC stroops. Fields mirror the Studio's existing AgentDraft.
• MVP agents are prompt-only. No tools. Ledger Scout, Market Pulse and Remit Pilot in the demo data describe tool-dependent work and must be rewritten or replaced in the seed (chore: deploy contracts to testnet and seed demo agents #15).
• The system prompt is never published. The full manifest lives in the Serverpod database; the public ERC-8004 registration file (the agent_uri) has no prompt; on-chain metadata holds puls3.manifestHash (SHA-256 of salt || canonical JSON) and puls3.manifestVersion.
• No change to the Identity Registry interface (feat: Agent Identity Registry contract #13): it uses register_full and set_metadata, within ADR-0002's limits.
• Deployed versions are immutable; a hire always runs the version it was paid for.

Acceptance criteria

• All 7 questions are answered, each with a source or reasoning (question 5 partially: steps 3 and 5 pending ADR-0003)
• ADR-0004 exists and lists its impact on each affected issue
• The example manifest follows the proposed fields exactly
• The prompt-privacy decision (question 3) is explicit
• The owners of feat: AgentManifest domain model and validation #34, feat: Agent Studio endpoints (drafts, test run, deploy) #35, and feat: Agent Studio UI (builder, playground, deploy) #37 confirm in the PR that they can start

Comment for #6 (deliverable 4): #6 is closed, so the metadata fields are listed here instead. The Identity Registry must accept two metadata keys per agent, which it already does through set_metadata / register_full (key ≤ 64 chars, value ≤ 4,096 bytes):

Key	Value
puls3.manifestHash	32 bytes: SHA-256 of `salt
puls3.manifestVersion	The manifest version

Verification evidence

The example manifest was checked against every rule in the spike (field order and names, lengths, kebab-case unique skill IDs, input/output limits, integer price, no floats):

$ python validate_manifest.py docs/architecture/examples/agent-manifest.example.json
VALIDO
prompt len 429 | canonical bytes 1280 | sha256(salt||canon) computed

• sha256 exists in soroban-sdk's Crypto and in pure Dart (package:crypto).
• Every external link in both documents returns HTTP 200 (checked 2026-09-26).
• Relative links resolve.

Notes for reviewers

• Initial values to tune after the demo: the 20 test runs per builder per day, the length limits, and the model allowlist. Which models the runtime supports first is a feat: agent runtime executing deployed manifests #20 decision.
• The issue text says "On Stellar there is no agent registry yet"; the spike notes that Stellar 8004 exists (as ADR-0002 does).

[cloudflare-workers-and-pages]

Deploying puls3 with    Cloudflare Pages

Latest commit:	bf7137b
Status:	✅  Deploy successful!
Preview URL:	https://af23713c.puls3-4lw.pages.dev
Branch Preview URL:	https://docs-33-agent-definition.puls3-4lw.pages.dev

View logs