From e90fb04931fc3868f969991e3dee844f12906b66 Mon Sep 17 00:00:00 2001 From: Robert Ray <215331614+TheRobertRay@users.noreply.github.com> Date: Fri, 17 Jul 2026 02:02:46 -0700 Subject: [PATCH] Package proven operator workflows as a plugin --- .agents/plugins/marketplace.json | 20 +++ .codex-plugin/plugin.json | 19 +++ .github/PULL_REQUEST_TEMPLATE.md | 4 + AGENTS.md | 8 ++ CHANGELOG.md | 9 ++ CONTRIBUTING.md | 2 + README.md | 164 +++++++++++++++------- docs/codex-for-oss-application.md | 39 +++-- docs/install-and-use.md | 117 ++++++++++++--- docs/maintenance-model.md | 15 +- docs/operator-field-guide.md | 63 +++++++++ docs/publication-risk.md | 3 + docs/quick-demo.md | 64 ++++++--- docs/shared-context-pattern.md | 91 ++++++++++++ docs/workflows.md | 44 ++++++ examples/bounded-loop.md | 30 ++++ examples/command-center-routing.md | 32 +++++ examples/live-surface-verification.md | 40 ++++++ examples/release-readiness.md | 2 + scripts/install-skills.sh | 33 ++++- scripts/plugin-smoke.sh | 49 +++++++ scripts/validate.sh | 101 +++++++++++-- skills/bounded-agent-loops/SKILL.md | 77 ++++++++++ skills/command-center-routing/SKILL.md | 75 ++++++++++ skills/live-surface-verification/SKILL.md | 67 +++++++++ skills/shared-context-briefs/SKILL.md | 67 +++++++++ templates/verification-contract.md | 40 ++++++ templates/worker-packet.md | 48 +++++++ 28 files changed, 1198 insertions(+), 125 deletions(-) create mode 100644 .agents/plugins/marketplace.json create mode 100644 .codex-plugin/plugin.json create mode 100644 docs/operator-field-guide.md create mode 100644 docs/shared-context-pattern.md create mode 100644 examples/bounded-loop.md create mode 100644 examples/command-center-routing.md create mode 100644 examples/live-surface-verification.md create mode 100755 scripts/plugin-smoke.sh create mode 100644 skills/bounded-agent-loops/SKILL.md create mode 100644 skills/command-center-routing/SKILL.md create mode 100644 skills/live-surface-verification/SKILL.md create mode 100644 skills/shared-context-briefs/SKILL.md create mode 100644 templates/verification-contract.md create mode 100644 templates/worker-packet.md diff --git a/.agents/plugins/marketplace.json b/.agents/plugins/marketplace.json new file mode 100644 index 0000000..ffe5078 --- /dev/null +++ b/.agents/plugins/marketplace.json @@ -0,0 +1,20 @@ +{ + "name": "robert-ray-oss", + "interface": { + "displayName": "Robert Ray OSS" + }, + "plugins": [ + { + "name": "codex-operator-kit", + "source": { + "source": "local", + "path": "./" + }, + "policy": { + "installation": "AVAILABLE", + "authentication": "ON_INSTALL" + }, + "category": "Productivity" + } + ] +} diff --git a/.codex-plugin/plugin.json b/.codex-plugin/plugin.json new file mode 100644 index 0000000..e49e288 --- /dev/null +++ b/.codex-plugin/plugin.json @@ -0,0 +1,19 @@ +{ + "name": "codex-operator-kit", + "version": "0.5.0", + "description": "Reusable workflows for reliable agent-assisted software maintenance.", + "author": { + "name": "Robert Ray", + "url": "https://github.com/TheRobertRay" + }, + "skills": "./skills/", + "interface": { + "displayName": "Codex Operator Kit", + "shortDescription": "Reliable routing, review, loops, and verification.", + "longDescription": "A focused collection of maintainer workflows for turning rough requests into bounded work, coordinating agents without write conflicts, verifying live behavior, and publishing reusable operator material safely.", + "developerName": "Robert Ray", + "category": "Productivity", + "capabilities": [], + "defaultPrompt": "Help me choose and apply the smallest Codex Operator Kit workflow that fits this maintenance task." + } +} diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md index 5521fb2..37dcfee 100644 --- a/.github/PULL_REQUEST_TEMPLATE.md +++ b/.github/PULL_REQUEST_TEMPLATE.md @@ -6,12 +6,16 @@ - [ ] Issue triage - [ ] Prompt/skill workflow +- [ ] Routing, delegation, or agent loop +- [ ] Live-surface verification +- [ ] Plugin or installation - [ ] Validation or release tooling - [ ] Documentation or example ## Validation - [ ] `bash scripts/validate.sh` +- [ ] `bash scripts/plugin-smoke.sh` when plugin packaging changed - [ ] Public/private context reviewed - [ ] Release notes or changelog updated when user-facing behavior changed diff --git a/AGENTS.md b/AGENTS.md index 8cd038d..11f0b3e 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -27,3 +27,11 @@ - For long-running, trust-sensitive, or multi-step work, run an adversarial completion review before calling the task done. - Challenge the completion claim against success criteria, constraints, evidence, likely regressions, and hidden assumptions. - A task is done only when critic findings are fixed, accepted as residual risk, or escalated. + +## Public Workflow Extraction + +- Preserve the reusable decision rule, not private project detail. +- Remove local paths, hostnames, credentials, account identifiers, private product names, and transport metadata. +- Label inference as inference and do not turn private usage into a public adoption claim. +- Keep plugin metadata, install docs, skill inventory, and changelog version aligned. +- Run `bash scripts/validate.sh` after material changes and `bash scripts/plugin-smoke.sh` when plugin packaging changes. diff --git a/CHANGELOG.md b/CHANGELOG.md index 0487766..7d30f1d 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,5 +1,14 @@ # Changelog +## 0.5.0 - 2026-07-17 + +- Packaged the collection as an installable Codex plugin with a repository marketplace. +- Added Command Center routing, bounded agent loop, live-surface verification, and shared-context skills. +- Added an operator field guide, shared-context architecture note, worker and verification templates, and three worked examples. +- Updated standalone skill installation to the current user skill location and made replacement require explicit `--force`. +- Added an isolated plugin marketplace/install smoke test and expanded structural validation. +- Refreshed the Codex for Open Source application packet as a conservative update to the June submission. + ## 0.4.0 - 2026-06-02 - Added a first-impression README pass with clearer maintainer use cases and public validation/release badges. diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index a235db6..88824dd 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -8,6 +8,7 @@ This repository accepts small, copyable workflow improvements for AI-assisted so - A skill that turns a repeated maintenance workflow into a reusable checklist - A validation check that catches stale placeholders or missing safety gates - Documentation that makes a maintainer workflow easier to repeat +- A sanitized workflow extracted from repeated real use, with provenance and a verifier ## Not In Scope @@ -23,3 +24,4 @@ Every change should answer: 1. What maintainer problem does this reduce? 2. What false-pass path does it prevent? 3. How can another maintainer validate that it works? +4. What private source details were intentionally generalized or excluded? diff --git a/README.md b/README.md index a7f0515..cfeda39 100644 --- a/README.md +++ b/README.md @@ -2,94 +2,150 @@ [![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) +[![license](https://img.shields.io/github/license/TheRobertRay/codex-operator-kit)](LICENSE) -Reusable prompt contracts, review gates, and maintenance workflows for running coding agents on real repositories without losing source-of-truth discipline. +Small, reusable workflows for running coding agents on real repositories without losing ownership, evidence, or source-of-truth discipline. -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. +The kit packages the operator patterns that tend to matter after the first impressive demo: turning rough input into the right task, coordinating workers without duplicate writes, bounding autonomous loops, proving the real user-facing path, and extracting public lessons without leaking private context. -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 -- maintainer triage skill for evidence-first issue and PR review -- milestone review skill for substantial implementation work -- application packet template for programs that evaluate OSS maintainer signal -- 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 +It is intentionally a toolkit, not an agent framework. ## 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 | +| Rough input may become the wrong task or write | `conversation-capture-receipts` | A human-readable understanding receipt before persistence | +| One main conversation coordinates several lanes | `command-center-routing` | Clear ownership, bounded workers, and compact user decisions | +| Autonomous work needs a real finish line | `bounded-agent-loops` | Goal, verifier, state, stop conditions, and approval boundary | +| An issue, PR, bounty, or application claim needs evidence | `oss-maintainer-triage` | Conservative claims and the smallest grounded next action | +| Substantial work may look complete while still failing | `milestone-review` | A review against false-pass paths and residual risk | +| A live route or workflow is broken | `live-surface-verification` | Proof through the exact layer and user path that failed | +| Several agents need the same current reality | `shared-context-briefs` | Provenance, freshness, expiry, and current-input priority | +| Private workflow knowledge needs to become public | publication-risk gate | Sanitized examples without private paths, hosts, or credentials | + +The [Operator Field Guide](docs/operator-field-guide.md) helps choose the smallest workflow. The [shared-context pattern](docs/shared-context-pattern.md) covers safe context exchange between several agents without copying raw transcripts. -## Current Status +## Install As A Codex Plugin -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. +The plugin bundles all skills and is the recommended install path for current Codex versions. -## Who This Is For +```bash +codex plugin marketplace add TheRobertRay/codex-operator-kit --ref main +codex plugin add codex-operator-kit@robert-ray-oss +``` -This kit is for maintainers who use coding agents to: +Verify the install: + +```bash +codex plugin list --marketplace robert-ray-oss +``` -- triage issues and pull requests without skipping evidence -- delegate bounded subtasks to subagents -- run adversarial completion checks before claiming work is done -- keep user-facing summaries separate from machine artifacts -- avoid false-pass paths during deployment, cleanup, and trust-sensitive changes +See [Install And Use](docs/install-and-use.md) for the standalone-skill path, safe temporary installs, updates, and removal. -## Quick Start +## Try It Without Changing Your Setup -Copy the contract into a repository: +Clone the repo and run: ```bash -cp templates/AGENTS.md AGENTS.md +bash scripts/validate.sh +demo_target="$(mktemp -d)/skills" +bash scripts/install-skills.sh --target "$demo_target" command-center-routing ``` -Try the maintainer demo in `docs/quick-demo.md` first if you want a temporary install path. +Then ask Codex: -Copy one or more skills into your local Codex skills directory when you are ready to use them in your setup: +```text +Read skills/command-center-routing/SKILL.md and examples/command-center-routing.md. +Turn this mixed maintainer request into the lightest safe execution shape, one +bounded worker packet if useful, and a compact final receipt: -```bash -bash scripts/install-skills.sh --dry-run -bash scripts/install-skills.sh +"The release job is failing, onboarding copy still feels wrong, and I need a +summary for tomorrow. Handle what you can and only bring me real decisions." ``` -Validate this repository: +The full [Quick Demo](docs/quick-demo.md) stays inside a temporary target. + +## Copyable Assets + +### Skills + +- `conversation-capture-receipts` +- `command-center-routing` +- `bounded-agent-loops` +- `oss-maintainer-triage` +- `milestone-review` +- `live-surface-verification` +- `shared-context-briefs` + +### Templates + +- [Bounded Worker Packet](templates/worker-packet.md) +- [Verification Contract](templates/verification-contract.md) +- [Repository Agent Contract](templates/AGENTS.md) + +### Worked Examples + +- [Conversation capture receipt](examples/conversation-capture-receipt.md) +- [Command Center routing](examples/command-center-routing.md) +- [Bounded documentation loop](examples/bounded-loop.md) +- [Issue triage](examples/issue-triage.md) +- [PR review gate](examples/pr-review-gate.md) +- [Live-surface verification](examples/live-surface-verification.md) +- [Release readiness](examples/release-readiness.md) + +## Maintenance Model + +The core loop is simple: + +1. Convert rough input into a concrete outcome. +2. Select the lightest execution shape. +3. Give delegated work exact scope and stop rules. +4. Make the smallest change that can satisfy the outcome. +5. Verify the layer that actually failed. +6. Challenge completion when the risk justifies it. +7. Return a compact receipt. +8. Promote repeated, public-safe patterns into skills. + +Read [Maintenance Model](docs/maintenance-model.md) for the full rationale. + +## Validation + +Repository validation checks required assets, skill metadata, documentation coverage, standalone installation, plugin and marketplace structure, application field limits, and common publication risks: ```bash bash scripts/validate.sh ``` -Run the publication-risk scanner directly: +When the Codex CLI is installed, exercise an isolated marketplace and plugin install: ```bash -bash scripts/check-publication-risk.sh +bash scripts/plugin-smoke.sh ``` +The smoke test uses a temporary Codex home and does not alter the user's configured marketplaces or installed plugins. + ## Repository Map -- `templates/AGENTS.md` - compact global intake and completion-review contract -- `skills/conversation-capture-receipts/SKILL.md` - no-write receipt workflow for messy human input -- `skills/oss-maintainer-triage/SKILL.md` - issue, PR, and bounty-style evidence triage -- `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 -- `docs/codex-for-oss-application.md` - application packet and field-ready answers -- `scripts/validate.sh` - local validation checks -- `scripts/install-skills.sh` - install all or selected skills into a Codex skills directory -- `scripts/check-publication-risk.sh` - conservative private-context leak scanner - -## Maintenance Posture - -The project is maintained as a practical operator kit rather than a framework. New additions should be small, copyable, and tied to a maintenance workflow that has been used in real work. +- `.codex-plugin/plugin.json` - plugin manifest +- `.agents/plugins/marketplace.json` - repo marketplace +- `skills/` - reusable Codex workflows +- `templates/` - copyable contracts +- `examples/` - sanitized worked examples +- `docs/operator-field-guide.md` - workflow selector +- `docs/shared-context-pattern.md` - provenance, freshness, and expiry architecture +- `docs/publication-risk.md` - public/private extraction gate +- `docs/codex-for-oss-application.md` - conservative application packet +- `scripts/validate.sh` - repository checks +- `scripts/plugin-smoke.sh` - isolated plugin installation check +- `scripts/install-skills.sh` - standalone skill installer +- `scripts/check-publication-risk.sh` - private-context scanner + +## Project Status + +Codex Operator Kit is an early public OSS project maintained through visible issues, pull requests, releases, CI, and public validation. Public adoption is still early, so the project makes no claim of broad usage. + +New contributions should stay small, copyable, grounded in a repeated maintenance failure, and accompanied by a way to validate the improvement. ## License -MIT. See `LICENSE`. +MIT. See [LICENSE](LICENSE). diff --git a/docs/codex-for-oss-application.md b/docs/codex-for-oss-application.md index 6f14cf6..5e9b41f 100644 --- a/docs/codex-for-oss-application.md +++ b/docs/codex-for-oss-application.md @@ -1,6 +1,6 @@ -# Codex for OSS Application Packet +# Codex for Open Source Application Packet -This packet is written for the OpenAI Codex for Open Source form as of 2026-06-01. It should be reviewed before submission, but it is ready to paste. +This packet matches the public OpenAI Codex for Open Source form reviewed on 2026-07-17. It is written as a transparent update to an application first submitted on 2026-06-01. ## Public Fields @@ -19,33 +19,48 @@ https://github.com/TheRobertRay/codex-operator-kit Role: ```text -Primary maintainer of Codex Operator Kit, a small public workflow kit that packages reusable prompt contracts, review gates, and validation habits for maintainers using coding agents on real repositories. +Primary maintainer of Codex Operator Kit, an open-source collection of reusable skills, templates, examples, and validation checks for reliable agent-assisted software maintenance. ``` Why this repository qualifies, 500 characters max: ```text -Codex Operator Kit is an early public OSS maintainer workflow project. It packages field-tested prompt contracts, milestone reviews, adversarial completion checks, and triage habits used in real maintenance work. It is small, but directly aligned with Codex for OSS: reducing review, triage, validation, and release-risk load for maintainers using coding agents. +Codex Operator Kit is an active OSS workflow pack for maintainers using coding agents. It ships seven reusable skills plus worker and verification templates, plugin installation, CI validation, and release/triage examples. Its practical ecosystem value is reducing false completion, context leaks, coordination conflicts, and live-verification failures in agent-assisted maintenance. ``` How API credits would be used, 500 characters max: ```text -I would use API credits to test Codex-based maintainer automation: issue/PR triage, review-packet generation, stale-context detection, milestone review, and release-readiness checks. The goal is to turn repeated agent maintenance patterns into reusable, validated OSS workflows without leaking private project data. +I would use credits to run reproducible evaluations for issue and PR triage, bounded worker routing, release readiness, live-surface verification, and context-safety checks, then publish sanitized fixtures, failure cases, and validation improvements. Credits would support this public repository and its maintainer automation, not private operational workloads. ``` Anything else, 500 characters max: ```text -This is a newly public repo, so public adoption signals are still early. The reason I am applying now is that the workflows come from repeated real maintenance runs across private and local systems, and I want to harden them in public for other maintainers. I will keep claims conservative and publish only sanitized, reusable operator material. +This updates my June 1 application after a material v0.5.0 expansion. The repository now installs as a Codex plugin and has seven skills, six releases, validated examples, and a visible issue/PR/release trail. Adoption is still early: no stars, forks, or external contributors yet; GitHub reported four unique clones in the latest 14-day window when checked July 17. ``` -## Recommended Checkboxes +## Recommended Selection -- ChatGPT Pro / Codex access -- API credits for project -- Codex Security only if the form allows interest without claiming current security scale +- Role: Primary maintainer +- Interest: API credits for my project +- Codex Security: leave unselected unless a future code-heavy security surface justifies it -## Honest Risk +## Evidence -This repository does not yet have broad public adoption, stars, downloads, or an external contributor base. The application should lean on clear ecosystem fit and real maintainer workflow value, not inflated usage claims. +- Public repository with MIT license +- Seven installable skills +- Codex plugin manifest and repository marketplace +- Worker and verification templates +- Sanitized public examples +- Validation and publication-risk scripts +- Issue, pull request, release, and GitHub Actions history +- Isolated plugin install smoke test + +## Honest Limits + +- The project is active but still early. +- It has no stars, forks, or external contributors as of 2026-07-17. +- Clone traffic does not prove ongoing adoption and should not be described as users. +- Private and local usage supports workflow provenance, not public adoption. +- Selection remains OpenAI's judgment; this packet should not imply guaranteed eligibility. diff --git a/docs/install-and-use.md b/docs/install-and-use.md index df79373..84c391c 100644 --- a/docs/install-and-use.md +++ b/docs/install-and-use.md @@ -1,8 +1,54 @@ # Install And Use -Codex Operator Kit is meant to be copied into real maintainer work. The fastest path is to install one or more skills into a Codex skills directory, then use the workflow docs and examples as prompts or checklists. +Codex Operator Kit can be installed as one plugin or copied as individual skills. -## List Skills +## Recommended: Plugin Install + +Add the repository marketplace: + +```bash +codex plugin marketplace add TheRobertRay/codex-operator-kit --ref main +``` + +Install the plugin: + +```bash +codex plugin add codex-operator-kit@robert-ray-oss +``` + +Verify: + +```bash +codex plugin list --marketplace robert-ray-oss +``` + +The plugin bundles every skill in the repository. Restart the Codex app if the new plugin does not appear immediately. + +### Update + +Refresh the marketplace snapshot: + +```bash +codex plugin marketplace upgrade robert-ray-oss +``` + +Remove and add the plugin again when a local Codex version requires reinstalling to pick up a changed plugin manifest: + +```bash +codex plugin remove codex-operator-kit@robert-ray-oss +codex plugin add codex-operator-kit@robert-ray-oss +``` + +### Remove + +```bash +codex plugin remove codex-operator-kit@robert-ray-oss +codex plugin marketplace remove robert-ray-oss +``` + +## Standalone Skills + +List the included skills: ```bash bash scripts/install-skills.sh --list @@ -10,54 +56,85 @@ bash scripts/install-skills.sh --list Current skills: +- `bounded-agent-loops` +- `command-center-routing` - `conversation-capture-receipts` +- `live-surface-verification` - `milestone-review` - `oss-maintainer-triage` +- `shared-context-briefs` -## Dry Run +### Dry Run ```bash bash scripts/install-skills.sh --dry-run ``` -The installer replaces same-named skill directories in the target. Use `--dry-run` first when installing into an existing Codex setup. +The default standalone target is: + +```text +$HOME/.agents/skills +``` + +Set a different target: + +```bash +bash scripts/install-skills.sh --target "$HOME/.agents/skills" +``` -## Install All Skills +### Install One Skill ```bash -bash scripts/install-skills.sh +bash scripts/install-skills.sh command-center-routing ``` -By default, the script installs to: +### Install All Skills -```text -${CODEX_HOME:-$HOME/.codex}/skills +```bash +bash scripts/install-skills.sh ``` -Set a target explicitly when needed: +The installer stops if a same-named skill already exists. Review the existing copy, then explicitly replace it when intended: ```bash -bash scripts/install-skills.sh --target "$HOME/.codex/skills" +bash scripts/install-skills.sh --force command-center-routing ``` -## Install One Skill +## Temporary Evaluation + +Install into a temporary directory without touching an existing Codex setup: ```bash -bash scripts/install-skills.sh conversation-capture-receipts +demo_target="$(mktemp -d)/skills" +bash scripts/install-skills.sh --target "$demo_target" command-center-routing ``` -## Use The Kit Without Installing +Read the installed `SKILL.md` directly in a prompt or point a temporary Codex configuration at that directory. + +## Use Without Installing + +Codex can read a repository skill directly: + +```text +Read skills/live-surface-verification/SKILL.md and +templates/verification-contract.md. Turn this bug report into a verification +contract, then identify the cheapest proof that exercises the failing layer. +``` -You can also copy individual files into a repository: +The templates and examples are normal Markdown and can also be copied into issue templates, review prompts, or repository instructions. -- `templates/AGENTS.md` for prompt intake and completion review -- `docs/workflows.md` for issue triage, capture receipts, PR review, release readiness, publication risk, and completion critic gates -- `examples/` for sanitized examples +## Validate The Package -## Validate Before Publishing Changes +Run the repository checks: ```bash bash scripts/validate.sh ``` -Validation checks required files, skill front matter, application-field lengths, and publication-risk patterns. +Run an isolated real plugin install when the Codex CLI is available: + +```bash +bash scripts/plugin-smoke.sh +``` + +The smoke test creates a temporary Codex home, adds the local marketplace there, installs the plugin, verifies it, and removes the temporary state. diff --git a/docs/maintenance-model.md b/docs/maintenance-model.md index 3716459..cb8c4e3 100644 --- a/docs/maintenance-model.md +++ b/docs/maintenance-model.md @@ -3,11 +3,13 @@ Codex Operator Kit is built around a simple maintainer loop: 1. Convert rough input into a concrete task contract. -2. Gather live evidence before changing behavior. -3. Make the smallest scoped change that can satisfy the contract. -4. Validate the real user-facing or maintainer-facing surface. -5. Run a review that tries to disprove the completion claim. -6. Record what changed and what remains risky. +2. Select the lightest execution shape and assign one owner per write lane. +3. Gather live evidence before changing behavior. +4. Make the smallest scoped change that can satisfy the contract. +5. Validate the real user-facing or maintainer-facing surface. +6. Run a review that tries to disprove the completion claim when the risk earns it. +7. Record what changed and what remains risky. +8. Promote a repeated public-safe pattern into a skill only after it proves useful. ## Why This Exists @@ -17,6 +19,9 @@ This kit packages the rules that prevent those failures: - source-trace before implementation - bounded write scope +- disjoint worker ownership +- verifier-driven loops with stop conditions +- provenance, freshness, and expiry for shared context - milestone reviews for larger changes - adversarial completion review for long-running work - honest residual-risk reporting diff --git a/docs/operator-field-guide.md b/docs/operator-field-guide.md new file mode 100644 index 0000000..d91b48a --- /dev/null +++ b/docs/operator-field-guide.md @@ -0,0 +1,63 @@ +# Operator Field Guide + +Codex Operator Kit is a set of small workflows, not a new agent framework. Pick the narrowest asset that matches the failure mode. + +| Situation | Start here | What it prevents | +| --- | --- | --- | +| Rough notes or dictated intake may be misunderstood | `conversation-capture-receipts` | Accidental tasks, writes, and flattened meaning | +| One main chat must coordinate several workstreams | `command-center-routing` | Context pollution, duplicate owners, and user relay work | +| A task needs autonomous iteration | `bounded-agent-loops` | Open-ended runs with no verifier or stop condition | +| An issue, PR, bounty, or application claim needs evidence | `oss-maintainer-triage` | Inflated claims and implementation before the failure is concrete | +| A substantial milestone needs a skeptical review | `milestone-review` | False completion and unexamined regressions | +| A live route or workflow is broken | `live-surface-verification` | Treating process health or config readback as product proof | +| Several agents need a shared view of current work | `shared-context-briefs` | Transcript copying, stale context, and provenance loss | +| Private operator knowledge should become public material | `docs/publication-risk.md` | Leaking paths, hostnames, credentials, or private project context | + +## The Default Maintenance Loop + +1. Turn rough input into a concrete outcome. +2. Select the lightest execution shape. +3. Give every delegated slice an exact packet. +4. Make the smallest scoped change. +5. Verify the layer that actually failed. +6. Challenge the completion claim when the risk justifies it. +7. Return a compact receipt. +8. Extract a reusable skill only after the workflow repeats. + +## Execution Shapes + +### Direct work + +Use for ordinary self-contained tasks. Keep planning implicit and verify with one relevant signal. + +### Bounded worker + +Use for an independent read, implementation, test, or review slice. Supply a complete packet and keep the main conversation focused on decisions. + +### Visible owner thread + +Use when durable context, independent continuation, or separate monitoring materially improves the result. + +### Bounded loop + +Use only when a verifier can reject failure and a stop rule prevents endless work. + +## A Good Packet + +Copy `templates/worker-packet.md`. The essential properties are disjoint ownership, explicit non-goals, a proof budget, and stop conditions. + +## A Good Proof + +Copy `templates/verification-contract.md`. Name the failed layer and require the final check to exercise the real user or maintainer path. + +## When To Turn A Pattern Into A Skill + +Create a skill when: + +- the same workflow has repeated; +- the trigger can be described clearly; +- the instructions reduce a known failure mode; +- the workflow is useful without private context; +- a user can validate the result. + +Keep `AGENTS.md` short and repository-specific. Put reusable task workflows in skills so they load only when relevant. diff --git a/docs/publication-risk.md b/docs/publication-risk.md index f89f1f8..2c9175c 100644 --- a/docs/publication-risk.md +++ b/docs/publication-risk.md @@ -23,6 +23,8 @@ Remove or generalize: Keep the maintainer decision intact. A good public example should preserve the reasoning pattern while replacing private specifics with neutral names. +For patterns extracted from repeated private work, record the source class privately while publishing only the generalized failure mode, decision rule, and verifier. Private use can establish workflow provenance, but it is not public adoption evidence. + ## Scanner Run: @@ -48,3 +50,4 @@ Do not tag a release until: 1. `bash scripts/validate.sh` passes. 2. `bash scripts/check-publication-risk.sh` passes. 3. Any scanner exceptions have a clear maintainer note in the release packet. +4. Public claims distinguish repeated private use, public maintainer activity, and external adoption. diff --git a/docs/quick-demo.md b/docs/quick-demo.md index cf17e47..52ca7b6 100644 --- a/docs/quick-demo.md +++ b/docs/quick-demo.md @@ -1,6 +1,6 @@ # 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. +This demo validates the package, installs one skill into a temporary target, and applies it to a mixed maintainer request. It does not change an existing Codex setup. ## 1. Validate The Kit @@ -8,7 +8,7 @@ This demo shows the smallest useful path through Codex Operator Kit from a repo bash scripts/validate.sh ``` -Expected result: +Expected final lines: ```text publication risk check passed @@ -16,44 +16,64 @@ application field lengths ok validation ok ``` -## 2. Install One Skill Into A Temporary Target +## 2. Install One Skill Temporarily ```bash demo_target="$(mktemp -d)/skills" -bash scripts/install-skills.sh --target "$demo_target" conversation-capture-receipts +bash scripts/install-skills.sh --target "$demo_target" command-center-routing ``` Expected result: ```text -installed conversation-capture-receipts -> ... +installed command-center-routing -> ... ``` -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 +## 3. Run A Routing 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. +From the repo checkout, ask Codex: ```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: +Read skills/command-center-routing/SKILL.md, +templates/worker-packet.md, and examples/command-center-routing.md. + +Turn this mixed maintainer request into: +1. the lightest safe execution shape, +2. one bounded worker packet only if it materially helps, +3. a compact final receipt. -"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." +"The release job is failing, onboarding copy still feels wrong, and I need a +summary for tomorrow. Handle what you can and only bring me real decisions." ``` -A good answer should produce a no-write receipt that separates: +A good result should: -- what was caught -- what is still uncertain -- what would need verification before a merge -- what should stay private or out of public release notes +- keep decisions and synthesis in the main conversation; +- delegate only an independent, bounded slice; +- make write ownership and non-goals explicit; +- avoid deploys, merges, or external sends without authority; +- return one compact receipt. -## 4. Try The Other Maintainer Workflows +## 4. Try A Verification Prompt -Use the same pattern with: +```text +Read skills/live-surface-verification/SKILL.md, +templates/verification-contract.md, and +examples/live-surface-verification.md. + +A web service is running and its HTML route returns 200, but the deployed screen +is blank. Draft the verification contract and name what evidence would be too +weak to call the issue fixed. +``` -- `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 answer should distinguish process, route, product behavior, and user acceptance. + +## Optional: Test The Plugin Package + +If the Codex CLI is installed: + +```bash +bash scripts/plugin-smoke.sh +``` -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. +This test uses an isolated temporary Codex home. diff --git a/docs/shared-context-pattern.md b/docs/shared-context-pattern.md new file mode 100644 index 0000000..e6038aa --- /dev/null +++ b/docs/shared-context-pattern.md @@ -0,0 +1,91 @@ +# Shared Context Without Transcript Copying + +Multiple agents often fail for a simple reason: each surface knows a different version of reality. Copying every transcript into every prompt creates a different failure: bloat, stale context, privacy risk, and hidden instruction conflicts. + +The safer pattern is a thin shared-reality layer. + +## Design Goal + +Let agents answer: + +- What is happening now? +- What changed? +- What is blocked? +- What decision is waiting? +- How fresh is this context? +- What source should be checked before acting? + +The layer should not attempt to recreate every conversation. + +## Push Plus Pull + +**Push meaningful transitions:** + +- work started, completed, blocked, or superseded; +- a decision was accepted; +- a user action became necessary; +- a verified receipt changed current state. + +**Pull bounded context:** + +- begin with a compact ambient brief; +- retrieve deeper context only when the present request warrants it; +- prefer canonical sources over summaries for consequential decisions. + +## Context Record + +A useful record contains: + +```text +id: +kind: +summary: +source: +authority: +confidence: +updated_at: +expires_at: +closure: +visibility: +``` + +- `source` makes provenance inspectable. +- `authority` separates direct user decisions from agent inference. +- `updated_at` and `expires_at` prevent stale context from silently persisting. +- `closure` explains when the record should be replaced or removed. +- `visibility` prevents private operational details from leaking into broad prompts. + +## Priority Rules + +1. The user's current input always wins. +2. Direct accepted decisions outrank agent summaries. +3. Current canonical state outranks old receipts. +4. Inference remains labeled as inference. +5. Expired or superseded state must not steer action. + +## Exclusions + +Do not use the shared layer to copy: + +- raw transcripts; +- hidden model reasoning; +- credentials or tokens; +- private transport metadata; +- full tool logs; +- unrelated personal context; +- pending ideas presented as accepted instructions. + +## Ownership + +Give the shared-context layer one clear owner. Other agents may publish bounded events or query it, but schema, retention, freshness, and cleanup need a durable maintenance surface. + +## Verification + +Test both directions: + +1. A meaningful work transition becomes retrievable by another agent with correct provenance and freshness. +2. An accepted durable decision colors a relevant new task without overriding the user's current request. +3. Expired or superseded state is excluded. +4. Raw transcript text and private metadata do not appear in the bounded brief. + +The success condition is shared current reality, not maximum memory. diff --git a/docs/workflows.md b/docs/workflows.md index 4ab2f6e..0e47b50 100644 --- a/docs/workflows.md +++ b/docs/workflows.md @@ -2,6 +2,28 @@ These workflows are intentionally short. They are meant to be copied into issue templates, PR review prompts, release checklists, or local Codex skills. +## Command Center Routing + +Use when one conversation owns intake and decisions while implementation may happen in bounded workers or visible owner threads. + +1. Keep priorities, decisions, synthesis, and receipts in the main conversation. +2. Delegate only independent slices that repay their coordination cost. +3. Give every worker exact scope, non-goals, proof budget, and stop conditions. +4. Keep one authoritative write-capable turn per owner. +5. Monitor read-only after handoff unless new facts, blockers, risk, or contradictory evidence justify intervention. +6. Bring the user one compact receipt; never require them to relay worker state. + +## Bounded Agent Loop + +Use when work needs iteration and a verifier can reject failure. + +1. Define goal, inputs, non-goals, verifier, state, stop rules, approval boundary, and receipt. +2. Make one focused change per iteration. +3. Run the same verifier after each relevant change. +4. Record only the state needed for the next pass. +5. Stop on success, hard cap, two no-progress passes, changed scope, or an approval boundary. +6. Do not schedule a loop whose only verifier is model self-grading. + ## Issue Triage Gate Use when a maintainer needs to decide whether an issue is actionable. @@ -42,6 +64,28 @@ Use before tagging a release or publishing a package. 4. Confirm no private paths, credentials, or internal hostnames were introduced. 5. Record known residual risks in the release notes. +## Live Surface Verification + +Use when configuration or process health may not prove the original user-visible behavior. + +1. Record the exact failing surface, expected behavior, observed behavior, and reproduction path. +2. Separate configuration, process, route, product behavior, and user acceptance. +3. Identify the component or service that owns the failure before broad restarts. +4. Repair the smallest durable layer. +5. Exercise the original failing path. +6. Run one adjacent check that would catch a near-miss. + +## Shared Context Brief + +Use when several agents need a consistent view of current work without transcript copying. + +1. Push meaningful lifecycle transitions only. +2. Pull a compact ambient brief before deeper targeted context. +3. Attach source, authority, confidence, freshness, expiry, closure, and visibility. +4. Let current user input override background context. +5. Exclude raw transcripts, hidden reasoning, credentials, private transport metadata, and full tool logs. +6. Verify expired or superseded state no longer steers action. + ## Publication Risk Gate Use before moving a workflow, skill, prompt, or example from private work into a public repo. diff --git a/examples/bounded-loop.md b/examples/bounded-loop.md new file mode 100644 index 0000000..0c8afbe --- /dev/null +++ b/examples/bounded-loop.md @@ -0,0 +1,30 @@ +# Example: Bounded Documentation Loop + +## Goal + +Make a CLI quick start executable by a new contributor. + +## Contract + +- Inputs: README, install script, and current CLI help. +- Non-goals: package publishing, dependency upgrades, and release tagging. +- Verifier: run every documented quick-start command in a temporary directory. +- State: one short iteration record in the working note. +- Stop: pass, three iterations, or two no-progress failures. +- Approval boundary: credentials, package registry writes, or changes outside the repo. + +## Iteration + +```text +objective: executable quick start +iteration: 1 +changed: corrected the install target and added the missing list command +verification: temp install passed; example invocation failed because the documented skill name was stale +failed_or_weak: example name mismatch +next: update the example and rerun the same verifier +blockers: none +``` + +## Completion + +The loop ends only when the documented commands run successfully from a clean temporary directory. A Markdown review alone is not the verifier. diff --git a/examples/command-center-routing.md b/examples/command-center-routing.md new file mode 100644 index 0000000..4c8d71a --- /dev/null +++ b/examples/command-center-routing.md @@ -0,0 +1,32 @@ +# Example: Command Center Routing + +## Intake + +```text +The release job is failing, the onboarding copy still feels wrong, and I also need a summary for tomorrow. Handle what you can and only bring me real decisions. +``` + +## Route + +- Main conversation: preserve priorities, synthesize results, and own user decisions. +- Bounded worker A: read-only CI failure diagnosis. +- Bounded worker B: copy review against the approved onboarding goal. +- Direct work: draft the summary after the other evidence returns. + +The workers have disjoint ownership. Neither can deploy, merge, or send the summary. + +## Receipt + +```text +Release: diagnosed. The packaging step is reading the old output directory; no deploy was attempted. + +Onboarding: the first screen asks for three choices before explaining value. Recommended change: show the outcome first and defer configuration. + +Tomorrow's summary: drafted from verified results and ready for review. + +Decision needed: approve the output-directory fix and the onboarding order change? Recommendation: yes to both. +``` + +## Why This Works + +The user sees one compact decision surface. Exploration logs stay out of the main conversation, write ownership is clear, and no worker invents external authority. diff --git a/examples/live-surface-verification.md b/examples/live-surface-verification.md new file mode 100644 index 0000000..268d04f --- /dev/null +++ b/examples/live-surface-verification.md @@ -0,0 +1,40 @@ +# Example: Live Surface Verification + +## Failure + +After a deployment, the application shell loads but its main screen stays blank. + +## Evidence Ladder + +- Configuration: deployment points at the intended commit. +- Process: web service is running. +- Route: HTML returns `200`. +- Product behavior: HTML references a JavaScript bundle that returns `404`. +- User acceptance: the screen cannot render. + +## Repair + +Update the deployment artifact path so the HTML and generated bundle names come from the same build output. Do not restart unrelated services. + +## Verification + +Primary verifier: + +```text +Load the public route and confirm every referenced script and stylesheet returns 200. +``` + +Near-miss check: + +```text +Open the main interaction and confirm the current release identifier appears in the visible screen. +``` + +## Receipt + +```text +Root cause: the HTML and asset directory came from different builds. +Changed: deployment artifact selection only. +Verified: public route, referenced assets, and the main visible interaction. +Residual risk: old cached HTML may persist until its normal cache window expires. +``` diff --git a/examples/release-readiness.md b/examples/release-readiness.md index 9773ede..932d191 100644 --- a/examples/release-readiness.md +++ b/examples/release-readiness.md @@ -7,7 +7,9 @@ ## Checks - [ ] `bash scripts/validate.sh` +- [ ] `bash scripts/plugin-smoke.sh` when plugin packaging changed - [ ] `bash scripts/check-publication-risk.sh` +- [ ] plugin manifest version matches the changelog and intended release tag - [ ] README quick start still matches the file layout - [ ] changelog includes the user-facing changes - [ ] release notes describe user-facing changes, not internal work logs diff --git a/scripts/install-skills.sh b/scripts/install-skills.sh index 1c245b8..ab97a03 100755 --- a/scripts/install-skills.sh +++ b/scripts/install-skills.sh @@ -2,14 +2,15 @@ set -euo pipefail root="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)" -target="${CODEX_SKILLS_DIR:-${CODEX_HOME:-$HOME/.codex}/skills}" +target="${CODEX_SKILLS_DIR:-$HOME/.agents/skills}" dry_run=0 list_only=0 +force=0 skills=() usage() { cat <<'USAGE' -Usage: bash scripts/install-skills.sh [--target DIR] [--dry-run] [--list] [skill...] +Usage: bash scripts/install-skills.sh [--target DIR] [--dry-run] [--force] [--list] [skill...] Installs Codex Operator Kit skills into a Codex skills directory. @@ -17,7 +18,8 @@ Examples: bash scripts/install-skills.sh --list bash scripts/install-skills.sh --dry-run bash scripts/install-skills.sh conversation-capture-receipts - bash scripts/install-skills.sh --target "$HOME/.codex/skills" + bash scripts/install-skills.sh --target "$HOME/.agents/skills" + bash scripts/install-skills.sh --force command-center-routing USAGE } @@ -32,6 +34,10 @@ while [[ $# -gt 0 ]]; do dry_run=1 shift ;; + --force) + force=1 + shift + ;; --list) list_only=1 shift @@ -81,6 +87,19 @@ for skill in "${skills[@]}"; do done if [[ "$dry_run" -eq 0 ]]; then + collisions=() + for skill in "${skills[@]}"; do + if [[ -e "$target/$skill" ]]; then + collisions+=("$target/$skill") + fi + done + + if [[ "${#collisions[@]}" -gt 0 && "$force" -eq 0 ]]; then + echo "existing skill directories found; rerun with --force to replace them:" >&2 + printf ' %s\n' "${collisions[@]}" >&2 + exit 1 + fi + mkdir -p "$target" fi @@ -88,7 +107,13 @@ for skill in "${skills[@]}"; do src="$root/skills/$skill" dst="$target/$skill" if [[ "$dry_run" -eq 1 ]]; then - echo "would install $skill -> $dst" + if [[ -e "$dst" && "$force" -eq 0 ]]; then + echo "would stop: existing $dst (use --force to replace)" + elif [[ -e "$dst" ]]; then + echo "would replace $skill -> $dst" + else + echo "would install $skill -> $dst" + fi else if [[ -e "$dst" ]]; then echo "replacing existing $dst" diff --git a/scripts/plugin-smoke.sh b/scripts/plugin-smoke.sh new file mode 100755 index 0000000..1cdc77f --- /dev/null +++ b/scripts/plugin-smoke.sh @@ -0,0 +1,49 @@ +#!/usr/bin/env bash +set -euo pipefail + +root="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)" + +if ! command -v codex >/dev/null 2>&1; then + echo "codex CLI is required for the plugin smoke test" >&2 + exit 1 +fi + +plugin_codex_home="$(mktemp -d)" +cleanup() { + rm -rf "$plugin_codex_home" +} +trap cleanup EXIT + +CODEX_HOME="$plugin_codex_home" codex plugin marketplace add "$root" --json >"$plugin_codex_home/marketplace-add.json" +CODEX_HOME="$plugin_codex_home" codex plugin list --marketplace robert-ray-oss --available --json >"$plugin_codex_home/available.json" +CODEX_HOME="$plugin_codex_home" codex plugin add codex-operator-kit@robert-ray-oss --json >"$plugin_codex_home/plugin-add.json" +CODEX_HOME="$plugin_codex_home" codex plugin list --marketplace robert-ray-oss --json >"$plugin_codex_home/installed.json" + +python3 - "$plugin_codex_home/available.json" "$plugin_codex_home/installed.json" <<'PY' +import json +import sys +from pathlib import Path + +available = json.loads(Path(sys.argv[1]).read_text()) +installed = json.loads(Path(sys.argv[2]).read_text()) + +def has_plugin(payload, installed_only): + if isinstance(payload, list): + rows = payload + else: + rows = payload.get("plugins", []) + rows = rows + payload.get("installed", []) + payload.get("available", []) + for row in rows: + name = row.get("name") or row.get("plugin", {}).get("name") + is_installed = row.get("installed", False) or row.get("status") == "installed" + if name == "codex-operator-kit" and (not installed_only or is_installed): + return True + return False + +if not has_plugin(available, installed_only=False): + raise SystemExit("plugin is not available from the isolated marketplace") +if not has_plugin(installed, installed_only=True): + raise SystemExit("plugin did not install in the isolated Codex home") +PY + +echo "plugin smoke test passed" diff --git a/scripts/validate.sh b/scripts/validate.sh index 456120e..a53157a 100755 --- a/scripts/validate.sh +++ b/scripts/validate.sh @@ -10,25 +10,39 @@ required=( "SECURITY.md" "CHANGELOG.md" "LICENSE" + ".codex-plugin/plugin.json" + ".agents/plugins/marketplace.json" ".github/PULL_REQUEST_TEMPLATE.md" ".github/ISSUE_TEMPLATE/config.yml" ".github/ISSUE_TEMPLATE/workflow-improvement.yml" "docs/install-and-use.md" "docs/maintenance-model.md" + "docs/operator-field-guide.md" "docs/quick-demo.md" "docs/publication-risk.md" + "docs/shared-context-pattern.md" "docs/workflows.md" "docs/codex-for-oss-application.md" + "examples/bounded-loop.md" + "examples/command-center-routing.md" "examples/conversation-capture-receipt.md" "examples/issue-triage.md" + "examples/live-surface-verification.md" "examples/pr-review-gate.md" "examples/release-readiness.md" + "skills/bounded-agent-loops/SKILL.md" + "skills/command-center-routing/SKILL.md" "skills/conversation-capture-receipts/SKILL.md" + "skills/live-surface-verification/SKILL.md" "skills/oss-maintainer-triage/SKILL.md" "skills/milestone-review/SKILL.md" + "skills/shared-context-briefs/SKILL.md" "templates/AGENTS.md" + "templates/verification-contract.md" + "templates/worker-packet.md" "scripts/install-skills.sh" "scripts/check-publication-risk.sh" + "scripts/plugin-smoke.sh" ) for path in "${required[@]}"; do @@ -47,13 +61,25 @@ fi for skill in "$root"/skills/*/SKILL.md; do grep -q '^---$' "$skill" || { echo "missing front matter: $skill" >&2; exit 1; } + skill_name="$(basename "$(dirname "$skill")")" + grep -q "^name: $skill_name$" "$skill" || { echo "skill name does not match directory: $skill" >&2; exit 1; } grep -q '^description:' "$skill" || { echo "missing description: $skill" >&2; exit 1; } grep -q '^##' "$skill" || { echo "missing sections: $skill" >&2; exit 1; } done +for script in "$root"/scripts/*.sh; do + bash -n "$script" +done + "$root/scripts/check-publication-risk.sh" -"$root/scripts/install-skills.sh" --list >/dev/null +listed_skills="$("$root/scripts/install-skills.sh" --list)" +discovered_skills="$(find "$root/skills" -mindepth 1 -maxdepth 1 -type d -exec basename {} \; | sort)" +if [[ "$listed_skills" != "$discovered_skills" ]]; then + echo "installer skill list does not match skills directory" >&2 + exit 1 +fi + "$root/scripts/install-skills.sh" --dry-run >/dev/null install_tmp="$(mktemp -d)" @@ -64,6 +90,10 @@ while IFS= read -r -d '' skill_dir; do echo "install guide is missing skill: $skill_name" >&2 exit 1 fi + if ! grep -q -- "\`$skill_name\`" "$root/README.md"; then + echo "README is missing skill: $skill_name" >&2 + exit 1 + fi "$root/scripts/install-skills.sh" --target "$install_tmp/skills" "$skill_name" >/dev/null if [[ ! -s "$install_tmp/skills/$skill_name/SKILL.md" ]]; then @@ -72,17 +102,72 @@ while IFS= read -r -d '' skill_dir; do fi done < <(find "$root/skills" -mindepth 1 -maxdepth 1 -type d -print0 | sort -z) -python3 - "$root/docs/codex-for-oss-application.md" <<'PY' +if "$root/scripts/install-skills.sh" --target "$install_tmp/skills" command-center-routing >/dev/null 2>&1; then + echo "installer replaced an existing skill without --force" >&2 + exit 1 +fi +"$root/scripts/install-skills.sh" --force --target "$install_tmp/skills" command-center-routing >/dev/null + +if "$root/scripts/install-skills.sh" --target "$install_tmp/skills" ../bad >/dev/null 2>&1; then + echo "installer accepted an invalid skill name" >&2 + exit 1 +fi +if "$root/scripts/install-skills.sh" --target "$install_tmp/skills" unknown-skill >/dev/null 2>&1; then + echo "installer accepted an unknown skill" >&2 + exit 1 +fi + +python3 - "$root" <<'PY' +import json import re import sys from pathlib import Path -text = Path(sys.argv[1]).read_text() -blocks = re.findall(r"```text\n(.*?)\n```", text, flags=re.S) -limited = blocks[3:6] -for index, block in enumerate(limited, start=1): - if len(block) > 500: - raise SystemExit(f"application answer {index} exceeds 500 chars: {len(block)}") +root = Path(sys.argv[1]) + +manifest = json.loads((root / ".codex-plugin/plugin.json").read_text()) +if manifest.get("name") != "codex-operator-kit": + raise SystemExit("unexpected plugin name") +if manifest.get("skills") != "./skills/": + raise SystemExit("plugin skills path must be ./skills/") +if not manifest.get("description"): + raise SystemExit("plugin description is required") + +changelog = (root / "CHANGELOG.md").read_text() +version_match = re.search(r"^## ([0-9]+\.[0-9]+\.[0-9]+) -", changelog, flags=re.M) +if not version_match or manifest.get("version") != version_match.group(1): + raise SystemExit("plugin version does not match latest changelog entry") + +marketplace = json.loads((root / ".agents/plugins/marketplace.json").read_text()) +if marketplace.get("name") != "robert-ray-oss": + raise SystemExit("unexpected marketplace name") +plugins = marketplace.get("plugins", []) +entry = next((row for row in plugins if row.get("name") == "codex-operator-kit"), None) +if not entry: + raise SystemExit("marketplace is missing codex-operator-kit") +if entry.get("source") != {"source": "local", "path": "./"}: + raise SystemExit("marketplace must load the plugin from the repository root") +if entry.get("policy", {}).get("installation") != "AVAILABLE": + raise SystemExit("marketplace installation policy must be AVAILABLE") +if entry.get("policy", {}).get("authentication") != "ON_INSTALL": + raise SystemExit("marketplace authentication policy must be ON_INSTALL") +if not entry.get("category"): + raise SystemExit("marketplace category is required") + +application = (root / "docs/codex-for-oss-application.md").read_text() +headings = [ + "Why this repository qualifies, 500 characters max:", + "How API credits would be used, 500 characters max:", + "Anything else, 500 characters max:", +] +for heading in headings: + pattern = re.escape(heading) + r"\n\n```text\n(.*?)\n```" + match = re.search(pattern, application, flags=re.S) + if not match: + raise SystemExit(f"application field missing: {heading}") + answer = match.group(1) + if len(answer) > 500: + raise SystemExit(f"application field exceeds 500 chars ({len(answer)}): {heading}") print("application field lengths ok") PY diff --git a/skills/bounded-agent-loops/SKILL.md b/skills/bounded-agent-loops/SKILL.md new file mode 100644 index 0000000..405727b --- /dev/null +++ b/skills/bounded-agent-loops/SKILL.md @@ -0,0 +1,77 @@ +--- +name: bounded-agent-loops +description: Design or run verifier-driven agent loops with explicit goals, state, stop conditions, proof budgets, and approval boundaries; avoid open-ended autonomy when failure cannot be rejected. +--- + +# Bounded Agent Loops + +Use a loop only when the agent can act end to end against a real verifier. + +## Fit Gate + +A loop is a good fit when most of these are true: + +- the work is multi-step, repeated, or likely to need more than one attempt; +- bad output can be rejected by tests, logs, screenshots, artifacts, or a concrete rubric; +- the agent has the tools and context to perform the whole cycle; +- completion is objective enough that the user does not need to grade every pass; +- the expected value justifies the extra state and review cost. + +Otherwise, use a normal prompt or a short manual workflow. + +## Loop Contract + +Define: + +- **Goal:** exact outcome. +- **Inputs:** sources that must be read first. +- **Non-goals:** files, systems, data, people, or side effects to avoid. +- **Verifier:** command, artifact, live check, or rubric that can reject failure. +- **State:** compact record of attempts and next action. +- **Stop:** success plus hard caps for time, iterations, cost, or no-progress passes. +- **Approval boundary:** credentials, payments, destructive actions, external sends, production writes, or broad access. +- **Receipt:** final evidence and residual risk. + +If the only verifier is model self-grading, label it weak and do not schedule the loop unattended. + +## Iteration Order + +1. Discover current state and the latest failure signal. +2. Select one focused next action. +3. Make the smallest change likely to improve the verifier. +4. Run the verifier. +5. Record what changed, what passed or failed, and the next move. +6. Continue, stop, or ask only when the contract requires it. + +## Proof Budget + +- Ordinary reversible work: direct readback or one authoritative signal. +- Moderate-risk work: one targeted test, lint, build, route check, or artifact review. +- Consequential or hard-to-detect failure: stronger live proof or an independent review. + +More proof is not automatically better. Every check should answer a material risk. + +## Compact State + +```text +objective: +iteration: +changed: +verification: +failed_or_weak: +next: +blockers: +``` + +## Stop Rules + +Stop when: + +- the verifier passes; +- a hard cap is reached; +- progress stalls for two consecutive iterations; +- the approval boundary is hit; +- the task changes direction; +- new evidence makes the original goal invalid. + +The final receipt must distinguish complete, applied-but-acceptance-pending, and blocked. diff --git a/skills/command-center-routing/SKILL.md b/skills/command-center-routing/SKILL.md new file mode 100644 index 0000000..d85a24a --- /dev/null +++ b/skills/command-center-routing/SKILL.md @@ -0,0 +1,75 @@ +--- +name: command-center-routing +description: Route rough intake, mixed workstreams, delegated tasks, and status updates through one main agent conversation while keeping implementation noise, ownership, and user decisions under control. +--- + +# Command Center Routing + +Use this workflow when one conversation is the user's main intake and decision surface, but the work may need scratch execution, bounded workers, or durable owner threads. + +## Operating Model + +- The main conversation owns intake, priorities, decisions, synthesis, and final receipts. +- A bounded worker owns one independent read, implementation, test, or review slice. +- A visible owner thread owns a durable workstream that benefits from its own context or independent continuation. +- The user should not need to understand or manage this topology unless they ask. + +## Routing Gate + +Keep work in the current conversation when it is self-contained, a quick decision, or a compact synthesis. + +Use one bounded worker when: + +- the slice is independent and large enough to repay handoff cost; +- the worker can receive exact scope and stop rules; +- its raw logs would distract from the main decision surface. + +Use a visible owner thread when: + +- the work is likely to span turns or resume later; +- independent progress needs to remain inspectable; +- durable project context materially improves future work; +- concurrent work must be monitored separately. + +Do not create a worker or thread merely because a task is long. Coordination overhead must earn its cost. + +## Ownership Rules + +1. Give each write-capable lane disjoint file, service, or workflow ownership. +2. Keep one authoritative write-capable turn active per owner. +3. Before retrying an ambiguous handoff, inspect the target. The original may already have landed. +4. After a complete handoff, monitor read-only. Intervene only for new facts, a real blocker, changed risk, contradictory evidence, or clearly stale work. +5. Preserve the owner's verifier and stopping rule. Do not weaken proof just to close the main conversation faster. + +## Worker Packet + +Every delegated slice should contain: + +- objective; +- exact scope; +- allowed changes; +- non-goals; +- required inputs; +- proof budget; +- stop conditions; +- receipt shape. + +Use `templates/worker-packet.md` as a copyable packet. + +## Receipt Contract + +Bring the user a compact receipt containing: + +- state: done, running, blocked, waiting, or parked; +- what changed; +- why it matters; +- verification evidence; +- residual uncertainty; +- the exact decision or action owed by the user, if any; +- a recommended default when a decision is needed. + +Do not make the user open a worker thread or read implementation logs to understand the result. + +## Stop Rules + +Stop routing and ask when a missing choice changes architecture, taste, credentials, cost, external side effects, destructive scope, or the definition of success. diff --git a/skills/live-surface-verification/SKILL.md b/skills/live-surface-verification/SKILL.md new file mode 100644 index 0000000..dd39e5a --- /dev/null +++ b/skills/live-surface-verification/SKILL.md @@ -0,0 +1,67 @@ +--- +name: live-surface-verification +description: Diagnose and verify user-visible software failures by tracing the exact failing path, identifying its owning layer, applying the smallest durable repair, and proving the original surface works. +--- + +# Live Surface Verification + +Use this workflow when a service, application route, integration, automation, or user-facing workflow is broken, stale, or untrusted. + +## Verification Ladder + +Treat these as different evidence layers: + +1. **Configuration:** the intended setting or code exists. +2. **Process:** the expected service or worker is running. +3. **Route:** the API, file, bundle, or network path responds. +4. **Product behavior:** the visible workflow produces the right result. +5. **User acceptance:** the original user-observed failure no longer reproduces. + +A lower layer cannot prove a higher one. A running process does not prove the route, and a healthy route does not prove the user workflow. + +## Failure Contract + +Record: + +- who sees the failure; +- where they see it; +- expected behavior; +- observed behavior; +- exact reproduction path; +- safest stopping condition. + +## Triage Flow + +1. Start read-only: current version, status, logs, routes, assets, and relevant configuration. +2. Identify the exact owner of the failure: component, route, worker, service, or log emitter. +3. Avoid broad restarts or rewrites until ownership is known. +4. Repair the smallest durable layer that owns the failure. +5. Exercise the original failing path. +6. Run one adjacent check that would catch a near-miss. + +## False-Pass Review + +Before calling the repair complete, ask: + +- Could stale assets still be served even though the build passed? +- Could one worker be healthy while a different worker emits the error? +- Could the API be correct while the visible copy or interaction is wrong? +- Could a config readback be correct before the process reloads it? +- Could the smoke test bypass authentication, caching, or the real client path? + +## Verification Contract + +Use `templates/verification-contract.md` to define the proof path before mutation. + +## Completion Receipt + +Report: + +- root cause and owning layer; +- exact change; +- original path exercised; +- adjacent check; +- residual risk; +- rollback or recovery note when relevant. + +Do not call the task fixed when the repair is only applied and acceptance is still pending. diff --git a/skills/shared-context-briefs/SKILL.md b/skills/shared-context-briefs/SKILL.md new file mode 100644 index 0000000..65c2a5e --- /dev/null +++ b/skills/shared-context-briefs/SKILL.md @@ -0,0 +1,67 @@ +--- +name: shared-context-briefs +description: Design or review bounded cross-agent context using provenance, authority, freshness, expiry, and current-input priority instead of copying raw conversations into every agent prompt. +--- + +# Shared Context Briefs + +Use this workflow when several agents, chats, or execution surfaces need a consistent view of current work without sharing full transcripts. + +## Goal + +Share enough current reality for another agent to act intelligently: + +- active work; +- recent verified changes; +- accepted decisions; +- blockers; +- pending user actions; +- provenance and freshness. + +Do not attempt to recreate every conversation. + +## Push And Pull + +Push only meaningful transitions such as started, completed, blocked, superseded, accepted, or waiting. + +Pull in two stages: + +1. a compact ambient brief; +2. deeper targeted retrieval only when the present task warrants it. + +## Record Contract + +Every item should identify: + +- summary; +- source; +- authority; +- confidence; +- updated time; +- expiry or closure condition; +- visibility boundary. + +Label inference as inference. Do not present an agent summary as a direct user decision. + +## Priority Rules + +1. Current user input wins. +2. Direct accepted decisions outrank derived summaries. +3. Canonical current state outranks old receipts. +4. Expired or superseded context does not steer action. +5. Consequential decisions should resolve back to the canonical source. + +## Exclusions + +Do not include raw transcripts, hidden reasoning, credentials, full tool logs, private transport metadata, or unrelated personal context. + +## Verification + +Test that: + +- another agent can retrieve a meaningful transition with correct provenance; +- accepted durable context colors a relevant task without overriding current input; +- expired state disappears; +- raw or private material is absent from the brief. + +Use `docs/shared-context-pattern.md` for the architecture and record shape. diff --git a/templates/verification-contract.md b/templates/verification-contract.md new file mode 100644 index 0000000..4d2b453 --- /dev/null +++ b/templates/verification-contract.md @@ -0,0 +1,40 @@ +# Verification Contract + +## Failing Surface + +- User or maintainer: +- Exact path: +- Expected: +- Observed: +- Reproduction: + +## Owning Layer + +- Configuration, process, route, product behavior, or user acceptance: +- Evidence that this layer owns the failure: + +## Proposed Change + +- Smallest durable repair: +- Explicit non-goals: + +## Primary Verifier + +- Command or action: +- Passing result: +- Why it exercises the failed layer: + +## Near-Miss Check + +- Adjacent failure this check catches: +- Command or action: + +## Stop Boundary + +- Credentials, destructive changes, external sends, production writes, or unclear rollback that require escalation: + +## Completion States + +- **Complete:** primary verifier and near-miss check pass. +- **Acceptance pending:** repair applied, but the real user path still needs an authorized action. +- **Blocked:** the boundary prevents safe continuation. diff --git a/templates/worker-packet.md b/templates/worker-packet.md new file mode 100644 index 0000000..12b919b --- /dev/null +++ b/templates/worker-packet.md @@ -0,0 +1,48 @@ +# Bounded Worker Packet + +## Objective + +State one concrete outcome. + +## Exact Scope + +- Files, services, issues, or documents the worker owns. +- Whether the slice is read-only or write-capable. + +## Allowed Changes + +- List the exact mutation surface. + +## Non-Goals + +- Name adjacent work that must not be touched. + +## Required Inputs + +- Sources to read before acting. + +## Proof Budget + +- One authoritative signal by default. +- Add stronger proof only for a named risk. + +## Stop Conditions + +Stop on: + +- ambiguity that changes the outcome; +- overlapping write ownership; +- unexpected credentials, cost, or external side effects; +- broadened scope; +- repeated failure without a new signal; +- destructive or hard-to-reverse action not already approved. + +## Receipt + +Return: + +- outcome; +- files or surfaces changed; +- validation result; +- blocker or residual risk; +- exact next action, if any.