[waleedkadous]

Summary

Specification for a major configuration overhaul covering four concerns:

• Unified .codev/config.json — layered config (global ~/.codev/ + project .codev/) replacing af-config.json, with deep merge semantics
• Pluggable consultation models — configurable via porch.consultation.models (single-model, none, parent modes)
• Runtime file resolution — framework files (protocols, roles, templates, consult-types) resolve from the npm package at runtime; eliminates codev update
• Remote framework sources — codev sync fetches shared team frameworks via forge or arbitrary CLI command

Two rounds of 3-way consultation (Gemini, Codex, Claude) completed. Architect review comments addressed.

Status

Spec only — no implementation code. Pending spec-approval gate.

Test plan

• Review spec for completeness and feasibility
• Validate config schema design
• Confirm migration path from af-config.json

🤖 Generated with Claude Code

[damongabrielle]

are these really models? I'm not raising an issue with terminology , just wondering if this is a spot where users would add custom ones. Is the model in this context the cli command that codev executes to trigger the consult? If yes, I might try and do gemini -m "<some model of my choosing>

[waleedkadous]

Good question! You're right that "models" here refers to CLI command names (gemini, codex, claude) — each maps to a consult -m <name> invocation, not a raw model ID like gemini-3-pro-preview. Your instinct about wanting to use a custom backing model is spot on though — today consult only knows these three backends, so models in the config must be from that set. Extending to support user-registered models (e.g. a custom Ollama backend) is a natural follow-on but out of scope for this spec. We'll make sure the spec clarifies this distinction.

[damongabrielle]

ah I see, this section makes it clearer to me that they're cli commands, and not the backing model names.

[damongabrielle]

wondering if models must be one of the three

[waleedkadous]

Yes, currently they must be one of the three registered backends. The spec should state this explicitly — and note that adding new backends would be a separate feature. Good catch.

[damongabrielle]

Does customize specifically mean override or does overrie behavior on ly occur if I the name I give the protocol in the path overlaps with an existing protocol? For instance if I named it SPIR that'd be an override but if I named the new protocol FOOBAR, then I've essentially created a new protocol? I am also not forgetting your guidance that my idea for a Quality engineering role I mentioned probably belongs somewhere as a part of a protocol or extension to an existing one.

[waleedkadous]

You've got it exactly right — it's both. Same name = override (your custom spir replaces the built-in one), new name like FOOBAR = net-new protocol. The resolution chain just looks for protocols/<name>/protocol.json at each tier, so whatever name you use in the path is what you get. And yes, your QE role idea could absolutely work as either a new protocol or an extension to SPIR (e.g. adding a QE verification phase). This framework makes both paths possible.

[damongabrielle]

This makes a lot of sense to me.

[damongabrielle]

This feature is going to be awesome!

[waleedkadous]

Thanks Damon! Really appreciate you taking the time to read through the whole spec and leave such thoughtful questions.

[damongabrielle]

This is exactly the feature I was hoping for. Quick clarifying question about frameworks. Will storing multiple frameworks in the same repo be ok? (Basically wondering if the full path would be respected) Thinking about collecting favorites in one repo.

  "framework": {
    "source": "myorg/our-codev-frameworks/team-a-favorite-framework",
    "ref": "v1.2.0"
  }

  "framework": {
    "source": "myorg/our-codev-frameworks/<team-b-python-framework">,
    "ref": "v1.2.0"
  }

[waleedkadous]

Great question, and the short answer is yes — the source field supports subpaths, so myorg/our-codev-frameworks/team-a-favorite-framework and myorg/our-codev-frameworks/team-b-python-framework would both work from the same repo. The forge repo-archive concept would need to handle extracting just the specified subdirectory rather than the entire repo archive. We'll make sure the spec explicitly addresses subpath extraction and cache keying so there's no ambiguity about how this works.

[nharward]

Suggestion: for config/temp/etc. file locations use the XDG Base Directory Specification. Benefits include avoiding clutter in $HOME, clear separation of concerns for different types of files, and well-known user-level customization with standard environment variables.

[waleedkadous]

Thanks for the suggestion, Neil! We considered XDG and it's a solid standard. We went with ~/.codev/ to stay consistent with Claude Code's ~/.claude/ convention, which our users are already familiar with. On macOS (our primary platform today) XDG isn't widely adopted. That said, if Linux adoption grows, adding XDG support as an alternative (respecting $XDG_CONFIG_HOME when set, falling back to ~/.codev/) would be a natural enhancement. We'll keep it in mind.

[waleedkadous]

Architect Integration Review (3-Way CMAP)

Excellent work on this massive overhaul — the unified config loader, four-tier resolution chain, and pluggable consultation models are all well-designed. The test coverage is strong. However, the 3-way review (Gemini, Codex, Claude) surfaced 5 issues I'd like to see addressed before merge.

1. Tower config reads not migrated to unified loader (all 3 reviewers)

tower-instances.ts and tower-terminals.ts (3 locations) still use raw fs.readFileSync + JSON.parse instead of the unified loadConfig(). This means they miss global ~/.codev/config.json layering and deep merge semantics. The spec explicitly lists these as sites that "must use new centralized loader."

2. af-config.json migration path (Codex + Gemini)

Two related issues:

• The loader hard-errors when af-config.json exists — the spec says there should be a migration period with a deprecation warning where af-config.json still works.
• Data loss scenario: if codev adopt creates a default .codev/config.json first, then codev update skips migrating af-config.json (because .codev/config.json already exists) but still deletes it. User customizations are lost.

3. Workspace detection false positive (Codex)

detectWorkspaceRoot() now checks for a .codev/ directory, which will match ~/.codev/ when run from $HOME. This causes false-positive workspace detection. Consider requiring both .codev/config.json and .git (or similar) to be present.

4. Framework cache never initialized for core commands (Gemini)

setFrameworkCacheDir() is only called from requireWorkspace(), which only runs for legacy team commands. Core commands (porch, consult, af) never call it, so remote framework resolution is effectively dead code in production. Perhaps move cache dir resolution to a shared module with lazy initialization.

5. URL sources not parsed correctly (Codex)

parseSource() in commands/sync.ts assumes owner/repo format and will mis-parse full URLs (e.g., https://gitlab.example.com/team/protocols) that the spec says are supported.

[waleedkadous]

6. codev update silently overwrites user-customized skills (Codex)

The old codev update called copySkills(targetDir, templatesDir, { skipExisting: true }) — preserving any skills the user had customized. The new version calls copySkills(targetDir, templatesDir) without skipExisting, which defaults to false. This means running codev update will silently overwrite user-customized .claude/skills/ files with the package defaults.

This is especially important given that the whole point of this PR is enabling user customization. Please restore { skipExisting: true } or add conflict handling similar to copyRootFiles.