# All-Day Build Contract: agentkit-cli v0.38.0 — `agentkit pr`

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

## 1. Objective

Add `agentkit pr github:<owner>/<repo>` command to agentkit-cli. This command:
1. Clones the target public GitHub repo to a temp dir
2. Runs `agentmd generate` to create a CLAUDE.md (and optionally AGENTS.md)
3. Creates a new branch (`agentkit/add-claude-md`)
4. Commits the generated file(s)
5. Pushes the branch to a fork under the authenticated user's GitHub account
6. Opens a GitHub PR against the original repo with a pre-written description

This is a viral distribution mechanic: one command creates value for open-source maintainers and puts @mikiships/agentkit-cli in front of thousands of developers.

Current version before this PR: v0.37.0 (1441 tests passing)

## 2. Non-Negotiable Build Rules

1. No time-based completion claims.
2. Completion only when ALL deliverable checkboxes are checked.
3. Full test suite must pass at end (`python3 -m pytest -q`).
4. New features ship with docs and CHANGELOG update in same pass.
5. CLI outputs must be deterministic and schema-backed where specified.
6. Never modify files outside the project directory (`~/repos/agentkit-cli/`).
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 push to PyPI. Do NOT push to GitHub. Those steps are for the build-loop orchestrator.
10. Do NOT run `agentkit pr` against real repos unless explicitly testing with a sandbox repo.

## 3. Deliverables

### D1: Core `pr` command implementation
- [ ] `agentkit_cli/commands/pr_cmd.py` with `pr` subcommand
- [ ] Clone repo to temp dir (use `git clone --depth 1`)
- [ ] Run `agentmd generate .` in cloned dir
- [ ] Support `--file AGENTS.md` flag to generate AGENTS.md instead of CLAUDE.md (default: CLAUDE.md)
- [ ] Skip if context file already exists (unless `--force`)
- [ ] `--dry-run` flag: show what would be done, no git ops

### D2: GitHub fork + branch + PR flow
- [ ] Check if user already has a fork; if not, create one via GitHub API (`POST /repos/{owner}/{repo}/forks`)
- [ ] Requires `GITHUB_TOKEN` env var (check with helpful error if missing)
- [ ] Create branch `agentkit/add-claude-md` on the fork
- [ ] Commit generated file(s) to branch
- [ ] Push branch to fork
- [ ] Open PR against original repo via GitHub API (`POST /repos/{owner}/{repo}/pulls`)
- [ ] PR title: `feat: add CLAUDE.md for AI coding agents`
- [ ] PR body from template in `agentkit_cli/templates/pr_body.md` (see section 6)
- [ ] `--pr-title` and `--pr-body-file` overrides

### D3: Output + UX
- [ ] Rich progress steps: Clone → Generate → Fork → Branch → Commit → Push → PR
- [ ] On success: print PR URL
- [ ] `--json` flag: `{"pr_url": "...", "repo": "...", "file": "...", "score_before": N, "score_after": N}`
- [ ] If score is computable (agentlint), show before/after in output
- [ ] Clear error messages for: missing GITHUB_TOKEN, fork failure, network errors

### D4: Tests
- [ ] `tests/test_pr_cmd.py` with mocked git + GitHub API
- [ ] Test: dry-run (no actual git ops)
- [ ] Test: file already exists → skip
- [ ] Test: file already exists + --force → proceeds
- [ ] Test: missing GITHUB_TOKEN → clear error
- [ ] Test: --json output structure
- [ ] Test: PR body template renders correctly
- [ ] At least 30 new tests

### D5: Docs + release prep
- [ ] `agentkit_cli/templates/pr_body.md` — PR body template
- [ ] README: new `agentkit pr` section with example
- [ ] CHANGELOG: v0.38.0 entry
- [ ] `pyproject.toml` version bump: 0.37.0 → 0.38.0
- [ ] `agentkit_cli/__init__.py` version bump
- [ ] `BUILD-REPORT.md` update
- [ ] All existing tests still pass

## 4. PR Body Template (section 6 reference)

The template at `agentkit_cli/templates/pr_body.md` should say:

```markdown
## Add CLAUDE.md for AI coding agents

This PR adds a `CLAUDE.md` file generated by [agentkit-cli](https://github.com/mikiships/agentkit-cli).

`CLAUDE.md` gives AI coding agents (Claude Code, Codex, etc.) structured context about this repository:
- Architecture overview and key patterns
- Common commands (build, test, lint)
- Conventions and style guidelines
- Areas to be careful with

### How it was generated

```bash
pip install agentkit-cli
agentkit pr github:{owner}/{repo}
```

The file was generated by analyzing the codebase structure, existing docs, and common patterns. Feel free to edit it to add project-specific guidance.

### Why this matters

With context files, AI agents perform substantially better on this codebase. Studies show context files reduce errors and improve first-pass success rates for agentic coding tasks.

---
*Generated by [agentkit-cli](https://pypi.org/project/agentkit-cli/) — the agent quality toolkit*
```

## 5. Validation Gates

Before declaring complete:
- [ ] `python3 -m pytest -q` — all tests pass (1441 baseline + 30+ new)
- [ ] `agentkit pr --help` renders cleanly
- [ ] `agentkit pr github:owner/repo --dry-run` runs without errors (uses mocked/test repo)
- [ ] `--json` output is valid JSON
- [ ] CHANGELOG and version bumps are in place
- [ ] BUILD-REPORT.md updated

## 6. Stop Conditions

Stop and write a blocker report (`pr-build-blocker-report.md`) if:
- GitHub API integration takes more than 3 failed attempts to get right
- Any test takes more than 30s (indicates real network call, not mock)
- Fork creation or PR opening fails with permissions errors — document the error and stop
- Test suite regresses (fewer passing tests than baseline 1441)

## 7. Out of Scope

- OAuth flow for GITHUB_TOKEN (user provides token manually or via env)
- Private repo support
- Multiple PR templates
- Auto-merge
- Any CI/CD changes beyond GitHub Actions input additions
- Pushing to PyPI (orchestrator does that)
- Pushing to GitHub (orchestrator does that)
