Add installer quickstart and maintainer templates

.github/ISSUE_TEMPLATE/config.yml

@@ -0,0 +1 @@
+blank_issues_enabled: true

.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

.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.

.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

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.

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

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.

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

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