Write a preferences.yaml schema and normalize repository.default_remote

[williamthorsen]

Problem

.agents/preferences.yaml stores configuration consumed by many agent skills, but its shape is undocumented as a machine-readable schema. Editors can't autocomplete or validate it, configs can drift from skill expectations silently, and the precondition for williamthorsen/configs.macos#12 (which depends on a published schema) cannot be met.

A second issue surfaced during design: repository.default_remote is currently a list, but only the first element is ever read. The shape was once intentional but has outlived its usefulness — the schema-writing exercise is the right time to normalize it.

Context

• Existing schemas in this package follow JSON Schema Draft 2020-12 (see packages/agents/schemas/label-map.json).
• Skills reference preferences keys both inside the literal .agents/preferences.yaml (10 sections) and beyond it (orchestration.*, artifacts.paths.*, merge.{strategy,delete_branch} reserved keys).
• repository.default_remote is read at packages/agents/content/skills/get-session-context/SKILL.md:134 as default_remote[0].name — only index 0 is ever consumed.
• Other references in ~/ai-artifacts/ are historical run snapshots (frozen records) and do not require migration.

Solution

1. Write a JSON Schema at packages/agents/schemas/preferences.json (Draft 2020-12) describing every preferences key consumed by an installed skill or present in the repo's .agents/preferences.yaml. Top-level sections covered: artifacts, commit, editors, integrations, merge, orchestration, platform, pr, project, repository, ticket.

2. Strictness rules:

   • Top-level: additionalProperties: false (catches typos in section names).
   • User-keyed inner maps (integrations, orchestration.models, artifacts.paths): additionalProperties constrains the value shape but permits any key name.
   • Reserved-but-not-honored keys (merge.strategy, merge.delete_branch): documented as such in description text; not flagged with deprecated.

3. Required vs optional:

   • Top-level: required: []. A fully empty preferences file is valid.
   • Sub-fields: required when their absence would make the parent object meaningless (e.g., editors[].name, editors[].command, repository.default_remote.name, integrations.<name>.enabled, format-string fields when their parent section is present).

4. Normalize repository.default_remote from a single-element list to a singular object across:

   • .agents/preferences.yaml
   • packages/agents/content/skills/get-session-context/SKILL.md
   • packages/agents/README.md (property table + example)
   • The new schema describes the singular shape only.

5. Test coverage in packages/agents/:

   • Schema is well-formed (loads as valid JSON Schema).
   • The live .agents/preferences.yaml validates against the schema (guards against drift).

6. Out of scope:

   • Runtime CLI schema validation (e.g., codeassembly-agents validate-prefs).
   • Editor $schema linking conventions in .agents/preferences.yaml.
   • Multi-remote awareness in the schema (would be a separate, additive change with a different shape).

Acceptance criteria

• packages/agents/schemas/preferences.json exists, uses JSON Schema Draft 2020-12, has the same $id pattern as label-map.json, and covers all top-level sections enumerated above.
• Top-level uses additionalProperties: false; user-keyed inner maps (integrations, orchestration.models, artifacts.paths) permit additional keys with constrained value shapes.
• Top-level required is []; sub-required lists are present where described above.
• repository.default_remote is a singular object in .agents/preferences.yaml, in get-session-context/SKILL.md, and in packages/agents/README.md. No remaining references to default_remote[0] or default_remote[].* in this repo.
• Tests verify the schema is well-formed and that .agents/preferences.yaml validates against it.
• packages/agents/README.md reflects the singular default_remote shape in both the property table and the example.
• New/modified behavior in this change is covered by tests.

[williamthorsen]

Preserved from williamthorsen/configs.macos#191.

agents/docs/preferences-template.yaml is being deleted from configs.macos as part of #191 after being preserved here. Attaching the current contents below for reference while the schema is drafted.

Original path in source repo: agents/docs/preferences-template.yaml

# Agent preferences
# This file provides default values for agent operations.
# Project-specific overrides can be placed in .agents/preferences.yaml

# Repository defaults
repository:
  # Default remote configuration (config-first optimization)
  # Agents check this first before falling back to git commands
  default_remote:
    - name: origin
      default_branch: main

# Integrations
integrations:
  jira:
    enabled: false
  github:
    enabled: true

# Artifact organization
artifacts:
  base_dir: ~/.ai
  # Ticket-scoped artifacts use {base_dir}/projects/{project-slug}/tickets/{ticket-id}/
  # Non-ticket categories are relative to the project directory:
  paths:
    chats: chats
    devlogs: devlogs

# Timestamp formats
timestamps:
  human: '%Y-%m-%d %H:%MZ'
  machine: '%Y%m%d-%H%MZ'
  iso: '%Y-%m-%dT%H:%M:%SZ'