spec: add identity.yaml — cryptographic agent identity (Ed25519)

[vystartasv]

Closes #70

What

Adds an optional identity.yaml file convention for verifiable agent identity via Ed25519 keypairs.

Changes

• spec/schemas/identity.schema.json — JSON Schema for identity.yaml (new)
• spec/SPECIFICATION.md — Section 3a added with field spec, example, and runtime semantics
• Directory structure — identity.yaml listed as optional file in agent repos

Schema (subset)

identity_version: "1.0.0-draft"
agent_id: "loan-reviewer"
public_key: "ed25519:BASE64"
key_fingerprint: "sha256:HEX"
passport_uri: "https://..."   # optional richer identity doc
did: "did:wwa:..."              # optional W3C DID
created_at: "2026-05-06T14:30:00Z"
hardware_binding: { type: tpm, attestation: ... }  # optional
owner: { name, email, proof }                        # optional

Alignment with #70

#70 proposed Ed25519 key binding + passport_uri + key_fingerprint. This PR implements all three plus optional DID, hardware binding, and owner identity from the reference standard.

Reference Standard

The schema implements the Works With Agents Identity Protocol (v1.0.0-draft, CC BY 4.0). All identity.yaml fields map 1:1 to the Identity Protocol — gitagent identity.yaml is a compatible subset.

Design decisions

• Separate file, not agent.yaml section — identity has its own lifecycle (rotation, revocation) independent of the manifest. Keeps agent.yaml clean.
• Fully optional — no breaking changes. Agents without identity.yaml work as before.
• Ed25519 — the proposal's suggested algorithm. Wide library support, compact signatures.

Tested

Schema validates against JSON Schema draft 2020-12. Manual test: identity.yaml conforms to identity.schema.json.

[shreyas-lyzr]

Thank you @vystartasv for picking this up — the work is real and the schema is competent. Brutally honest, though: there's a design conflict between this PR and the RFC that just merged (#73, spec/rfcs/identity.md), and I need to resolve it before this can land.

The conflict:

• This PR puts identity in a separate identity.yaml file alongside agent.yaml.
• The RFC (RFC: Optional cryptographic identity layer for gitagent manifests #73) puts identity in an identity block inside agent.yaml, not a separate file.

The RFC direction was the one I asked for in the original review of #70 — and the reason is to keep the canonical surface area finite. Every additional required-or-optional file at the repo root is a thing every adapter, validator, and reviewer has to know about. The identity block inside agent.yaml is one additional optional field on a schema we already validate.

The Works With Agents Identity Protocol angle:
Your linked WWA spec at workswithagents.dev is interesting — Section 7 of the merged RFC already includes a cross-walk to a reference identity protocol (Agent Passport System). The two can coexist: identity.passport_uri is exactly the pointer to a richer document like a WWA Identity profile or an APS profile. The spec doesn't pick a winner; it provides the seam.

Concrete ask before merge:

1. Move the schema into agent-yaml.schema.json under a new top-level optional identity property, matching the shape in Section 3 of spec/rfcs/identity.md. The fields you have (public_key, key_fingerprint, passport_uri, did, created_at, expires_at, hardware_binding, owner) are mostly compatible — the RFC has public_key, key_fingerprint, passport_uri, and signatures; your did, created_at, expires_at, hardware_binding, owner would fit cleanly under an optional passport_uri document or be additive optional fields on the block.
2. Drop spec/schemas/identity.schema.json as a separate file. Roll its constraints into the agent-yaml.schema.json identity block.
3. Update spec/SPECIFICATION.md Section 3a to describe the block (not the separate file).

If the WWA Identity Protocol is something you want to advocate as the canonical reference impl alongside APS, I'd accept a separate small PR adding a Section 7-style cross-walk to the RFC. But the spec mechanics need to be the identity block first.

If you'd rather close this and open a fresh PR aligned with the RFC, that works too — your authorship credit stays. Let me know which path you prefer.

Real apologies that this lands as a "redo" — the timing with the RFC merge was unfortunate. The substance of your work isn't wasted; the schema fields are mostly right.

[vystartasv]

Thank you for the thorough review — I appreciate you taking the time to map out exactly how this should align with RFC #73. The conflict is real and your reasoning is sound: keeping the canonical surface area finite by folding identity into the existing agent-yaml.schema.json is the right call.

I'm closing this PR. I'll open a fresh one that:

1. Adds an identity block to agent-yaml.schema.json matching the shape in Section 3 of spec/rfcs/identity.md, with the additive optional fields (did, created_at, expires_at, hardware_binding, owner) as optional properties on the block
2. Updates spec/SPECIFICATION.md Section 3a to describe the block
3. Leaves the separate-file approach dropped entirely

If there's room on the spec side afterward, I'd also like to open a cross-walk PR showing Works With Agents Identity Protocol as a passport_uri target alongside APS (Section 7 approach).

Thanks again for the clear direction — much better than a silent close. I'd rather redo it right than have it land wrong.