ask-colleague 0.1.0

package/docs/publishing.md

@@ -0,0 +1,154 @@
+# Publishing Ask Colleague to npm
+
+This package is designed so the public install path is one command:
+
+```bash
+npx ask-colleague@latest install
+```
+
+`npx` runs the npm package's executable once. The executable then copies the long-lived `colleague` command and both skill files into the user's home directory, recording checksums in `~/.ask-colleague/install-manifest.tsv`.
+
+## 1. Pick the package name
+
+The starter `package.json` uses:
+
+```json
+"name": "ask-colleague"
+```
+
+Before publishing, check that the package name is available. If it is taken, use a scoped package name instead:
+
+```json
+"name": "@your-scope/ask-colleague"
+```
+
+With a scoped name, the install command becomes:
+
+```bash
+npx @your-scope/ask-colleague@latest install
+```
+
+## 2. Add public repository metadata
+
+This starter package intentionally does not include fake GitHub metadata. Before publishing from your real repo, add fields like:
+
+```json
+{
+  "homepage": "https://github.com/<owner>/<repo>#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/<owner>/<repo>.git"
+  },
+  "bugs": {
+    "url": "https://github.com/<owner>/<repo>/issues"
+  }
+}
+```
+
+Also replace `<your-ask-colleague-repo-url>` in `README.md`.
+
+## 3. Run local checks
+
+```bash
+npm test
+npm pack --dry-run
+```
+
+Then build a real local tarball and run it through `npx`:
+
+```bash
+npm pack --pack-destination /tmp
+npx --yes --package /tmp/ask-colleague-0.4.0.tgz ask-colleague --version
+npx --yes --package /tmp/ask-colleague-0.4.0.tgz ask-colleague install --dry-run
+```
+
+If you changed the package name or version, update the tarball path accordingly.
+
+## 4. Inspect package contents
+
+Make sure the npm tarball includes only what users need:
+
+```bash
+npm pack --dry-run
+```
+
+Expected included paths:
+
+```text
+package.json
+README.md
+LICENSE
+CONTRIBUTING.md
+bin/colleague
+install.sh
+uninstall.sh
+scripts/ask-codex.sh
+scripts/ask-claude.sh
+skills/claude/colleague/SKILL.md
+skills/codex/colleague/SKILL.md
+skills/codex/colleague/agents/openai.yaml
+prompts/colleague.md
+snippets/AGENTS.md
+snippets/CLAUDE.md
+templates/context.md
+docs/security.md
+docs/publishing.md
+```
+
+## 5. Publish
+
+```bash
+npm login
+npm publish --access public
+```
+
+For scoped packages, `--access public` is required unless your npm account/org has different defaults.
+
+## 6. Verify public install
+
+After npm finishes publishing:
+
+```bash
+npx ask-colleague@latest --version
+npx ask-colleague@latest install --dry-run
+```
+
+Then do a real install in a clean shell:
+
+```bash
+npx ask-colleague@latest install
+export PATH="$HOME/.local/bin:$PATH"
+colleague doctor
+```
+
+Also verify overwrite protection and uninstall behavior:
+
+```bash
+colleague uninstall --dry-run
+colleague uninstall
+```
+
+## 7. Optional AGENTS.md fallback
+
+Do not enable the global Codex AGENTS.md fallback by default in release notes. Users who want it can opt in:
+
+```bash
+npx ask-colleague@latest install --agents-md
+```
+
+## 8. Release updates
+
+Bump the version before each publish:
+
+```bash
+npm version patch
+npm publish --access public
+```
+
+Use `minor` for new features and `major` for breaking changes.
+
+## Notes
+
+- The package intentionally has no runtime npm dependencies.
+- The executable is Bash, so the supported target environments are macOS, Linux, and WSL-like shells.
+- `npx ask-colleague@latest install` is a bootstrap. The persistent command after install is `colleague`.

package/docs/security.md

@@ -0,0 +1,63 @@
+# Security notes
+
+`ask-colleague` is a convenience bridge, not a trust boundary. It sends whatever you put in the context file to another local AI CLI authenticated as you.
+
+## Principles
+
+1. **Minimize context.** A short, hand-written briefing is safer and more useful than a raw transcript.
+2. **No secrets.** Never include `.env` files, private keys, API tokens, cookies, credentials, proprietary customer data, or raw production logs.
+3. **One-shot by default.** Avoid agent-to-agent loops. If the answer is bad, rewrite the briefing and ask again.
+4. **Read-oriented.** Codex is invoked with `--sandbox read-only` by default. Claude is invoked with `--bare`, print mode, no session persistence, one max turn, `--tools ""`, and `--` before its positional prompt.
+5. **Explicit-only skills.** The installed Claude and Codex skills are configured so the user or primary agent must invoke them intentionally.
+6. **Advice, not authority.** The primary agent/human reviews the peer’s answer before making changes.
+
+## Prompt injection
+
+The bridge wraps the context in `<session_context>` and instructs the peer to treat it as untrusted. That helps, but it is not a formal security guarantee. Do not include hostile or sensitive data unless you are comfortable with the peer model reading it.
+
+The consulting prompt also tells the peer not to start nested colleague calls, not to spawn tools, and not to modify files. Treat this as defense-in-depth, not as a hard sandbox.
+
+## Temporary files
+
+Skills and snippets use `mktemp` instead of a fixed predictable temp path. This avoids collisions and reduces accidental exposure on shared machines.
+
+Recommended pattern:
+
+```bash
+ctx="$(mktemp -t colleague-ctx.XXXXXX.md)"
+trap 'rm -f "$ctx"' EXIT
+```
+
+## Sandboxing
+
+Codex defaults to:
+
+```bash
+codex exec --color never --ephemeral --skip-git-repo-check --sandbox read-only -
+```
+
+You can opt into broader access with `--sandbox workspace-write` or `--sandbox danger-full-access`, but this is not recommended for a consultation bridge.
+
+Claude Code is called with:
+
+```bash
+claude --bare -p --output-format text --no-session-persistence --max-turns 1 --tools "" -- "Read the consulting request from stdin and answer it directly."
+```
+
+`--bare` avoids MCP auto-discovery, `--tools ""` disables built-in Claude Code tools for the consultant call, and `--` prevents the positional prompt from being consumed by the variadic `--tools` option. The bridge passes the consulting package on stdin.
+
+## Install and uninstall safety
+
+`install.sh` writes a manifest to:
+
+```text
+~/.ask-colleague/install-manifest.tsv
+```
+
+The manifest records installed files and checksums. Reinstall overwrites only files that are tracked and unmodified. Uninstall removes only tracked, unmodified files. Use `--force` for legacy installs or intentional replacement/removal.
+
+The installer does not modify `~/.codex/AGENTS.md` by default. Pass `--agents-md` to opt into that global fallback.
+
+## Recommended team policy
+
+For shared or public repos, keep the installed skill instruction-only and require normal shell approval on first use. Teams can add their own allow rules after reviewing the scripts.

package/install.sh

@@ -0,0 +1,254 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+ROOT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+PREFIX="${PREFIX:-$HOME/.local}"
+STATE_DIR="${COLLEAGUE_STATE_DIR:-$HOME/.ask-colleague}"
+MANIFEST="$STATE_DIR/install-manifest.tsv"
+INSTALL_BIN=0
+INSTALL_CLAUDE=0
+INSTALL_CODEX=0
+INSTALL_AGENTS_MD=0
+DRY_RUN=0
+FORCE=0
+
+AGENTS_BEGIN_MARK='<!-- BEGIN ask-colleague bridge -->'
+AGENTS_END_MARK='<!-- END ask-colleague bridge -->'
+
+usage() {
+  cat <<'USAGE'
+Usage: colleague install [--all] [--bin] [--claude] [--codex] [--prefix DIR] [--agents-md] [--force] [--dry-run]
+       ./install.sh        [--all] [--bin] [--claude] [--codex] [--prefix DIR] [--agents-md] [--force] [--dry-run]
+
+Default with no component flags is --all.
+
+Installs:
+  bin/colleague                         -> $PREFIX/bin/colleague
+  bin/colleague                         -> $PREFIX/bin/ask-colleague
+  skills/claude/colleague/SKILL.md      -> ~/.claude/skills/colleague/SKILL.md
+  skills/codex/colleague/SKILL.md       -> ~/.agents/skills/colleague/SKILL.md
+  skills/codex/.../agents/openai.yaml   -> ~/.agents/skills/colleague/agents/openai.yaml
+  prompts/colleague.md                  -> ~/.codex/prompts/colleague.md  (legacy custom prompt)
+
+Optional:
+  --agents-md                           append snippets/AGENTS.md once to ~/.codex/AGENTS.md
+                                         (opt-in because it affects all Codex sessions)
+
+Safety:
+  Existing files are overwritten only if they are tracked in the
+  ~/.ask-colleague install manifest and have not been modified.
+  Use --force to overwrite intentionally.
+
+Set PREFIX=/some/path or pass --prefix DIR to choose the binary location.
+USAGE
+}
+
+log() { printf '%s\n' "$*"; }
+die() { printf 'install: %s\n' "$*" >&2; exit 1; }
+have() { command -v "$1" >/dev/null 2>&1; }
+
+need_value() {
+  local opt="$1"
+  local val="${2-}"
+  if [[ -z "$val" || "$val" == --* ]]; then
+    die "$opt requires a value"
+  fi
+  printf '%s\n' "$val"
+}
+
+run() {
+  if [[ "$DRY_RUN" == "1" ]]; then
+    printf '+ %q' "$1"
+    shift
+    local arg
+    for arg in "$@"; do
+      printf ' %q' "$arg"
+    done
+    printf '\n'
+  else
+    "$@"
+  fi
+}
+
+checksum_file() {
+  local file="$1"
+  if have sha256sum; then
+    sha256sum "$file" | awk '{print $1}'
+  elif have shasum; then
+    shasum -a 256 "$file" | awk '{print $1}'
+  else
+    cksum "$file" | awk '{print $1 "-" $2}'
+  fi
+}
+
+manifest_file_matches() {
+  local path="$1"
+  [[ -f "$MANIFEST" && -f "$path" ]] || return 1
+  local entry_type recorded_checksum recorded_path current_checksum
+  current_checksum="$(checksum_file "$path" 2>/dev/null || true)"
+  [[ -n "$current_checksum" ]] || return 1
+  while IFS=$'\t' read -r entry_type recorded_checksum recorded_path; do
+    if [[ "$entry_type" == "file" && "$recorded_path" == "$path" && "$recorded_checksum" == "$current_checksum" ]]; then
+      return 0
+    fi
+  done < "$MANIFEST"
+  return 1
+}
+
+manifest_record() {
+  local entry_type="$1"
+  local recorded_checksum="$2"
+  local path="$3"
+  if [[ "$DRY_RUN" == "1" ]]; then
+    printf '+ record %q %q in %q\n' "$entry_type" "$path" "$MANIFEST"
+    return 0
+  fi
+
+  mkdir -p "$STATE_DIR"
+  local tmp
+  tmp="$(mktemp)"
+  if [[ -f "$MANIFEST" ]]; then
+    awk -F '\t' -v path="$path" '$3 != path { print }' "$MANIFEST" > "$tmp"
+  else
+    : > "$tmp"
+  fi
+  printf '%s\t%s\t%s\n' "$entry_type" "$recorded_checksum" "$path" >> "$tmp"
+  mv "$tmp" "$MANIFEST"
+}
+
+safe_copy_file() {
+  local src="$1"
+  local dst="$2"
+  local mode="${3:-}"
+  [[ -f "$src" ]] || die "missing packaged file: $src"
+
+  if [[ -e "$dst" ]]; then
+    [[ -f "$dst" ]] || die "refusing to overwrite non-file path: $dst"
+    if [[ "$FORCE" != "1" ]] && ! manifest_file_matches "$dst"; then
+      cat >&2 <<MSG
+Refusing to overwrite existing file: $dst
+It is not tracked as an unmodified ask-colleague install.
+Re-run with --force if this file belongs to ask-colleague and should be replaced.
+MSG
+      exit 1
+    fi
+  fi
+
+  run mkdir -p "$(dirname "$dst")"
+  run cp "$src" "$dst"
+  if [[ -n "$mode" ]]; then
+    run chmod "$mode" "$dst"
+  fi
+
+  if [[ "$DRY_RUN" == "1" ]]; then
+    manifest_record file "dry-run" "$dst"
+  else
+    manifest_record file "$(checksum_file "$dst")" "$dst"
+  fi
+}
+
+append_agents_block() {
+  local agents="$HOME/.codex/AGENTS.md"
+  local snippet="$ROOT_DIR/snippets/AGENTS.md"
+  [[ -f "$snippet" ]] || die "missing packaged file: $snippet"
+
+  if [[ -f "$agents" ]] && grep -qF "$AGENTS_BEGIN_MARK" "$agents"; then
+    if ! grep -qF "$AGENTS_END_MARK" "$agents"; then
+      die "$agents contains the ask-colleague begin marker but no end marker"
+    fi
+    log "Codex AGENTS.md already contains the colleague block"
+    manifest_record agents_block present "$agents"
+    return 0
+  fi
+
+  if [[ "$DRY_RUN" == "1" ]]; then
+    printf '+ append %q to %q\n' "$snippet" "$agents"
+  else
+    mkdir -p "$HOME/.codex"
+    {
+      if [[ -s "$agents" ]]; then printf '\n'; fi
+      cat "$snippet"
+    } >> "$agents"
+  fi
+  manifest_record agents_block present "$agents"
+  log "Appended colleague block to ~/.codex/AGENTS.md"
+}
+
+while [[ $# -gt 0 ]]; do
+  case "$1" in
+    --all)
+      INSTALL_BIN=1; INSTALL_CLAUDE=1; INSTALL_CODEX=1; shift ;;
+    --bin)
+      INSTALL_BIN=1; shift ;;
+    --claude)
+      INSTALL_CLAUDE=1; shift ;;
+    --codex)
+      INSTALL_CODEX=1; shift ;;
+    --prefix)
+      PREFIX="$(need_value "$1" "${2-}")"; shift 2 ;;
+    --agents-md)
+      INSTALL_AGENTS_MD=1; shift ;;
+    --no-agents-md)
+      # Accepted for compatibility with older releases. It is now the default.
+      INSTALL_AGENTS_MD=0; shift ;;
+    --force)
+      FORCE=1; shift ;;
+    --dry-run)
+      DRY_RUN=1; shift ;;
+    -h|--help)
+      usage; exit 0 ;;
+    *)
+      echo "Unknown option: $1" >&2; usage >&2; exit 2 ;;
+  esac
+done
+
+[[ -n "$PREFIX" ]] || die "--prefix cannot be empty"
+
+if [[ "$INSTALL_BIN$INSTALL_CLAUDE$INSTALL_CODEX" == "000" ]]; then
+  INSTALL_BIN=1; INSTALL_CLAUDE=1; INSTALL_CODEX=1
+fi
+
+if [[ "$INSTALL_BIN" == "1" ]]; then
+  safe_copy_file "$ROOT_DIR/bin/colleague" "$PREFIX/bin/colleague" "+x"
+  safe_copy_file "$ROOT_DIR/bin/colleague" "$PREFIX/bin/ask-colleague" "+x"
+  log "Installed colleague binary to $PREFIX/bin/colleague"
+  log "Installed ask-colleague alias to $PREFIX/bin/ask-colleague"
+fi
+
+if [[ "$INSTALL_CLAUDE" == "1" ]]; then
+  safe_copy_file "$ROOT_DIR/skills/claude/colleague/SKILL.md" "$HOME/.claude/skills/colleague/SKILL.md"
+  log "Installed Claude Code skill to ~/.claude/skills/colleague/SKILL.md"
+fi
+
+if [[ "$INSTALL_CODEX" == "1" ]]; then
+  safe_copy_file "$ROOT_DIR/skills/codex/colleague/SKILL.md" "$HOME/.agents/skills/colleague/SKILL.md"
+  safe_copy_file "$ROOT_DIR/skills/codex/colleague/agents/openai.yaml" "$HOME/.agents/skills/colleague/agents/openai.yaml"
+  log "Installed Codex skill to ~/.agents/skills/colleague/SKILL.md"
+
+  # Older Codex versions may still support custom prompts. Keep this as a
+  # compatibility fallback, but prefer the skill on versions that support skills.
+  safe_copy_file "$ROOT_DIR/prompts/colleague.md" "$HOME/.codex/prompts/colleague.md"
+  log "Installed legacy Codex custom prompt to ~/.codex/prompts/colleague.md"
+
+  if [[ "$INSTALL_AGENTS_MD" == "1" ]]; then
+    append_agents_block
+  else
+    log "Skipped ~/.codex/AGENTS.md fallback block. Pass --agents-md to opt in."
+  fi
+fi
+
+cat <<NEXT_STEPS
+
+Next steps:
+1. Ensure $PREFIX/bin is in your PATH.
+2. Run: colleague doctor
+3. In Claude Code, invoke: /colleague ask Codex to critique this plan
+4. In Codex, invoke: \$colleague ask Claude to critique my current plan
+   Legacy custom prompt fallback: /prompts:colleague should I use a queue or cron here?
+
+For one-command public installs after publishing to npm:
+  npx ask-colleague@latest install
+
+Optional global Codex AGENTS.md fallback:
+  npx ask-colleague@latest install --agents-md
+NEXT_STEPS

package/package.json

@@ -0,0 +1,50 @@
+{
+  "name": "ask-colleague",
+  "version": "0.1.0",
+  "description": "Ask a colleague, a bridge that lets Claude Code and Codex ask each other for one-shot peer advice.",
+  "license": "MIT",
+  "homepage": "https://github.com/stevyhacker/ask-colleague#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/stevyhacker/ask-colleague.git"
+  },
+  "bugs": {
+    "url": "https://github.com/stevyhacker/ask-colleague/issues"
+  },
+  "keywords": [
+    "agent",
+    "ai",
+    "claude-code",
+    "codex",
+    "cli",
+    "skills",
+    "peer-review",
+    "coding-agent"
+  ],
+  "bin": {
+    "ask-colleague": "bin/colleague",
+    "colleague": "bin/colleague"
+  },
+  "files": [
+    "bin/",
+    "scripts/",
+    "skills/",
+    "snippets/",
+    "prompts/",
+    "templates/",
+    "docs/",
+    "install.sh",
+    "uninstall.sh",
+    "README.md",
+    "LICENSE",
+    "CONTRIBUTING.md"
+  ],
+  "scripts": {
+    "test": "bash tests/smoke.sh",
+    "pack:check": "npm pack --dry-run",
+    "local:npx": "npm pack --pack-destination /tmp >/tmp/ask-colleague-pack-name && npx --yes --package /tmp/$(cat /tmp/ask-colleague-pack-name) ask-colleague --version"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/prompts/colleague.md

@@ -0,0 +1,41 @@
+---
+description: Consult Claude Code for a one-shot second opinion
+argument-hint: "[question]"
+---
+
+# /prompts:colleague — consult Claude Code for a second opinion
+
+You can ask Claude Code, an independent local AI coding agent, for advice. It has no access to this session, so everything it knows must come from a compact briefing you write.
+
+This custom prompt is a legacy compatibility fallback. Prefer the `$colleague` skill on Codex versions that load user skills.
+
+Steps:
+
+1. Create a private temp file and clean it up after use:
+
+   ```bash
+   ctx="$(mktemp -t colleague-ctx.XXXXXX.md)"
+   trap 'rm -f "$ctx"' EXIT
+   ```
+
+2. Write a compact briefing into `$ctx` containing:
+
+   - **Goal** — what the user is ultimately trying to achieve
+   - **Relevant files and snippets** — paths plus only the key snippets
+   - **What has been tried** — approaches attempted and their results/errors
+   - **Current error or dilemma** — exact error, failing test, or design choice
+   - **Constraints / non-goals**
+
+   Summarize aggressively. Never paste the raw session transcript, tool logs, `.env` files, API keys, tokens, or credentials.
+
+3. Run:
+
+   ```bash
+   colleague ask claude --context "$ctx" --question "$ARGUMENTS"
+   ```
+
+   If `colleague` is not on PATH, use `~/.local/bin/colleague`.
+
+4. Treat the response as peer advice, not ground truth: compare it with your own analysis, tell the user where you agree or disagree, then proceed using your own judgment.
+
+Rules: one focused question per consultation; do not start nested agent-to-agent consultation; if the answer misses, improve the briefing and ask once more rather than starting a multi-turn loop; if the `claude` CLI is not installed, say so and continue without it.

package/scripts/ask-claude.sh

@@ -0,0 +1,9 @@
+#!/usr/bin/env bash
+set -euo pipefail
+if [[ $# -lt 2 ]]; then
+  echo 'Usage: ask-claude.sh <context_file> "question"' >&2
+  exit 2
+fi
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+ROOT_DIR="$(cd "$SCRIPT_DIR/.." && pwd)"
+exec "$ROOT_DIR/bin/colleague" ask claude --context "$1" --question "$2" "${@:3}"

package/scripts/ask-codex.sh

@@ -0,0 +1,9 @@
+#!/usr/bin/env bash
+set -euo pipefail
+if [[ $# -lt 2 ]]; then
+  echo 'Usage: ask-codex.sh <context_file> "question"' >&2
+  exit 2
+fi
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+ROOT_DIR="$(cd "$SCRIPT_DIR/.." && pwd)"
+exec "$ROOT_DIR/bin/colleague" ask codex --context "$1" --question "$2" "${@:3}"

package/skills/claude/colleague/SKILL.md

@@ -0,0 +1,61 @@
+---
+name: colleague
+description: Consult Codex as a second local AI coding agent for a one-shot peer review when explicitly requested.
+disable-model-invocation: true
+argument-hint: "[question]"
+---
+
+# Colleague: ask Codex for advice
+
+Use this skill only when the user explicitly asks to "ask Codex", "ask a colleague", or "get a second opinion". It gets a one-shot second opinion from Codex without handing control of the repo to it.
+
+## Workflow
+
+1. Create a private, unpredictable temp file with `mktemp`, and clean it up after use:
+
+   ```bash
+   ctx="$(mktemp -t colleague-ctx.XXXXXX.md)"
+   trap 'rm -f "$ctx"' EXIT
+   ```
+
+2. Write a compact briefing into `$ctx`. Include only what Codex needs:
+
+   - user-facing goal
+   - relevant file paths and short snippets
+   - what you have already tried
+   - exact error, dilemma, or design choice
+   - constraints and non-goals
+
+   Do not dump the raw conversation transcript, tool logs, `.env` files, API keys, private URLs, tokens, or credentials. Summarize aggressively.
+
+3. Ask Codex with the installed bridge:
+
+   ```bash
+   colleague ask codex \
+     --context "$ctx" \
+     --question "What is the strongest critique of my current plan?"
+   ```
+
+   Use `--model <model>` only when the user asks for a specific model. The bridge runs Codex non-interactively (`codex exec`) in a read-only sandbox by default for the one-shot consult.
+
+4. Treat the response as peer advice, not ground truth. Compare it to your own analysis.
+
+5. In your response to the user, say that you consulted Codex, then explain where you agree, disagree, or remain uncertain. Continue with the implementation or recommendation using your own judgment.
+
+## Good briefing template
+
+```markdown
+# Goal
+
+# Relevant files and snippets
+
+# What I tried
+
+# Current error or dilemma
+
+# Constraints / non-goals
+```
+
+## When not to use this skill
+
+Do not use it for simple questions you can answer directly. Do not use it to outsource user-private or secret material. Do not start a multi-turn agent-to-agent loop; if the answer misses, improve the briefing and ask once more.