ask-colleague 0.1.0

package/skills/codex/colleague/SKILL.md

@@ -0,0 +1,60 @@
+---
+name: colleague
+description: Consult Claude Code as a second local AI coding agent for a one-shot peer review when explicitly requested.
+argument-hint: "[question]"
+---
+
+# Colleague: ask Claude Code for advice
+
+Use this skill only when the user explicitly asks to "ask Claude", "ask a colleague", or "get a second opinion". It gets a one-shot second opinion from Claude Code without letting it take over the repo.
+
+## 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 Claude 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 Claude with the installed bridge:
+
+   ```bash
+   colleague ask claude \
+     --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 calls Claude in print mode with no session persistence, one max turn, `--bare`, and `--tools ""`.
+
+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 Claude, 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.

package/skills/codex/colleague/agents/openai.yaml

@@ -0,0 +1,5 @@
+interface:
+  display_name: "Colleague"
+  short_description: "Ask Claude Code for a one-shot second opinion."
+policy:
+  allow_implicit_invocation: false

package/snippets/AGENTS.md

@@ -0,0 +1,24 @@
+<!-- BEGIN ask-colleague bridge -->
+## Colleague bridge
+
+A `colleague` CLI may be available for a one-shot second opinion from Claude Code. Use it only when the user explicitly asks to "ask Claude", "ask a colleague", or after you have made a concrete attempt and are genuinely blocked.
+
+Procedure:
+
+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 context briefing into `$ctx`. Include the goal, relevant file paths/snippets, what has been tried, the exact error or dilemma, and constraints. Do not include secrets or raw transcripts.
+
+3. Run:
+
+   ```bash
+   colleague ask claude --context "$ctx" --question "your specific question"
+   ```
+
+4. Treat Claude's response as advice from a peer, not ground truth. Compare it to your own analysis before acting. Do not start a nested or multi-turn agent-to-agent loop.
+<!-- END ask-colleague bridge -->

package/snippets/CLAUDE.md

@@ -0,0 +1,22 @@
+## Colleague bridge
+
+A `colleague` CLI may be available for a one-shot second opinion from Codex. Use it only when the user explicitly asks to "ask Codex", "ask a colleague", or after you have made a concrete attempt and are genuinely blocked.
+
+Procedure:
+
+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 context briefing into `$ctx`. Include the goal, relevant file paths/snippets, what has been tried, the exact error or dilemma, and constraints. Do not include secrets or raw transcripts.
+
+3. Run:
+
+   ```bash
+   colleague ask codex --context "$ctx" --question "your specific question"
+   ```
+
+4. Treat Codex's response as advice from a peer, not ground truth. Compare it to your own analysis before acting. Do not start a nested or multi-turn agent-to-agent loop.

package/templates/context.md

@@ -0,0 +1,42 @@
+# Colleague briefing
+
+Use this with a private temp file, for example:
+
+```bash
+ctx="$(mktemp -t colleague-ctx.XXXXXX.md)"
+trap 'rm -f "$ctx"' EXIT
+colleague make-context --output "$ctx"
+```
+
+## Goal
+
+Explain the user-facing goal in 2-5 sentences.
+
+## Relevant files and snippets
+
+Include file paths and only the snippets needed for the peer to reason.
+Summarize large files rather than dumping them.
+
+```text
+path/to/file.ext
+short snippet or description
+```
+
+## What has been tried
+
+- Attempt 1:
+- Attempt 2:
+
+## Current error, dilemma, or design choice
+
+Paste the exact error message or the decision being debated.
+
+## Constraints and non-goals
+
+- Runtime / framework / compatibility constraints:
+- Security or privacy constraints:
+- Non-goals:
+
+## Question for the peer
+
+What should the primary agent double-check, change, or avoid?

package/uninstall.sh

@@ -0,0 +1,165 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+PREFIX="${PREFIX:-$HOME/.local}"
+STATE_DIR="${COLLEAGUE_STATE_DIR:-$HOME/.ask-colleague}"
+MANIFEST="$STATE_DIR/install-manifest.tsv"
+DRY_RUN=0
+FORCE=0
+
+AGENTS_BEGIN_MARK='<!-- BEGIN ask-colleague bridge -->'
+AGENTS_END_MARK='<!-- END ask-colleague bridge -->'
+
+usage() {
+  cat <<'USAGE'
+Usage: colleague uninstall [--prefix DIR] [--force] [--dry-run]
+       ./uninstall.sh      [--prefix DIR] [--force] [--dry-run]
+
+By default, uninstall reads ~/.ask-colleague/install-manifest.tsv and removes
+only files that this package installed and that have not been modified.
+
+Use --force only for legacy installs without a manifest or to remove modified
+ask-colleague files intentionally.
+USAGE
+}
+
+die() { printf 'uninstall: %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
+}
+
+strip_agents_block() {
+  local agents="$HOME/.codex/AGENTS.md"
+  [[ -f "$agents" ]] || return 0
+  grep -qF "$AGENTS_BEGIN_MARK" "$agents" || return 0
+
+  local tmp
+  tmp="$(mktemp)"
+  if ! awk -v begin="$AGENTS_BEGIN_MARK" -v end="$AGENTS_END_MARK" '
+    index($0, begin) { skipping = 1; next }
+    skipping && index($0, end) { skipping = 0; next }
+    !skipping { print }
+    END { if (skipping) exit 2 }
+  ' "$agents" > "$tmp"; then
+    rm -f "$tmp"
+    printf 'Refusing to strip incomplete ask-colleague block from %s: missing end marker.\n' "$agents" >&2
+    return 1
+  fi
+
+  if [[ "$DRY_RUN" == "1" ]]; then
+    rm -f "$tmp"
+    printf '+ strip colleague block from %q\n' "$agents"
+    return 0
+  fi
+
+  mv "$tmp" "$agents"
+}
+
+legacy_force_uninstall() {
+  run rm -f "$PREFIX/bin/colleague" "$PREFIX/bin/ask-colleague"
+  run rm -f "$HOME/.claude/skills/colleague/SKILL.md"
+  run rm -f "$HOME/.agents/skills/colleague/SKILL.md" "$HOME/.agents/skills/colleague/agents/openai.yaml"
+  run rmdir "$HOME/.agents/skills/colleague/agents" 2>/dev/null || true
+  run rmdir "$HOME/.agents/skills/colleague" 2>/dev/null || true
+  run rmdir "$HOME/.claude/skills/colleague" 2>/dev/null || true
+  run rm -f "$HOME/.codex/prompts/colleague.md"
+  strip_agents_block
+}
+
+while [[ $# -gt 0 ]]; do
+  case "$1" in
+    --prefix)
+      PREFIX="$(need_value "$1" "${2-}")"; shift 2 ;;
+    --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 [[ ! -f "$MANIFEST" ]]; then
+  if [[ "$FORCE" == "1" ]]; then
+    printf 'No install manifest found; performing legacy forced uninstall.\n' >&2
+    legacy_force_uninstall
+    exit 0
+  fi
+  printf 'No install manifest found at %s.\n' "$MANIFEST" >&2
+  printf 'Refusing to remove unknown files. Re-run with --force for a legacy uninstall.\n' >&2
+  exit 1
+fi
+
+failures=0
+while IFS=$'\t' read -r entry_type recorded_checksum path; do
+  [[ -n "${entry_type:-}" ]] || continue
+  case "$entry_type" in
+    file)
+      [[ -e "$path" ]] || continue
+      if [[ "$FORCE" != "1" ]]; then
+        current_checksum="$(checksum_file "$path" 2>/dev/null || true)"
+        if [[ -z "$current_checksum" || "$current_checksum" != "$recorded_checksum" ]]; then
+          printf 'Leaving modified file in place: %s (use --force to remove)\n' "$path" >&2
+          failures=1
+          continue
+        fi
+      fi
+      run rm -f "$path"
+      ;;
+    agents_block)
+      if ! strip_agents_block; then
+        failures=1
+      fi
+      ;;
+  esac
+done < "$MANIFEST"
+
+run rmdir "$HOME/.agents/skills/colleague/agents" 2>/dev/null || true
+run rmdir "$HOME/.agents/skills/colleague" 2>/dev/null || true
+run rmdir "$HOME/.claude/skills/colleague" 2>/dev/null || true
+run rmdir "$HOME/.codex/prompts" 2>/dev/null || true
+
+if [[ "$failures" == "0" ]]; then
+  run rm -f "$MANIFEST"
+  run rmdir "$STATE_DIR" 2>/dev/null || true
+  echo "Removed files tracked by the ask-colleague install manifest."
+else
+  echo "Uninstall incomplete because one or more tracked files were modified or could not be safely removed." >&2
+  exit 1
+fi