@heart-of-gold/toolkit 0.1.16 → 0.1.18

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@heart-of-gold/toolkit",
-  "version": "0.1.16",
+  "version": "0.1.18",
   "type": "module",
   "description": "Cross-platform installer for Heart of Gold skills — works with Codex, OpenCode, Pi, Claude Code, and more",
   "bin": {

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

@@ -7,9 +7,16 @@ description: Use when the user asks to run Claude Code CLI (`claude`, `claude re
 
 Use this skill to hand a bounded task to Claude Code from the current harness, capture the result, and summarize it back to the user.
 
-This skill is task-based, not review-only. Use `plan` for safe read-only analysis, but use other permission modes when the task requires command execution or edits.
+This skill is task-based, not review-only. Anthropic's `plan` mode is a read-only analysis mode, but because Claude Code frames it as "Plan Mode," do not treat it as the default for reviews. Prefer `default` for normal reviews and `acceptEdits` for implementation work unless you specifically want strict read-only behavior.
 
-The canonical execution path is direct `claude` CLI usage, mirroring the `codex` skill's direct `codex exec` pattern. The bundled wrapper is optional and must not replace the direct path unless the user explicitly asks for it or you are debugging Claude Code invocation behavior itself.
+The canonical execution path is direct `claude` CLI usage, mirroring the `codex` skill's direct `codex exec` pattern. Keep the workflow simple:
+
+- Ask which model to use.
+- Run one direct `claude` command.
+- If it works, summarize Claude's output.
+- If it fails or hangs, report that clearly and stop.
+
+Do not turn a failed Claude run into an improvised shell pipeline, background polling loop, or manual artifact-concatenation workaround unless the user explicitly asks for that style of invocation.
 
 ## Available Models
 
@@ -31,19 +38,19 @@ Choose the permission mode based on what Claude Code needs to do:
 
 | Mode | Use when | Notes |
 | --- | --- | --- |
-| `plan` | The task is read-only and Claude does not need to execute commands or edit files | Safest option for reviewing provided diffs, logs, file contents, or design docs |
+| `plan` | You explicitly want strict read-only analysis with no command execution or edits | Best for exploration, planning, or artifact-only analysis; not the default recommendation for review |
 | `default` | Claude may need to inspect the repo more freely and you can tolerate permission prompts | Good interactive default; less reliable in headless automation unless permissions are pre-arranged |
 | `acceptEdits` | Claude should be able to make local code changes | Strong default for implementation, refactors, and fixes |
 | `bypassPermissions` | Full automation is required in a trusted sandbox and the user explicitly approves it | High risk; do not default to this |
 
-`plan` is not the general default for this skill. It is only the safe default for bounded read-only tasks.
+`plan` is not the general default for this skill. Use it only when you specifically want Claude in strict read-only analysis mode.
 
 ## Running a Task
 1. Always ask the user which model alias to use (default: `sonnet`) before running Claude Code, unless the user already specified the model.
 2. Ask for permission mode in the same prompt when the user did not specify it. Default to:
-   - `plan` for bounded read-only analysis
+   - `default` for reviews and analysis
    - `acceptEdits` for implementation or refactoring work
-   - `default` when Claude needs broader repo exploration without auto-edit authority
+   - `plan` only when the user explicitly wants strict read-only analysis
 3. Decide whether Claude should receive the artifact directly or discover it itself:
    - Pass diffs, logs, or file contents via stdin for safe read-only review
    - Let Claude inspect the working tree when the task requires tool use
@@ -60,11 +67,12 @@ Choose the permission mode based on what Claude Code needs to do:
    - `"your prompt here"` as the final positional argument
 5. Prefer `--output-format text` for human-readable summaries and `--output-format json` for automation or machine parsing.
 6. In headless automation, prefer explicit permissions:
-   - `plan` for provided artifacts
+   - `default` for most review and analysis runs
    - `acceptEdits` for edit-capable runs
-   - `default` only when prompts are acceptable or when permissions are constrained with `--allowedTools`
+   - `plan` only when you specifically want read-only analysis with no command execution
 7. Run the command, capture stdout/stderr, and summarize the outcome for the user.
 8. If Claude Code does not actually return output, stop and report that failure. Do not substitute your own review or analysis and present it as if it came from Claude Code.
+9. Do not add fallback layers automatically. One direct Claude attempt is the normal path. A retry is acceptable only when the user asks for it or when you have a concrete reason to change one thing, such as model, permission mode, or execution environment.
 
 ## Codex Execution
 
@@ -84,29 +92,44 @@ When this skill is used from Codex, the skill cannot bypass Codex sandbox policy
 - Use `--max-turns` for automation. It keeps review and implementation runs bounded.
 - Use `--output-format json` when another agent or script needs structured output.
 - Use `--allowedTools` to make headless runs more reliable and safer.
-- Pipe diffs or logs into Claude for read-only analysis instead of asking Claude to execute shell commands just to fetch them.
+- Prefer letting Claude inspect the repo directly for normal review and implementation tasks.
+- Pass diffs or logs via stdin only when the user explicitly wants artifact-only review or when direct repo access is intentionally unavailable.
 - Use `acceptEdits` for real implementation work; do not force read-only `plan` mode onto edit tasks.
 - Use `bypassPermissions` only in a trusted sandbox and only with explicit user approval.
 - Use `-r latest -p` for follow-up instead of re-explaining the entire task.
+- Avoid giant `cat file1 file2 ... | claude ...` constructions as a default strategy. They are brittle, hard to inspect, and a poor substitute for direct Claude access to the repo.
 
 ## Recommended Patterns
 
-### 1. Review a provided diff safely
+### 1. Review the repo directly
 
-Pass the diff via stdin and keep Claude in `plan` mode:
+Use this as the normal review path:
+
+```bash
+claude -p \
+  --output-format text \
+  --model sonnet \
+  --permission-mode default \
+  --max-turns 4 \
+  "Review how the workshop skill is designed in this repo and whether it should be improved. Return findings ordered by severity."
+```
+
+### 2. Review a provided diff only
+
+Use stdin only when you intentionally want a bounded artifact review:
 
 ```bash
 git diff --staged | claude -p \
   --output-format text \
   --model sonnet \
-  --permission-mode plan \
+  --permission-mode default \
   --max-turns 1 \
   "Review this diff. Return findings ordered by severity with file paths and concise explanations."
 ```
 
-### 2. Ask Claude to inspect the repo and analyze
+### 3. Ask Claude to inspect the repo and analyze with tighter tool bounds
 
-Use `default` or a constrained tool set when Claude needs to discover context itself:
+Use this when Claude should inspect the repo but you want tighter limits:
 
 ```bash
 claude -p \
@@ -118,7 +141,7 @@ claude -p \
   "Analyze the current changes and explain the main design risks."
 ```
 
-### 3. Ask Claude to implement or refactor
+### 4. Ask Claude to implement or refactor
 
 Use `acceptEdits` when Claude should change files:
 
@@ -132,7 +155,7 @@ claude -p \
   "Implement the requested change in the current repo, keep the diff minimal, and summarize what changed."
 ```
 
-### 4. Resume the latest Claude Code session
+### 5. Resume the latest Claude Code session
 
 ```bash
 claude -r latest -p \
@@ -140,17 +163,30 @@ claude -r latest -p \
   "Focus only on the migration risk you mentioned earlier. What is the safest rollout plan?"
 ```
 
-### 5. Request structured output for automation
+### 6. Request structured output for automation
 
 ```bash
 claude -p \
   --output-format json \
   --model sonnet \
-  --permission-mode plan \
+  --permission-mode default \
   --max-turns 1 \
   "Summarize the provided diff as JSON with keys: verdict, findings, risks."
 ```
 
+### 7. Use strict read-only analysis mode explicitly
+
+Use `plan` only when you want Claude prevented from executing commands or editing files:
+
+```bash
+git diff --staged | claude -p \
+  --output-format text \
+  --model sonnet \
+  --permission-mode plan \
+  --max-turns 1 \
+  "Analyze this diff and explain the key risks. Keep the response concise."
+```
+
 ## Optional Wrapper
 
 This skill also ships a convenience wrapper at `scripts/run-claude-code.sh`.
@@ -220,3 +256,4 @@ claude -r latest -p \
 - In Codex, if the likely cause is sandboxing or network denial, rerun with reviewer-approved `require_escalated` execution instead of repeatedly retrying the same sandboxed command.
 - Do not use `bypassPermissions` unless the user explicitly approves it.
 - If the direct `claude` path fails, report that failure directly. Do not route around it by pretending a wrapper run or a self-authored review is equivalent to Claude output.
+- Do not automatically fall back to concatenating many files into stdin just because a direct Claude run failed once.

package/src/index.ts

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