# Hv Config > **Print the banner below verbatim before any other action — skip if dispatched as a subagent.** See `references/banner-preamble.md`. - Skill: `l4ci/hv-config` (Agent Skill) - Install (CLI): `npx skillmds@latest add l4ci/hv-config` - Raw SKILL.md: https://api.skillmd.com/api/skills/l4ci/hv-config/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Coding & Dev Tools - Author: l4ci (https://skillmd.com/u/l4ci) - Updated: 2026-09-17 - Page: https://skillmd.com/skills/l4ci/hv-config --- **Print the banner below verbatim before any other action — skip if dispatched as a subagent.** See `references/banner-preamble.md`. ``` ════════════════════════════════════════════════════════════════════════ 🔧 hv-config · change project settings interactively triggers: "change config", "edit settings" · pairs: hv-init ════════════════════════════════════════════════════════════════════════ ``` # hv-config — Edit `.hv/config.json` Interactively Change one or more configuration values without hand-editing JSON. Same option vocabulary as `/hv-init`, but you pick exactly which keys to change and the rest stay untouched. > **Authoring note (when adding a new flag):** boolean opt-in feature flags default to `false`. Owning skills flip them to `true` only via explicit user approval — never silently on first detection. `/hv-config` edits them explicitly. See the *Authoring rule* section in `hv-init/SKILL.md` for the full rule + exemptions. ## When to Use - Toggle a single setting — *"switch to worktree isolation"*, *"turn autonomy on loop"* - Adjust a few keys at once after the project has matured - You forgot the exact JSON path for a setting - Apply a single known value fast — `/hv-config work.isolation=worktree` ## When NOT to Use - First-time setup → `/hv-init` writes the whole file from scratch - Just inspecting current values → `cat .hv/config.json` - Adding a brand-new key after a plugin upgrade → `/hv-init` runs the STALE migration and asks only for the missing key ## Step 1 — Preflight ```bash .hv/bin/hv-preflight ``` See `docs/reference/preflight.md` for exit-code handling. **Initialize task list.** Follow the canonical pattern in `references/task-list-init.md` — load `TaskCreate(…)` via `ToolSearch select:TaskCreate,TaskUpdate` if needed, then create one task per phase below. Phases: 1. *Parse positional args* — empty / `` / `=` shapes resolved (Step 1.5) 2. *Pick keys* — category-then-keys two-stage selection (Steps 2–3) 3. *Validate* — new values normalized and checked against allowed sets (Step 4) 4. *Write* — `.hv/config.json` updated; managed CLAUDE.md blocks regenerated if relevant (Steps 5–6) ## Step 1.5 — Parse Positional Arguments Inspect `$ARGUMENTS`. The skill supports three invocation shapes: | Shape | Behavior | |-------|----------| | Empty / whitespace only | Continue to Step 2 — full guided flow. | | `` (no `=`) | Skip Step 2 and Step 3. Treat `` as the single picked key; jump straight to Step 4. | | `=` | Skip Steps 2–4. Validate, apply directly via `hv-config-set`, jump to Step 6. | **Split on the FIRST `=` only.** Free-text keys (`docs.path`, `git.baseBranch`) may contain `=` in their values; later `=` characters belong to the value. **Trim whitespace** around the key and around the value. `docs.path=` (empty value after `=`) is valid for free-text keys and writes the empty string. **Validate ``** against the canonical list. Valid keys (exact match required, case-sensitive): - `models.orchestrator`, `models.worker` - `work.isolation`, `work.mergeStrategy`, `work.dispatch`, `work.workerSlots`, `work.workerCommand`, `work.accounts`, `work.operatorCommand` - `ship.review`, `ship.secondOpinion`, `learn.verify`, `refactor.confirmBeforeExecute`, `debug.competingHypotheses` - `learn.promoteThreshold` - `autonomy.level` - `docs.path`, `docs.autoCreate`, `docs.afterWork` - `git.baseBranch` - `umbrella.enabled` - `issues.label`, `issues.autoCreateLabel`, `issues.filterMineOnly`, `issues.providers.github`, `issues.providers.gitlab` Unknown key → stop with: *"Error: `` is not a configurable setting. Run `/hv-config` with no arguments to see the full list."* Do **not** silently fall through to the guided flow — the positional invocation is an explicit ask for one specific key. **Validate ``** when present, against the allowed values for that key from `docs/reference/config-options.md`: - Enum keys (`work.isolation`, `work.mergeStrategy`, `work.dispatch`, `autonomy.level`, `models.orchestrator`, `models.worker`) — value must be one of the documented options. `work.dispatch` accepts `subagent` or `tmux`. - Boolean keys (`ship.review`, `ship.secondOpinion`, `learn.verify`, `refactor.confirmBeforeExecute`, `debug.competingHypotheses`, `docs.autoCreate`, `docs.afterWork`, `umbrella.enabled`, `issues.autoCreateLabel`, `issues.filterMineOnly`, `issues.providers.github`, `issues.providers.gitlab`) — accept `true`, `false`, `on`, `off` (case-insensitive). Normalize `on`/`off` to `true`/`false`. Anything else is invalid. - JSON-array keys (`refactor.verifyCommands`, `work.accounts`) — value must parse as a JSON array; `work.accounts` entries need a `name` and a `configDir`. Not offered in the guided flow; set via `hv-config-set work.accounts '[{"name":"personal","configDir":"~/.claude"}]'`. - Free-text keys (`docs.path`, `git.baseBranch`, `issues.label`, `work.workerCommand`, `work.operatorCommand`) — accept any value including the empty string. - Integer keys (`learn.promoteThreshold`, `work.workerSlots`) — accept any non-negative integer (≥0) as a string of digits. Anything else (negative, non-numeric, decimal) is invalid. `work.workerSlots` additionally rejects `0` — a pool with no slots cannot dispatch. Invalid value → stop with: *"Error: `` is not a valid value for ``. Allowed: ."* On the `` (no `=`) path, carry the single key forward as the only picked key in Step 4 — that one question is asked, the user's answer is written, then jump to Step 6. On the `=` path, write directly: ```bash .hv/bin/hv-config-set ``` Then jump to Step 6 to print the one-line diff. ## Step 2 — Read & Display Current Config ```bash python3 - <<'PY' import json from pathlib import Path cfg = json.loads(Path(".hv/config.json").read_text()) def profile(o, w): pairs = { ("opus","sonnet"): "Balanced", ("opus","opus"): "Premium", ("sonnet","sonnet"): "Fast", ("sonnet","haiku"): "Minimal", } return pairs.get((o,w), f"Custom ({o} + {w})") m = cfg.get("models", {}) o, w = m.get("orchestrator"), m.get("worker") print("Current configuration:") print(f" Models {profile(o, w)} ({o} + {w})") print(f" Isolation {cfg.get('work',{}).get('isolation','branch')}") print(f" Integration {cfg.get('work',{}).get('mergeStrategy','direct')}") print(f" Ship review {'on' if cfg.get('ship',{}).get('review',True) else 'off'}") print(f" Ship second-opinion {'on' if cfg.get('ship',{}).get('secondOpinion',False) else 'off'}") print(f" Verify learnings {'on' if cfg.get('learn',{}).get('verify',True) else 'off'}") print(f" Confirm before refactor {'on' if cfg.get('refactor',{}).get('confirmBeforeExecute',True) else 'off'}") print(f" Autonomy {cfg.get('autonomy',{}).get('level','off')}") print(f" Competing hypotheses {'on' if cfg.get('debug',{}).get('competingHypotheses',False) else 'off'}") print(f" Docs path {cfg.get('docs',{}).get('path','docs')}") print(f" Docs auto-create {'on' if cfg.get('docs',{}).get('autoCreate',False) else 'off'}") print(f" Docs after-work {'on' if cfg.get('docs',{}).get('afterWork',False) else 'off'}") print(f" Git base branch {cfg.get('git',{}).get('baseBranch','') or '(auto-detect)'}") print(f" Umbrella mode {'on' if cfg.get('umbrella',{}).get('enabled',False) else 'off'}") iss = cfg.get('issues', {}) prov = iss.get('providers', {}) print(f" Issues label {iss.get('label','in-progress')}") print(f" Issues auto-create label {'on' if iss.get('autoCreateLabel',True) else 'off'}") print(f" Issues filter mine only {'on' if iss.get('filterMineOnly',False) else 'off'}") print(f" Issues GitHub provider {'on' if prov.get('github',True) else 'off'}") print(f" Issues GitLab provider {'on' if prov.get('gitlab',True) else 'off'}") print(f" hv-skills version {cfg.get('hvSkills',{}).get('version','') or '(unstamped)'}") PY ``` Print the helper output verbatim — the user needs to see what they're editing. `hv-skills version` is auto-stamped by `/hv-init`; not in the edit list. ## Step 3 — Pick Which Keys to Change Skip this step entirely when Step 1.5 parsed a `` or `=` argument — the key is already picked (or already written). The 18 configurable keys group into 5 categories; pick categories first, then drill into the keys in each. This two-stage flow keeps every question within `AskUserQuestion`'s 4-option UI cap. ### Stage A — Pick categories Two `AskUserQuestion` calls in sequence (both multiSelect), because 5 categories exceed the 4-option ceiling. Aggregate the picks from both calls before Stage B. **Call A1:** - **Header:** `"Edit"` - **Question:** *"Which areas of config do you want to edit? (1 of 2)"* - **multiSelect:** `true` - **Options:** 1. *"Work — models, isolation, integration, autonomy"* 2. *"Quality gates — ship review, verify learnings, refactor confirm, competing hypotheses"* 3. *"Docs — path, auto-create, after-work"* 4. *"Other — umbrella mode, git base branch"* **Call A2:** - **Header:** `"Edit"` - **Question:** *"Any further areas? (2 of 2)"* - **multiSelect:** `true` - **Options:** 1. *"Issues — label, auto-create label, filter mine only, providers"* If the user selects nothing across both calls, print *"No changes."* and stop. ### Stage B — Pick keys within each category For each category the user selected in Stage A, issue one `AskUserQuestion` call with the keys in that category. Substitute the live values from Step 2 into each option label so the user sees what they're replacing. Aggregate the picks across all category calls into a single set before Step 4. | Category | Keys (multiSelect, ≤4 per call) | |----------|---------------------------------| | Work | *"Models — current: "*, *"Isolation — current: "*, *"Integration — current: "*, *"Autonomy — current: "* | | Quality gates | Two calls (5 keys exceed cap): **call 1** — *"Ship review — current: "*, *"Ship second-opinion — current: "*, *"Verify learnings — current: "*, *"Confirm before refactor — current: "*; **call 2** — *"Competing hypotheses — current: "* | | Docs | *"Docs path — current: "*, *"Docs auto-create — current: "*, *"Docs after-work — current: "* | | Other | *"Umbrella mode — current: "*, *"Git base branch — current: "* | | Issues | Two calls (5 keys exceed cap): **call 1** — *"Issues label — current: