@4pm/cli 1.5.16 → 1.5.17-b

package/dist/project-sample/.claude/hooks/autonomous-tick.sh

@@ -0,0 +1,356 @@
+#!/usr/bin/env bash
+# Cron tick for the autonomous workflow — install on WSL. The schedule & control flags live in
+# .claude/.autonomous.settings.json (paused, max_session_pct, max_weekly_pct, cron_schedule, …);
+# read EVERY tick, so changes take effect on the next tick (cron_schedule auto-syncs into the crontab).
+#
+#   Install once:  crontab -e   →   */10 * * * * /path/to/project/.claude/hooks/autonomous-tick.sh
+#   After that, change the cadence/priority by editing cron_schedule in .autonomous.settings.json.
+#
+# "Busy ⇒ wait for the next tick" via the EXISTENCE of the file `.autonomous.lock` (not flock):
+#   - If the lock file exists  → another tick is running → log "skip" and exit.
+#   - If it doesn't            → create the lock → call Claude headless to run /auto-cycle.
+# Removing the lock is /auto-cycle's job (on success or error). The trap below is only a SAFETY NET:
+# if the process dies before /auto-cycle removes it, the wrapper cleans it up on exit.
+set -euo pipefail
+
+# Project root = two levels above this file (.claude/hooks → .claude → root)
+PROJECT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")/../.." && pwd)"
+LOCK="$PROJECT_DIR/.claude/.autonomous.lock"
+# State + cron history COMBINED into ONE JSON file (replacing the 3 old cron-applied/fails/ticks files).
+HIST="$PROJECT_DIR/.claude/.autonomous.histories.json"
+HIST_PY="$PROJECT_DIR/.claude/hooks/autonomous-history.py"
+LOG_DIR="$PROJECT_DIR/.claude/logs"
+mkdir -p "$LOG_DIR"
+LOG="$LOG_DIR/autonomous-tick-$(date +%F).log"   # per-DAY log (so log_retention_days is meaningful)
+ts() { date '+%F %T'; }
+
+# Create the lock atomically: `noclobber` makes `> file` FAIL if the file exists, closing the race
+# where two ticks both pass a separate "does it exist?" check.
+if ! ( set -o noclobber; : > "$LOCK" ) 2>/dev/null; then
+  echo "$(ts) [skip] busy (.autonomous.lock exists) — waiting for the next tick" >> "$LOG"
+  exit 0
+fi
+# Safety net: ensure the lock is cleaned when the wrapper exits, even if Claude dies silently.
+trap 'rm -f "$LOCK"' EXIT
+
+cd "$PROJECT_DIR"
+
+# IMPORTANT: cron runs with a minimal PATH (/usr/bin:/bin) and does NOT load ~/.bashrc/~/.profile.
+# `claude` is installed NATIVELY in WSL. Add common WSL install dirs so cron can find the claude binary:
+#   - $HOME/.local/bin      : native installer (curl … | sh)
+#   - $HOME/.npm-global/bin : npm global with a custom prefix
+#   - /usr/local/bin        : default npm global when installed with sudo
+export PATH="$HOME/.local/bin:$HOME/.npm-global/bin:/usr/local/bin:$PATH"
+
+# --- Python (needed for: reading settings + the token gate) ------------------------------------
+PY_BIN="$(command -v python3 || command -v python || true)"
+if [ -z "$PY_BIN" ]; then
+  echo "$(ts) [error] python/python3 not found — skipping this tick" >> "$LOG"
+  exit 0
+fi
+
+# --- Claude config dir (CLAUDE_CONFIG_DIR) from project.settings.json (MULTIPLE accounts) --------
+# claudeConfigDir is a LIST of absolute paths, tried in fallback order. Pick the FIRST account whose
+# token is still valid; if none is valid, pick the first account WITH credentials and mark it for
+# refresh (calling 'claude /usage' once CLAUDE_BIN is known). Empty/missing -> keep the default (~/.claude).
+SEL="$("$PY_BIN" - "$PROJECT_DIR/project.settings.json" <<'PY'
+import json, os, sys, time
+def exp_at(d):
+    try:
+        o = json.load(open(os.path.join(d, ".credentials.json"), encoding="utf-8")).get("claudeAiOauth", {})
+        return o.get("expiresAt")
+    except Exception:
+        return None
+try:
+    s = json.load(open(sys.argv[1], encoding="utf-8"))
+    dirs = s.get("claudeConfigDir", []) if isinstance(s, dict) else []
+except Exception:
+    dirs = []
+if isinstance(dirs, str):
+    dirs = [dirs]
+dirs = [str(x).strip() for x in dirs if str(x).strip().startswith("/")]
+now = time.time() * 1000
+chosen, expired = "", "0"
+for d in dirs:                 # prefer an account whose token is still valid
+    e = exp_at(d)
+    if e and e > now:
+        chosen = d
+        break
+else:
+    for d in dirs:             # none valid -> first account with credentials (will refresh)
+        if exp_at(d) is not None:
+            chosen, expired = d, "1"
+            break
+print(chosen)
+print(expired)
+PY
+)"
+CFG_CLAUDE_DIR="$(printf '%s\n' "$SEL" | sed -n 1p)"
+CFG_CLAUDE_EXPIRED="$(printf '%s\n' "$SEL" | sed -n 2p)"
+if [ -n "$CFG_CLAUDE_DIR" ]; then
+  export CLAUDE_CONFIG_DIR="$CFG_CLAUDE_DIR"
+  echo "$(ts) [cfg] CLAUDE_CONFIG_DIR=$CFG_CLAUDE_DIR (expired=$CFG_CLAUDE_EXPIRED)" >> "$LOG"
+fi
+
+# 'hist' wrapper: every read/write of .autonomous.histories.json goes through the Python helper.
+# (get-cron/set-cron, get-fails/set-fails, get-ticks/set-ticks, record — see autonomous-history.py)
+hist() { "$PY_BIN" "$HIST_PY" "$HIST" "$@"; }
+
+# --- Read the autonomous config (.autonomous.settings.json) ------------------------------------
+# User-editable; read EVERY tick so changes take effect next tick. Python prints CFG_*=<shlex-quoted>
+# lines to eval; a missing/corrupt file -> use defaults (no break).
+SETTINGS="$PROJECT_DIR/.claude/.autonomous.settings.json"
+eval "$("$PY_BIN" - "$SETTINGS" <<'PY'
+import json, sys, shlex
+defaults = {"paused": False, "max_session_pct": 80, "max_weekly_pct": 90,
+            "cron_schedule": "*/10 * * * *", "command": "/auto-cycle", "model": "",
+            "quiet_hours": "", "max_ticks_per_day": -1, "stop_on_consecutive_failures": 3,
+            "log_retention_days": 14, "notify_webhook": ""}
+try:
+    d = json.load(open(sys.argv[1], encoding="utf-8"))
+    if not isinstance(d, dict): d = {}
+except Exception:
+    d = {}
+def g(k): return d.get(k, defaults[k])
+print("CFG_PAUSED=" + ("1" if bool(g("paused")) else "0"))
+print("CFG_MAX_SESSION_PCT=" + shlex.quote(str(g("max_session_pct"))))
+print("CFG_MAX_WEEKLY_PCT=" + shlex.quote(str(g("max_weekly_pct"))))
+print("CFG_CRON_SCHEDULE=" + shlex.quote(str(g("cron_schedule"))))
+print("CFG_COMMAND=" + shlex.quote(str(g("command"))))
+print("CFG_MODEL=" + shlex.quote(str(g("model"))))
+print("CFG_QUIET_HOURS=" + shlex.quote(str(g("quiet_hours"))))
+print("CFG_MAX_TICKS_PER_DAY=" + shlex.quote(str(g("max_ticks_per_day"))))
+print("CFG_STOP_ON_CONSEC_FAILURES=" + shlex.quote(str(g("stop_on_consecutive_failures"))))
+print("CFG_LOG_RETENTION_DAYS=" + shlex.quote(str(g("log_retention_days"))))
+print("CFG_NOTIFY_WEBHOOK=" + shlex.quote(str(g("notify_webhook"))))
+PY
+)"
+# Export CFG_* so the history helper (autonomous-history.py 'record') can read the run config from env.
+export CFG_CRON_SCHEDULE CFG_COMMAND CFG_MODEL CFG_MAX_SESSION_PCT CFG_MAX_WEEKLY_PCT \
+       CFG_QUIET_HOURS CFG_MAX_TICKS_PER_DAY CFG_STOP_ON_CONSEC_FAILURES CFG_PAUSED
+
+# --- Sync the crontab when cron_schedule changes ----------------------------------------------
+# Compare with the last-applied schedule (cron_applied in .autonomous.histories.json); if different,
+# rewrite the crontab LINE pointing at this script. Safe: only self-edit when the crontab already has
+# the autonomous line (or one was applied before) -> avoid creating a crontab during a manual run.
+SELF="$PROJECT_DIR/.claude/hooks/autonomous-tick.sh"
+PREV_SCHED="$(hist get-cron 2>/dev/null || true)"
+if [ "$CFG_CRON_SCHEDULE" != "$PREV_SCHED" ]; then
+  if command -v crontab >/dev/null 2>&1; then
+    CUR="$(crontab -l 2>/dev/null || true)"
+    if printf '%s\n' "$CUR" | grep -qF "$SELF" || [ -n "$PREV_SCHED" ]; then
+      NEWTAB="$( { printf '%s\n' "$CUR" | grep -vF "$SELF" || true; echo "$CFG_CRON_SCHEDULE $SELF"; } )"
+      if printf '%s\n' "$NEWTAB" | crontab - 2>>"$LOG"; then
+        hist set-cron "$CFG_CRON_SCHEDULE" 2>>"$LOG" || true
+        echo "$(ts) [cron] synced schedule -> '$CFG_CRON_SCHEDULE'" >> "$LOG"
+      else
+        echo "$(ts) [warn] could not write crontab (keeping the old schedule)" >> "$LOG"
+      fi
+    else
+      echo "$(ts) [cron] crontab has no autonomous line — skipping auto-install (install it once manually first)" >> "$LOG"
+    fi
+  else
+    echo "$(ts) [cron] no 'crontab' on PATH — skipping schedule sync" >> "$LOG"
+  fi
+fi
+
+# --- Pause flag -------------------------------------------------------------------------------
+if [ "$CFG_PAUSED" = "1" ]; then
+  echo "$(ts) [skip] paused=true in .autonomous.settings.json — skipping this tick" >> "$LOG"
+  exit 0
+fi
+
+# --- Prune old logs by log_retention_days (logs are per-day in $LOG_DIR) -----------------------
+if [ "${CFG_LOG_RETENTION_DAYS:-0}" -gt 0 ] 2>/dev/null; then
+  find "$LOG_DIR" -maxdepth 1 -type f -name 'autonomous-tick-*.log' -mtime +"$CFG_LOG_RETENTION_DAYS" -delete 2>/dev/null || true
+fi
+
+# --- Quiet hours ------------------------------------------------------------------------------
+# Empty = run all day. 'HH:MM-HH:MM' = skip within the window; supports a window crossing midnight.
+if [ -n "$CFG_QUIET_HOURS" ]; then
+  if printf '%s' "$CFG_QUIET_HOURS" | grep -Eq '^[0-9]{1,2}:[0-9]{2}-[0-9]{1,2}:[0-9]{2}$'; then
+    q_start="${CFG_QUIET_HOURS%%-*}"; q_end="${CFG_QUIET_HOURS##*-}"
+    _min() { echo $(( 10#${1%%:*} * 60 + 10#${1##*:} )); }   # "HH:MM" -> minutes (10# forces base 10)
+    qs=$(_min "$q_start"); qe=$(_min "$q_end"); qn=$(_min "$(date +%H:%M)")
+    in_q=0
+    if [ "$qs" -le "$qe" ]; then
+      { [ "$qn" -ge "$qs" ] && [ "$qn" -lt "$qe" ]; } && in_q=1
+    else
+      { [ "$qn" -ge "$qs" ] || [ "$qn" -lt "$qe" ]; } && in_q=1   # window crossing midnight
+    fi
+    if [ "$in_q" = 1 ]; then
+      echo "$(ts) [skip] within quiet_hours ($CFG_QUIET_HOURS) — skipping this tick" >> "$LOG"
+      exit 0
+    fi
+  else
+    echo "$(ts) [warn] quiet_hours has a bad format ('$CFG_QUIET_HOURS') — ignoring the check" >> "$LOG"
+  fi
+fi
+
+# --- Max ticks/day (max_ticks_per_day) --------------------------------------------------------
+# -1 = unlimited. Counted per local day, stored under ticks{day,count} in .autonomous.histories.json.
+TODAY="$(date +%F)"
+tick_count="$(hist get-ticks "$TODAY" 2>/dev/null || echo 0)"; [ -z "$tick_count" ] && tick_count=0
+if [ "${CFG_MAX_TICKS_PER_DAY:--1}" -gt 0 ] 2>/dev/null && [ "${tick_count:-0}" -ge "$CFG_MAX_TICKS_PER_DAY" ]; then
+  echo "$(ts) [skip] reached max_ticks_per_day=$CFG_MAX_TICKS_PER_DAY ($tick_count ticks today) — skipping" >> "$LOG"
+  exit 0
+fi
+
+# --- "Has work" gate (USER_TODO / APPROVED AI_TODO / AI_PROGRESS) -------------------------------
+# Skip IMMEDIATELY (WITHOUT calling Claude — /auto-cycle would still cost tokens just to start + stop)
+# UNLESS there is one of three kinds of work:
+#   1) USER_TODO.md has a new request  → /auto-cycle will generate tasks (Step 2);
+#   2) AI_TODO.md has AT LEAST 1 APPROVED task (approved in .autonomous.approvals.json) → Step 3 can take
+#      it. Tasks not approved DON'T count as work (VERIFY gate: wait for the user to approve them first);
+#   3) AI_PROGRESS.md is non-empty      → work left over from a previous tick to continue.
+#
+# "EMPTY" (USER_TODO / AI_PROGRESS) = COMPARE TO THE TEMPLATE: the content (normalized: trim trailing
+# whitespace + leading/trailing blank lines) EQUALS the empty template in .claude/templates/. AI_TODO is
+# judged separately via approvals (a full AI_TODO of unapproved tasks != the empty template but has NO work).
+TPL="$PROJECT_DIR/.claude/templates"
+WORK="$(AI_TODO="$PROJECT_DIR/AI_TODO.md" USER_TODO="$PROJECT_DIR/USER_TODO.md" \
+        AI_PROGRESS="$PROJECT_DIR/AI_PROGRESS.md" \
+        APPROVALS="$PROJECT_DIR/.claude/.autonomous.approvals.json" \
+        USER_TODO_TPL="$TPL/USER_TODO.empty.md" AI_PROGRESS_TPL="$TPL/AI_PROGRESS.empty.md" \
+        "$PY_BIN" - <<'PY'
+import os, json
+def norm(p):
+    # Read + normalize; return None if the file can't be read.
+    try:
+        lines = [ln.rstrip() for ln in open(p, encoding="utf-8").read().splitlines()]
+    except Exception:
+        return None
+    while lines and not lines[0]:   lines.pop(0)
+    while lines and not lines[-1]:  lines.pop()
+    return "\n".join(lines)
+def has_work(live, tpl):
+    nv = norm(live)
+    if nv is None:        # no live file -> treat as NO work (safe, don't call Claude)
+        return False
+    nt = norm(tpl)
+    if nt is None:        # no template -> can't compare -> any non-empty content counts as work
+        return bool(nv)
+    return nv != nt       # differs from the empty template = has work
+def has_approved(aitodo_p, approvals_p):
+    # At least 1 APPROVED task still in the queue (ADR-0152): the approval source is
+    # .autonomous.approvals.json ("<TSK-id>": {approved:true,...}) — the ✓ column is no longer read.
+    try:
+        ap = json.load(open(approvals_p, encoding="utf-8"))
+        approved = {k for k, v in ap.items() if isinstance(v, dict) and v.get("approved") is True}
+    except Exception:
+        return False
+    if not approved:
+        return False
+    try:
+        todo = open(aitodo_p, encoding="utf-8").read()
+    except Exception:
+        return False
+    return any(tid in todo for tid in approved)   # approved AND still present in AI_TODO
+user = has_work(os.environ["USER_TODO"],   os.environ["USER_TODO_TPL"])
+prog = has_work(os.environ["AI_PROGRESS"], os.environ["AI_PROGRESS_TPL"])
+ai   = has_approved(os.environ["AI_TODO"], os.environ["APPROVALS"])
+print("WORK" if (user or prog or ai) else "EMPTY")
+PY
+)"
+if [ "$WORK" != "WORK" ]; then
+  echo "$(ts) [skip] no new request (USER_TODO), approved task (AI_TODO), or in-progress work (AI_PROGRESS) — skipping (no Claude call)" >> "$LOG"
+  exit 0
+fi
+
+# Allow an override via env; if still not found, log a clear error and skip.
+CLAUDE_BIN="${CLAUDE_BIN:-$(command -v claude || true)}"
+if [ -z "$CLAUDE_BIN" ]; then
+  echo "$(ts) [error] 'claude' not found on PATH — check the claude install in WSL (e.g. ~/.local/bin/claude)" >> "$LOG"
+  exit 0
+fi
+
+# The chosen account's token expired -> try to refresh with 'claude /usage' (startup refresh).
+# (Switching accounts was done in the CLAUDE_CONFIG_DIR selection above.) Best-effort, doesn't block.
+if [ -n "${CLAUDE_CONFIG_DIR:-}" ] && [ "${CFG_CLAUDE_EXPIRED:-0}" = "1" ]; then
+  echo "$(ts) [cfg] token expired -> refreshing with 'claude /usage'" >> "$LOG"
+  "$CLAUDE_BIN" /usage >/dev/null 2>&1 || true
+fi
+
+# --- Token gate (moved from /auto-cycle Step 0 to here) ---------------------------------------
+# Reason: check quota BEFORE calling Claude so we don't spend tokens just to start + self-stop when
+# quota is already high. Thresholds from settings: session_pct < max_session_pct AND weekly_pct < max_weekly_pct.
+USAGE_JSON="$PROJECT_DIR/.claude/skills/check-usage/output/last-usage-check.json"
+if ! "$PY_BIN" "$PROJECT_DIR/.claude/skills/check-usage/check_usage.py" >> "$LOG" 2>&1; then
+  echo "$(ts) [skip] check_usage.py failed (can't read quota) — skipping to be safe" >> "$LOG"
+  exit 0
+fi
+GATE="$(MAXS="$CFG_MAX_SESSION_PCT" MAXW="$CFG_MAX_WEEKLY_PCT" "$PY_BIN" - "$USAGE_JSON" <<'PY'
+import json, os, sys
+try:
+    d = json.load(open(sys.argv[1], encoding="utf-8"))
+    s = float(d.get("session_pct", 100))
+    w = float(d.get("weekly_pct", 100))
+    maxs = float(os.environ.get("MAXS", "80"))
+    maxw = float(os.environ.get("MAXW", "90"))
+except Exception as e:
+    print(f"ERR {e}")
+    sys.exit(0)
+print(f"{'OK' if (s < maxs and w < maxw) else 'HIGH'} session={s:.0f}% weekly={w:.0f}% (max {maxs:.0f}/{maxw:.0f})")
+PY
+)"
+case "$GATE" in
+  OK*)   echo "$(ts) [gate] tokens ok ($GATE) — continue" >> "$LOG" ;;
+  HIGH*) echo "$(ts) [skip] tokens high ($GATE) — skipping this tick" >> "$LOG"
+         hist record "$(ts)" skip "" "$GATE" "tokens high — skipped" 2>>"$LOG" || true; exit 0 ;;
+  *)     echo "$(ts) [skip] can't read usage ($GATE) — skipping to be safe" >> "$LOG"
+         hist record "$(ts)" skip "" "$GATE" "can't read usage" 2>>"$LOG" || true; exit 0 ;;
+esac
+# -----------------------------------------------------------------------------------------------
+
+# Record 1 tick that ACTUALLY calls Claude (for max_ticks_per_day) — stored in ticks{day,count}.
+tick_count=$(( ${tick_count:-0} + 1 ))
+hist set-ticks "$TODAY" "$tick_count" 2>>"$LOG" || true
+
+echo "$(ts) [run] starting $CFG_COMMAND (tick $tick_count/$TODAY)" >> "$LOG"
+# No GUI window (cron has no desktop session). Everything goes to "$LOG"; watch it live with:
+#   tail -f .claude/logs/autonomous-tick-$(date +%F).log
+
+# Headless: -p runs one cycle then exits. No permission prompts (unattended on WSL).
+# Force the model if settings has 'model' (empty array is safe under set -u via ${arr[@]+...}).
+MODEL_ARGS=()
+[ -n "$CFG_MODEL" ] && MODEL_ARGS=(--model "$CFG_MODEL")
+set +e
+"$CLAUDE_BIN" -p "$CFG_COMMAND" \
+  ${MODEL_ARGS[@]+"${MODEL_ARGS[@]}"} \
+  --permission-mode bypassPermissions \
+  --dangerously-skip-permissions \
+  >> "$LOG" 2>&1
+RC=$?
+set -e
+
+# --- Record the run + count consecutive failures + auto-stop (stop_on_consecutive_failures) ----
+# RC != 0 -> increment; reaching the threshold -> set paused=true (needs a manual resume). RC == 0 -> reset.
+# The consecutive-failure count is stored under consecutive_fails in .autonomous.histories.json.
+fails="$(hist get-fails 2>/dev/null || echo 0)"; [ -z "$fails" ] && fails=0
+if [ "$RC" -ne 0 ]; then
+  echo "$(ts) [warn] $CFG_COMMAND exited $RC" >> "$LOG"
+  fails=$(( ${fails:-0} + 1 )); hist set-fails "$fails" 2>>"$LOG" || true
+  hist record "$(ts)" failure "$RC" "$GATE" "consecutive failure #$fails" 2>>"$LOG" || true
+  if [ "${CFG_STOP_ON_CONSEC_FAILURES:-0}" -gt 0 ] 2>/dev/null && [ "$fails" -ge "$CFG_STOP_ON_CONSEC_FAILURES" ]; then
+    "$PY_BIN" - "$SETTINGS" <<'PY' 2>>"$LOG" || true
+import json, sys
+p = sys.argv[1]
+try:
+    d = json.load(open(p, encoding="utf-8"))
+    d["paused"] = True
+    with open(p, "w", encoding="utf-8") as f:
+        json.dump(d, f, ensure_ascii=False, indent=2); f.write("\n")
+except Exception:
+    pass
+PY
+    echo "$(ts) [stop] $fails consecutive failures >= $CFG_STOP_ON_CONSEC_FAILURES → set paused=true (resume manually)" >> "$LOG"
+  fi
+else
+  hist set-fails 0 2>>"$LOG" || true   # success → reset the consecutive-failure count
+  hist record "$(ts)" success "$RC" "$GATE" "cycle complete" 2>>"$LOG" || true
+fi
+
+# notify_webhook: TBD — this is where a run summary would be POSTed to a webhook if CFG_NOTIFY_WEBHOOK is set.
+
+echo "$(ts) [done] tick finished" >> "$LOG"
+# The EXIT trap above removes `.autonomous.lock` if /auto-cycle didn't → the lock is released.

package/dist/project-sample/.claude/settings.json

@@ -0,0 +1,17 @@
+{
+  "$schema": "https://json.schemastore.org/claude-code-settings.json",
+  "model": "claude-opus-4-8",
+  "cleanupPeriodDays": 30,
+  "env": {
+    "XNDP_ENV": "development"
+  },
+  "permissions": {
+    "defaultMode": "bypassPermissions",
+    "allow": [],
+    "ask": [],
+    "deny": [
+      "Read(./project.secrets.json)"
+    ]
+  },
+  "enableAllProjectMcpServers": true
+}

package/dist/project-sample/.claude/skills/check-usage/SKILL.md

@@ -0,0 +1,40 @@
+---
+name: check-usage
+description: Show Claude Code plan usage limits — current session % and reset time, weekly % and reset time (same data as the built-in /usage screen). Use when the user asks "how much usage left", "khi nao reset", "check usage/quota/limit", or invokes /check-usage.
+---
+
+# check-usage — Claude Code plan usage limits
+
+Fetches the same data the built-in `/usage` screen shows (session + weekly utilization and
+reset times), by calling the Anthropic OAuth usage endpoint with the local credentials.
+
+## How to run
+
+Run the bundled script with the Bash tool. It prints a compact bullet list to the console;
+relay that output to the user.
+
+```bash
+python .claude/skills/check-usage/check_usage.py
+```
+
+On Windows if `python` is missing, try `py .claude/skills/check-usage/check_usage.py`.
+
+Add `--json` to dump the raw API response instead of the formatted view:
+
+```bash
+python .claude/skills/check-usage/check_usage.py --json
+```
+
+## Output file
+Every run (the formatted view, not `--json`) rewrites `./output/last-usage-check.json` next to
+the script: it deletes the previous file then creates a fresh one with this run's result. The
+record has machine-readable fields the autonomous workflow reads back:
+`session_pct`, `weekly_pct`, `session_resets_at`, `weekly_resets_at`, `checked_at`, `plan`,
+plus the human `summary` and the full `raw` API payload.
+
+## Notes
+- Reads the OAuth access token from `~/.claude/.credentials.json` (Claude Code keeps it refreshed).
+- If the call returns HTTP 401, the token expired — tell the user to run the real `/usage` once
+  inside Claude Code (or re-login) to refresh credentials, then retry.
+- Reset times are printed in the machine's local timezone with a "con Xh Ym" countdown.
+- Do not print the access token.

package/dist/project-sample/.claude/skills/check-usage/check_usage.py

@@ -0,0 +1,161 @@
+#!/usr/bin/env python3
+"""Fetch Claude Code plan-usage limits (same data as the built-in /usage screen).
+
+Reads the OAuth access token from ~/.claude/.credentials.json and queries the
+Anthropic usage endpoint, then prints session + weekly utilization and reset times
+in the local timezone.
+"""
+import json
+import os
+import subprocess
+import sys
+import urllib.request
+import urllib.error
+from datetime import datetime, timezone
+
+# Windows consoles default to cp1252 which can't encode the emoji/bar glyphs.
+for _s in (sys.stdout, sys.stderr):
+    try:
+        _s.reconfigure(encoding="utf-8")
+    except Exception:
+        pass
+
+CRED_PATH = os.path.expanduser("~/.claude/.credentials.json")
+URL = "https://api.anthropic.com/api/oauth/usage"
+
+
+class UsageError(Exception):
+    """Recoverable failure while loading the token or calling the usage API.
+    Raised (instead of exiting) so the caller can refresh the token and retry once."""
+
+
+def load_token():
+    try:
+        with open(CRED_PATH, "r", encoding="utf-8") as f:
+            data = json.load(f)
+    except FileNotFoundError:
+        raise UsageError(f"Credentials not found: {CRED_PATH} (log in to Claude Code first).")
+    oauth = data.get("claudeAiOauth", data)
+    token = oauth.get("accessToken")
+    if not token:
+        raise UsageError("No accessToken in credentials.")
+    exp = oauth.get("expiresAt")
+    if exp and datetime.now(timezone.utc).timestamp() * 1000 > exp:
+        print("Warning: token may be expired — run /usage once in Claude Code to refresh.\n",
+              file=sys.stderr)
+    return token, oauth.get("subscriptionType", "?")
+
+
+def fetch(token):
+    req = urllib.request.Request(URL, headers={
+        "Authorization": f"Bearer {token}",
+        "anthropic-beta": "oauth-2025-04-20",
+        "User-Agent": "claude-cli/2.0.0 (external, cli)",
+    })
+    try:
+        with urllib.request.urlopen(req, timeout=20) as r:
+            return json.load(r)
+    except urllib.error.HTTPError as e:
+        body = e.read().decode("utf-8", "replace")[:300]
+        raise UsageError(f"API error HTTP {e.code}: {body}")
+    except urllib.error.URLError as e:
+        raise UsageError(f"Could not reach API: {e.reason}")
+
+
+def get_usage():
+    """Load the token and query the usage API. Raises UsageError on any failure."""
+    token, sub = load_token()
+    return fetch(token), sub
+
+
+def refresh_token():
+    """Best-effort token refresh: run `claude /usage`, which refreshes the OAuth
+    token on startup. On Windows we go through `wsl` (the credentials this script
+    reads live in WSL); on POSIX we call `claude` directly. Output is discarded and
+    the call is bounded by a timeout so it can never hang the usage check."""
+    cmd = ["wsl", "claude", "/usage"] if sys.platform == "win32" else ["claude", "/usage"]
+    print(f"Refreshing token via: {' '.join(cmd)}", file=sys.stderr)
+    try:
+        subprocess.run(
+            cmd, timeout=60,
+            stdin=subprocess.DEVNULL,
+            stdout=subprocess.DEVNULL,
+            stderr=subprocess.DEVNULL,
+        )
+    except Exception as e:
+        print(f"Token refresh attempt failed: {e}", file=sys.stderr)
+
+
+def fmt_reset(iso):
+    if not iso:
+        return "?"
+    dt = datetime.fromisoformat(iso).astimezone()  # -> local tz
+    return f"{dt:%a %d/%m %H:%M}"
+
+
+def save_last_result(record):
+    """Delete the previous ./output/last-usage-check.json, then write a fresh one
+    holding this run's result. Console output is still printed by the caller."""
+    out_dir = os.path.join(os.path.dirname(os.path.abspath(__file__)), "output")
+    os.makedirs(out_dir, exist_ok=True)
+    out_path = os.path.join(out_dir, "last-usage-check.json")
+    # Remove the stale file first, then recreate it from scratch.
+    try:
+        os.remove(out_path)
+    except FileNotFoundError:
+        pass
+    with open(out_path, "w", encoding="utf-8") as f:
+        json.dump(record, f, ensure_ascii=False, indent=2)
+    return out_path
+
+
+def main():
+    try:
+        data, sub = get_usage()
+    except UsageError as e:
+        # First attempt failed — try to refresh the token once, then retry once.
+        print(f"Usage check failed: {e}", file=sys.stderr)
+        refresh_token()
+        try:
+            data, sub = get_usage()
+        except UsageError as e2:
+            print(f"Still failing after token refresh — skipping: {e2}", file=sys.stderr)
+            sys.exit(1)
+
+    if "--json" in sys.argv:
+        print(json.dumps(data, indent=2))
+        return
+
+    fh = data.get("five_hour") or {}
+    sd = data.get("seven_day") or {}
+
+    lines = [
+        f"- Plan: {sub}",
+        f"- Session: {fh.get('utilization', 0):.0f}% — reset {fmt_reset(fh.get('resets_at'))}",
+        f"- Weekly: {sd.get('utilization', 0):.0f}% — reset {fmt_reset(sd.get('resets_at'))}",
+    ]
+    extra = data.get("extra_usage") or {}
+    if extra.get("is_enabled") and extra.get("used_credits"):
+        dp = extra.get("decimal_places", 2)
+        lines.append(f"- Extra: {extra['used_credits'] / (10 ** dp):.2f} {extra.get('currency', 'USD')}")
+
+    summary = "\n".join(lines)
+    print(summary)  # keep the console output
+
+    # Persist this run's result so the autonomous workflow can read it back.
+    record = {
+        "checked_at": datetime.now().astimezone().isoformat(timespec="seconds"),
+        "plan": sub,
+        "session_pct": fh.get("utilization", 0),
+        "weekly_pct": sd.get("utilization", 0),
+        "session_resets_at": fh.get("resets_at"),
+        "weekly_resets_at": sd.get("resets_at"),
+        "summary": summary,
+        "raw": data,
+    }
+    out_path = save_last_result(record)
+    print(f"\nSaved result to: {out_path}")
+
+
+if __name__ == "__main__":
+    main()

package/dist/project-sample/.claude/templates/AI_DONE.empty.md

@@ -0,0 +1,9 @@
+# AI_DONE — Completed tasks + incidents
+
+> The autonomous cycle appends completed tasks here (ID, description, timestamp) and logs incidents/notes.
+
+## Done
+_(none)_
+
+## Incidents / notes
+_(none)_

package/dist/project-sample/.claude/templates/AI_DONE.sample.md

@@ -0,0 +1,7 @@
+# AI_DONE — Completed tasks + incidents
+
+## Done
+- 2026-01-01 10:00 · TSK-0001-0001 · Added login-form validation. Files: src/auth/login.ts.
+
+## Incidents / notes
+- 2026-01-01 10:05 · Cycle only generated tasks; waiting for VERIFY approval.

package/dist/project-sample/.claude/templates/AI_PLACEHOLDER.empty.md

@@ -0,0 +1,11 @@
+# AI_PLACEHOLDER — Placeholder table (key + explanation)
+
+> Lists **placeholders** the AI understands: each has a **key** and an **explanation**. Reference them in
+> docs/config as `${key}$` (e.g. `${ai_dev_branch}$`); the tool substitutes the real **value** at runtime.
+>
+> **Where values live:** the real value of each key is stored in `project.secrets.json` (same folder). This
+> file holds only keys + explanations, so it is **safe to commit** and the AI can read it for context.
+
+| Key | Explanation |
+|-----|-------------|
+| ai_dev_branch | The shared dev branch the AI merges tasks into before the main branch. |

package/dist/project-sample/.claude/templates/AI_PLACEHOLDER.sample.md

@@ -0,0 +1,9 @@
+# AI_PLACEHOLDER — Placeholder table (key + explanation)
+
+> Reference placeholders as `${key}$`. Real values live in `project.secrets.json` (not committed).
+
+| Key | Explanation |
+|-----|-------------|
+| ai_dev_branch | The shared dev branch the AI merges tasks into before the main branch. |
+| api_base_url | Base URL of the internal API the AI calls during integration tests. |
+| api_key | Key for the internal API (real value in project.secrets.json, NOT committed). |

package/dist/project-sample/.claude/templates/AI_PROGRESS.empty.md

@@ -0,0 +1,5 @@
+# AI_PROGRESS — Task in progress
+
+> The current in-progress task (set when the cycle starts a task, cleared when it finishes).
+
+_(no task in progress)_

package/dist/project-sample/.claude/templates/AI_PROGRESS.sample.md

@@ -0,0 +1,3 @@
+# AI_PROGRESS — Task in progress
+
+- Started 2026-01-01 10:00 · TSK-0001-0001 · Add login-form validation.

package/dist/project-sample/.claude/templates/AI_TODO.empty.md

@@ -0,0 +1,14 @@
+# AI_TODO — Task queue (generated by the AI)
+
+> Tasks are generated from `USER_TODO.md`. ID format `TSK-{groupid:0000}-{taskid:0000}`
+> (group = one request/batch, task = a small sub-task doable in ~1 cycle).
+> **Priority** = High / Medium / Low.
+> **Approved**: the source of truth is `.claude/.autonomous.approvals.json` (the user ticks it in the
+> web VERIFY tab — ADR-0152); the Approved column here is display-only, not where the decision is made.
+> **Depends** = the `TSK-…` ids that must be DONE (present in `AI_DONE.md`) first.
+> `/auto-cycle` only takes tasks that are approved AND have their dependencies met → moves them to
+> `AI_PROGRESS.md`; runs group by group, within a group High → Medium → Low.
+
+| ID | Priority | Approved | Depends | Group | Task description | Notes |
+|----|----------|----------|---------|-------|------------------|-------|
+| | | | | | | |

package/dist/project-sample/.claude/templates/AI_TODO.sample.md

@@ -0,0 +1,10 @@
+# AI_TODO — Task queue (generated by the AI)
+
+> Tasks are generated from `USER_TODO.md`. ID format `TSK-{groupid:0000}-{taskid:0000}`.
+> **Priority** = High / Medium / Low. **Approved** source of truth = `.claude/.autonomous.approvals.json`
+> (web VERIFY tab). **Depends** = `TSK-…` ids that must be in `AI_DONE.md` first.
+
+| ID | Priority | Approved | Depends | Group | Task description | Notes |
+|----|----------|----------|---------|-------|------------------|-------|
+| TSK-0001-0001 | High | ✓ | | Auth | Add login-form validation per docs/auth.md | |
+| TSK-0001-0002 | Medium |  | TSK-0001-0001 | Auth | Wire the login API call + error handling | After 0001 |