saving-token 0.1.0 → 1.0.0

package/README.md

@@ -1,46 +1,69 @@
 # 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.
+A native writer makes file changes; the host directs and reviews. The writer
+model is selected during setup, while the host 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.
+Inspired by [karpathy-guidelines](https://github.com/multica-ai/andrej-karpathy-skills).
 
 ## Install
 
-### Codex via npm (after publication)
+### Interactive setup
 
-After the package is published to npm, run:
+```bash
+bash skills/saving-token/scripts/setup.sh
+```
+
+Use **Up/Down** and **Enter** to choose the platform, writer model, optional
+reasoning effort, and final action. Press **Esc** to cancel. The final menu
+starts on **Cancel**. Model entries are suggestions only; availability is not
+checked. The effort menu includes the host default and values accepted by the
+target; account and model support still depend on the host.
+
+The model menu has no free-text entry. Use `--model` for a custom model ID or
+for non-interactive setup:
 
 ```bash
-npx saving-token@latest install --agent codex
+bash skills/saving-token/scripts/setup.sh \
+  --target codex --model '<model-id>' --yes
 ```
 
-This interactively prompts you to choose a writer model and optional reasoning effort, then asks you to confirm installation.
+`--target` and `--model` are required without a terminal. Add
+`--reasoning-effort <effort>` when supported by the selected model. `--yes`
+approves the displayed installation and replacements; it never chooses a
+model. Rerun setup to change the writer. Extra files in an existing Skill
+directory are preserved.
+
+### npm wrapper
 
-### Manual / multi-platform
+After publication, run:
 
 ```bash
-bash skills/saving-token/scripts/setup.sh
+npx saving-token@latest install --agent codex
 ```
 
-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.
+The wrapper supports `install --agent codex` and keeps the interactive menus.
+Use the Bash script directly for `--target`, `--model`, `--reasoning-effort`,
+or `--yes`.
 
-| Platform | Skill location | Writer configuration |
+### Installed paths
+
+| Platform | Skill | 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
-```
+Restart the host, then invoke `$saving-token` in Codex or `/saving-token` in
+standalone Claude Code and Cursor. A generated configuration does not prove
+runtime routing; verify the model in exposed task metadata when available.
+Claude Code and Cursor may substitute a model under account or administrator
+policy.
 
-`--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`.
+The writer implements and verifies delegated changes. The host personally
+reviews the actual changes and verification evidence against the requirements,
+sends defects back to the same writer for fixes and re-review, and announces
+completion only after review passes.
 
 ## Claude Code plugin
 
@@ -49,15 +72,12 @@ Rerun setup to change the writer model. Existing distributed Skill files and the
 /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.
+The plugin collects `writer_model` through its configuration and leaves effort
+to the host. Invoke `/saving-token:saving-token`; its writer is
+`saving-token:saving-token-writer`. Use either the plugin or standalone setup.
 
-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).
+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), and
+[Agent Skills](https://agentskills.io/specification).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "saving-token",
-  "version": "0.1.0",
+  "version": "1.0.0",
   "bin": {
     "saving-token": "bin/saving-token.cjs"
   },

package/skills/saving-token/SKILL.md

@@ -34,8 +34,8 @@ 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.
+- After the writer finishes, the host must personally review the actual diff, new files, and verification evidence against the requirements, never relying on the writer's summary alone; send any defects to the same writer for fixes and re-review, and announce completion only after the review passes.
+- 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/scripts/setup.sh

@@ -3,12 +3,96 @@ set -euo pipefail
 
 fail() { printf 'Error: %s\n' "$*" >&2; exit 1; }
 
+cursor_hidden=false
+terminal_state=''
+restore_cursor() {
+  if [[ "$cursor_hidden" == true ]]; then
+    printf '\033[?25h'
+    cursor_hidden=false
+  fi
+  if [[ -n "$terminal_state" ]]; then
+    stty "$terminal_state" 2>/dev/null || stty echo
+    terminal_state=''
+  fi
+}
+trap restore_cursor EXIT
+trap 'exit 130' INT TERM
+
+choose_menu() {
+  local prompt=$1
+  shift
+  local -a labels values
+  local entry label value key sequence
+  local selected=0 rendered=false line_count
+  MENU_RESULT=''
+
+  for entry in "$@"; do
+    label=${entry%%|*}
+    value=${entry#*|}
+    labels[${#labels[@]}]=$label
+    values[${#values[@]}]=$value
+  done
+  line_count=$(( ${#labels[@]} + 1 ))
+  terminal_state=$(stty -g)
+  stty -echo
+  printf '\033[?25l'
+  cursor_hidden=true
+
+  while :; do
+    if [[ "$rendered" == true ]]; then
+      printf '\033[%sA' "$line_count"
+    fi
+    printf '\033[2K\r%s (Up/Down, Enter to select, Esc to cancel)\n' "$prompt"
+    for entry in "${!labels[@]}"; do
+      printf '\033[2K\r'
+      if [[ "$entry" -eq "$selected" ]]; then
+        printf '> %s\n' "${labels[$entry]}"
+      else
+        printf '  %s\n' "${labels[$entry]}"
+      fi
+    done
+    rendered=true
+
+    if ! IFS= read -r -s -n 1 key; then
+      restore_cursor
+      return 2
+    fi
+    case "$key" in
+      ''|$'\n'|$'\r')
+        MENU_RESULT=${values[$selected]}
+        restore_cursor
+        printf '\n'
+        return 0
+        ;;
+      $'\033')
+        if IFS= read -r -s -n 2 -t 1 sequence; then
+          case "$sequence" in
+            '[A') selected=$(( (selected + ${#labels[@]} - 1) % ${#labels[@]} )) ;;
+            '[B') selected=$(( (selected + 1) % ${#labels[@]} )) ;;
+            *) restore_cursor; printf '\n'; return 1 ;;
+          esac
+        else
+          restore_cursor
+          printf '\n'
+          return 1
+        fi
+        ;;
+    esac
+  done
+}
+
+cancel_install() {
+  printf 'Installation cancelled; no files were changed.\n'
+  exit 0
+}
+
 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.
+Use Up/Down and Enter to choose a platform, model, effort, and confirmation.
+Esc cancels before any files are changed.
   --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.
@@ -48,8 +132,11 @@ 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
+  if choose_menu 'Choose a platform:' 'Codex|codex' 'Claude Code|claude' 'Cursor|cursor'; then
+    target=$MENU_RESULT
+  else
+    cancel_install
+  fi
 fi
 
 case "$target" in
@@ -77,18 +164,13 @@ 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
+  model_options=()
+  for model in "${models[@]}"; do model_options[${#model_options[@]}]="$model|$model"; done
+  if choose_menu 'Choose a writer model:' "${model_options[@]}"; then
+    writer_model=$MENU_RESULT
+  else
+    cancel_install
+  fi
 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 -.'
 
@@ -97,7 +179,24 @@ case "$writer_model" in
 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.'
+  effort_options=('Use host default (omit)|')
+  case "$target" in
+    codex) effort_options+=(
+      'none|none' 'minimal|minimal' 'low|low' 'medium|medium' 'high|high'
+      'xhigh|xhigh' 'max|max' 'ultra|ultra'
+    ) ;;
+    claude) effort_options+=(
+      'low|low' 'medium|medium' 'high|high' 'xhigh|xhigh' 'max|max'
+    ) ;;
+    cursor) effort_options+=(
+      'low|low' 'medium|medium' 'high|high' 'xhigh|xhigh' 'max|max' 'ultra|ultra'
+    ) ;;
+  esac
+  if choose_menu 'Choose reasoning effort (model support may vary):' "${effort_options[@]}"; then
+    reasoning_effort=$MENU_RESULT
+  else
+    cancel_install
+  fi
 fi
 case "$reasoning_effort" in
   ''|none|minimal|low|medium|high|xhigh|max|ultra) ;;
@@ -135,11 +234,12 @@ 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
+  [[ -t 0 ]] || fail 'Pass --yes in non-interactive use.'
+  if choose_menu 'Install this configuration?' 'Cancel|no' 'Install|yes'; then
+    [[ "$MENU_RESULT" == yes ]] || cancel_install
+  else
+    cancel_install
+  fi
 else
   printf 'Install this configuration? yes (--yes)\n'
 fi