/settings — view or change project config

Manages project.yaml (team-wide config, committed) and project.local.yaml (per-developer overrides, gitignored). Use this skill to inspect current settings or change them without manually editing YAML.

Automation mode: Resolve modes.automation (project.local.yaml → project.yaml → default collaborative). The approval gates in Phase 4 and Phase 5 follow the pattern in .claude/docs/automation-modes.md. Note: writing to project.yaml is a schema_changes decision (a default automation_always_ask category), so /settings confirms config writes even in autonomous mode unless the user has removed schema_changes from their always-ask list.

Phase 0: Parse Arguments

Determine which of the four forms the user invoked:

For Set-yaml and Set-local, <key> is a dotted YAML path (e.g. modes.review_mode, testing.strict.logic) and <value> is the new value.

Empty-operand validation: After splitting the key=value operand on =, if either <key> or <value> is empty, this is malformed — route to Phase 6 (usage) rather than attempting the write. The rule applies in both Set-yaml and Set-local routing: for --local, strip the --local token first, then check the remaining operand the same way (so /settings --local =foo and /settings --local key= both go to Phase 6).

Anything else that doesn't match the four forms above → Phase 6 (usage).

Phase 1: Load Helper

All four subcommands need yaml-helper.sh. Source it once via Bash:

source "${CLAUDE_PROJECT_DIR:-.}/.claude/hooks/yaml-helper.sh"

If .claude/hooks/yaml-helper.sh is missing, this is not a CCGS project. Report the error and exit.

Phase 1b: Reserved-setting detection

Some settings are fully documented, enum-validated and settable, and no skill or hook reads them — setting one changes nothing. This skill must say so. Returning an ordinary success lets a user reasonably believe the behaviour the setting describes is now enforced — an accessibility tier being the case that motivates this. (The key is not named here on purpose; see the note below.) The banner exists only in .claude/docs/effects-map.md, which someone configuring their project will never open. A setting that does nothing must never look exactly like one that works — .claude/rules/skill-authoring.md obligation 3.

Derive the set; do not hardcode it (obligation 5):

grep -B14 '^> ### RESERVED' .claude/docs/effects-map.md | grep -E '^## '

Match the banner HEADING (> ### RESERVED), never the bare word "RESERVED". platform.cert_tier's section mentions the banner in prose, to record that it carried one and later became a live setting. A looser match re-reports a working setting as dead — the direction that understates what the framework does, and why the dead-settings gate asserts both directions.

A heading may name two keys joined by " and " — split on that separator so both are captured, or the second one silently escapes the set. Let RESERVED_SET be the result.

Deliberately phrased without naming those keys. The dead-settings gate asserts that a setting on the allowlist has no readers, and it counts any skill file that spells the key. Naming them here to illustrate the split would make /settings register as a reader of two settings nothing reads, and the gate would fail — correctly. Spelling a dead path out while explaining why not to use it trips the same wire. Reword instead of adding an exemption: the strictness is the point, so do not re-introduce the literal names to make an example clearer.

Never refuse a write to a reserved key. Storing the value a user intends is legitimate; storing it silently is the defect.

Phase 2: View-all Mode

(when no arguments)

1. Confirm project.yaml exists. If missing, report:

   "No project.yaml found — run /start to create one." And exit.

2. Check if project.local.yaml exists.

3. Run validate_yaml_enum project.yaml and capture any errors. If project.local.yaml exists, also run validate_yaml_enum project.local.yaml. Tag each error with its source file so the user can tell them apart.

4. Enumerate leaves. Use the Read tool to read both YAML files as text. Walk through each file's structure and collect every leaf key into a deduplicated list of dotted paths. A leaf is a key: value line whose value is non-empty (a scalar or inline-array) — NOT a parent block that introduces a nested map. Maintain insertion order per file; merge by appending leaves from project.local.yaml that aren't already present from project.yaml. The resulting list is the set of leaves to display.

   Then append the rigor family — modes.rigor, modes.workflow, docs.density, qa.level, modes.story_granularity, modes.review_mode, team.size — for any of the seven the merged list does not already contain. These are normally leaves of neither file: modes.rigor has a terminal default and the other six are supplied by the rigor expansion (modes.review_mode and team.size may also appear as file leaves when set locally, but must still be appended so their derived value shows). Enumerating only file leaves would hide exactly the settings a user just chose, in the one view meant to show them.

5. For each leaf, perform three reads and one check:

   • resolve_setting <path> → <value>, TAB, <source>. This walks the whole chain (project.local.yaml → project.yaml → legacy file → rigor expansion → default), so it is the only read that can report a derived value or name what supplied it.
   • get_yaml_key project.yaml <path> → yaml-only value (needed only to show what a local override is shadowing)
   • is_locally_overridable <path> → 0 (overridable) or 1 (locked)

   Compute the source annotation from <source>:

   <source>	Annotation
   project.local.yaml, yaml-only value non-empty	(LOCAL OVERRIDE — yaml has: <yamlvalue>)
   project.local.yaml, yaml-only value empty	(project.local.yaml)
   project.yaml	(project.yaml)
   a legacy file path (e.g. production/review-mode.txt)	(<path>, legacy)
   rigor:<level>	(derived from rigor: <level>)
   default	(default)
   unset	skip the leaf (don't print unset keys)

   Append , locked to the annotation when is_locally_overridable returned 1.

   Append , reserved when the leaf is in RESERVED_SET (Phase 1b), and print this line with the legend below the block:

   reserved = stored and validated, but nothing reads it. Setting it changes
   no behaviour today.
   

   All four phases must carry the reserved marking — view-one, view-all, and both write paths. Marking view-one and the writes while leaving view-all — the most-used form of this skill — unmarked means a user who set a reserved key sees it listed beside working settings with an ordinary (project.yaml) annotation, in the view most people actually run. Guard all four: view-one and view-all are twins in exactly the way the two write paths are.

6. Print, grouped by top-level section (framework, modes, engine, etc.) in the order leaves first appeared. The grouping is determined by the dotted path, not by which file the leaf came from — e.g. modes.automation groups under modes: even if only project.local.yaml defines it. Within each section, indent leaves by 2 spaces; nest further for sub-blocks (e.g. testing.strict.*). Example output:

project.yaml: present
project.local.yaml: present

Schema validation: ok

Effective config:

framework:
  version: 1.1.1            (project.yaml, locked)

modes:
  review_mode: lean         (project.yaml)
  automation: autonomous    (LOCAL OVERRIDE — yaml has: collaborative)
  rigor: full               (project.yaml, locked)
  workflow: full            (derived from rigor: full, locked)
  story_granularity: fine   (derived from rigor: full, locked)

docs:
  density: terse            (project.yaml, locked)

qa:
  level: full               (derived from rigor: full, locked)

engine:
  name: Godot               (project.yaml, locked)
  version: 4.6              (project.yaml, locked)

testing:
  strict:
    logic: false            (LOCAL OVERRIDE — yaml has: true)
    integration: true       (project.yaml)

locked = cannot be overridden in project.local.yaml (project-wide setting).
It does NOT mean fixed: a derived value can still be set explicitly with
/settings <key>=<value>, and an explicit value wins over rigor.

Print that two-line legend after the config block whenever any rendered line carries locked. Without it users read locked as "immutable" and conclude a rigor-derived knob cannot be changed — the opposite of what Phase 3's view-one tells them for the same knob ("an explicit value wins over rigor"). The two views must not leave contradictory impressions of the same knob's mutability.

The docs.density line above is the precedence rule made visible: an explicit project.yaml value keeps winning over the level rigor would otherwise derive, so "comprehensive but compact" stays expressible.

If schema errors exist, print them in this form before the effective config block:

Schema validation: ERRORS
  [project.yaml] modes.review_mode: 'chaotic' is not a valid value (expected: full|lean|solo)
  [project.local.yaml] engine.name: 'Pygame' is not a valid value (expected: Godot|Unity|Unreal)

Phase 3: View-one Mode

(when single arg, no =)

If <key> is in RESERVED_SET, print this BEFORE the value block — above, not below. A caveat under a value reads as a footnote on a working setting:

<key> is RESERVED — nothing reads it. The value below is stored and validated; it changes no behaviour today.

Let <key> be the argument. Perform four reads:

1. resolve_setting <key> → <value>, TAB, <source> (effective value + provenance)
2. get_yaml_key project.yaml <key> → yaml-only value
3. get_yaml_key project.local.yaml <key> → local-only value (skip if file absent)
4. is_locally_overridable <key> → 0 (overridable) or 1 (locked)

Determine the source from <source> (same table as Phase 2 step 5) and the Locally overridden status:

• yes if the local-only value is non-empty
• no otherwise

Print:

<key>

  Effective value: <effective-value or "(not set)" if <source> is unset>
  Source: <project.yaml | project.local.yaml | project.local.yaml (overrides project.yaml) | derived from rigor: <level> | default>
  Locally overridden: <yes | no>
  Whitelist: <"can be locally overridden" if is_locally_overridable returned 0, else "locked — project-wide">

When both files set the key (the LOCAL OVERRIDE case), add two more lines under Source:

  project.yaml value: <yamlvalue>
  project.local.yaml value: <localvalue>

When <source> is rigor:<level>, add one line under Source so the user knows the value is settable and how:

  Set explicitly with: /settings <key>=<value>   (an explicit value wins over rigor)

When the effective value is empty (key not set anywhere), print just:

<key>

  Effective value: (not set)
  Locally overridden: no
  Whitelist: <"can be locally overridden" | "locked — project-wide">

Phase 4: Set-yaml Mode

(when <key>=<value>, no --local)

1. Schema validation: call validate_enum_value <key> <value>. If it returns 1, the stderr line is shown to the user verbatim (Invalid value '<value>' for '<key>'. Allowed: ...) and the skill exits without writing. If it returns 0, the value is either valid or the key has no enum constraint — proceed.

2. Reserved warning: if <key> is in RESERVED_SET (Phase 1b), print BEFORE the approval prompt:

   "Note: <key> is RESERVED — no skill or hook reads it, so setting it will not change any behaviour. Your value is stored either way."

   Then continue to the approval gate as normal. Phase 5 carries the identical warning. Warning on one write path and not the other leaves a silent route to the same outcome, which is the whole failure this guards against.

3. Shadow warning: read get_yaml_key project.local.yaml <key>. If it returns a non-empty value, print BEFORE the approval prompt:

   "Note: this setting is currently locally overridden in project.local.yaml (value: <localvalue>). Writing to project.yaml will not change your effective value."

4. Approval gate: use AskUserQuestion:

   • Prompt: Set `<key>=<value>` in `project.yaml`?
   • Options: [A] Yes, write / [B] No, cancel

5. Write using the Edit tool. The edit strategy depends on what already exists in project.yaml:

   Case A — key exists: Read project.yaml. Locate the line <lastsegment>: <oldvalue> and the line immediately above it that introduces its parent block (e.g. modes: for modes.review_mode). Construct the Edit with old_string that includes the parent block line PLUS the leaf line, so the match is unique even if <lastsegment>: <oldvalue> appears elsewhere. Example for modes.review_mode=full:

   old_string:
     modes:
       review_mode: lean
   new_string:
     modes:
       review_mode: full
   

   Case B — parent block exists, leaf doesn't: Find the last line of the parent block. Use Edit to append the new leaf line at the correct indentation, using the last existing leaf as the old_string anchor.

   Case C — parent block doesn't exist: Append a new top-level block at end-of-file (deterministic — always end-of-file, never between blocks). Use Edit with the last non-empty line of the file as old_string and append the new block after it.

   Case D — file structure is unusual (commented-out keys with the same name, ambiguous nesting, malformed YAML): STOP and ask via AskUserQuestion:

   "Couldn't find a clean insertion point for <key> in project.yaml. Show me what to do."

6. Confirm: Set `<key>=<value>` in `project.yaml`.

   When <key> is modes.rigor, the write also moves six other knobs, so print what they resolve to now — re-read each with resolve_setting rather than reciting the expansion table, since any of them may carry an explicit value that still wins:

   Set modes.rigor=full in project.yaml. It now supplies:
     modes.workflow: full            (derived from rigor: full)
     docs.density: terse             (project.yaml — explicit, unchanged)
     qa.level: full                  (derived from rigor: full)
     modes.story_granularity: fine   (derived from rigor: full)
     modes.review_mode: full         (derived from rigor: full)
     team.size: studio               (derived from rigor: full)
   

Phase 5: Set-local Mode

(when --local <key>=<value>)

1. Whitelist check: call is_locally_overridable <key>.

   • If it returns 1 (locked), print one line:

     <key> cannot be locally overridden — it's a project-wide setting. Use `/settings <key>=<value>` (no `--local`) to change it for the whole team.

   • Exit without writing.

2. Schema validation: call validate_enum_value <key> <value>. If it returns 1, show the stderr message verbatim and exit without writing.

2b. Reserved warning: if <key> is in RESERVED_SET (Phase 1b), print BEFORE the approval prompt:

"Note: <key> is RESERVED — no skill or hook reads it, so setting it will not change any behaviour. Your value is stored either way."

Identical to Phase 4 step 2, and deliberately so. Both write paths reach the same file-of-record for a user's intent; warning on one only would leave --local as the silent route.

3. Base check: if project.yaml doesn't exist:

   "Cannot create project.local.yaml — project.yaml is missing. Run /start to create one first." Exit. (Local overrides require a base, per spec.)

4. Approval gate: use AskUserQuestion:

   • Prompt: Set `<key>=<value>` in `project.local.yaml` (your personal override, gitignored)?
   • Options: [A] Yes, write / [B] No, cancel

5. Write:

   • If project.local.yaml doesn't exist, use Write to create it with the new setting wrapped in its parent block(s). Minimal example for --local modes.automation=autonomous:

     # project.local.yaml — per-developer overrides (gitignored)
     modes:
       automation: autonomous
     

   • If it exists, use Edit with the same Case A/B/C strategy from Phase 4 step 4.

6. Confirm: Set `<key>=<value>` in `project.local.yaml` (your override).

Phase 6: Usage

When the argument doesn't match any of the four valid forms (or has empty operands), print:

Usage:
  /settings                          — view all effective config
  /settings <key>                    — view a single setting
  /settings <key>=<value>            — change a setting (project.yaml)
  /settings --local <key>=<value>    — change a setting locally
                                       (project.local.yaml, gitignored)

Examples:
  /settings modes.review_mode
  /settings modes.review_mode=full
  /settings --local modes.automation=autonomous

Notes

• All YAML writes go through Edit (existing keys/blocks) or Write (new files). The skill does not depend on yq or any external YAML library.
• The whitelist is enforced in yaml-helper.sh (is_locally_overridable function). To extend it, edit the _yaml_helper_locally_overridable constant — do not duplicate the list here.
• Derived values are not stored anywhere. modes.workflow, docs.density, qa.level, modes.story_granularity, modes.review_mode and team.size have no terminal default; when no file sets them their value comes from the modes.rigor expansion in yaml-helper.sh (_yaml_helper_rigor_expansion). Report them via resolve_setting — a get_yaml_key read returns empty and would render them "(not set)" while every skill is in fact acting on a real value.
• The schema-validation enum constants are in yaml-helper.sh (_yaml_helper_enums). validate_enum_value is the single-key validator for pending writes; validate_yaml_enum validates whole files (used by session-start.sh).
• project.local.yaml is gitignored. These overrides never propagate to teammates.
• For which value to choose for a given game type or situation — and when to suggest changing one — see .claude/docs/settings-guidance.md (advisory presets
  • change triggers). effects-map.md says what each setting does; that doc says which to pick.