@heart-of-gold/toolkit 0.1.9 → 0.1.11

package/README.md

@@ -2,7 +2,7 @@
 
 > **Don't Panic.**
 
-25 skills for AI coding agents. Five plugins. Works with **Claude Code, Codex, OpenCode, Pi**, and any tool supporting the [agentskills.io](https://agentskills.io) standard. Named after *The Hitchhiker's Guide to the Galaxy* because the universe is absurd and your tools should at least have personality.
+29 skills for AI coding agents. Five plugins. Works with **Claude Code, Codex, OpenCode, Pi**, and any tool supporting the [agentskills.io](https://agentskills.io) standard. Named after *The Hitchhiker's Guide to the Galaxy* because the universe is absurd and your tools should at least have personality.
 
 ## Installation
 
@@ -107,13 +107,14 @@ Your personal content engine.
 
 Configurable sources (RSS, Gmail, HN, web search), narrative briefs, LinkedIn drafts, blog outlines, voice fidelity checking, iMessage delivery, and two-way captures.
 
-6 skills · 2 agents · 4 scripts
+7 skills · 2 agents · 5 scripts
 
 ```
 /guide:setup       # configure your sources, themes, and voice
 /guide:pipeline    # run the full content engine
 /guide:capture     # morning/evening thought capture
 /guide:write-post  # guided blog writing (7 phases)
+/guide:claude-code # Claude Code CLI guidance
 /guide:codex       # Codex CLI guidance
 /guide:gemini      # Gemini CLI guidance
 ```

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@heart-of-gold/toolkit",
-  "version": "0.1.9",
+  "version": "0.1.11",
   "type": "module",
   "description": "Cross-platform installer for Heart of Gold skills — works with Codex, OpenCode, Pi, Claude Code, and more",
   "bin": {
@@ -59,6 +59,7 @@
       "./plugins/deep-thought/skills/review",
       "./plugins/deep-thought/skills/think",
       "./plugins/guide/skills/capture",
+      "./plugins/guide/skills/claude-code",
       "./plugins/guide/skills/codex",
       "./plugins/guide/skills/gemini",
       "./plugins/guide/skills/pipeline",

package/plugins/guide/README.md

@@ -73,6 +73,12 @@ Guided blog writing in seven phases:
 
 Can pick up blog outlines generated by the pipeline (`needs_write_post: true` in frontmatter).
 
+### /guide:claude-code
+
+Headless Claude Code handoff for second opinions, code review, targeted analysis, or follow-up on a bounded task.
+
+Use it when you want another agent harness to invoke Claude Code non-interactively, capture the result, and summarize it back. The skill ships with a small wrapper script that standardizes `claude -p` / resume usage across installs.
+
 ## How the Pipeline Works
 
 ```

package/plugins/guide/skills/claude-code/SKILL.md

@@ -0,0 +1,118 @@
+---
+name: claude-code
+description: Use when the user asks to run Claude Code CLI (`claude`, `claude resume`) or asks for a second opinion, review, analysis, refactor, or follow-up specifically from Claude Code.
+---
+
+# Claude Code CLI Skill Guide
+
+## Available Models
+
+| Model | Best for |
+| --- | --- |
+| `sonnet` | Default recommendation for most coding, review, and analysis tasks |
+| `opus` | Stronger reasoning for ambiguous or high-stakes reviews |
+| `haiku` | Faster and cheaper for lightweight follow-ups |
+
+Default recommendation: `sonnet` for most tasks, `opus` when depth matters more than speed.
+
+## Running a Task
+1. Ask the user which model to use (default: `sonnet`) AND which permission mode to use (`plan`, `acceptEdits`, `default`, `auto`, or `bypassPermissions`) in a single prompt when both matter.
+2. Default to `--permission-mode plan` for reviews, read-only analysis, and second opinions.
+3. Assemble the command with the appropriate options:
+   - `-p, --print` for non-interactive output
+   - `--output-format <text|json|stream-json>`
+   - `--model <MODEL>`
+   - `--permission-mode <MODE>`
+   - `--effort <low|medium|high|max>`
+   - `--add-dir <DIR>` when Claude Code must read outside the current working directory
+   - `"your prompt here"` as the final positional argument
+4. Prefer `--output-format text` unless the caller explicitly needs JSON.
+5. Run the command, capture stdout/stderr, and summarize the outcome for the user.
+6. After Claude Code completes, tell the user they can resume by asking for `claude resume` or another Claude Code follow-up.
+
+### Quick Reference
+| Use case | Permission mode | Key flags |
+| --- | --- | --- |
+| Read-only review or analysis | `plan` | `-p --output-format text --permission-mode plan` |
+| Apply local edits | `acceptEdits` | `-p --output-format text --permission-mode acceptEdits` |
+| Stronger review pass | `plan` | `--model opus --effort high` |
+| Resume recent session | Inherited | `-r latest -p "new prompt" --output-format text` |
+
+## Recommended Commands
+
+### Review the current diff
+
+```bash
+claude -p \
+  --output-format text \
+  --model sonnet \
+  --permission-mode plan \
+  --effort medium \
+  "Review the current git diff. Return findings ordered by severity with file paths and concise explanations."
+```
+
+### Review a specific file
+
+```bash
+claude -p \
+  --output-format text \
+  --model sonnet \
+  --permission-mode plan \
+  --effort high \
+  "Review src/server.ts for correctness, regressions, and missing tests. Keep the response concise."
+```
+
+### Continue the latest Claude Code session
+
+```bash
+claude -r latest -p \
+  --output-format text \
+  "Focus only on the migration risk you mentioned. What is the safest rollout plan?"
+```
+
+## Optional Wrapper
+
+This skill also ships a convenience wrapper at `scripts/run-claude-code.sh`.
+
+Use it only as a thin helper around the direct `claude` commands above:
+
+- `scripts/run-claude-code.sh --check` verifies that Claude Code is installed
+- `scripts/run-claude-code.sh --prompt "..." --permission-mode plan` mirrors the direct CLI usage
+
+Prefer the direct `claude` commands in this document when debugging, because they are easier to inspect and adapt.
+
+## Following Up
+
+- After every Claude Code command, confirm whether the user wants a follow-up, a resume, or a different model / permission mode.
+- When resuming, keep the new prompt narrow instead of restating the whole task.
+- Restate the chosen model, effort, and permission mode when proposing a retry.
+
+## Critical Evaluation of Claude Code Output
+
+Claude Code is a colleague, not an authority.
+
+### Guidelines
+- Trust your own knowledge when confident.
+- Push back if Claude Code makes a claim that conflicts with the code or docs in front of you.
+- Research disagreements before accepting them for high-impact decisions.
+- Do not defer blindly on models, tool flags, or fast-moving best practices.
+
+### When Claude Code Seems Wrong
+1. State the disagreement clearly to the user.
+2. Provide evidence from the codebase, documentation, or your own verification.
+3. Optionally resume the Claude Code session with a corrective prompt:
+
+```bash
+claude -r latest -p \
+  --output-format text \
+  "I disagree with your earlier conclusion because [evidence]. Re-evaluate only that point."
+```
+
+4. Treat the exchange as a discussion, not a correction ritual.
+
+## Error Handling
+
+- Stop and report failures whenever `claude --version` or a `claude -p` command exits non-zero.
+- If Claude Code reports permission issues, retry only after choosing the correct `--permission-mode`.
+- Do not use `bypassPermissions` unless the user explicitly approves it.
+- If debugging a failing wrapper invocation, fall back to the direct `claude` command first.

package/plugins/guide/skills/claude-code/scripts/run-claude-code.sh

@@ -0,0 +1,142 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+usage() {
+  cat <<'EOF'
+Usage:
+  run-claude-code.sh --check
+  run-claude-code.sh --prompt "..." [options]
+
+Options:
+  --check                       Verify that Claude Code is installed
+  --prompt TEXT                 Prompt to send to Claude Code
+  --model MODEL                 Claude model or alias (default: sonnet)
+  --permission-mode MODE        plan, acceptEdits, default, auto, dontAsk, bypassPermissions
+  --effort LEVEL                low, medium, high, max
+  --output-format FORMAT        text, json, stream-json (default: text)
+  --resume VALUE                Resume a session, for example: latest
+  --continue                    Continue the most recent session in the current directory
+  --add-dir PATH                Additional directory to allow tool access to; repeatable
+  --cwd PATH                    Working directory to run Claude Code from
+  --help                        Show this help text
+EOF
+}
+
+check_only=0
+prompt=""
+model="sonnet"
+permission_mode=""
+effort=""
+output_format="text"
+resume_value=""
+continue_mode=0
+cwd=""
+declare -a add_dirs=()
+
+while [[ $# -gt 0 ]]; do
+  case "$1" in
+    --check)
+      check_only=1
+      shift
+      ;;
+    --prompt)
+      [[ $# -ge 2 ]] || { echo "Missing value for --prompt" >&2; exit 2; }
+      prompt="$2"
+      shift 2
+      ;;
+    --model)
+      [[ $# -ge 2 ]] || { echo "Missing value for --model" >&2; exit 2; }
+      model="$2"
+      shift 2
+      ;;
+    --permission-mode)
+      [[ $# -ge 2 ]] || { echo "Missing value for --permission-mode" >&2; exit 2; }
+      permission_mode="$2"
+      shift 2
+      ;;
+    --effort)
+      [[ $# -ge 2 ]] || { echo "Missing value for --effort" >&2; exit 2; }
+      effort="$2"
+      shift 2
+      ;;
+    --output-format)
+      [[ $# -ge 2 ]] || { echo "Missing value for --output-format" >&2; exit 2; }
+      output_format="$2"
+      shift 2
+      ;;
+    --resume)
+      [[ $# -ge 2 ]] || { echo "Missing value for --resume" >&2; exit 2; }
+      resume_value="$2"
+      shift 2
+      ;;
+    --continue)
+      continue_mode=1
+      shift
+      ;;
+    --add-dir)
+      [[ $# -ge 2 ]] || { echo "Missing value for --add-dir" >&2; exit 2; }
+      add_dirs+=("$2")
+      shift 2
+      ;;
+    --cwd)
+      [[ $# -ge 2 ]] || { echo "Missing value for --cwd" >&2; exit 2; }
+      cwd="$2"
+      shift 2
+      ;;
+    --help|-h)
+      usage
+      exit 0
+      ;;
+    *)
+      echo "Unknown argument: $1" >&2
+      usage >&2
+      exit 2
+      ;;
+  esac
+done
+
+if [[ "$check_only" -eq 1 ]]; then
+  exec claude --version
+fi
+
+if [[ -z "$prompt" ]]; then
+  echo "--prompt is required unless --check is used" >&2
+  exit 2
+fi
+
+if [[ -n "$resume_value" && "$continue_mode" -eq 1 ]]; then
+  echo "--resume and --continue cannot be used together" >&2
+  exit 2
+fi
+
+cmd=(claude)
+
+if [[ -n "$resume_value" ]]; then
+  cmd+=(-r "$resume_value")
+elif [[ "$continue_mode" -eq 1 ]]; then
+  cmd+=(-c)
+fi
+
+cmd+=(--print --output-format "$output_format" --model "$model")
+
+if [[ -n "$permission_mode" ]]; then
+  cmd+=(--permission-mode "$permission_mode")
+fi
+
+if [[ -n "$effort" ]]; then
+  cmd+=(--effort "$effort")
+fi
+
+if ((${#add_dirs[@]} > 0)); then
+  for dir in "${add_dirs[@]}"; do
+    cmd+=(--add-dir "$dir")
+  done
+fi
+
+cmd+=("$prompt")
+
+if [[ -n "$cwd" ]]; then
+  cd "$cwd"
+fi
+
+exec "${cmd[@]}"

package/src/index.ts

@@ -7,7 +7,7 @@ import { targetsCommand } from "./commands/targets";
 const main = defineCommand({
   meta: {
     name: "heart-of-gold",
-    version: "0.1.3",
+    version: "0.1.11",
     description:
       "Cross-platform installer for Heart of Gold skills — Codex, OpenCode, Pi, Claude Code, and more",
   },

package/src/utils/transform.ts

@@ -9,6 +9,7 @@ const CODEX_COMMAND_ALIASES: Record<string, string> = {
   "/brainstorm": "$brainstorm",
   "/capture": "$capture",
   "/coach": "$coach",
+  "/claude-code": "$claude-code",
   "/codex": "$codex",
   "/compound": "$compound",
   "/craft-skill": "$craft-skill",
@@ -26,6 +27,7 @@ const CODEX_COMMAND_ALIASES: Record<string, string> = {
   "/goal-checkin": "$goal-checkin",
   "/goal-setting": "$goal-setting",
   "/guide:capture": "$capture",
+  "/guide:claude-code": "$claude-code",
   "/guide:codex": "$codex",
   "/guide:gemini": "$gemini",
   "/guide:pipeline": "$pipeline",