# All-Day Build Contract: agentkit-cli v0.24.0 — `agentkit share`

Status: In Progress
Date: 2026-03-15
Owner: Codex execution pass
Scope type: Deliverable-gated (no hour promises)

## 1. Objective

Add `agentkit share` — a command that generates a public shareable score card hosted on here.now and returns a short URL. This is the viral mechanic: after running `agentkit score` or `agentkit run`, developers can share their agent quality score card with a single command.

Also add `--share` as a flag on `agentkit run` and `agentkit report` so sharing is zero-friction after an existing run.

Score cards are standalone HTML pages (dark theme, matches existing agentkit report style) showing: composite score, per-tool breakdown, project name/ref, timestamp. Optional: `--no-scores` for private mode (shows only pass/fail, not raw numbers).

The here.now API pattern is already used by agentkit publish — reuse that client code.

This contract is considered complete only when every deliverable and validation gate below is satisfied.

## 2. Non-Negotiable Build Rules

1. No time-based completion claims.
2. Completion is allowed only when all checklist items are checked.
3. Full test suite must pass at the end.
4. New features must ship with docs and report addendum updates in the same pass.
5. CLI outputs must be deterministic and schema-backed where specified.
6. Never modify files outside the project directory.
7. Commit after each completed deliverable (not at the end).
8. If stuck on same issue for 3 attempts, stop and write a blocker report.
9. Do NOT refactor, restyle, or "improve" code outside the deliverables.
10. Read existing tests and docs before writing new code.

## 3. Feature Deliverables

### D1. Score card HTML generator (`agentkit_cli/share.py`)

Build a score card HTML generator that takes a score result dict (from agentkit score or a report JSON) and produces a standalone dark-theme HTML page.

Required files:
- `agentkit_cli/share.py` — `generate_scorecard_html(score_result, project_name, ref, timestamp) -> str`

Score card layout:
- Header: project name + git ref (or "unknown")
- Hero number: composite score (big, color-coded: green ≥80, yellow 60-79, red <60)
- Per-tool row: tool name, score/status, indicator (✓/✗/–)
- Footer: "Generated by agentkit-cli v0.24.0 | agentkit-cli on PyPI"
- Dark background (#0d1117), monospace font, minimal CSS (no external CDN)

- [ ] `generate_scorecard_html()` function implemented
- [ ] Unit tests: HTML contains composite score, tool names, project name
- [ ] Edge cases: missing tools, scores of 0 and 100

### D2. here.now upload integration (`agentkit_cli/share.py`)

Reuse or extend the here.now publish logic from `agentkit_cli/commands/publish.py` to upload the score card HTML and return the public URL.

The function signature: `upload_scorecard(html: str, api_key: str | None) -> str` returns the URL.

Anonymous publish (no API key): score card expires in 24h. With HERENOW_API_KEY: persistent.

Required:
- `upload_scorecard()` in `agentkit_cli/share.py`
- Handle network errors gracefully: print a warning and return None (don't crash the parent command)

- [ ] `upload_scorecard()` implemented
- [ ] Integration with here.now API (anonymous + authenticated)
- [ ] Graceful fallback on network failure
- [ ] Tests: mock HTTP layer to test success + error paths

### D3. `agentkit share` command (`agentkit_cli/commands/share.py`)

New CLI command: `agentkit share [--report <path>] [--project <name>] [--no-scores] [--json]`

Behavior:
1. If `--report <path>` given: load that JSON report file and extract scores.
2. Else: run `agentkit score` inline to get current scores.
3. Generate score card HTML.
4. Upload to here.now.
5. Print the URL to stdout (or `{"url": "..."}` with --json).

Flags:
- `--report PATH`: load from a saved report file instead of running fresh
- `--project NAME`: override project name (default: git remote origin repo name or cwd basename)
- `--no-scores`: generate card with pass/fail only, no raw numbers
- `--json`: output `{"url": "...", "score": N}` instead of plain text

Required:
- `agentkit_cli/commands/share.py`
- Registered in `agentkit_cli/cli.py`

- [ ] `agentkit share` command implemented and registered
- [ ] `--report` path loads JSON correctly
- [ ] `--project` overrides project name
- [ ] `--no-scores` hides raw numbers
- [ ] `--json` outputs structured JSON
- [ ] Tests for all flags

### D4. `--share` flag on `agentkit run` and `agentkit report`

Add `--share` flag to both `agentkit run` and `agentkit report`. When set, automatically uploads a score card after the run and prints the URL.

Required changes:
- `agentkit_cli/commands/run.py`: add `--share` flag, call `upload_scorecard()` at end
- `agentkit_cli/commands/report.py`: add `--share` flag, call `upload_scorecard()` at end
- Both should print: `Score card: <url>` at the end of their normal output

- [ ] `--share` on `agentkit run` implemented
- [ ] `--share` on `agentkit report` implemented
- [ ] Tests for both flags

### D5. Docs, version bump, BUILD-REPORT

- README: add "Sharing Results" section with `agentkit share` usage example and `--share` flag examples for run/report
- CHANGELOG: v0.24.0 entry with all features
- Version bump to 0.24.0 in `pyproject.toml` and `agentkit_cli/__init__.py`
- BUILD-REPORT.md in repo root (status, deliverables, test count, blockers if any)
- 40+ new tests (D1–D4 combined)

- [ ] README updated
- [ ] CHANGELOG entry
- [ ] Version bumped to 0.24.0
- [ ] BUILD-REPORT.md written
- [ ] Full test suite passes (891 baseline + 40+ new)

## 4. Test Requirements

- [ ] Unit tests: score card HTML generation (D1)
- [ ] Unit tests: upload_scorecard with mocked HTTP (D2)
- [ ] Unit tests: `agentkit share` command with mocked upload (D3)
- [ ] Integration tests: `--share` flag on run and report (D4)
- [ ] All 891 existing tests still pass
- [ ] Minimum 40 new tests added

## 5. Reports

- Write progress to `progress-log-v0.24.0.md` after each deliverable
- Final summary when all deliverables done

## 6. Stop Conditions

- All deliverables checked and all tests passing → DONE, write BUILD-REPORT.md
- 3 consecutive failed attempts on same issue → STOP, write blocker report
- Scope creep detected → STOP, report
