# Build Contract: agentmd v0.3.0 — D2-D5 (GitHub Action + Formatter + Tests + Docs)

Status: In Progress
Date: 2026-03-03
Owner: Codex execution pass
Scope type: Deliverable-gated

## 1. Objective

Complete the remaining deliverables for agentmd v0.3.0. D1 (drift command) is already done and committed. This contract covers: GitHub Action definition, PR comment formatter, integration tests, and docs/packaging. The drift command already works (`agentmd drift --json`, `--format github`, exit codes 0/1).

## 2. Non-Negotiable Build Rules

1. No time-based completion claims.
2. Completion only when all checklist items are checked.
3. Full test suite must pass at the end (currently 340, target 380+).
4. New features ship with docs in the same pass.
5. Never modify files outside the project directory.
6. Do NOT attempt git operations (git add, git commit, etc.) — the sandbox restricts .git/ access. Write all files; the orchestrator will commit.
7. If stuck on same issue for 3 attempts, stop and write a blocker report to progress-log.md.
8. Do NOT refactor or "improve" code outside the deliverables.
9. Read existing code before writing new code. Especially read agentmd/drift.py and agentmd/formatters.py if it exists.

## 3. Feature Deliverables

### D2. GitHub Action definition

Create `action.yml` at repo root (for GitHub Marketplace publishing) that:
- Is a composite action
- Installs agentmd from PyPI (`pip install agentmd-gen`)
- Runs `agentmd drift` against the repo checkout
- Configurable inputs: `agent` (default "claude"), `fail-on-drift` (default "true"), `comment` (default "true"), `python-version` (default "3.11")
- If `comment` is true, uses `peter-evans/create-or-update-comment@v4` to post/update a PR comment with drift results
- Comment body comes from `agentmd drift --format markdown` output (you'll build this in D3)

Also create `.github/workflows/agentmd-drift.yml` as a reusable workflow example.

Files:
- `action.yml` (repo root)
- `.github/workflows/agentmd-drift.yml`

- [ ] action.yml with proper inputs/outputs
- [ ] Composite steps: setup python, install, run drift, format output, comment
- [ ] Example workflow file
- [ ] Validation: action.yml parses correctly (use `python3 -c "import yaml; yaml.safe_load(open('action.yml'))"` or manual check)

### D3. PR Comment Formatter (`--format markdown`)

Add a `--format markdown` option to `agentmd drift` that outputs a clean PR comment:
- Header: "## 🔍 agentmd Context Drift Report"
- Summary line: "✅ Context files are fresh" or "⚠️ N sections drifted in CLAUDE.md"
- Table: section name | status (fresh/stale/missing/new) | brief detail
- Collapsible `<details>` blocks with full diff for each drifted section
- Footer: "Generated by [agentmd](https://github.com/mikiships/agentmd)"

Files:
- `agentmd/formatters.py` (new, or extend if exists)
- `agentmd/cli.py` (add --format markdown option)

- [ ] Markdown PR comment formatter
- [ ] Collapsible diff sections using <details>
- [ ] Summary line generation
- [ ] Integration with CLI --format flag
- [ ] Tests for D3

### D4. Integration tests

- [ ] End-to-end: create temp dir with a Python project + stale CLAUDE.md, run `agentmd drift`, verify exit 1 and output
- [ ] Fresh context: generate then immediately drift-check, verify exit 0
- [ ] Missing context file: verify detection
- [ ] JSON schema validation test
- [ ] Markdown format output structure test

### D5. Docs + Packaging

- [ ] Update README.md: add drift command docs, GitHub Action usage section with copy-paste workflow YAML
- [ ] Add/update CHANGELOG.md
- [ ] Bump version to 0.3.0 in pyproject.toml
- [ ] Verify `pip install -e .` still works

## 4. Test Requirements

- All existing 340 tests must still pass
- Target: 380+ total tests
- Run: `python3 -m pytest` (not `uv run`)

## 5. Reports

Write progress to `progress-log.md` after each deliverable.

## 6. Stop Conditions

- All deliverables checked and all tests passing -> DONE
- 3 consecutive failed attempts on same issue -> STOP, write blocker report
- Scope creep detected -> STOP, report what's new

When completely finished, run this command to notify me:
openclaw system event --text "Done: agentmd v0.3.0 D2-D5 complete — GitHub Action, formatter, tests, docs" --mode now
