# Class Profiles

[![Prototype checks](https://github.com/sylin-org/classprofiles/actions/workflows/validate.yml/badge.svg)](https://github.com/sylin-org/classprofiles/actions/workflows/validate.yml)

> **Prototype 0.1 · for discussion · not a standard**

## The question

Can an agent use one small Calendar contract unchanged across unlike MCP servers?

A Class Profile is a candidate contract for a capability class. It names the shared operations, their inputs and results, optional facets, degradation rules, and behavioral examples. A server may implement the contract directly or project an existing API through a binding capsule.

[classprofiles.org](https://classprofiles.org) illustrates the intended property with two deterministic local backends: the profile requests and comparable outcome stay the same while the backend traces differ. The illustration is a simulation, not implementation or conformance evidence.

## Scope of Prototype 0.1

The prototype contains one Calendar vertical slice:

- one Core baseline with six verbs;
- optional recurrence, RSVP, and reminders facets;
- one worked vendor member;
- native implementation and projection guidance;
- one profile descriptor and five fixture documents containing 15 scenarios.

[`profiles/calendar/profile.json`](profiles/calendar/profile.json) is authoritative within this prototype. The fixtures make its intended behavior concrete. Everything remains amendable.

## Worked artifacts

Start with the artifact closest to your task:

1. **Use the capability:** [`profiles/calendar/SKILL.md`](profiles/calendar/SKILL.md)
2. **Review the candidate contract:** [`profiles/calendar/profile.json`](profiles/calendar/profile.json)
3. **Read its rationale:** [`profiles/calendar/PROFILE.md`](profiles/calendar/PROFILE.md)
4. **Inspect the cases:** [`profiles/calendar/fixtures/`](profiles/calendar/fixtures/)
5. **Implement it directly:** [`guides/build-a-server.md`](guides/build-a-server.md)
6. **Map an existing server:** [`guides/wrap-a-server.md`](guides/wrap-a-server.md)

Run the repository checks with:

```powershell
npm test
pwsh ./scripts/validate.ps1
```

The artifact validator currently finds six JSON files and 15 fixture scenarios. These checks validate this repository; they do not test an external implementation.

## What it shows—and what it does not

Prototype 0.1 shows:

- a reviewable candidate contract for one capability class;
- explicit Core, optional, and degradation boundaries;
- deterministic examples of the intended behavior;
- how direct and projected backends could present the same profile surface;
- a local simulation of one unchanged two-call journey.

It does not show:

- two independent real backends passing the same suite;
- an official runner, passing Claim, receipt, or certification;
- a registry or discovery mechanism;
- that the design generalizes beyond Calendar;
- an adopted or stable standard.

## Questions for discussion

- Is the Core baseline the smallest useful Calendar contract?
- Do the fixtures distinguish semantic agreement from matching JSON shapes?
- Are facets and explicit degradation enough to avoid pretending every backend supports the same jobs?
- Can two independent implementations complete the same agent journey without backend-specific reasoning?
- Which parts should be removed, renamed, or replaced by existing work?

Concrete counterexamples are more useful than endorsements. See [CONTRIBUTING.md](CONTRIBUTING.md) for the current contribution boundary and [PRIOR-ART.md](PRIOR-ART.md) for related designs and lessons.

## Repository map

| Path | Purpose |
|---|---|
| [`profiles/calendar/`](profiles/calendar/) | Calendar descriptor, human view, operating skill, and fixtures |
| [`spec/`](spec/) | Reusable concepts behind the worked profile |
| [`guides/`](guides/) | Direct implementation and projection paths |
| [`src/`](src/) | Eleventy website and local backend-swap illustration |
| [`PRIOR-ART.md`](PRIOR-ART.md) | Related protocols, interfaces, and specification practices |
| [`DEVELOPMENT.md`](DEVELOPMENT.md) | Local checks, site build, and Cloudflare Pages delivery |
| [`AGENTS.md`](AGENTS.md) | Model-oriented reading order and invariants |
| [`llms.txt`](llms.txt) | Compact machine-readable repository index |

## Relationship to Shiguchi

[Shiguchi](https://github.com/sylin-org/shiguchi) is a separate reference-toolkit project from which this experiment was extracted. Class Profiles contains the candidate contract; Shiguchi is one possible consumer or implementation. Keeping them separate allows other implementations to evaluate the proposal on equal terms.

## License

This repository is available under [Apache-2.0](LICENSE). [NOTICE](NOTICE) records provenance.