saving-token 0.1.0

package/README.md

@@ -0,0 +1,63 @@
+# saving-token
+
+A native writer makes file changes; the parent agent decides and reviews. You choose the writer model during setup. The parent model and global defaults stay unchanged.
+
+Inspired by [karpathy-guidelines](https://github.com/multica-ai/andrej-karpathy-skills). Delegation aims to reduce parent-context output; extra context and retries can increase total tokens.
+
+## Install
+
+### Codex via npm (after publication)
+
+After the package is published to npm, run:
+
+```bash
+npx saving-token@latest install --agent codex
+```
+
+This interactively prompts you to choose a writer model and optional reasoning effort, then asks you to confirm installation.
+
+### Manual / multi-platform
+
+```bash
+bash skills/saving-token/scripts/setup.sh
+```
+
+Choose **platform → model → optional reasoning effort → confirm**. The model menu offers a few suggestions and a custom ID option, with no default selection. Suggestions do not verify account availability. Leave effort blank to use the host's default behavior.
+
+| Platform | Skill location | Writer configuration |
+|---|---|---|
+| Codex | `${CODEX_HOME:-~/.codex}/skills/saving-token/` | `${CODEX_HOME:-~/.codex}/agents/saving-token-writer.toml` |
+| Claude Code | `~/.claude/skills/saving-token/` | `~/.claude/agents/saving-token-writer.md` |
+| Cursor | `~/.cursor/skills/saving-token/` | `~/.cursor/agents/saving-token-writer.md` |
+
+Restart the host, then invoke `$saving-token` in Codex or `/saving-token` in standalone Claude Code and Cursor. Automatic Skill discovery remains available. Verify the writer model in runtime task metadata when exposed; generated configuration alone does not prove routing. Claude Code and Cursor may substitute a model under account or administrator policy.
+
+To automate an already approved installation:
+
+```bash
+bash skills/saving-token/scripts/setup.sh --target codex --model '<model-id>' --yes
+```
+
+`--target` and `--model` are required without a terminal. Add `--reasoning-effort <effort>` only if supported by the selected model. Explicit `--model` skips the menu; `--yes` approves installation and displayed replacements, without choosing a model.
+
+Rerun setup to change the writer model. Existing distributed Skill files and the writer configuration are replaced after confirmation; extra files in the Skill directory are preserved. Setup also works from the installed Skill's `scripts/setup.sh`.
+
+## Claude Code plugin
+
+```text
+/plugin marketplace add JerryWu1234/saving-token
+/plugin install saving-token@saving-token
+```
+
+Claude's plugin configuration collects the required `writer_model` as text; it does not use the script's menu. The plugin leaves reasoning effort to the host. Invoke `/saving-token:saving-token`; its writer is `saving-token:saving-token-writer`. Change the model through plugin configuration, then reload the session. Use either the plugin or standalone installation.
+
+## Structure
+
+- [`skills/saving-token/SKILL.md`](skills/saving-token/SKILL.md): canonical delegation and review rules.
+- `skills/saving-token/scripts/setup.sh` and `assets/`: standalone installer and native agent templates.
+- `agents/` and `.claude-plugin/`: Claude plugin writer and marketplace metadata.
+- `AGENTS.md`, `CLAUDE.md`, [`CURSOR.md`](CURSOR.md), and `.cursor/rules/`: repository adapters that point to the Skill.
+
+Other hosts can read the Skill or `AGENTS.md`, but delegation requires writable native subagents and independent model configuration. Without those capabilities, support is instruction-only.
+
+Official references: [Codex subagents](https://developers.openai.com/codex/subagents), [Claude subagents](https://code.claude.com/docs/en/sub-agents), [Claude plugins](https://code.claude.com/docs/en/plugins-reference), [Cursor subagents](https://cursor.com/docs/subagents), [Agent Skills](https://agentskills.io/specification).

package/bin/saving-token.cjs

@@ -0,0 +1,36 @@
+#!/usr/bin/env node
+'use strict';
+
+const path = require('node:path');
+const { spawnSync } = require('node:child_process');
+
+const args = process.argv.slice(2);
+
+if (
+  args.length !== 3 ||
+  args[0] !== 'install' ||
+  args[1] !== '--agent' ||
+  args[2] !== 'codex'
+) {
+  console.error('Usage: saving-token install --agent codex');
+  process.exit(1);
+}
+
+const setupPath = path.join(
+  __dirname,
+  '..',
+  'skills',
+  'saving-token',
+  'scripts',
+  'setup.sh'
+);
+const result = spawnSync('bash', [setupPath, '--target', 'codex'], {
+  stdio: 'inherit'
+});
+
+if (result.error) {
+  console.error(`Failed to start bash: ${result.error.message}`);
+  process.exit(1);
+}
+
+process.exit(result.status === null ? 1 : result.status);

package/package.json

@@ -0,0 +1,14 @@
+{
+  "name": "saving-token",
+  "version": "0.1.0",
+  "bin": {
+    "saving-token": "bin/saving-token.cjs"
+  },
+  "files": [
+    "bin/saving-token.cjs",
+    "skills/saving-token"
+  ],
+  "engines": {
+    "node": ">=18"
+  }
+}

package/skills/saving-token/SKILL.md

@@ -0,0 +1,41 @@
+---
+name: saving-token
+description: Delegate file changes to a user-configured writer subagent while the parent agent directs and reviews. Use for code, script, and document edits or generation.
+---
+
+# Saving Token
+
+The parent directs and reviews; a native writer implements and verifies.
+If your identity is `saving-token-writer` or `saving-token:saving-token-writer`, implement directly and never delegate again. The remaining rules are parent-only.
+
+## Configure
+
+- Use `saving-token-writer` on Codex, standalone Claude Code, or Cursor; use `saving-token:saving-token-writer` for the Claude plugin.
+- When setup is requested or the writer is missing, collect the platform and the user's model choice. Reasoning effort is optional and must be supported by that model.
+- With installation approval, run the bundled `scripts/setup.sh`. It offers platform/model selection and previews replacements before confirmation. For automation, pass `--target <codex|claude|cursor> --model <id>`, optionally `--reasoning-effort <effort>`, and `--yes` only after approval. Do not generate substitute setup code.
+- The Claude plugin collects `writer_model` through plugin configuration and leaves effort to the host. Do not install a duplicate standalone writer.
+- Running the approved setup script is the only parent-side write exception. Preserve the parent model and global subagent defaults.
+- If a writable native writer or independent model configuration is unavailable, report instruction-only compatibility and ask before implementing directly.
+- Configuration is not runtime proof. Check exposed model metadata and disclose mismatches; never silently substitute a model yourself. Claude Code and Cursor may apply host-level fallback.
+
+## Delegate
+
+- Delegate every file write, including edits, deletions, documents, temporary scripts, and formatting.
+- Give goals and acceptance criteria, not implementation text to paste. Prefer file paths and issue locations over copied source or conversation history.
+- Batch related changes into one scoped task and reuse the writer for revisions.
+- The writer follows project rules and authorization boundaries, preserves user edits, implements directly, and runs relevant checks.
+
+```text
+Goal: <expected behavior>
+Scope: <paths; prohibited changes>
+Verify: <acceptance criteria and checks>
+Return: changed paths; check results; blockers.
+```
+
+## Accept
+
+- Inspect the actual diff, new files, and check evidence; never accept from the writer summary alone.
+- Send remaining defects and acceptance conditions to the same writer, then review again. Stop and report blockers or repeated failures without progress.
+- Report the outcome, verification, and material routing uncertainty concisely. Keep full logs in files when needed.
+
+Delegation aims to reduce parent-context output; a second context and retries can increase total token usage.

package/skills/saving-token/assets/claude/saving-token-writer.md.template

@@ -0,0 +1,15 @@
+---
+name: saving-token-writer
+description: Implement file changes delegated by the saving-token Skill and run verification.
+model: "__WRITER_MODEL__"
+effort: "__REASONING_EFFORT__"
+disallowedTools:
+  - Agent
+---
+
+# Saving Token Writer
+
+Implement directly. Never delegate or invoke another subagent.
+Follow project rules and authorization boundaries, and preserve existing user edits.
+Make only the requested changes and run the requested checks.
+Return changed paths, check commands and results, and blockers only.

package/skills/saving-token/assets/codex/saving-token-writer.toml.template

@@ -0,0 +1,11 @@
+name = "saving-token-writer"
+description = "Implement file changes delegated by the saving-token Skill and run verification."
+model = "__WRITER_MODEL__"
+model_reasoning_effort = "__REASONING_EFFORT__"
+
+developer_instructions = """
+Implement directly. Do not delegate further.
+Follow project rules and preserve existing user edits.
+Run the requested checks.
+Return changed paths, check results, and blockers only.
+"""

package/skills/saving-token/assets/cursor/saving-token-writer.md.template

@@ -0,0 +1,14 @@
+---
+name: saving-token-writer
+description: Implement file changes delegated by the saving-token Skill and run verification.
+model: "__WRITER_MODEL__"
+readonly: false
+is_background: false
+---
+
+# Saving Token Writer
+
+Implement directly. Never delegate or invoke another subagent.
+Follow project rules and authorization boundaries, and preserve existing user edits.
+Make only the requested changes and run the requested checks.
+Return changed paths, check commands and results, and blockers only.

package/skills/saving-token/scripts/setup.sh

@@ -0,0 +1,184 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+fail() { printf 'Error: %s\n' "$*" >&2; exit 1; }
+
+usage() {
+  cat <<'HELP'
+Usage: setup.sh [--target codex|claude|cursor] [--model ID]
+                [--reasoning-effort EFFORT] [--yes]
+
+Choose a platform and writer model, preview, then confirm installation.
+  --target PLATFORM          Prompted when omitted; required without a terminal.
+  --model ID                 Skip the model menu; required without a terminal.
+  --reasoning-effort EFFORT   Optional. Omit to use the host's default behavior.
+  --yes                      Approve installation and displayed replacements.
+  -h, --help                 Show this help.
+
+Model suggestions are not an account availability check. Use only models and
+reasoning efforts supported by your host and account. --yes never picks a model.
+HELP
+}
+
+SCRIPT_DIR="$(cd -- "$(dirname -- "${BASH_SOURCE[0]}")" && pwd -P)"
+SKILL_SOURCE="$(cd -- "$SCRIPT_DIR/.." && pwd -P)"
+target=''
+writer_model=''
+reasoning_effort=''
+model_was_set=false
+effort_was_set=false
+assume_yes=false
+
+while [[ $# -gt 0 ]]; do
+  case "$1" in
+    --target|--model|--reasoning-effort)
+      [[ $# -ge 2 && -n "$2" && "$2" != -* ]] || fail "$1 requires a value."
+      case "$1" in
+        --target) target=$2 ;;
+        --model) writer_model=$2; model_was_set=true ;;
+        --reasoning-effort) reasoning_effort=$2; effort_was_set=true ;;
+      esac
+      shift 2 ;;
+    --yes) assume_yes=true; shift ;;
+    -h|--help) usage; exit 0 ;;
+    *) fail "Unknown option: $1" ;;
+  esac
+done
+
+[[ -n "${HOME:-}" ]] || fail 'HOME is not set.'
+if [[ -z "$target" ]]; then
+  [[ -t 0 ]] || fail 'Pass --target in non-interactive use.'
+  IFS= read -r -p 'Platform: 1) codex  2) claude  3) cursor: ' target || fail 'No platform selected.'
+  case "$target" in 1) target=codex ;; 2) target=claude ;; 3) target=cursor ;; esac
+fi
+
+case "$target" in
+  codex)
+    codex_home="${CODEX_HOME:-$HOME/.codex}"
+    skill_target="$codex_home/skills/saving-token"
+    agent_dir="$codex_home/agents"
+    agent_file='saving-token-writer.toml'
+    models=(gpt-5.6-luna gpt-5.6-terra gpt-5.3-codex-spark)
+    ;;
+  claude)
+    skill_target="$HOME/.claude/skills/saving-token"
+    agent_dir="$HOME/.claude/agents"
+    agent_file='saving-token-writer.md'
+    models=(haiku sonnet opus)
+    ;;
+  cursor)
+    skill_target="$HOME/.cursor/skills/saving-token"
+    agent_dir="$HOME/.cursor/agents"
+    agent_file='saving-token-writer.md'
+    models=(composer-2.5 gpt-5.6-sol)
+    ;;
+  *) fail "Unsupported target '$target'. Expected codex, claude, or cursor." ;;
+esac
+
+if [[ "$model_was_set" != true ]]; then
+  [[ -t 0 ]] || fail 'Pass --model in non-interactive use.'
+  printf '\nWriter model suggestions (availability depends on your account):\n'
+  for i in "${!models[@]}"; do printf '  %s) %s\n' "$((i + 1))" "${models[$i]}"; done
+  printf '  c) Custom model ID\n  q) Cancel\n'
+  IFS= read -r -p 'Choose a model: ' choice || fail 'No model selected.'
+  case "$choice" in
+    q|Q) printf 'Installation cancelled; no files were changed.\n'; exit 0 ;;
+    c|C) IFS= read -r -p 'Writer model ID: ' writer_model || fail 'No model selected.' ;;
+    [1-3])
+      [[ "$choice" -le "${#models[@]}" ]] || fail 'Invalid model selection.'
+      writer_model=${models[$((choice - 1))]} ;;
+    *) fail 'Choose a listed number, c, or q; no model is selected by default.' ;;
+  esac
+fi
+[[ "$writer_model" =~ ^[a-zA-Z0-9][a-zA-Z0-9._:/-]*$ ]] || fail 'Model ID must be nonempty, without whitespace or parameters; use letters, digits, ., _, :, /, or -.'
+
+case "$writer_model" in
+  inherit|auto) fail 'Choose a specific writer model instead of inherit or auto.' ;;
+esac
+
+if [[ "$effort_was_set" != true && "$assume_yes" != true && -t 0 ]]; then
+  IFS= read -r -p 'Reasoning effort (Enter to omit): ' reasoning_effort || fail 'Input cancelled.'
+fi
+case "$reasoning_effort" in
+  ''|none|minimal|low|medium|high|xhigh|max|ultra) ;;
+  *) fail 'Unknown reasoning effort; use none, minimal, low, medium, high, xhigh, max, or ultra if your model supports it.' ;;
+esac
+if [[ "$target" == claude ]]; then
+  case "$reasoning_effort" in
+    ''|low|medium|high|xhigh|max) ;;
+    *) fail 'Claude effort must be low, medium, high, xhigh, or max if supported by your model.' ;;
+  esac
+fi
+
+template_path="$SKILL_SOURCE/assets/$target/$agent_file.template"
+agent_target="$agent_dir/$agent_file"
+distributed_files=(SKILL.md scripts/setup.sh assets/codex/saving-token-writer.toml.template assets/claude/saving-token-writer.md.template assets/cursor/saving-token-writer.md.template)
+for file in "${distributed_files[@]}"; do
+  [[ -f "$SKILL_SOURCE/$file" ]] || fail "Missing required Skill file: $SKILL_SOURCE/$file"
+done
+skill_source_is_target=false
+if [[ -d "$skill_target" && "$(cd -- "$skill_target" && pwd -P)" == "$SKILL_SOURCE" ]]; then
+  skill_source_is_target=true
+fi
+
+printf '\nPlatform: %s\nWriter model: %s\nReasoning effort: %s\n' "$target" "$writer_model" "${reasoning_effort:-omitted (host default)}"
+printf 'Skill target: %s\nAgent target: %s\n' "$skill_target" "$agent_target"
+printf 'The parent model and global defaults remain unchanged. Model availability and runtime routing are not verified.\n'
+if [[ "$target" != codex ]]; then
+  printf 'The host may substitute a model because of account or administrator policy.\n'
+fi
+if [[ "$skill_source_is_target" == true ]]; then
+  printf 'Running from the installed Skill; only the writer configuration will change.\n'
+elif [[ -e "$skill_target" ]]; then
+  printf 'Existing distributed Skill files will be replaced; extra files will be preserved.\n'
+fi
+[[ ! -e "$agent_target" ]] || printf 'Existing writer configuration will be replaced.\n'
+
+if [[ "$assume_yes" != true ]]; then
+  IFS= read -r -p 'Install this configuration? [y/N] ' answer || fail 'Confirmation required; use --yes after approval.'
+  case "$answer" in
+    y|Y|yes|YES|Yes) ;;
+    *) printf 'Installation cancelled; no files were changed.\n'; exit 0 ;;
+  esac
+else
+  printf 'Install this configuration? yes (--yes)\n'
+fi
+
+render_agent_config() {
+  local line model=$writer_model model_count=0 effort_count=0
+  if [[ "$target" == cursor && -n "$reasoning_effort" ]]; then
+    model+="[effort=$reasoning_effort]"
+  fi
+  while IFS= read -r line || [[ -n "$line" ]]; do
+    if [[ "$line" == *'__WRITER_MODEL__'* ]]; then
+      model_count=$((model_count + 1))
+      line=${line//__WRITER_MODEL__/$model}
+    fi
+    if [[ "$line" == *'__REASONING_EFFORT__'* ]]; then
+      effort_count=$((effort_count + 1))
+      [[ -n "$reasoning_effort" ]] || continue
+      line=${line//__REASONING_EFFORT__/$reasoning_effort}
+    fi
+    printf '%s\n' "$line"
+  done < "$template_path"
+  [[ $model_count -eq 1 ]] || fail 'Agent template must contain exactly one model placeholder.'
+  if [[ "$target" != cursor ]]; then
+    [[ $effort_count -eq 1 ]] || fail 'Agent template must contain exactly one effort placeholder.'
+  fi
+}
+
+mkdir -p "$agent_dir"
+temporary_agent="$(mktemp "$agent_dir/.${agent_file}.XXXXXX")"
+trap 'rm -f "$temporary_agent"' EXIT
+render_agent_config > "$temporary_agent"
+chmod 600 "$temporary_agent"
+if [[ "$skill_source_is_target" != true ]]; then
+  for file in "${distributed_files[@]}"; do
+    mkdir -p "$(dirname -- "$skill_target/$file")"
+    cp "$SKILL_SOURCE/$file" "$skill_target/$file"
+  done
+  chmod u+x "$skill_target/scripts/setup.sh"
+fi
+mv -f "$temporary_agent" "$agent_target"
+trap - EXIT
+printf '\nConfigured saving-token for %s. Start a new session and verify the writer model with a small task.\n' "$target"