claude-code-token-saver 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 NgTrgGiang
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,140 @@
+# claude-code-token-saver
+
+Script cài đặt để dựng bộ "rails" (khung làm việc) cho [Claude Code](https://claude.com/claude-code) trong bất kỳ repo git nào — giúp tiết kiệm token và làm việc kỷ luật hơn.
+
+Chạy một lần, bạn sẽ có sẵn: `CLAUDE.md` gọn nhẹ, hooks kiểm soát chất lượng + an toàn, hệ thống dev-docs để không mất ngữ cảnh, các subagent chuyên biệt, và vài slash command tiện dụng.
+
+---
+
+## Cài đặt
+
+Vào **thư mục gốc** repo bạn muốn gắn rails, rồi chọn 1 trong các cách:
+
+**① npx — không cần cài gì (khuyên dùng)**
+
+```bash
+npx claude-code-token-saver
+```
+
+**② curl — 1 dòng, không cần Node**
+
+```bash
+curl -fsSL https://raw.githubusercontent.com/NgTrgGiang/claude-code-token-saver/main/setup-claude-code.sh | bash
+```
+
+**③ Chạy trực tiếp file** (nếu đã có sẵn script)
+
+```bash
+bash setup-claude-code.sh
+```
+
+Cả 3 cách đều **không ghi đè** file đã tồn tại. Toàn bộ nội dung nằm trong `.claude/` (+ `CLAUDE.md` ở gốc), an toàn để commit và chia sẻ cho cả team.
+
+> Mọi cách đều cần **bash** trên máy. Trên Windows: dùng Git Bash / WSL, hoặc cài [Git for Windows](https://git-scm.com/download/win).
+
+### Tùy chọn
+
+| Cờ | Ý nghĩa |
+|----|---------|
+| `--force` | Ghi đè cả những file đã tồn tại (mặc định: bỏ qua) |
+| `--no-detect` | Không tự dò lệnh build/test/lint |
+| `-h`, `--help` | Hiện hướng dẫn |
+
+Ví dụ:
+
+```bash
+bash setup-claude-code.sh --force        # dựng lại từ đầu, ghi đè hết
+bash setup-claude-code.sh --no-detect    # không tự dò lệnh build/test/lint
+```
+
+---
+
+## Sử dụng
+
+### Bước 1 — Cài rails vào dự án của bạn
+
+Lưu ý: chạy **trong repo dự án bạn muốn code** (ví dụ `my-shop`, `my-api`...), **không phải** trong repo `claude-code-token-saver`.
+
+```bash
+cd đường/dẫn/tới/du-an-cua-ban
+npx claude-code-token-saver            # hoặc dùng cách curl ở trên
+```
+
+Xong bước này, dự án của bạn sẽ mọc ra `CLAUDE.md` + thư mục `.claude/`. Script tự nhận diện dự án là Node / Python / Go / Rust để điền sẵn lệnh build/test/lint.
+
+### Bước 2 — Điền `CLAUDE.md`
+
+Mở `CLAUDE.md`, viết ngắn gọn phần **Architecture** (code nằm đâu), **Conventions** (quy ước riêng), và **lệnh dev/run**. Đây là phần Claude đọc mỗi lượt nên giữ thật gọn.
+
+### Bước 3 — Commit cho cả team
+
+```bash
+git add CLAUDE.md .claude/
+git commit -m "Add Claude Code rails"
+```
+
+### Bước 4 — Làm việc trong Claude Code
+
+Mở Claude Code **ngay trong thư mục dự án đó**. Từ giờ bạn có sẵn các slash command và làm theo vòng lặp:
+
+```
+/plan   →   /clear   →   code   →   /verify   →   /save
+```
+
+1. **`/plan <ý tưởng>`** — Claude phỏng vấn bạn rồi viết spec vào `.claude/dev-docs/SPEC.md` **trước khi** code.
+2. **`/clear`** — xoá ngữ cảnh cho nhẹ (spec đã nằm trên đĩa, không mất gì).
+3. **Code** — để Claude làm theo spec. Việc điều tra nặng nó tự đẩy sang subagent `explorer`.
+4. **`/verify`** — subagent `verifier` độc lập chạy test/build/lint, soi diff, báo PASS/FAIL.
+5. **`/save`** — lưu tiến độ vào `.claude/dev-docs/` để phiên sau resume không mất ngữ cảnh.
+
+Trong lúc đó các hook tự chạy ngầm: chặn lệnh nguy hiểm, tự format file, không cho Claude đọc `.env`. Chạy `/hooks` trong Claude Code để xác nhận hook đã đăng ký.
+
+---
+
+## Nó tạo ra những gì
+
+| Đường dẫn | Công dụng |
+|-----------|-----------|
+| `CLAUDE.md` | Bộ nhớ dự án gọn (< ~200 dòng): commands, kiến trúc, quy ước, gotchas, workflow |
+| `.claude/settings.json` | Hooks + danh sách chặn quyền (chặn đọc `.env`, `secrets/`) — **nên commit** |
+| `.claude/hooks/guard-bash.sh` | Chặn lệnh shell nguy hiểm (`rm -rf /`, fork bomb, `git push --force`, `chmod -R 777`, pipe script từ mạng vào shell) |
+| `.claude/hooks/format-file.sh` | Tự động format file sau khi Claude ghi (prettier / ruff / gofmt / rustfmt) |
+| `.claude/agents/explorer.md` | Subagent điều tra codebase **read-only**, chạy model `haiku` để tiết kiệm token |
+| `.claude/agents/verifier.md` | Subagent kiểm chứng độc lập — chạy test/build/lint, soi diff, báo PASS/FAIL |
+| `.claude/commands/*.md` | Các slash command: `/plan`, `/save`, `/verify`, `/wrap` |
+| `.claude/dev-docs/` | Lưu trạng thái task **ngoài** hội thoại, sống sót qua `/clear` và compaction |
+
+Script tự nhận diện stack (**Node/TS, Python, Go, Rust**) và điền sẵn lệnh build/test/lint tương ứng.
+
+---
+
+## Các slash command
+
+| Lệnh | Tác dụng |
+|------|----------|
+| `/plan <ý tưởng>` | Phỏng vấn bạn kỹ lưỡng rồi viết spec vào `.claude/dev-docs/SPEC.md` **trước khi** code |
+| `/save` | Ghi trạng thái task vào dev-docs để phiên mới resume không mất ngữ cảnh |
+| `/verify` | Giao thay đổi hiện tại cho subagent `verifier` kiểm chứng độc lập |
+| `/wrap` | Post-mortem bug: giải thích nguyên nhân gốc, xác nhận fix, thêm rule vào `## Gotchas` |
+
+---
+
+## Vì sao "token-saver"?
+
+- **Delegate cho subagent** — việc điều tra/đọc code nặng nề đẩy sang `explorer` (chạy `haiku`), giữ context chính sạch.
+- **Dev-docs** — trạng thái task nằm trên đĩa, nên `/clear` thoải mái mà không mất công việc đang dở.
+- **CLAUDE.md gọn** — mỗi dòng đều được nạp mỗi lượt, nên chỉ giữ thứ thật sự cần.
+
+---
+
+## Lưu ý an toàn
+
+> ⚠️ Hooks chạy lệnh shell thật. Hãy đọc kỹ hai script trong `.claude/hooks/` trước khi tin dùng trên repo nhạy cảm.
+
+---
+
+## Yêu cầu
+
+- `bash`
+- `python3` (dùng để hooks đọc JSON từ stdin — không cần `jq`)
+- Tùy chọn: `jq` (dò script trong `package.json` chính xác hơn), và các trình format (`prettier`, `ruff`, `gofmt`, `rustfmt`)

package/bin/cli.js

@@ -0,0 +1,66 @@
+#!/usr/bin/env node
+"use strict";
+
+/*
+ * npx launcher for claude-code-token-saver.
+ *
+ * The real installer is the bundled bash script `setup-claude-code.sh`.
+ * This wrapper just locates a bash interpreter and runs that script in the
+ * user's current directory, forwarding any CLI args (--force, --no-detect...).
+ *
+ * Works on macOS / Linux / WSL, and on Windows when Git Bash is installed.
+ */
+
+const { spawnSync } = require("child_process");
+const path = require("path");
+const fs = require("fs");
+
+const script = path.join(__dirname, "..", "setup-claude-code.sh");
+
+if (!fs.existsSync(script)) {
+  console.error("claude-code-token-saver: cannot find setup-claude-code.sh");
+  process.exit(1);
+}
+
+// Candidate bash locations. First hit that runs wins.
+function candidateBashes() {
+  const list = ["bash"];
+  if (process.platform === "win32") {
+    const pf = process.env["ProgramFiles"] || "C:\\Program Files";
+    const pf86 = process.env["ProgramFiles(x86)"] || "C:\\Program Files (x86)";
+    const local = process.env["LOCALAPPDATA"] || "";
+    list.push(
+      path.join(pf, "Git", "bin", "bash.exe"),
+      path.join(pf, "Git", "usr", "bin", "bash.exe"),
+      path.join(pf86, "Git", "bin", "bash.exe"),
+      local && path.join(local, "Programs", "Git", "bin", "bash.exe"),
+      "C:\\Windows\\System32\\bash.exe" // WSL
+    );
+  }
+  return list.filter(Boolean);
+}
+
+const args = process.argv.slice(2);
+
+for (const bash of candidateBashes()) {
+  const res = spawnSync(bash, [script, ...args], {
+    stdio: "inherit",
+    cwd: process.cwd(),
+  });
+  if (res.error && res.error.code === "ENOENT") {
+    continue; // this bash isn't here, try the next candidate
+  }
+  process.exit(res.status == null ? 1 : res.status);
+}
+
+console.error(
+  [
+    "claude-code-token-saver: no bash interpreter found.",
+    "",
+    "This tool runs a bash script, so it needs bash on your PATH.",
+    "  • Windows: install Git for Windows (https://git-scm.com/download/win)",
+    "             then run this from Git Bash, or ensure bash.exe is on PATH.",
+    "  • macOS / Linux / WSL: bash is already available.",
+  ].join("\n")
+);
+process.exit(1);

package/package.json

@@ -0,0 +1,45 @@
+{
+  "name": "claude-code-token-saver",
+  "version": "0.1.0",
+  "description": "One-shot installer that adds token-saving Claude Code rails (CLAUDE.md, hooks, subagents, slash commands, dev-docs) to any git repo.",
+  "bin": {
+    "claude-code-token-saver": "bin/cli.js",
+    "claude-rails": "bin/cli.js"
+  },
+  "files": [
+    "bin/cli.js",
+    "setup-claude-code.sh"
+  ],
+  "scripts": {
+    "start": "node bin/cli.js"
+  },
+  "keywords": [
+    "claude",
+    "claude-code",
+    "anthropic",
+    "ai",
+    "hooks",
+    "subagents",
+    "developer-tools",
+    "scaffold",
+    "token-saver"
+  ],
+  "author": "NgTrgGiang",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/NgTrgGiang/claude-code-token-saver.git"
+  },
+  "bugs": {
+    "url": "https://github.com/NgTrgGiang/claude-code-token-saver/issues"
+  },
+  "homepage": "https://github.com/NgTrgGiang/claude-code-token-saver#readme",
+  "engines": {
+    "node": ">=14"
+  },
+  "os": [
+    "darwin",
+    "linux",
+    "win32"
+  ]
+}

package/setup-claude-code.sh

@@ -0,0 +1,385 @@
+#!/usr/bin/env bash
+#
+# setup-claude-code.sh
+# ---------------------------------------------------------------------------
+# One-shot setup that installs the "rails" the Claude Code community
+# recommends: a lean CLAUDE.md, quality-gate + safety hooks, a dev-docs
+# system, exploration/verification subagents, and helper slash commands.
+#
+# Run once inside the ROOT of a git repo:
+#     bash setup-claude-code.sh
+#
+# It never overwrites existing files unless you pass --force.
+# Everything it writes lives under .claude/ (+ CLAUDE.md at the root),
+# so it is safe to commit to your repo and share with your team.
+# ---------------------------------------------------------------------------
+
+set -euo pipefail
+
+# ---------- options ---------------------------------------------------------
+FORCE=0
+SKIP_DETECT=0
+for arg in "$@"; do
+  case "$arg" in
+    --force)       FORCE=1 ;;
+    --no-detect)   SKIP_DETECT=1 ;;
+    -h|--help)
+      cat <<'EOF'
+Usage: bash setup-claude-code.sh [--force] [--no-detect]
+
+  --force       Overwrite files that already exist (default: skip them)
+  --no-detect   Do not auto-detect build/test/lint commands
+EOF
+      exit 0 ;;
+    *) echo "Unknown option: $arg" >&2; exit 1 ;;
+  esac
+done
+
+# ---------- pretty output ---------------------------------------------------
+c_reset=$'\033[0m'; c_grn=$'\033[32m'; c_ylw=$'\033[33m'; c_cyn=$'\033[36m'; c_dim=$'\033[2m'
+info()  { printf "%s»%s %s\n" "$c_cyn" "$c_reset" "$*"; }
+ok()    { printf "%s✓%s %s\n" "$c_grn" "$c_reset" "$*"; }
+skip()  { printf "%s•%s %s%s%s\n" "$c_ylw" "$c_reset" "$c_dim" "$*" "$c_reset"; }
+
+# writes a file unless it exists (respects --force). $1=path, stdin=content
+write_file() {
+  local path="$1"
+  if [[ -e "$path" && $FORCE -eq 0 ]]; then
+    skip "exists, skipped: $path  (use --force to overwrite)"
+    cat > /dev/null   # drain stdin
+    return
+  fi
+  mkdir -p "$(dirname "$path")"
+  cat > "$path"
+  ok "wrote $path"
+}
+
+# ---------- sanity ----------------------------------------------------------
+if [[ ! -d .git ]]; then
+  info "No .git here — this doesn't look like a repo root."
+  printf "  Continue anyway? [y/N] "
+  read -r reply
+  [[ "$reply" =~ ^[Yy]$ ]] || { echo "Aborted."; exit 1; }
+fi
+
+PROJECT_NAME="$(basename "$PWD")"
+info "Setting up Claude Code rails for: ${c_grn}${PROJECT_NAME}${c_reset}"
+echo
+
+# ---------- detect commands -------------------------------------------------
+BUILD_CMD="# add your build command"
+TEST_CMD="# add your test command"
+LINT_CMD="# add your lint command"
+STACK="unknown"
+
+if [[ $SKIP_DETECT -eq 0 ]]; then
+  if [[ -f package.json ]]; then
+    STACK="Node / JavaScript-TypeScript"
+    command -v jq >/dev/null 2>&1 && HAVE_JQ=1 || HAVE_JQ=0
+    has_script() { [[ $HAVE_JQ -eq 1 ]] && jq -e ".scripts.\"$1\" // empty" package.json >/dev/null 2>&1; }
+    if [[ $HAVE_JQ -eq 1 ]]; then
+      has_script build && BUILD_CMD="npm run build"
+      has_script test  && TEST_CMD="npm test"
+      has_script lint  && LINT_CMD="npm run lint"
+      has_script typecheck && LINT_CMD="npm run typecheck && ${LINT_CMD#\# *}"
+    else
+      BUILD_CMD="npm run build"; TEST_CMD="npm test"; LINT_CMD="npm run lint"
+    fi
+  elif [[ -f pyproject.toml || -f requirements.txt || -f setup.py ]]; then
+    STACK="Python"
+    TEST_CMD="pytest -q"
+    LINT_CMD="ruff check . && ruff format --check ."
+    [[ -f pyproject.toml ]] && BUILD_CMD="python -m build" || BUILD_CMD="# (library — no build step)"
+  elif [[ -f go.mod ]]; then
+    STACK="Go"
+    BUILD_CMD="go build ./..."; TEST_CMD="go test ./..."; LINT_CMD="go vet ./... && golangci-lint run"
+  elif [[ -f Cargo.toml ]]; then
+    STACK="Rust"
+    BUILD_CMD="cargo build"; TEST_CMD="cargo test"; LINT_CMD="cargo clippy -- -D warnings && cargo fmt --check"
+  fi
+  info "Detected stack: ${c_grn}${STACK}${c_reset}"
+fi
+echo
+
+# ===========================================================================
+# 1. CLAUDE.md  — lean project memory (< ~200 lines, command-first)
+# ===========================================================================
+write_file "CLAUDE.md" <<EOF
+# ${PROJECT_NAME}
+
+> Project memory for Claude Code. Keep this SHORT (< ~200 lines).
+> Every line is loaded on every turn — delete anything a linter/formatter
+> already enforces, and anything Claude gets right without being told.
+
+## Commands
+- Build:     ${BUILD_CMD}
+- Test:      ${TEST_CMD}
+- Lint:      ${LINT_CMD}
+- Run/dev:   # add your dev/run command
+
+## Architecture
+<!-- One paragraph. Where does code live, what are the key modules? -->
+<!-- Point to files instead of pasting code:  See src/... for X. -->
+
+## Conventions
+<!-- Only rules a formatter can't enforce. Prefer "do X instead of Y". -->
+- Prefer editing existing files over creating new ones.
+- Never commit secrets; config lives in .env (git-ignored).
+
+## Gotchas
+<!-- Things Claude repeatedly gets wrong here. Add to this over time. -->
+
+## Workflow
+- Use **plan mode** before non-trivial edits; get the plan approved first.
+- Always verify with tests/build before declaring a task done.
+- For big investigations, delegate to the \`explorer\` subagent so the
+  main context stays clean.
+- Detailed task state lives in \`.claude/dev-docs/\` (plan / context / tasks).
+EOF
+
+# ===========================================================================
+# 2. Hooks + permissions  — .claude/settings.json
+#    (safe to commit; secrets go in settings.local.json)
+# ===========================================================================
+# Quality gate: block `git commit` unless tests pass.
+# Safety gate: block obviously destructive shell commands.
+write_file ".claude/settings.json" <<'EOF'
+{
+  "$schema": "https://json.schemastore.org/claude-code-settings.json",
+  "permissions": {
+    "deny": [
+      "Read(./.env)",
+      "Read(./.env.*)",
+      "Read(./**/secrets/**)"
+    ]
+  },
+  "hooks": {
+    "PreToolUse": [
+      {
+        "matcher": "Bash",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "\"$CLAUDE_PROJECT_DIR/.claude/hooks/guard-bash.sh\""
+          }
+        ]
+      }
+    ],
+    "PostToolUse": [
+      {
+        "matcher": "Write|Edit",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "\"$CLAUDE_PROJECT_DIR/.claude/hooks/format-file.sh\""
+          }
+        ]
+      }
+    ]
+  }
+}
+EOF
+
+# 2a. Safety hook — blocks destructive Bash commands (exit 2 = block)
+write_file ".claude/hooks/guard-bash.sh" <<'EOF'
+#!/usr/bin/env bash
+# PreToolUse(Bash) guard. Reads tool JSON on stdin, blocks dangerous commands.
+# Exit 2 = block (stderr shown to Claude). Exit 0 = allow.
+set -euo pipefail
+input="$(cat)"
+
+# Extract the command field without requiring jq.
+cmd="$(printf '%s' "$input" | python3 -c 'import sys,json;print(json.load(sys.stdin).get("tool_input",{}).get("command",""))' 2>/dev/null || true)"
+
+block() { echo "BLOCKED by guard-bash: $1" >&2; exit 2; }
+
+case "$cmd" in
+  *"rm -rf /"*|*"rm -rf ~"*|*"rm -rf ."*) block "recursive force-delete of a dangerous path" ;;
+  *":(){ :|:& };:"*)                       block "fork bomb" ;;
+  *"git push"*"--force"*|*"git push -f"*)  block "force push (do a normal push or ask the human)" ;;
+  *"chmod -R 777"*)                        block "world-writable recursive chmod" ;;
+  *"curl"*"| bash"*|*"wget"*"| sh"*|*"curl"*"| sh"*) block "piping a remote script straight into a shell" ;;
+esac
+exit 0
+EOF
+chmod +x ".claude/hooks/guard-bash.sh" 2>/dev/null || true
+
+# 2b. Format hook — auto-formats files Claude writes (best-effort, never blocks)
+write_file ".claude/hooks/format-file.sh" <<'EOF'
+#!/usr/bin/env bash
+# PostToolUse(Write|Edit): format the touched file. Never blocks (exit 0).
+set -uo pipefail
+input="$(cat)"
+f="$(printf '%s' "$input" | python3 -c 'import sys,json;print(json.load(sys.stdin).get("tool_input",{}).get("file_path",""))' 2>/dev/null || true)"
+[[ -z "$f" || ! -f "$f" ]] && exit 0
+
+case "$f" in
+  *.js|*.jsx|*.ts|*.tsx|*.json|*.css|*.md|*.html)
+      command -v npx >/dev/null 2>&1 && npx --no-install prettier --write "$f" >/dev/null 2>&1 || true ;;
+  *.py)
+      command -v ruff >/dev/null 2>&1 && ruff format "$f" >/dev/null 2>&1 || true ;;
+  *.go)
+      command -v gofmt >/dev/null 2>&1 && gofmt -w "$f" >/dev/null 2>&1 || true ;;
+  *.rs)
+      command -v rustfmt >/dev/null 2>&1 && rustfmt "$f" >/dev/null 2>&1 || true ;;
+esac
+exit 0
+EOF
+chmod +x ".claude/hooks/format-file.sh" 2>/dev/null || true
+
+# ===========================================================================
+# 3. Subagents  — .claude/agents/*.md  (each has its own context window)
+# ===========================================================================
+write_file ".claude/agents/explorer.md" <<'EOF'
+---
+name: explorer
+description: Read-only codebase investigator. Use PROACTIVELY for any "how does X work / where is Y / trace this flow" question so exploration does not fill the main context window. Returns a concise findings summary, not raw file dumps.
+tools: Read, Grep, Glob
+model: haiku
+---
+
+You are a focused codebase explorer running in your own context window.
+
+Your job: answer the specific investigation question and nothing more.
+
+Rules:
+- Scope tightly. Read only what the question needs — do not wander the repo.
+- Never edit files. You are read-only.
+- Return a SHORT summary: the answer, the 3–8 key files/symbols involved
+  (with paths), and any surprising gotchas. No verbatim file dumps.
+- If the question is ambiguous, state your interpretation, then answer it.
+EOF
+
+write_file ".claude/agents/verifier.md" <<'EOF'
+---
+name: verifier
+description: Independent verification agent. Use after an implementation to confirm it actually works — runs tests/build/lint and reviews the diff against the stated goal. Blocks "should work" claims.
+tools: Read, Grep, Glob, Bash
+# No model pinned → inherits the main session's model. Verifying a diff needs
+# real reasoning, so keep it on whatever tier you're coding with (not haiku).
+---
+
+You are an independent verifier. You did NOT write the code, so be skeptical.
+
+Steps:
+1. Restate the goal in one sentence (from the task / dev-docs).
+2. Run the project's test, build, and lint commands (see CLAUDE.md).
+3. Read the diff and check it against the goal, including edge cases.
+4. Report PASS or FAIL with evidence: actual command output, failing cases,
+   or missing handling. Never say "should work" — show that it does.
+
+If you cannot verify something, say so explicitly rather than assuming.
+EOF
+
+# ===========================================================================
+# 4. Slash commands  — .claude/commands/*.md
+# ===========================================================================
+write_file ".claude/commands/plan.md" <<'EOF'
+---
+description: Interview me, then write a self-contained spec before any code.
+---
+I want to build: $ARGUMENTS
+
+Interview me in detail using the AskUserQuestion tool. Ask about technical
+implementation, UI/UX, edge cases, concerns, and tradeoffs. Skip obvious
+questions; dig into the hard parts I might not have considered. Keep going
+until we've covered everything.
+
+Then write a self-contained spec to `.claude/dev-docs/SPEC.md` that names the
+files and interfaces involved, states what is OUT of scope, and ends with an
+end-to-end verification step that proves the feature works.
+
+Do NOT write implementation code yet. When the spec is ready, tell me to start
+a fresh session (/clear) to execute it against the spec.
+EOF
+
+write_file ".claude/commands/save.md" <<'EOF'
+---
+description: Persist task state to dev-docs so context survives /clear or compaction.
+---
+Update the dev-docs for the current task so a fresh session can resume with no
+lost context. Write/refresh these files under `.claude/dev-docs/`:
+
+- `plan.md`    — the accepted plan / approach
+- `context.md` — key files, decisions made, constraints, things that surprised us
+- `tasks.md`   — a checklist of what's done and what's left
+
+Be concise but specific (name real files and decisions). Then remind me I can
+safely run /clear and later say "read .claude/dev-docs and brief me".
+EOF
+
+write_file ".claude/commands/verify.md" <<'EOF'
+---
+description: Hand the current change to the independent verifier subagent.
+---
+Delegate to the `verifier` subagent: confirm the current change actually meets
+its goal. It should run tests/build/lint (see CLAUDE.md), review the diff, and
+report PASS/FAIL with real evidence. Do not mark the task done until it passes.
+EOF
+
+write_file ".claude/commands/wrap.md" <<'EOF'
+---
+description: Debug post-mortem — fix, explain, and harden against recurrence.
+---
+For the bug we just dealt with:
+1. Explain the root cause in 2–3 sentences.
+2. Confirm the fix and how it was verified.
+3. If this is a class of mistake likely to recur here, add a one-line rule to
+   the "## Gotchas" section of CLAUDE.md so it doesn't happen again.
+EOF
+
+# ===========================================================================
+# 5. Dev-docs scaffold  + .gitignore hints
+# ===========================================================================
+write_file ".claude/dev-docs/README.md" <<'EOF'
+# dev-docs
+
+Task state that lives OUTSIDE the conversation, so context survives `/clear`
+and compaction. Update with `/save`. Resume a session with:
+
+    read .claude/dev-docs and brief me on where we are
+
+Files (per active task): plan.md, context.md, tasks.md, and SPEC.md (from /plan).
+EOF
+
+# Add ignore hints for personal/local settings, without clobbering an existing file.
+if [[ -f .gitignore ]]; then
+  for line in ".claude/settings.local.json" ".claude/dev-docs/*.local.md"; do
+    grep -qxF "$line" .gitignore 2>/dev/null || { echo "$line" >> .gitignore; ok ".gitignore += $line"; }
+  done
+else
+  write_file ".gitignore" <<'EOF'
+# Claude Code — personal/local overrides (keep out of git)
+.claude/settings.local.json
+.claude/dev-docs/*.local.md
+EOF
+fi
+
+# ===========================================================================
+# Summary
+# ===========================================================================
+echo
+info "Done. Here's what got installed:"
+cat <<EOF
+
+  CLAUDE.md                         lean project memory (fill in the blanks)
+  .claude/settings.json             hooks + permission deny-list (commit this)
+  .claude/hooks/guard-bash.sh       blocks destructive shell commands
+  .claude/hooks/format-file.sh      auto-formats files Claude writes
+  .claude/agents/explorer.md        read-only investigator (own context)
+  .claude/agents/verifier.md        independent "prove it works" agent
+  .claude/commands/plan.md          /plan  — interview → SPEC.md
+  .claude/commands/save.md          /save  — persist task state
+  .claude/commands/verify.md        /verify — run the verifier subagent
+  .claude/commands/wrap.md          /wrap  — post-mortem + harden CLAUDE.md
+  .claude/dev-docs/                 persistent task state across sessions
+
+${c_ylw}Next:${c_reset}
+  1. Open CLAUDE.md and fill in Architecture / Conventions / dev command.
+  2. Commit .claude/ and CLAUDE.md so your team gets the same rails.
+  3. In Claude Code: run /hooks to confirm hooks are registered.
+  4. Try the habits: /plan → /clear → build → /verify → /save.
+
+${c_dim}Note: hooks run real shell commands. Read the two scripts in
+.claude/hooks/ before trusting them on a sensitive repo.${c_reset}
+EOF