feat(settings): pivotable settings.json or config between providers

[soulcodex]

Goals

1. Do a reaserch about the different structures around the settings for the different agents supported by the agentic to figure out how to make most of them pivotable
2. Do a research about different structures related to commands like Claude does and see if there´re interoperable concepts between the different agents we currently support

[soulcodex]

Reviewed Implementation Plan

Implementation Plan for Issue #89 - feat(settings): pivotable settings.json or config between providers

Source

• Issue: feat(settings): pivotable settings.json or config between providers #89 - feat(settings): pivotable settings.json or config between providers
• URL: feat(settings): pivotable settings.json or config between providers #89
• Labels: none
• Author: soulcodex
• Assignees: none
• Milestone: none
• Created: 2026-04-23T22:41:40Z
• Updated: 2026-04-25T23:23:17Z

Problem summary

The repository already has one vendor-pivot mechanism: .agentic/mcp.yaml can seed .mcp.json and, when those files already exist, can also translate into opencode.json and .gemini/settings.json through tooling/lib/mcp.sh. Everything else about provider configuration is fragmented or unmanaged. Claude project settings and project commands are not generated. Gemini project settings beyond ad hoc MCP insertion are not modeled. OpenCode command/config generation is intentionally skipped. Copilot and Codex have instruction-file support, but no repository-level command/config generation path in this repo today.

Issue #89 asks for two related outcomes:

1. Research the provider configuration surfaces used by the currently supported agents and determine which parts are realistically pivotable.
2. Research reusable project command surfaces across providers, starting from Claude slash commands, and identify an interoperable subset.

The implementation should not invent a fake universal config model. The safe path is:

• a research-backed capability matrix
• a shared commands manifest for the truly portable subset
• vendor-specific settings/config generation only where the repo can own the file safely
• explicit non-support for vendors and features that do not fit the model

Current behavior / context

• tooling/lib/compose.sh already calls seed_mcp_servers(), which delegates to tooling/lib/mcp.sh.
• tooling/lib/mcp.sh translates a shared MCP declaration into:
  • .mcp.json with mcpServers
  • opencode.json with mcp
  • .gemini/settings.json with mcpServers and httpUrl
• That MCP seed flow is not a general provider-config generator:
  • .mcp.json is created and owned by the seed path
  • opencode.json and .gemini/settings.json are only updated if those files already exist
  • tooling/lib/vendor-switch.sh does not manage either file today
• tooling/lib/vendor-gen.sh only generates vendor instruction files under .agentic/vendor-files/{vendor}/.
• tooling/lib/vendor-switch.sh only switches vendor instruction entrypoints and skills symlinks. It does not manage:
  • .claude/settings.json
  • .claude/commands/
  • .gemini/settings.json
  • .gemini/commands/
  • .opencode/commands/
  • opencode.json
• tooling/lib/init.sh scaffolds only:
  • .agentic/config.yaml
  • .agentic/profile.yaml
  • .agentic/mcp.yaml
  • .agentic/project-skills/
• schemas/mcp.schema.json is the only schema that models a cross-provider runtime config surface today.
• schemas/config.schema.json is a strict machine-managed lock file and should not become the source of truth for user-authored provider settings.
• tooling/lib/lint.sh currently validates library-owned fragments, profiles, skills, and adapter files. It does not validate target-local .agentic/*.yaml files.
• tooling/lib/validate.sh currently validates a composed target’s AGENTS.md, optional AGENTS.local.md, and lock-file basics. It does not validate target-local provider config manifests or managed provider-command outputs.
• vendors/_schema/capability-matrix.md is currently stale for this topic:
  • it misstates some Gemini support details
  • it does not model custom command file paths
  • it mixes generated-output facts with capability facts
• Current tests encode important behavior that must be preserved unless intentionally migrated:
  • T42 asserts opencode.json is not generated by normal deploy flows
  • T68 and T69 cover MCP translation into opencode.json and .gemini/settings.json
  • T72 asserts no MCP files are created when nothing is declared
  • T93-T95 cover Gemini symlink activation
  • T99-T101 cover init scaffolding

Relevant code paths

Include concrete files, packages, symbols, endpoints, jobs, migrations, commands, configuration, tests, or workflows.

• tooling/lib/mcp.sh
  • translate_to_opencode()
  • translate_to_gemini()
  • action_seed()
• tooling/lib/compose.sh
  • seed_mcp_servers()
  • compose lock/profile copy flow
• tooling/lib/vendor-gen.sh
  • current instruction generation entrypoint
  • VENDOR_FILES_DIR convention under .agentic/vendor-files/
• tooling/lib/vendor-switch.sh
  • remove_all_vendor_symlinks()
  • create_vendor_symlinks()
  • vendor_files_exist()
• tooling/lib/init.sh
  • current .agentic/ scaffold
• tooling/lib/validate.sh
  • target validation flow that should grow to understand new target-local manifests and managed vendor assets
• tooling/lib/lint.sh
  • library validation flow; may validate new schema files and docs, but not target-local files directly
• tooling/lib/test.sh
  • T42
  • T68-T72
  • T93-T95
  • T99-T101
• schemas/config.schema.json
  • strict lock file; not the right place for user-authored provider settings
• schemas/mcp.schema.json
  • existing cross-provider translation schema
• vendors/_schema/capability-matrix.md
  • current research artifact that should become the canonical input for this issue
• vendors/claude/README.md
• vendors/gemini/README.md
• vendors/opencode/README.md
• vendors/copilot/README.md
• vendors/codex/README.md
• docs/vendors.md
• docs/customization.md
• docs/commands.md
• README.md

Proposed implementation

Implement this issue in three deliberate layers: capability research, shared source manifests, and vendor generation/switching. Keep compose and the existing MCP seed path backward compatible in v1.

1. Add a research-backed capability inventory before changing generation logic.

   • Update vendors/_schema/capability-matrix.md first and treat it as the design gate for the implementation.
   • Record, per vendor:
     • repo-scoped settings/config file path
     • repo-scoped custom command path and file format
     • whether those files are safe for team-shared generation versus mostly user-local/auth/UI state
     • whether project commands are prompt-only or can inject shell/context
     • whether the repo can manage the path through vendor-gen + vendor-switch
   • Base the matrix on current official vendor docs and then align repo READMEs to that matrix in the same change.
   • Do not formalize this into vendors/*/adapter.json in v1 unless a concrete implementation need appears. The matrix alone is enough as the research artifact.

2. Keep the source-of-truth files under .agentic/, but do not overload .agentic/config.yaml.

   • Keep .agentic/config.yaml machine-managed and lock-like.
   • Keep .agentic/mcp.yaml as the authoritative cross-provider MCP declaration.
   • Add one new target-local schema/file for provider-managed settings:
     • schemas/provider-settings.schema.json
     • .agentic/provider-settings.yaml
   • Add one new target-local schema/file for reusable project commands:
     • schemas/commands.schema.json
     • .agentic/commands.yaml
   • These files are source inputs for target projects, not library metadata. Their main coverage will come through init, vendor-gen, validate, and integration tests, not through the repo’s existing library-only lint walk.

3. Keep the provider-settings model vendor-specific in v1.

   • Do not promise a meaningful cross-provider shared settings block yet. The real shared settings surface is too small and too unstable.
   • Use a schema shaped around explicit vendor blocks:
     • providers.claude.settings
     • providers.gemini.settings
     • providers.opencode.config
   • Reserve future extensibility if needed, but the first implementation should treat the cross-provider shared subset for settings as effectively empty.
   • Good initial ownership rules:
     • Claude: safe to generate .claude/settings.json if sourced from project-managed YAML
     • Gemini: safe to generate managed .gemini/settings.json only through vendor files and symlinks, not by having compose write directly into the root file
     • OpenCode: root opencode.json remains opt-in only because the current repo intentionally leaves it user-managed
   • Explicitly do not manage:
     • user-home settings such as ~/.claude/settings.json
     • local-only files such as .claude/settings.local.json
     • Copilot or Codex personal/app settings

4. Add a vendor-neutral commands manifest, but keep the supported subset intentionally narrow.

   • Model .agentic/commands.yaml around the actual common denominator across Claude, Gemini, and OpenCode:
     • stable command id
     • description
     • prompt/template body
     • simple argument mode
   • Supported v1 subset:
     • prompt/template text
     • short description
     • simple raw argument substitution
   • Explicitly defer shell pre-execution or dynamic shell-context injection to a follow-up. Those features are not safely isomorphic across providers.
   • Render targets:
     • Claude -> .claude/commands/*.md
     • Gemini -> .gemini/commands/*.toml
     • OpenCode -> .opencode/commands/*.md
   • For vendors without a credible native project-command surface in this repo:
     • Copilot: document as unsupported in v1
     • Codex: document as unsupported in v1
   • Do not add AGENTS-level fallback command indexes for unsupported vendors in this issue. That broadens scope and risks overlap with wider instruction-layout work.

5. Make vendor-gen the canonical generation path for new managed provider assets.

   • Do not make compose.sh the primary generator for provider settings or commands.
   • Generate managed provider settings and commands under .agentic/vendor-files/{vendor}/..., then let vendor-switch.sh activate them through symlinks.
   • Concrete examples:
     • .agentic/vendor-files/claude/settings.json
     • .agentic/vendor-files/claude/commands/<id>.md
     • .agentic/vendor-files/gemini/settings.json
     • .agentic/vendor-files/gemini/commands/<id>.toml
     • .agentic/vendor-files/opencode/commands/<id>.md
     • optional .agentic/vendor-files/opencode/opencode.json only when explicitly enabled
   • This keeps the design consistent with the repo’s existing vendor-file switching model and avoids turning compose into a second config generator.

6. Preserve the existing MCP seed flow, but stage managed provider-settings integration carefully.

   • Leave current compose + mcp.sh behavior intact for legacy/manual root-owned files:
     • .mcp.json
     • existing opencode.json
     • existing .gemini/settings.json
   • For new managed provider settings, have vendor-gen read .agentic/mcp.yaml and merge the translated MCP content into generated vendor settings/config where applicable.
   • Avoid a split-brain implementation by extracting reusable MCP translation helpers out of mcp.sh if needed, so both the legacy seed path and the new vendor-generation path share the same transformation logic.
   • Do not require compose.sh to start generating or mutating managed provider settings in v1.

7. Extend vendor-switch.sh only for assets that are actually managed.

   • Add symlink support for:
     • .claude/settings.json
     • .claude/commands/
     • .gemini/settings.json
     • .gemini/commands/
     • .opencode/commands/
     • opencode.json only if opt-in root-config generation is enabled
   • Keep activation rules conditional on generated files/directories actually existing.
   • Preserve current behavior when the new manifests are absent. Existing targets that only use AGENTS + skills + current MCP seeding must continue to work unchanged.

8. Update scaffolding, validation, and docs in the same change.

   • tooling/lib/init.sh
     • scaffold .agentic/provider-settings.yaml
     • scaffold .agentic/commands.yaml
     • include schema headers and commented examples
   • tooling/lib/validate.sh
     • if these new source files exist, validate their presence/shape and the presence of expected managed vendor assets after generation
     • keep validation backward compatible for targets that do not use the new manifests
   • tooling/lib/lint.sh
     • validate the new schema files themselves if added to the library
     • do not pretend to validate every target-local .agentic/*.yaml because just lint is a library walk, not a target-project validation command
   • Update docs required by the repo rules for any new vendor output files or symlink paths:
     • README.md
     • docs/vendors.md
     • docs/customization.md
     • docs/commands.md
     • vendors/claude/README.md
     • vendors/gemini/README.md
     • vendors/opencode/README.md
     • vendors/copilot/README.md
     • vendors/codex/README.md

9. Keep unsupported and partial cases visible instead of silently degrading.

   • If a command definition uses unsupported features such as shell prelude injection, fail validation or generation with a clear error.
   • If a vendor is unsupported for project commands or managed settings, document it explicitly and leave it out of generation.
   • Do not silently ignore a user-authored manifest entry that looks valid but cannot be rendered safely.

Files likely affected

• New schema and target-source definitions
  • schemas/provider-settings.schema.json
  • schemas/commands.schema.json
• Generation and switching
  • tooling/lib/vendor-gen.sh
  • tooling/lib/vendor-switch.sh
  • tooling/lib/mcp.sh only if translation helpers are extracted or shared
  • likely a new helper such as tooling/lib/provider-config.sh or tooling/lib/command-gen.sh
• Scaffolding and validation
  • tooling/lib/init.sh
  • tooling/lib/validate.sh
  • tooling/lib/lint.sh
• Vendor metadata and docs
  • vendors/_schema/capability-matrix.md
  • vendors/claude/README.md
  • vendors/gemini/README.md
  • vendors/opencode/README.md
  • vendors/copilot/README.md
  • vendors/codex/README.md
  • docs/vendors.md
  • docs/customization.md
  • docs/commands.md
  • README.md
• Tests
  • tooling/lib/test.sh

Tests to add or update

• Keep T68-T72 green unless the implementation intentionally changes the legacy MCP seed contract. The default compose-time MCP behavior should remain backward compatible in v1.
• Keep T42 green by default:
  • normal deploy flow must still not generate opencode.json
  • if opt-in OpenCode root-config generation is implemented, add a separate positive test for the opt-in path rather than changing the default assertion
• Extend T99-T101 so init scaffolding verifies:
  • .agentic/provider-settings.yaml
  • .agentic/commands.yaml
  • schema annotation headers for both files
• Add vendor-generation tests asserting command outputs are created from .agentic/commands.yaml:
  • .agentic/vendor-files/claude/commands/*.md
  • .agentic/vendor-files/gemini/commands/*.toml
  • .agentic/vendor-files/opencode/commands/*.md
• Add managed-settings generation tests asserting:
  • .agentic/vendor-files/claude/settings.json is rendered from .agentic/provider-settings.yaml
  • .agentic/vendor-files/gemini/settings.json is rendered from .agentic/provider-settings.yaml and merged with .agentic/mcp.yaml where applicable
  • opencode.json generation only occurs when explicitly opted in
• Extend vendor-switch tests so symlinks are created and removed for:
  • .claude/settings.json
  • .claude/commands/
  • .gemini/settings.json
  • .gemini/commands/
  • .opencode/commands/
  • opencode.json only for opt-in coverage
• Add backward-compatibility tests proving that when .agentic/provider-settings.yaml and .agentic/commands.yaml are absent, current vendor generation and switching behavior remains unchanged.
• Add negative tests for:
  • invalid command ids or unsafe filenames
  • unsupported shared command features such as shell-prelude constructs
  • unsupported vendor blocks in provider settings
  • malformed target-local YAML manifests
• Run and keep green:
  • just lint
  • just test
• just index is not required unless the implementation unexpectedly touches skills or fragments.

Risks and unknowns

• The true shared settings surface is much smaller than the issue title suggests. Trying to force a universal settings model would produce a brittle abstraction quickly.
• The current repo has two ownership models already:
  • legacy/manual root-owned files updated by MCP seeding
  • canonical managed vendor files switched by symlink
    The implementation must not blur them accidentally.
• opencode.json is deliberately not generated today. Changing that default would be a behavioral regression unless made opt-in and documented.
• Managed .gemini/settings.json generation can conflict with user-local expectations if the file is treated as an all-purpose workspace settings file. The generated scope must be explicitly limited to project-owned config.
• tooling/lib/lint.sh is a library validator, not a target-project manifest validator. Promising too much there will create a false sense of safety.
• Command templating is not isomorphic across providers. V1 must resist shell/context injection features unless the normalization rules are precise and testable.

Dependencies or blockers

• Confirm whether OpenCode root config remains opt-in in the first implementation. Recommended: yes.
• Decide the exact managed-file ownership model for Gemini settings:
  • recommended v1: managed file generated by vendor-gen and activated by vendor-switch
  • keep legacy compose/mcp.sh root-file seeding unchanged for manual files
• Decide whether to extract MCP translation helpers out of mcp.sh to avoid duplicating JSON transformations in the new vendor-generation path.
• Complete the official-doc research pass and record it in vendors/_schema/capability-matrix.md before implementing schemas or generators.

Execution checklist

• Update vendors/_schema/capability-matrix.md from current official provider docs for settings and commands, and align vendor READMEs to it.
• Define schemas/provider-settings.schema.json with vendor-specific settings blocks and explicit opt-in handling for OpenCode root config.
• Define schemas/commands.schema.json around the prompt-only, simple-arguments common denominator.
• Update tooling/lib/init.sh to scaffold .agentic/provider-settings.yaml and .agentic/commands.yaml.
• Implement command generation under .agentic/vendor-files/{vendor}/commands/.
• Implement managed provider-settings generation under .agentic/vendor-files/{vendor}/, leaving legacy compose-time MCP seeding backward compatible.
• Extract or share MCP translation helpers if needed so vendor generation and legacy MCP seeding use the same transforms.
• Extend tooling/lib/vendor-switch.sh so managed settings/commands are activated by symlink when present.
• Update tooling/lib/validate.sh for the new target-local manifests and generated assets.
• Update docs and vendor READMEs in the same change for any new vendor output files or symlink paths.
• Update tooling/lib/test.sh for init, vendor generation, vendor switching, negative cases, and backward compatibility.
• Run just lint.
• Run just test.

Suggested worker prompt

Implement Issue #89 in /Users/soulcodex/Code/Personal/agentic as a vendor-gen / vendor-switch feature, not as a new compose-time universal config system.

Before changing anything, inspect:

• tooling/lib/mcp.sh
• tooling/lib/compose.sh
• tooling/lib/vendor-gen.sh
• tooling/lib/vendor-switch.sh
• tooling/lib/init.sh
• tooling/lib/validate.sh
• tooling/lib/test.sh
• vendors/_schema/capability-matrix.md
• vendors/claude/README.md
• vendors/gemini/README.md
• vendors/opencode/README.md
• vendors/copilot/README.md
• vendors/codex/README.md

Implementation scope:

• Update vendors/_schema/capability-matrix.md from current official vendor docs and use it as the design gate.
• Add:
  • schemas/provider-settings.schema.json
  • schemas/commands.schema.json
• Update tooling/lib/init.sh to scaffold:
  • .agentic/provider-settings.yaml
  • .agentic/commands.yaml
• Generate managed provider assets through vendor-gen into .agentic/vendor-files/{vendor}/...:
  • Claude: settings.json and commands/*.md
  • Gemini: settings.json and commands/*.toml
  • OpenCode: commands/*.md, plus opencode.json only as an explicit opt-in path
• Extend vendor-switch.sh to symlink those managed assets into their native paths when they exist.
• Keep current compose + mcp.sh behavior backward compatible for legacy/manual files.
• If needed, extract MCP translation helpers so the new vendor-generation path can reuse the same JSON transforms without duplicating logic.
• Do not invent a universal shared settings abstraction. Use vendor-specific settings blocks in v1.
• Do not implement shell-prelude or shell-context-injection command features in v1.
• Do not invent command/config outputs for Copilot or Codex in v1; document them as unsupported for this feature instead.

Validation requirements:

• Existing MCP tests (T68-T72) remain green unless you intentionally migrate behavior and can justify it.
• Existing default no-op OpenCode root-config behavior (T42) remains green by default.
• Add init, generation, switch, negative-case, and backward-compatibility test coverage for the new manifests and managed vendor assets.
• Run just lint.
• Run just test.
• Do not run just index unless you end up touching skills or fragments.