# Agent Package Format Specification

**Version:** 1.0
**Status:** Draft

## Overview

The `.agent` format is a ZIP-based archive for packaging portable AI agents.
Every `.agent` file contains a `manifest.yaml` describing the agent, the
agent source code, and a `checksums.sha256` integrity file.

## Archive layout

```
my-agent-0.1.0.agent          (ZIP archive)
  manifest.yaml                Zone 1 + Zone 2
  checksums.sha256             SHA-256 hashes for all user files
  src/agent.py                 Entry point (example)
  requirements.txt             Dependencies (example)
```

## Manifest zones

### Zone 1 — open core

Zone 1 fields are authored by the developer and describe the agent:

| Section | Purpose |
|---------|---------|
| Identity | `name`, `version`, `description`, `author`, `tags` |
| Runtime | `language`, `language_version`, `entry_point`, `dependencies` |
| Model | LLM preferences (`preferred`, `agnostic`, `minimum_context`) |
| Framework | Agent framework (`langchain`, `crewai`, etc.) |
| Capabilities | Tools the agent exposes (`id`, `scope`, `required`) |
| Permissions | Data classifications and environment variable access |
| Execution | Type (`scheduled`, `triggered`, `continuous`, `on-demand`), schedule, timeouts, retry |
| Resources | Compute requests (`memory_mb`, `cpu_shares`, `network`) |

### Zone 2 — `_package`

Zone 2 is auto-generated by `agent pack` and must not be edited by hand:

| Field | Description |
|-------|-------------|
| `format` | Always `agent-package-format` |
| `format_version` | Package format version |
| `packaged_at` | ISO 8601 build timestamp |
| `packaged_by` | Tool that created the package |
| `manifest_hash` | SHA-256 of Zone 1 content |
| `files_hash` | Combined SHA-256 of all user files |
| `total_files` | Number of files in the archive |
| `package_size_bytes` | Archive size in bytes |

## Validation pipeline

The agentpk CLI validates `.agent` packages in six stages:

1. **Pre-flight** — directory exists, YAML parseable, `spec_version` known
2. **Identity** — `name`, `version`, `description`, and `runtime` present
3. **File presence** — `entry_point` and `dependencies` files exist on disk
4. **Consistency** — field values match allowed enums, cross-field rules
5. **Checksums** — `checksums.sha256` present and all hashes match *(package only)*
6. **Post-package** — `_package.manifest_hash` matches Zone 1 *(package only)*

Stages 1-4 run during `agent validate` on directories.
All six stages run during `agent validate` on `.agent` files.

## Naming rules

Agent names must match `^[a-z][a-z0-9-]*$` — lowercase letters, digits, and
hyphens only, starting with a letter.

## Versioning

Agent versions must follow semantic versioning (`MAJOR.MINOR.PATCH`), with
optional pre-release and build metadata suffixes per the SemVer 2.0 spec.

## Checksums

The `checksums.sha256` file contains one line per user file:

```
sha256:<hex-digest>  <relative-path>
```

The file itself is excluded from its own checksums.

## Extending .agent

The `.agent` format is designed to be extended. Future specification versions
may introduce additional manifest sections, new validation stages, or
supplementary metadata files inside the archive. Extensions should:

- Use new top-level keys in `manifest.yaml` (do not modify existing keys)
- Increment `spec_version` for breaking changes
- Remain backward-compatible within a major version when possible
- Document new fields in this specification before adoption

Third-party tools that read `.agent` files should ignore unrecognised
top-level keys to maintain forward compatibility.

Proposals for spec changes should be discussed via a GitHub issue at
[nomoticai/agentpk](https://github.com/nomoticai/agentpk) before
implementation.

## License

This specification is licensed under
[CC BY 4.0](https://creativecommons.org/licenses/by/4.0/).
