agent-instruction-protocol 0.7.0__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (102) hide show
  1. agent_instruction_protocol-0.7.0/.github/workflows/release.yml +222 -0
  2. agent_instruction_protocol-0.7.0/.gitignore +11 -0
  3. agent_instruction_protocol-0.7.0/.python-version +1 -0
  4. agent_instruction_protocol-0.7.0/AGENTS.md +125 -0
  5. agent_instruction_protocol-0.7.0/CHANGELOG.md +206 -0
  6. agent_instruction_protocol-0.7.0/LICENSE +201 -0
  7. agent_instruction_protocol-0.7.0/PKG-INFO +474 -0
  8. agent_instruction_protocol-0.7.0/README.md +453 -0
  9. agent_instruction_protocol-0.7.0/docs/PLAN-0.6a0.md +492 -0
  10. agent_instruction_protocol-0.7.0/docs/cli-json.md +269 -0
  11. agent_instruction_protocol-0.7.0/docs/client-execution.md +146 -0
  12. agent_instruction_protocol-0.7.0/docs/examples/aip-runtime-session.md +523 -0
  13. agent_instruction_protocol-0.7.0/docs/run-modes.md +69 -0
  14. agent_instruction_protocol-0.7.0/docs/running.md +363 -0
  15. agent_instruction_protocol-0.7.0/docs/sdk.md +120 -0
  16. agent_instruction_protocol-0.7.0/docs/server-design.md +400 -0
  17. agent_instruction_protocol-0.7.0/docs/state.md +237 -0
  18. agent_instruction_protocol-0.7.0/docs/upgrading.md +177 -0
  19. agent_instruction_protocol-0.7.0/examples/billing-support/SKILL.md +127 -0
  20. agent_instruction_protocol-0.7.0/examples/billing-support/assets/config.json +1 -0
  21. agent_instruction_protocol-0.7.0/examples/billing-support/assets/policy.md +4 -0
  22. agent_instruction_protocol-0.7.0/examples/billing-support/assets/reply.md +12 -0
  23. agent_instruction_protocol-0.7.0/examples/billing-support/references/help.md +5 -0
  24. agent_instruction_protocol-0.7.0/examples/billing-support/scripts/escalate.py +15 -0
  25. agent_instruction_protocol-0.7.0/examples/billing-support/source/README.md +6 -0
  26. agent_instruction_protocol-0.7.0/img/aip-authoring.png +0 -0
  27. agent_instruction_protocol-0.7.0/img/aip-console-example-email-blast.png +0 -0
  28. agent_instruction_protocol-0.7.0/img/aip-console-example.png +0 -0
  29. agent_instruction_protocol-0.7.0/img/aip-console-example2.png +0 -0
  30. agent_instruction_protocol-0.7.0/img/aip-logo.png +0 -0
  31. agent_instruction_protocol-0.7.0/img/aip-skill-example2.png +0 -0
  32. agent_instruction_protocol-0.7.0/img/aip.png +0 -0
  33. agent_instruction_protocol-0.7.0/install.sh +75 -0
  34. agent_instruction_protocol-0.7.0/packages/aip-spec/LICENSE +201 -0
  35. agent_instruction_protocol-0.7.0/packages/aip-spec/README.md +29 -0
  36. agent_instruction_protocol-0.7.0/packages/aip-spec/docs/specification.md +266 -0
  37. agent_instruction_protocol-0.7.0/packages/aip-spec/hatch_build.py +29 -0
  38. agent_instruction_protocol-0.7.0/packages/aip-spec/pyproject.toml +46 -0
  39. agent_instruction_protocol-0.7.0/packages/aip-spec/src/aip_spec/__init__.py +15 -0
  40. agent_instruction_protocol-0.7.0/packages/aip-spec/src/aip_spec/agents.py +269 -0
  41. agent_instruction_protocol-0.7.0/packages/aip-spec/src/aip_spec/cli.py +203 -0
  42. agent_instruction_protocol-0.7.0/packages/aip-spec/src/aip_spec/models.py +322 -0
  43. agent_instruction_protocol-0.7.0/packages/aip-spec/src/aip_spec/resources.py +58 -0
  44. agent_instruction_protocol-0.7.0/packages/aip-spec/src/aip_spec/runtime-0.5a1.md +19 -0
  45. agent_instruction_protocol-0.7.0/packages/aip-spec/src/aip_spec/runtime-0.6a0.md +19 -0
  46. agent_instruction_protocol-0.7.0/packages/aip-spec/src/aip_spec/runtime.md +19 -0
  47. agent_instruction_protocol-0.7.0/packages/aip-spec/src/aip_spec/skill.py +503 -0
  48. agent_instruction_protocol-0.7.0/packages/aip-spec/tests/conftest.py +9 -0
  49. agent_instruction_protocol-0.7.0/packages/aip-spec/tests/fixtures/dialogue-graph.yaml +168 -0
  50. agent_instruction_protocol-0.7.0/packages/aip-spec/tests/test_spec.py +627 -0
  51. agent_instruction_protocol-0.7.0/pyproject.toml +46 -0
  52. agent_instruction_protocol-0.7.0/skills/aip-compile/SKILL.md +482 -0
  53. agent_instruction_protocol-0.7.0/skills/aip-compile/assets/procedure.schema.json +740 -0
  54. agent_instruction_protocol-0.7.0/skills/aip-compile/references/skill-creation-best-practices.md +241 -0
  55. agent_instruction_protocol-0.7.0/skills/aip-runtime/SKILL.md +117 -0
  56. agent_instruction_protocol-0.7.0/src/aip/__init__.py +15 -0
  57. agent_instruction_protocol-0.7.0/src/aip/client/__init__.py +20 -0
  58. agent_instruction_protocol-0.7.0/src/aip/client/aip-runtime/SKILL.md +117 -0
  59. agent_instruction_protocol-0.7.0/src/aip/client/backend.py +306 -0
  60. agent_instruction_protocol-0.7.0/src/aip/client/cli.py +702 -0
  61. agent_instruction_protocol-0.7.0/src/aip/client/executor.py +139 -0
  62. agent_instruction_protocol-0.7.0/src/aip/client/resolver.py +120 -0
  63. agent_instruction_protocol-0.7.0/src/aip/client/runner.py +304 -0
  64. agent_instruction_protocol-0.7.0/src/aip/client/server.py +219 -0
  65. agent_instruction_protocol-0.7.0/src/aip/db/__init__.py +1 -0
  66. agent_instruction_protocol-0.7.0/src/aip/db/neo4j.py +58 -0
  67. agent_instruction_protocol-0.7.0/src/aip/errors.py +18 -0
  68. agent_instruction_protocol-0.7.0/src/aip/model/__init__.py +24 -0
  69. agent_instruction_protocol-0.7.0/src/aip/model/engine.py +314 -0
  70. agent_instruction_protocol-0.7.0/src/aip/model/environment.py +150 -0
  71. agent_instruction_protocol-0.7.0/src/aip/model/procedure.py +116 -0
  72. agent_instruction_protocol-0.7.0/src/aip/model/resources.py +85 -0
  73. agent_instruction_protocol-0.7.0/src/aip/model/steps.py +607 -0
  74. agent_instruction_protocol-0.7.0/src/aip/model/types.py +150 -0
  75. agent_instruction_protocol-0.7.0/src/aip/sdk.py +716 -0
  76. agent_instruction_protocol-0.7.0/src/aip/server/__init__.py +1 -0
  77. agent_instruction_protocol-0.7.0/src/aip/server/app.py +639 -0
  78. agent_instruction_protocol-0.7.0/src/aip/server/backend.py +132 -0
  79. agent_instruction_protocol-0.7.0/src/aip/server/backends/__init__.py +1 -0
  80. agent_instruction_protocol-0.7.0/src/aip/server/backends/filesystem.py +414 -0
  81. agent_instruction_protocol-0.7.0/src/aip/server/backends/neo4j.py +1030 -0
  82. agent_instruction_protocol-0.7.0/src/aip/server/config.py +236 -0
  83. agent_instruction_protocol-0.7.0/src/aip/server/governance.py +196 -0
  84. agent_instruction_protocol-0.7.0/src/aip/server/records.py +293 -0
  85. agent_instruction_protocol-0.7.0/src/aip/server/search.py +220 -0
  86. agent_instruction_protocol-0.7.0/src/aip/spec/__init__.py +18 -0
  87. agent_instruction_protocol-0.7.0/src/aip/spec/loader.py +119 -0
  88. agent_instruction_protocol-0.7.0/tests/conftest.py +15 -0
  89. agent_instruction_protocol-0.7.0/tests/server/test_config.py +126 -0
  90. agent_instruction_protocol-0.7.0/tests/server/test_contract.py +789 -0
  91. agent_instruction_protocol-0.7.0/tests/server/test_http.py +681 -0
  92. agent_instruction_protocol-0.7.0/tests/server/test_records.py +100 -0
  93. agent_instruction_protocol-0.7.0/tests/server/test_runs.py +258 -0
  94. agent_instruction_protocol-0.7.0/tests/server/test_search.py +117 -0
  95. agent_instruction_protocol-0.7.0/tests/test_cli_json.py +372 -0
  96. agent_instruction_protocol-0.7.0/tests/test_client_execution.py +223 -0
  97. agent_instruction_protocol-0.7.0/tests/test_loader.py +86 -0
  98. agent_instruction_protocol-0.7.0/tests/test_model.py +306 -0
  99. agent_instruction_protocol-0.7.0/tests/test_runner.py +450 -0
  100. agent_instruction_protocol-0.7.0/tests/test_runtime_skill.py +140 -0
  101. agent_instruction_protocol-0.7.0/tests/test_sdk.py +267 -0
  102. agent_instruction_protocol-0.7.0/uv.lock +609 -0
@@ -0,0 +1,222 @@
1
+ name: Release to PyPI
2
+
3
+ # Manual trigger from the Actions tab, after the release PR is merged. Reads the version from
4
+ # both pyprojects (the release PR aligned them), refuses if they differ or the tag exists,
5
+ # builds all four distributions, pushes the tag, publishes `aip-spec` and then
6
+ # `agent-instruction-protocol` with PyPI Trusted Publishing, and cuts a GitHub Release whose
7
+ # notes are the `## [X.Y.Z]` section of CHANGELOG.md.
8
+ #
9
+ # Two publish jobs because PyPI allows one pending publisher per (repo, workflow, environment):
10
+ # `aip-spec` publishes from the `release-spec` environment and `agent-instruction-protocol`
11
+ # from `release`. The spec goes first so the runtime's exact pin (`aip-spec==X.Y.Z`) resolves
12
+ # the moment the runtime lands. The GitHub environments and the pending publishers are set up
13
+ # by hand once (issue #17, "Before starting").
14
+ #
15
+ # `target: testpypi` is the dry run for a new or changed workflow: same checks, same build,
16
+ # both uploads go to test.pypi.org (its own account and its own two pending publishers under
17
+ # the same names), no tag is pushed and no GitHub Release is created. TestPyPI refuses a
18
+ # filename it has seen before, so one dry run per version; to repeat, suffix the version
19
+ # `.dev1` in both pyprojects on a scratch branch.
20
+ on:
21
+ workflow_dispatch:
22
+ inputs:
23
+ target:
24
+ description: "Where to publish. testpypi is the dry run: no tag, no GitHub Release."
25
+ type: choice
26
+ options: [pypi, testpypi]
27
+ default: pypi
28
+
29
+ jobs:
30
+ build:
31
+ name: Check, build, tag
32
+ runs-on: ubuntu-latest
33
+ permissions:
34
+ contents: write # push the tag
35
+ outputs:
36
+ version: ${{ steps.v.outputs.version }}
37
+ tag: ${{ steps.v.outputs.tag }}
38
+ steps:
39
+ - uses: actions/checkout@v4
40
+
41
+ - name: Install uv
42
+ uses: astral-sh/setup-uv@v6
43
+ with:
44
+ enable-cache: true
45
+
46
+ - name: Set up Python
47
+ run: uv python install 3.14
48
+
49
+ - name: Resolve the version from both pyprojects
50
+ id: v
51
+ # The two packages always share a version and the runtime pins the spec exactly, so
52
+ # all three numbers must agree before anything is built.
53
+ run: |
54
+ uv run --no-project python - <<'PY' >> "$GITHUB_OUTPUT"
55
+ import re, sys, tomllib, pathlib
56
+ runtime = tomllib.loads(pathlib.Path("pyproject.toml").read_text())["project"]
57
+ spec = tomllib.loads(pathlib.Path("packages/aip-spec/pyproject.toml").read_text())["project"]
58
+ pin = next((d for d in runtime["dependencies"] if re.match(r"aip-spec\s*==", d)), "")
59
+ pinned = pin.split("==", 1)[1].strip() if pin else None
60
+ if not (runtime["version"] == spec["version"] == pinned):
61
+ print(f"::error::versions differ: pyproject.toml {runtime['version']}, "
62
+ f"packages/aip-spec/pyproject.toml {spec['version']}, pin {pin or '(none)'}. "
63
+ "Align all three in the release PR.", file=sys.stderr)
64
+ sys.exit(1)
65
+ print(f"version={runtime['version']}")
66
+ print(f"tag=v{runtime['version']}")
67
+ PY
68
+ echo "version $(grep '^version=' "$GITHUB_OUTPUT" | tail -1 | cut -d= -f2)"
69
+
70
+ - name: Refuse to release a version that already has a tag
71
+ # Forces a version bump before re-running. Without this, a re-run after a successful
72
+ # tag-and-publish would try to double-publish. Runs for testpypi too: a dry run of a
73
+ # version that has shipped is a mistake.
74
+ run: |
75
+ if git ls-remote --tags origin "refs/tags/${{ steps.v.outputs.tag }}" | grep -q .; then
76
+ echo "::error::tag ${{ steps.v.outputs.tag }} already exists. Bump both pyprojects before re-running."
77
+ exit 1
78
+ fi
79
+
80
+ - name: Build all four distributions
81
+ # Before tagging, so a build failure leaves the repo clean. `--all-packages` builds
82
+ # every workspace member: a wheel and an sdist each for agent-instruction-protocol
83
+ # and aip-spec.
84
+ run: |
85
+ rm -rf dist/
86
+ uv build --all-packages
87
+ ls -1 dist/
88
+ count=$(find dist/ -type f \( -name '*.whl' -o -name '*.tar.gz' \) | wc -l) # uv also writes dist/.gitignore
89
+ if [ "$count" -ne 4 ]; then
90
+ echo "::error::expected 4 files in dist/, found $count"
91
+ exit 1
92
+ fi
93
+ for d in agent_instruction_protocol aip_spec; do
94
+ test -f dist/${d}-${{ steps.v.outputs.version }}-py3-none-any.whl
95
+ test -f dist/${d}-${{ steps.v.outputs.version }}.tar.gz
96
+ done
97
+
98
+ - name: Extract release notes from CHANGELOG.md
99
+ # Pulls the section under `## [<version>] ...` up to (but not including) the next
100
+ # `## [...` heading. Empty file is fine; the GitHub Release just won't have a body.
101
+ run: |
102
+ awk -v ver="${{ steps.v.outputs.version }}" '
103
+ $0 ~ "^## \\[" ver "\\]" { found=1; next }
104
+ found && /^## \[/ { exit }
105
+ found { print }
106
+ ' CHANGELOG.md > release-notes.md
107
+ echo "----- release-notes.md -----"
108
+ cat release-notes.md
109
+ if [ ! -s release-notes.md ]; then
110
+ echo "::warning::CHANGELOG.md has no '## [${{ steps.v.outputs.version }}]' section; the GitHub Release will have no notes."
111
+ fi
112
+
113
+ - name: Upload the distributions and the notes
114
+ uses: actions/upload-artifact@v4
115
+ with:
116
+ name: release-${{ steps.v.outputs.version }}
117
+ path: |
118
+ dist/
119
+ release-notes.md
120
+ if-no-files-found: error
121
+
122
+ - name: Create and push the tag
123
+ if: inputs.target == 'pypi'
124
+ # Before the first publish, as in the original single-package workflow: a publish
125
+ # failure leaves a tag with no release behind it, which is visible and recoverable.
126
+ run: |
127
+ git config user.name "github-actions[bot]"
128
+ git config user.email "github-actions[bot]@users.noreply.github.com"
129
+ git tag -a "${{ steps.v.outputs.tag }}" -m "Release ${{ steps.v.outputs.tag }}"
130
+ git push origin "${{ steps.v.outputs.tag }}"
131
+
132
+ publish-spec:
133
+ name: Publish aip-spec
134
+ needs: build
135
+ runs-on: ubuntu-latest
136
+ environment:
137
+ name: release-spec
138
+ url: ${{ inputs.target == 'testpypi' && 'https://test.pypi.org/p/aip-spec' || 'https://pypi.org/p/aip-spec' }}
139
+ permissions:
140
+ contents: read
141
+ id-token: write # PyPI Trusted Publishing
142
+ steps:
143
+ - uses: actions/download-artifact@v4
144
+ with:
145
+ name: release-${{ needs.build.outputs.version }}
146
+
147
+ - name: Keep only the aip-spec files
148
+ run: |
149
+ mkdir -p upload
150
+ mv dist/aip_spec-*.whl dist/aip_spec-*.tar.gz upload/
151
+ ls -1 upload/
152
+
153
+ - name: Publish aip-spec
154
+ uses: pypa/gh-action-pypi-publish@release/v1
155
+ with:
156
+ packages-dir: upload/
157
+ repository-url: ${{ inputs.target == 'testpypi' && 'https://test.pypi.org/legacy/' || 'https://upload.pypi.org/legacy/' }}
158
+
159
+ publish-runtime:
160
+ name: Publish agent-instruction-protocol
161
+ needs: [build, publish-spec]
162
+ runs-on: ubuntu-latest
163
+ environment:
164
+ name: release
165
+ url: ${{ inputs.target == 'testpypi' && 'https://test.pypi.org/p/agent-instruction-protocol' || 'https://pypi.org/p/agent-instruction-protocol' }}
166
+ permissions:
167
+ contents: read
168
+ id-token: write # PyPI Trusted Publishing
169
+ steps:
170
+ - uses: actions/download-artifact@v4
171
+ with:
172
+ name: release-${{ needs.build.outputs.version }}
173
+
174
+ - name: Keep only the agent-instruction-protocol files
175
+ run: |
176
+ mkdir -p upload
177
+ mv dist/agent_instruction_protocol-*.whl dist/agent_instruction_protocol-*.tar.gz upload/
178
+ ls -1 upload/
179
+
180
+ - name: Publish agent-instruction-protocol
181
+ uses: pypa/gh-action-pypi-publish@release/v1
182
+ with:
183
+ packages-dir: upload/
184
+ repository-url: ${{ inputs.target == 'testpypi' && 'https://test.pypi.org/legacy/' || 'https://upload.pypi.org/legacy/' }}
185
+
186
+ - name: How to verify the dry run
187
+ if: inputs.target == 'testpypi'
188
+ # TestPyPI holds only these two packages; the dependencies come from PyPI.
189
+ run: |
190
+ {
191
+ echo "## Dry run published to TestPyPI"
192
+ echo
193
+ echo "Verify in a fresh venv:"
194
+ echo
195
+ echo '```'
196
+ echo "pip install --index-url https://test.pypi.org/simple/ --extra-index-url https://pypi.org/simple/ agent-instruction-protocol==${{ needs.build.outputs.version }}"
197
+ echo "aip --version"
198
+ echo '```'
199
+ } | tee -a "$GITHUB_STEP_SUMMARY"
200
+
201
+ github-release:
202
+ name: GitHub Release
203
+ if: inputs.target == 'pypi'
204
+ needs: [build, publish-runtime]
205
+ runs-on: ubuntu-latest
206
+ permissions:
207
+ contents: write # create the GitHub Release
208
+ steps:
209
+ - uses: actions/download-artifact@v4
210
+ with:
211
+ name: release-${{ needs.build.outputs.version }}
212
+
213
+ - name: Create GitHub Release
214
+ # After both publishes, so a publish failure doesn't leave behind a GitHub Release
215
+ # pointing at nothing on PyPI. The tag already exists; the action attaches to it.
216
+ uses: softprops/action-gh-release@v2
217
+ with:
218
+ tag_name: ${{ needs.build.outputs.tag }}
219
+ name: ${{ needs.build.outputs.tag }}
220
+ body_path: release-notes.md
221
+ files: dist/*
222
+ fail_on_unmatched_files: true
@@ -0,0 +1,11 @@
1
+ scratch/
2
+ *identity-and-naming.md
3
+ .DS_Store
4
+ .idea/
5
+ .claude
6
+ __pycache__/
7
+ .aip/
8
+ .obsidian/
9
+ .env
10
+ dist/
11
+ *.egg-info/
@@ -0,0 +1 @@
1
+ 3.14
@@ -0,0 +1,125 @@
1
+ # AGENTS.md
2
+
3
+ Instructions for AI agents working **on** this repository. If you are an agent being asked to
4
+ *use* AIP, read `skills/aip-runtime/SKILL.md` (running a published procedure) or
5
+ `skills/aip-compile/SKILL.md` (compiling material into one) instead.
6
+
7
+ ## What this repo is
8
+
9
+ The Agent Instruction Protocol (AIP): a format for procedures as graph-shaped Agent Skills, and
10
+ the runtime that executes them. Two Python packages live here as one uv workspace and release
11
+ together under one version:
12
+
13
+ | package | where | what |
14
+ |---|---|---|
15
+ | `agent-instruction-protocol` | the root (`src/aip/`) | the runtime: the `aip` command, the Python SDK, `aip server`, the Neo4j and filesystem backends, the `aip-runtime` skill |
16
+ | `aip-spec` | `packages/aip-spec/` | the format: pydantic models, the JSON Schema generated from them, the runtime block every skill carries, the `aip-spec` validator CLI, the `aip-compile` skill and the example |
17
+
18
+ The distribution name of the runtime is `agent-instruction-protocol` (PyPI blocks `aip` as a
19
+ look-alike of an existing project); its module and command are `aip`. The runtime depends on
20
+ `aip-spec==<the same version>`. The web console is a separate repository,
21
+ [aip-console](https://github.com/zach-blumenfeld/aip-console), with its own npm version.
22
+
23
+ ## Repo map
24
+
25
+ | Path | What's there |
26
+ |---|---|
27
+ | `pyproject.toml` | the `agent-instruction-protocol` package and the uv workspace root (`[tool.uv.workspace] members = ["packages/*"]`); `testpaths` lists both packages' tests |
28
+ | `src/aip/client/` | the `aip` command (`cli.py`), the local runner, the executor that runs scripts and asks the decision model, the resolver, the HTTP client; `aip-runtime/SKILL.md` is the bundled copy of the runtime skill |
29
+ | `src/aip/model/` | the execution engine: steps, types, the environment a run carries, the procedure graph |
30
+ | `src/aip/server/` | `aip server`: the FastAPI app, catalog search, run records, governance, and `backends/` (Neo4j, filesystem) |
31
+ | `src/aip/spec/` | loads a skill folder through `aip_spec` into the runtime's model |
32
+ | `src/aip/sdk.py` | `aip.Client`, the runtime as a library; the CLI is a thin wrapper over it (`docs/sdk.md`) |
33
+ | `tests/` | the runtime's tests; `tests/server/` drives the HTTP API; the Neo4j backend tests skip unless `NEO4J_URI` is set |
34
+ | `packages/aip-spec/src/aip_spec/` | **where the format lives**: `models.py` (the pydantic models, `FORMAT_VERSION`, `SCHEMA_ID`, `SPEC_URL`), `runtime.md` (the runtime block; `runtime-0.5a1.md` and `runtime-0.6a0.md` are the earlier ones the validator still recognises), `cli.py` (`aip-spec validate`, `schema`, `runtime`, `skill`, `example`), `resources.py` (finds the skill and the example in a checkout or a wheel, `SKILL_NAME`, `LEGACY_SKILL_NAMES`), `agents.py` (the agent skills directories), `skill.py` |
35
+ | `packages/aip-spec/docs/specification.md` | the format specification as prose; the models are the source of truth |
36
+ | `packages/aip-spec/tests/` | the format's tests, including the schema-sync and runtime-block drift checks |
37
+ | `packages/aip-spec/hatch_build.py` | bundles `skills/aip-compile/` and `examples/` into the `aip_spec` wheel from the checkout or from the sdist |
38
+ | `skills/aip-compile/` | the authoring skill (`SKILL.md`, `references/`, `assets/procedure.schema.json`); reviewed line by line, keep diffs small |
39
+ | `skills/aip-runtime/` | the runtime skill agents read to run published procedures; `tests/test_runtime_skill.py` fails if it drifts from the copy under `src/aip/client/` or lags `FORMAT_VERSION` |
40
+ | `examples/billing-support/` | the bundled example skill; validation fails on `aip_version_mismatch` if the format moves without it |
41
+ | `docs/` | design and reference: `running.md`, `run-modes.md`, `state.md`, `client-execution.md`, `server-design.md`, `sdk.md`, `cli-json.md`, `upgrading.md` |
42
+ | `CHANGELOG.md` | one changelog for both packages; before `0.7.0` the two histories are interleaved and marked `(aip)` or `(aip-spec)` |
43
+ | `install.sh` | the one-command installer: uv, `aip-spec`, `agent-instruction-protocol[server]`, both skills, `aip skill prune` |
44
+ | `.github/workflows/release.yml` | the release workflow, below |
45
+
46
+ ## Conventions
47
+
48
+ - **Python, built with `uv` and `hatchling`.** `uv sync --group dev` to set up; `uv run pytest -q`
49
+ at the root runs both packages' tests and must pass before any commit. No `pip install`, no
50
+ `python -m venv`.
51
+ - **One version, two pyprojects.** `pyproject.toml` and `packages/aip-spec/pyproject.toml` carry
52
+ the same `version`, and the root's dependency pin `aip-spec==<version>` matches. The workflow
53
+ refuses to release if the three differ.
54
+ - **Change the format in one place and let the tests find the rest.** `models.py` is normative;
55
+ `aip-spec schema` regenerates the JSON Schema, and the schema-sync test fails until
56
+ `skills/aip-compile/assets/procedure.schema.json` matches. The runtime block in `runtime.md`
57
+ is copied into every skill under its own heading; the drift tests compare the copies.
58
+ - **Do not change behaviour in a release branch.** If a test must change for a path, say so in
59
+ the commit; if it must change for a behaviour, stop and write it down in the plan issue.
60
+ - **Plans live in issues, not in the repo.** The roadmap is
61
+ [#20](https://github.com/zach-blumenfeld/aip/issues/20); each release has a plan issue with a
62
+ checklist of milestones, each naming the command that proves it. A fresh agent implements one
63
+ milestone per session: read the plan's "Context" and "Rules", then only the first unchecked
64
+ milestone; run its proof, tick it, comment `Done <date>, commit <sha>: <one sentence>`, commit.
65
+ Product-visible questions sit under "Open items" with a default; take the default and say so.
66
+
67
+ ## Versioning
68
+
69
+ The rules, decided 2026-11-01 in the roadmap (#20):
70
+
71
+ - **Package version** `X.Y.Z` in both pyprojects, SemVer, pre-1.0 so breaking changes bump the
72
+ minor. Moves every release. PyPI distribution names: `agent-instruction-protocol` (import and
73
+ command `aip`) and `aip-spec`.
74
+ - **Format version** `X.Y` (`FORMAT_VERSION` in `models.py`, the runtime block heading of every
75
+ `SKILL.md`). It is the package's `major.minor` at the last release that changed the format. A
76
+ format change is breaking by definition, so it never happens in a patch release; the format has
77
+ no third number. An additive change (a new optional field) may ride on a patch release without
78
+ moving the format version.
79
+ - Concretely: 0.7.0 ships format `0.6a1`; 0.8.0 introduces `0.8`; 0.8.1 stays `0.8`; 0.9.0
80
+ introduces `0.9`.
81
+ - **Every format change ships `aip upgrade <folder>`** that rewrites a skill where the change is
82
+ mechanical, reports what it could not migrate, and validates the result. The validator's
83
+ outdated-format message names it.
84
+ - The console has its own package version (npm) and declares the minimum `aip` it works with
85
+ (`MINIMUM_AIP` in its `bin/aip-console.mjs`).
86
+
87
+ ## Releasing
88
+
89
+ Releases are cut by the **`.github/workflows/release.yml`** workflow, **triggered manually**
90
+ (Actions → *Release to PyPI* → Run workflow) by a maintainer **after the release PR is merged to
91
+ `main`**. The workflow reads the version from both pyprojects and refuses if they differ or if
92
+ the tag already exists, builds all four distributions (`uv build --all-packages`), tags
93
+ `vX.Y.Z`, publishes `aip-spec` and then `agent-instruction-protocol` to PyPI with Trusted
94
+ Publishing (two jobs, two GitHub environments, `release-spec` then `release`, because PyPI
95
+ allows one publisher per environment; the spec goes first so the runtime's exact pin resolves
96
+ the moment it lands), and cuts a GitHub Release whose body is the matching `## [X.Y.Z]` section
97
+ of `CHANGELOG.md`.
98
+
99
+ Running it with `target: testpypi` is the dry run for a new or changed workflow: same checks,
100
+ same build, both uploads go to test.pypi.org, no tag and no GitHub Release, and the run ends by
101
+ printing the `pip install` line to verify with. TestPyPI refuses a filename it has seen before,
102
+ so a failed dry run cannot be repeated at the same version: fix the workflow, then rerun with
103
+ the version temporarily suffixed `.dev1` in both pyprojects on a scratch branch, or accept one
104
+ dry run per version.
105
+
106
+ So an agent's job for a release is **prep only — never build, tag, or publish by hand:**
107
+
108
+ 1. **Align the version** in both `pyproject.toml` files and in the root's `aip-spec==` pin
109
+ (`version = "X.Y.Z"`; SemVer, pre-1.0 → breaking changes bump the minor), then `uv lock`.
110
+ 2. **Finalize `CHANGELOG.md`**: roll `## [Unreleased]` into a single `## [X.Y.Z] — <date>`
111
+ section (one section per release — the workflow extracts just that one). The `## [X.Y.Z]`
112
+ heading format is **load-bearing** (awk-matched); leave a fresh empty `## [Unreleased]` above
113
+ it.
114
+ 3. Open the release PR. The maintainer merges it and triggers the workflow.
115
+
116
+ The tags `vX.Y.Z` are shared by both packages; never move or force-push a published tag.
117
+
118
+ ## When you're unsure
119
+
120
+ - For what a procedure may contain, `packages/aip-spec/docs/specification.md` is the prose and
121
+ `models.py` is the law.
122
+ - For how a run moves, `docs/running.md`, `docs/state.md` and `docs/run-modes.md`; for the
123
+ server, `docs/server-design.md` with `docs/client-execution.md` on top.
124
+ - For what agents see, the two `SKILL.md` files are the contract; a change to the runtime's
125
+ behaviour that they describe changes them in the same commit.