diff --git a/CHANGELOG.md b/CHANGELOG.md index f01f0e1..0487766 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,5 +1,10 @@ # Changelog +## 0.4.0 - 2026-06-02 + +- Added a first-impression README pass with clearer maintainer use cases and public validation/release badges. +- Added a quick demo path so maintainers can validate the kit, install one skill into a temporary target, and try a reusable workflow prompt. + ## 0.3.0 - 2026-06-01 - Added a skill installer script and install/use guide so maintainers can adopt the kit more directly. diff --git a/README.md b/README.md index 60c04d2..a7f0515 100644 --- a/README.md +++ b/README.md @@ -1,8 +1,13 @@ # Codex Operator Kit +[![validate](https://github.com/TheRobertRay/codex-operator-kit/actions/workflows/validate.yml/badge.svg)](https://github.com/TheRobertRay/codex-operator-kit/actions/workflows/validate.yml) +[![release](https://img.shields.io/github/v/release/TheRobertRay/codex-operator-kit?label=release)](https://github.com/TheRobertRay/codex-operator-kit/releases/latest) + Reusable prompt contracts, review gates, and maintenance workflows for running coding agents on real repositories without losing source-of-truth discipline. -This repository is intentionally small. It packages field-tested operator patterns into files that other maintainers can copy into their own repos: +If you maintain software with coding agents in the loop, this kit gives you copyable operating patterns for the work that usually breaks trust: ambiguous task intake, issue and PR triage, delegated implementation, release readiness, and public/private context screening. + +This repository is intentionally small. It packages worked-through operator patterns into files that other maintainers can copy into their own repos: - `AGENTS.md` prompt intake contract for ambiguous or dictated tasks - conversation capture receipts for rough chat, voice notes, and inbox dumps @@ -12,9 +17,18 @@ This repository is intentionally small. It packages field-tested operator patter - validation and publication-risk scripts that check for broken placeholders, missing sections, and private-context leaks - public examples for issue triage, PR review, and release-readiness gates +## What You Can Use Today + +| Maintainer problem | Use this | Outcome | +| --- | --- | --- | +| Rough user input turns into the wrong task | `templates/AGENTS.md` and `conversation-capture-receipts` | A clear receipt before writes happen | +| Agent work passes local checks but misses the real risk | `milestone-review` and completion critic gates | A second pass against false-positive completion | +| Private workflow knowledge needs to become public OSS material | `docs/publication-risk.md` and `scripts/check-publication-risk.sh` | Sanitized examples without private paths, hostnames, or secrets | +| A maintainer wants to try the kit quickly | `scripts/install-skills.sh` and `docs/quick-demo.md` | A dry-run and temp install path before touching an existing setup | + ## Current Status -Codex Operator Kit was published on 2026-06-01 as a public OSS workspace for Codex operator workflows. The first release is intentionally compact: copyable contracts, skills, examples, and validation checks that can be reused by maintainers. +Codex Operator Kit was published on 2026-06-01 as a public OSS workspace for Codex operator workflows. It is intentionally compact: copyable contracts, skills, examples, and validation checks that can be reused by maintainers. ## Who This Is For @@ -34,7 +48,9 @@ Copy the contract into a repository: cp templates/AGENTS.md AGENTS.md ``` -Copy one or more skills into your local Codex skills directory: +Try the maintainer demo in `docs/quick-demo.md` first if you want a temporary install path. + +Copy one or more skills into your local Codex skills directory when you are ready to use them in your setup: ```bash bash scripts/install-skills.sh --dry-run @@ -61,6 +77,7 @@ bash scripts/check-publication-risk.sh - `skills/milestone-review/SKILL.md` - milestone and adversarial completion review workflow - `docs/maintenance-model.md` - the operating model behind the kit - `docs/install-and-use.md` - installer and adoption guide +- `docs/quick-demo.md` - short maintainer demo path - `docs/workflows.md` - copyable maintainer workflows - `docs/publication-risk.md` - how to screen workflow packs before publishing - `examples/` - sanitized example packets and receipts diff --git a/docs/quick-demo.md b/docs/quick-demo.md new file mode 100644 index 0000000..cf17e47 --- /dev/null +++ b/docs/quick-demo.md @@ -0,0 +1,59 @@ +# Quick Demo + +This demo shows the smallest useful path through Codex Operator Kit from a repo checkout: validate the public package, install one skill into a temporary target, then use a maintainer workflow prompt on a sanitized example. + +## 1. Validate The Kit + +```bash +bash scripts/validate.sh +``` + +Expected result: + +```text +publication risk check passed +application field lengths ok +validation ok +``` + +## 2. Install One Skill Into A Temporary Target + +```bash +demo_target="$(mktemp -d)/skills" +bash scripts/install-skills.sh --target "$demo_target" conversation-capture-receipts +``` + +Expected result: + +```text +installed conversation-capture-receipts -> ... +``` + +The installer replaces same-named skill directories in the target. Using a temporary target keeps the demo separate from an existing Codex setup. + +## 3. Run A Maintainer Prompt + +From the repo checkout in Codex, use this prompt. It asks Codex to read the skill file directly, so the temp install above can stay isolated from your real setup. + +```text +Read skills/conversation-capture-receipts/SKILL.md and examples/conversation-capture-receipt.md. Explain the reusable receipt pattern in plain language. Then draft a fresh no-write receipt for this rough input: + +"I think the agent fixed the bug, but I do not know what changed, what was verified, or whether it touched anything private. I need a clear receipt before I merge." +``` + +A good answer should produce a no-write receipt that separates: + +- what was caught +- what is still uncertain +- what would need verification before a merge +- what should stay private or out of public release notes + +## 4. Try The Other Maintainer Workflows + +Use the same pattern with: + +- `skills/oss-maintainer-triage/SKILL.md` and `examples/issue-triage.md` +- `skills/milestone-review/SKILL.md` and `examples/pr-review-gate.md` +- `docs/workflows.md` for release readiness and publication-risk gates + +The point is not to adopt a framework. The point is to make agent-assisted maintenance more reviewable, more honest about uncertainty, and safer to publish. diff --git a/scripts/validate.sh b/scripts/validate.sh index a9cf865..456120e 100755 --- a/scripts/validate.sh +++ b/scripts/validate.sh @@ -15,6 +15,7 @@ required=( ".github/ISSUE_TEMPLATE/workflow-improvement.yml" "docs/install-and-use.md" "docs/maintenance-model.md" + "docs/quick-demo.md" "docs/publication-risk.md" "docs/workflows.md" "docs/codex-for-oss-application.md"