Skip to content

Commit 5565b68

Browse files
ebartiebarti
authored
Merge pull request #5 from ebarti/stack/phase-5-release-readiness
Prepare public release docs and checks
2 parents 7243a7b + 6930b74 commit 5565b68

14 files changed

Lines changed: 368 additions & 25 deletions

File tree

‎.planning/REQUIREMENTS.md‎

Lines changed: 7 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -149,11 +149,11 @@ Which phases cover which requirements. Updated during roadmap creation.
149149

150150
| Requirement | Phase | Status |
151151
|-------------|-------|--------|
152-
| PKG-01 | Phase 5 | Pending |
152+
| PKG-01 | Phase 5 | Ready (publish pending) |
153153
| PKG-02 | Phase 2 | Complete |
154154
| PKG-03 | Phase 1 | Complete |
155155
| PKG-04 | Phase 1 | Complete |
156-
| PKG-05 | Phase 5 | Pending |
156+
| PKG-05 | Phase 5 | Complete |
157157
| CORE-01 | Phase 1 | Complete |
158158
| CORE-02 | Phase 1 | Complete |
159159
| CORE-03 | Phase 1 | Complete |
@@ -177,14 +177,14 @@ Which phases cover which requirements. Updated during roadmap creation.
177177
| TEST-02 | Phase 2 | Complete |
178178
| TEST-03 | Phase 1 | Complete |
179179
| TEST-04 | Phase 1 | Complete |
180-
| TEST-05 | Phase 5 | Pending |
180+
| TEST-05 | Phase 5 | Complete |
181181
| TEST-06 | Phase 4 | Complete |
182-
| DOCS-01 | Phase 5 | Pending |
182+
| DOCS-01 | Phase 5 | Complete |
183183
| DOCS-02 | Phase 3 | Complete |
184184
| DOCS-03 | Phase 4 | Complete |
185-
| DOCS-04 | Phase 5 | Pending |
186-
| DOCS-05 | Phase 5 | Pending |
187-
| DOCS-06 | Phase 5 | Pending |
185+
| DOCS-04 | Phase 5 | Complete |
186+
| DOCS-05 | Phase 5 | Complete |
187+
| DOCS-06 | Phase 5 | Complete |
188188

189189
**Coverage:**
190190
- v1 requirements: 36 total

‎.planning/ROADMAP.md‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -21,7 +21,7 @@ Decimal phases appear between their surrounding integers in numeric order.
2121
- [x] **Phase 2: Events and Test Harness** - Optional extras skeleton, event system, and fake SDK contract tests.
2222
- [x] **Phase 3: Claude and Codex Runtimes** - First two real vendor adapters through the shared API.
2323
- [x] **Phase 4: Antigravity and Cross-Runtime Proof** - Third adapter plus same-task multi-runtime proof and Mestre compatibility checks.
24-
- [ ] **Phase 5: Public Release Readiness** - Documentation, capability matrix, live-smoke guidance, and PyPI publish checklist.
24+
- [x] **Phase 5: Public Release Readiness** - Documentation, capability matrix, live-smoke guidance, and PyPI publish checklist.
2525

2626
## Phase Details
2727

@@ -121,4 +121,4 @@ Phases execute in numeric order: 1 -> 2 -> 3 -> 4 -> 5
121121
| 2. Events and Test Harness | 3/3 | Complete | 2026-06-10 |
122122
| 3. Claude and Codex Runtimes | 3/3 | Complete | 2026-06-10 |
123123
| 4. Antigravity and Cross-Runtime Proof | 3/3 | Complete | 2026-06-10 |
124-
| 5. Public Release Readiness | 0/3 | Not started | - |
124+
| 5. Public Release Readiness | 3/3 | Complete | 2026-06-10 |

‎.planning/STATE.md‎

Lines changed: 17 additions & 13 deletions
Original file line numberDiff line numberDiff line change
@@ -1,12 +1,12 @@
11
---
22
gsd_state_version: '1.0'
3-
status: executing
3+
status: complete
44
progress:
55
total_phases: 5
6-
completed_phases: 4
6+
completed_phases: 5
77
total_plans: 15
8-
completed_plans: 12
9-
percent: 80
8+
completed_plans: 15
9+
percent: 100
1010
---
1111

1212
# Project State
@@ -18,21 +18,21 @@ See: .planning/PROJECT.md (updated 2026-06-10)
1818
**Core value:** Developers can run the same agentic task through Claude, Codex,
1919
or Antigravity using one small, typed Python API while preserving the
2020
vendor-specific capabilities needed for real work.
21-
**Current focus:** Phase 5: Public Release Readiness
21+
**Current focus:** Roadmap delivered as stacked PRs
2222

2323
## Current Position
2424

2525
Phase: 5 of 5 (Public Release Readiness)
26-
Plan: 0 of 3 in current phase
27-
Status: Phase 4 complete; ready for Phase 5
28-
Last activity: 2026-06-10 - Phase 4 added Antigravity and cross-runtime proof.
26+
Plan: 3 of 3 in current phase
27+
Status: All phases complete; stacked PR publication pending
28+
Last activity: 2026-06-10 - Phase 5 completed release readiness and build verification.
2929

30-
Progress: [########--] 80%
30+
Progress: [##########] 100%
3131

3232
## Performance Metrics
3333

3434
**Velocity:**
35-
- Total plans completed: 12
35+
- Total plans completed: 15
3636
- Average duration: n/a
3737
- Total execution time: 0.0 hours
3838

@@ -44,9 +44,10 @@ Progress: [########--] 80%
4444
| 2. Events and Test Harness | 3 | 3 | n/a |
4545
| 3. Claude and Codex Runtimes | 3 | 3 | n/a |
4646
| 4. Antigravity and Cross-Runtime Proof | 3 | 3 | n/a |
47+
| 5. Public Release Readiness | 3 | 3 | n/a |
4748

4849
**Recent Trend:**
49-
- Last 5 plans: 03-02, 03-03, 04-01, 04-02, 04-03
50+
- Last 5 plans: 04-02, 04-03, 05-01, 05-02, 05-03
5051
- Trend: n/a
5152

5253
*Updated after each plan completion*
@@ -71,15 +72,18 @@ Recent decisions affecting current work:
7172
so default CI remains credential-free.
7273
- Phase 4: Antigravity MCP stdio server env values are rejected because the
7374
SDK config surface does not expose env.
75+
- Phase 5: Actual PyPI publication remains pending after review/merge; release
76+
checklist includes a fresh name check.
7477

7578
### Pending Todos
7679

77-
None yet.
80+
- Publish stacked PRs.
81+
- Recheck PyPI name immediately before actual publication.
7882

7983
### Blockers/Concerns
8084

8185
- PyPI name availability for `agent-runtime-kit` must be rechecked immediately before publishing.
82-
- Vendor SDK surfaces are moving; adapter phases must verify installed package APIs before implementation.
86+
- Vendor SDK surfaces are moving; rerun live smoke tests before release if credentials are available.
8387

8488
## Deferred Items
8589

‎.planning/phases/05-public-release-readiness/05-CONTEXT.md‎

Lines changed: 61 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,61 @@
1+
# Phase 5: Public Release Readiness - Context
2+
3+
**Gathered:** 2026-06-10
4+
**Status:** Ready for planning
5+
6+
<domain>
7+
## Phase Boundary
8+
9+
Prepare the package for a first public PyPI release with README, provider docs,
10+
capability matrix, live smoke guidance, build verification, license, and
11+
publish checklist.
12+
13+
</domain>
14+
15+
<decisions>
16+
## Implementation Decisions
17+
18+
### Documentation
19+
- README should explain what the package is and is not.
20+
- Provider docs should document capability differences rather than hiding them.
21+
- Capability matrix should be concise and release-facing.
22+
23+
### Release Verification
24+
- Live smoke tests must be skipped unless explicit environment flags are set.
25+
- Publish checklist must include a fresh PyPI name check.
26+
- Build verification must produce wheel and sdist successfully.
27+
28+
### the agent's Discretion
29+
Keep release material practical and avoid promising hosted infrastructure or
30+
full orchestration features.
31+
32+
</decisions>
33+
34+
<code_context>
35+
## Existing Code Insights
36+
37+
### Reusable Assets
38+
- Phase 1-4 package, adapter, test, and docs structure is in place.
39+
40+
### Established Patterns
41+
- Tests use explicit opt-in for provider work that needs credentials.
42+
43+
### Integration Points
44+
- `docs/publish-checklist.md` is the final release gate.
45+
46+
</code_context>
47+
48+
<specifics>
49+
## Specific Ideas
50+
51+
The PyPI name `agent-runtime-kit` was rechecked during this phase and returned
52+
404/FREE on 2026-06-10.
53+
54+
</specifics>
55+
56+
<deferred>
57+
## Deferred Ideas
58+
59+
Actual PyPI publication is deferred until after review/merge.
60+
61+
</deferred>

‎.planning/phases/05-public-release-readiness/05-PLAN.md‎

Lines changed: 19 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,19 @@
1+
# Phase 5: Public Release Readiness - Plan
2+
3+
## Plan 05-01: README, provider setup docs, and capability matrix
4+
5+
- Expand README with install, provider extras, runtime fields, and doc links.
6+
- Add capability matrix.
7+
- Update provider docs for all three runtimes.
8+
9+
## Plan 05-02: Optional live smoke test harness and documentation
10+
11+
- Add skipped-by-default live smoke tests.
12+
- Gate live tests behind explicit environment flags.
13+
- Document provider setup and invocation.
14+
15+
## Plan 05-03: Build, publish checklist, and Mestre migration notes
16+
17+
- Add MIT license.
18+
- Add publish checklist with fresh PyPI name check.
19+
- Verify package build with `python -m build`.

‎.planning/phases/05-public-release-readiness/05-SUMMARY.md‎

Lines changed: 10 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,10 @@
1+
# Phase 5: Public Release Readiness - Summary
2+
3+
Implemented release-readiness artifacts:
4+
5+
- Expanded README.
6+
- Capability matrix.
7+
- Live smoke test docs and skipped-by-default tests.
8+
- Publish checklist with fresh PyPI name check.
9+
- MIT license.
10+
- Build verification.

‎.planning/phases/05-public-release-readiness/05-VERIFICATION.md‎

Lines changed: 19 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,19 @@
1+
---
2+
status: passed
3+
---
4+
5+
# Phase 5 Verification
6+
7+
## Automated Checks
8+
9+
- `uv run pytest` - passed, 22 tests and 3 opt-in live smoke tests skipped.
10+
- `uv run ruff check .` - passed.
11+
- `uv run mypy` - passed.
12+
- `uv run python -m build` - passed, produced wheel and sdist.
13+
14+
## Result
15+
16+
Phase 5 success criteria are satisfied. Release docs, capability matrix,
17+
skipped-by-default live smoke tests, publish checklist, fresh PyPI name check,
18+
license, and package build are complete. Actual PyPI publication remains
19+
pending until review/merge.

‎LICENSE‎

Lines changed: 21 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,21 @@
1+
MIT License
2+
3+
Copyright (c) 2026 Eloi Barti
4+
5+
Permission is hereby granted, free of charge, to any person obtaining a copy
6+
of this software and associated documentation files (the "Software"), to deal
7+
in the Software without restriction, including without limitation the rights
8+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9+
copies of the Software, and to permit persons to whom the Software is
10+
furnished to do so, subject to the following conditions:
11+
12+
The above copyright notice and this permission notice shall be included in all
13+
copies or substantial portions of the Software.
14+
15+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21+
SOFTWARE.

‎README.md‎

Lines changed: 60 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1,14 +1,32 @@
11
# agent-runtime-kit
22

33
`agent-runtime-kit` is a small Python runtime layer for agent SDKs. It gives
4-
applications one typed async API for dispatching an agentic task while keeping
5-
vendor-specific capabilities visible.
4+
applications one typed async API for dispatching an agentic task through Claude
5+
Agent SDK, OpenAI Codex SDK, or Google Antigravity SDK while keeping provider
6+
capabilities visible.
67

78
The package is intentionally not a router, benchmark harness, queue, hosted
89
service, or full agent framework. It is the reusable layer underneath those
910
systems: task models, runtime capabilities, event sinks, availability
1011
diagnostics, and adapters.
1112

13+
## Install
14+
15+
Core only:
16+
17+
```bash
18+
pip install agent-runtime-kit
19+
```
20+
21+
Provider extras:
22+
23+
```bash
24+
pip install "agent-runtime-kit[claude]"
25+
pip install "agent-runtime-kit[codex]"
26+
pip install "agent-runtime-kit[antigravity]"
27+
pip install "agent-runtime-kit[all]"
28+
```
29+
1230
```python
1331
import asyncio
1432

@@ -25,4 +43,43 @@ asyncio.run(main())
2543
```
2644

2745
The core package has no Claude, Codex, or Antigravity dependency. Vendor SDKs
28-
are added through optional extras in later phases.
46+
are added through optional extras.
47+
48+
## Real Providers
49+
50+
```python
51+
import asyncio
52+
53+
from agent_runtime_kit import AgentTask
54+
from agent_runtime_kit.adapters import ClaudeAgentRuntime
55+
56+
57+
async def main() -> None:
58+
runtime = ClaudeAgentRuntime(default_model="claude-sonnet-4-6")
59+
diagnostic = runtime.availability()
60+
if not diagnostic.available:
61+
raise RuntimeError(diagnostic.message)
62+
result = await runtime.run(AgentTask(goal="Summarize this repository"))
63+
print(result.output)
64+
65+
66+
asyncio.run(main())
67+
```
68+
69+
## Runtime Fields
70+
71+
`AgentTask` supports goal, system prompt, working directory, permission profile,
72+
MCP stdio servers, session/resume handles, output schema, budget, metadata, and
73+
an async event sink.
74+
75+
`AgentResult` returns output, finish reason, parsed structured output, usage,
76+
cost, session id, artifacts, tool-call audits, and provider metadata.
77+
78+
## Docs
79+
80+
- [Quickstart](docs/quickstart.md)
81+
- [Provider diagnostics](docs/providers.md)
82+
- [Capability matrix](docs/capability-matrix.md)
83+
- [Live smoke tests](docs/live-smoke.md)
84+
- [Mestre migration notes](docs/mestre-migration.md)
85+
- [Publish checklist](docs/publish-checklist.md)

‎docs/capability-matrix.md‎

Lines changed: 19 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,19 @@
1+
# Capability Matrix
2+
3+
| Capability | Claude Agent SDK | OpenAI Codex SDK | Google Antigravity SDK |
4+
|------------|------------------|------------------|------------------------|
5+
| Optional extra | `claude` | `codex` | `antigravity` |
6+
| Core import without extra | Yes | Yes | Yes |
7+
| Working directory | Yes | Yes | Yes |
8+
| Session resume | Yes | Yes | Yes |
9+
| Structured output | Native `output_format` when available | Native output schema / JSON parse fallback | Native response schema / JSON parse fallback |
10+
| MCP stdio servers | Yes | No per-task MCP config | Yes, without per-server env |
11+
| Permission mapping | `permission_mode` | approval mode + sandbox | capabilities + policies |
12+
| Streaming output events | From streamed SDK messages | Not enabled in v1 adapter | From response chunks |
13+
| Tool audit events | Best effort from message content | Best effort from result surface | From tool chunks |
14+
| Missing package diagnostics | Yes | Yes | Yes |
15+
| Missing credential diagnostics | Provider-owned/local auth | Provider-owned/local auth | `GEMINI_API_KEY` or `GOOGLE_API_KEY` |
16+
| Live smoke test | Opt-in | Opt-in | Opt-in |
17+
18+
The matrix is intentionally not a lowest-common-denominator contract. Adapters
19+
reject unsupported inputs when silently dropping them would be misleading.

0 commit comments

Comments
 (0)