@heart-of-gold/toolkit 0.1.9 → 0.1.10

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.10",
   "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
+
+Use this skill to hand a bounded task to Claude Code from the current harness, capture the output, and summarize it back to the user.
+
+## Defaults
+
+- Default model: `sonnet`
+- Default permission mode for review or analysis: `plan`
+- Default permission mode for requested edits: `acceptEdits`
+- Default effort: `medium`
+
+Prefer the harness's structured question UI when available; otherwise ask plainly in text and wait for the answer before continuing.
+
+## Running a Task
+
+1. Ask the user which model to use if they care. Default to `sonnet`.
+2. Ask for permission mode only when it materially affects safety:
+   - `plan` for review, analysis, and read-only second opinions
+   - `acceptEdits` when the user explicitly wants Claude Code to make local changes
+   - `bypassPermissions` only with explicit user approval
+3. Resolve the bundled runner relative to this skill:
+   - `scripts/run-claude-code.sh`
+4. Build a concrete prompt for Claude Code. For review requests, include scope and output shape:
+   - Ask for findings ordered by severity
+   - Ask for file paths in each finding
+   - Ask for a short final verdict
+5. Run the bundled script:
+
+```bash
+bash <skill-dir>/scripts/run-claude-code.sh \
+  --prompt "<PROMPT>" \
+  --model <MODEL> \
+  --permission-mode <MODE> \
+  --effort <EFFORT>
+```
+
+6. Capture stdout and summarize the result for the user.
+7. If the user wants a follow-up, resume the latest Claude Code session instead of starting from scratch:
+
+```bash
+bash <skill-dir>/scripts/run-claude-code.sh \
+  --resume latest \
+  --prompt "<FOLLOW_UP_PROMPT>" \
+  --model <MODEL> \
+  --permission-mode <MODE> \
+  --effort <EFFORT>
+```
+
+## Quick Reference
+
+| Use case | Permission mode | Suggested prompt shape |
+| --- | --- | --- |
+| Read-only code review | `plan` | "Review the current diff and return findings ordered by severity with file paths." |
+| Architecture second opinion | `plan` | "Assess this design and name the top risks, tradeoffs, and missing tests." |
+| Targeted implementation | `acceptEdits` | "Implement X, keep changes minimal, and explain what changed." |
+| Continue prior thread | prior mode | Resume with a narrow follow-up prompt instead of restating everything |
+
+## Prompting Guidance
+
+- Keep prompts bounded. Claude Code performs better when the scope is explicit.
+- Name the artifact under review: current diff, specific files, or a directory.
+- For reviews, ask for bugs, regressions, missing tests, and risky assumptions first.
+- For implementation requests, specify what must not change.
+- If you disagree with the result, treat Claude Code as a colleague and challenge it with evidence.
+
+## Examples
+
+### Review the current diff
+
+```bash
+bash <skill-dir>/scripts/run-claude-code.sh \
+  --prompt "Review the current git diff. Return only findings, ordered by severity, with file paths and concise explanations." \
+  --model sonnet \
+  --permission-mode plan \
+  --effort medium
+```
+
+### Ask Claude Code to inspect a single file
+
+```bash
+bash <skill-dir>/scripts/run-claude-code.sh \
+  --prompt "Review src/server.ts for correctness, edge cases, and missing tests. Keep the response concise." \
+  --model sonnet \
+  --permission-mode plan \
+  --effort high
+```
+
+### Continue the latest Claude Code session
+
+```bash
+bash <skill-dir>/scripts/run-claude-code.sh \
+  --resume latest \
+  --prompt "Focus only on the migration risk you mentioned. What is the safest rollout plan?" \
+  --model sonnet \
+  --permission-mode plan \
+  --effort medium
+```
+
+## Script
+
+Use the bundled runner instead of assembling `claude` commands ad hoc:
+
+- `scripts/run-claude-code.sh --check` verifies that Claude Code is installed
+- `scripts/run-claude-code.sh --help` prints usage
+
+The wrapper keeps flag handling deterministic and portable when this skill is installed into Codex, Pi, or other agent harnesses.
+
+## Error Handling
+
+- Stop and report failures when `claude --version` or the runner exits non-zero.
+- If Claude Code is missing, tell the user to install or authenticate Claude Code before retrying.
+- If output is partial or Claude reports permission issues, summarize that clearly and ask whether to retry with a different permission mode.
+- Do not use `bypassPermissions` unless the user explicitly approves it.

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

@@ -0,0 +1,140 @@
+#!/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=""
+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
+
+for dir in "${add_dirs[@]}"; do
+  cmd+=(--add-dir "$dir")
+done
+
+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.10",
     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",