Project Settings Manager

/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.2            (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">