diff --git a/.github/ISSUE_TEMPLATE/config.yml b/.github/ISSUE_TEMPLATE/config.yml new file mode 100644 index 0000000..0086358 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/config.yml @@ -0,0 +1 @@ +blank_issues_enabled: true diff --git a/.github/ISSUE_TEMPLATE/workflow-improvement.yml b/.github/ISSUE_TEMPLATE/workflow-improvement.yml new file mode 100644 index 0000000..a2c7229 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/workflow-improvement.yml @@ -0,0 +1,33 @@ +name: Workflow improvement +description: Suggest a maintainer workflow, skill, example, or validation improvement. +title: "[workflow] " +labels: ["workflow"] +body: + - type: textarea + id: problem + attributes: + label: Maintainer problem + description: What repeated maintenance task or false-pass path should this improve? + validations: + required: true + - type: textarea + id: proposed + attributes: + label: Proposed reusable pattern + description: Describe the smallest reusable workflow, skill, example, or script that would help. + validations: + required: true + - type: textarea + id: evidence + attributes: + label: Evidence and validation + description: What would prove the improvement works? + validations: + required: true + - type: checkboxes + id: safety + attributes: + label: Publication safety + options: + - label: This can be described without private project names, secrets, local paths, or account-specific context. + required: true diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md new file mode 100644 index 0000000..5521fb2 --- /dev/null +++ b/.github/PULL_REQUEST_TEMPLATE.md @@ -0,0 +1,20 @@ +## Summary + +- Describe the change in one or two bullets. + +## Maintenance Surface + +- [ ] Issue triage +- [ ] Prompt/skill workflow +- [ ] Validation or release tooling +- [ ] Documentation or example + +## Validation + +- [ ] `bash scripts/validate.sh` +- [ ] Public/private context reviewed +- [ ] Release notes or changelog updated when user-facing behavior changed + +## Risk + +Name any false-pass path, private-context risk, or follow-up that should remain visible after merge. diff --git a/.github/workflows/validate.yml b/.github/workflows/validate.yml index da7e41e..0291658 100644 --- a/.github/workflows/validate.yml +++ b/.github/workflows/validate.yml @@ -8,6 +8,6 @@ jobs: validate: runs-on: ubuntu-latest steps: - - uses: actions/checkout@v4 + - uses: actions/checkout@v6 - name: Validate repository pack run: bash scripts/validate.sh diff --git a/CHANGELOG.md b/CHANGELOG.md index d89f52b..f01f0e1 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,5 +1,10 @@ # Changelog +## 0.3.0 - 2026-06-01 + +- Added a skill installer script and install/use guide so maintainers can adopt the kit more directly. +- Added GitHub issue and pull request templates to support public triage, review, validation, and release habits. + ## 0.2.0 - 2026-06-01 - Added a conversation capture receipts skill for turning rough chat, voice-note, or inbox-dump input into human-useful no-write receipts. diff --git a/README.md b/README.md index 090ee3a..60c04d2 100644 --- a/README.md +++ b/README.md @@ -37,8 +37,8 @@ cp templates/AGENTS.md AGENTS.md Copy one or more skills into your local Codex skills directory: ```bash -mkdir -p ~/.codex/skills -cp -R skills/* ~/.codex/skills/ +bash scripts/install-skills.sh --dry-run +bash scripts/install-skills.sh ``` Validate this repository: @@ -60,11 +60,13 @@ bash scripts/check-publication-risk.sh - `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/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 diff --git a/docs/install-and-use.md b/docs/install-and-use.md new file mode 100644 index 0000000..df79373 --- /dev/null +++ b/docs/install-and-use.md @@ -0,0 +1,63 @@ +# 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. + +## List Skills + +```bash +bash scripts/install-skills.sh --list +``` + +Current skills: + +- `conversation-capture-receipts` +- `milestone-review` +- `oss-maintainer-triage` + +## 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. + +## Install All Skills + +```bash +bash scripts/install-skills.sh +``` + +By default, the script installs to: + +```text +${CODEX_HOME:-$HOME/.codex}/skills +``` + +Set a target explicitly when needed: + +```bash +bash scripts/install-skills.sh --target "$HOME/.codex/skills" +``` + +## Install One Skill + +```bash +bash scripts/install-skills.sh conversation-capture-receipts +``` + +## Use The Kit Without Installing + +You can also copy individual files into a repository: + +- `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 Before Publishing Changes + +```bash +bash scripts/validate.sh +``` + +Validation checks required files, skill front matter, application-field lengths, and publication-risk patterns. diff --git a/scripts/install-skills.sh b/scripts/install-skills.sh new file mode 100755 index 0000000..1c245b8 --- /dev/null +++ b/scripts/install-skills.sh @@ -0,0 +1,100 @@ +#!/usr/bin/env bash +set -euo pipefail + +root="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)" +target="${CODEX_SKILLS_DIR:-${CODEX_HOME:-$HOME/.codex}/skills}" +dry_run=0 +list_only=0 +skills=() + +usage() { + cat <<'USAGE' +Usage: bash scripts/install-skills.sh [--target DIR] [--dry-run] [--list] [skill...] + +Installs Codex Operator Kit skills into a Codex skills directory. + +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" +USAGE +} + +while [[ $# -gt 0 ]]; do + case "$1" in + --target) + [[ $# -ge 2 ]] || { echo "--target requires a directory" >&2; exit 2; } + target="$2" + shift 2 + ;; + --dry-run) + dry_run=1 + shift + ;; + --list) + list_only=1 + shift + ;; + -h|--help) + usage + exit 0 + ;; + -*) + echo "unknown option: $1" >&2 + usage >&2 + exit 2 + ;; + *) + skills+=("$1") + shift + ;; + esac +done + +available=() +while IFS= read -r -d '' skill_dir; do + available+=("$(basename "$skill_dir")") +done < <(find "$root/skills" -mindepth 1 -maxdepth 1 -type d -print0 | sort -z) + +if [[ "$list_only" -eq 1 ]]; then + printf '%s\n' "${available[@]}" + exit 0 +fi + +if [[ "${#skills[@]}" -eq 0 ]]; then + skills=("${available[@]}") +fi + +for skill in "${skills[@]}"; do + if [[ ! "$skill" =~ ^[a-z0-9-]+$ ]]; then + echo "invalid skill name: $skill" >&2 + echo "skill names must use lowercase letters, numbers, and hyphens" >&2 + exit 1 + fi + if [[ ! -d "$root/skills/$skill" ]]; then + echo "unknown skill: $skill" >&2 + echo "available skills:" >&2 + printf ' %s\n' "${available[@]}" >&2 + exit 1 + fi +done + +if [[ "$dry_run" -eq 0 ]]; then + mkdir -p "$target" +fi + +for skill in "${skills[@]}"; do + src="$root/skills/$skill" + dst="$target/$skill" + if [[ "$dry_run" -eq 1 ]]; then + echo "would install $skill -> $dst" + else + if [[ -e "$dst" ]]; then + echo "replacing existing $dst" + fi + rm -rf "$dst" + cp -R "$src" "$dst" + echo "installed $skill -> $dst" + fi +done diff --git a/scripts/validate.sh b/scripts/validate.sh index 77c98bf..a9cf865 100755 --- a/scripts/validate.sh +++ b/scripts/validate.sh @@ -10,6 +10,10 @@ required=( "SECURITY.md" "CHANGELOG.md" "LICENSE" + ".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/publication-risk.md" "docs/workflows.md" @@ -22,6 +26,7 @@ required=( "skills/oss-maintainer-triage/SKILL.md" "skills/milestone-review/SKILL.md" "templates/AGENTS.md" + "scripts/install-skills.sh" "scripts/check-publication-risk.sh" ) @@ -47,6 +52,25 @@ done "$root/scripts/check-publication-risk.sh" +"$root/scripts/install-skills.sh" --list >/dev/null +"$root/scripts/install-skills.sh" --dry-run >/dev/null + +install_tmp="$(mktemp -d)" +trap 'rm -rf "$install_tmp"' EXIT +while IFS= read -r -d '' skill_dir; do + skill_name="$(basename "$skill_dir")" + if ! grep -q -- "- \`$skill_name\`" "$root/docs/install-and-use.md"; then + echo "install guide 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 + echo "installer smoke test failed for: $skill_name" >&2 + exit 1 + fi +done < <(find "$root/skills" -mindepth 1 -maxdepth 1 -type d -print0 | sort -z) + python3 - "$root/docs/codex-for-oss-application.md" <<'PY' import re import sys