Support repo-local Kanon overlays for project-owned agent context

[kelos-bot]

🤖 Kelos Strategist Agent @gjkim42

Area: New Use Cases

Summary

The highest-value new use case I found is multi-repo teams that need a central agent baseline plus repository-owned context.

Kanon already has the right destination shape: --project can render project-scoped AGENTS.md, CLAUDE.md, .mcp.json, .codex/, .claude/, and skill files. But the source shape is still a single Kanon home. There is no way for an org/platform team to own the global baseline while each repository owns its local instructions, MCP servers, hooks, and skills in that repository.

That leaves teams with bad choices:

• Put every repo’s instructions/MCP/hooks into one central ~/.config/kanon repo, which does not scale across dozens of services and makes repo owners dependent on a central config maintainer.
• Keep per-repo AGENTS.md, CLAUDE.md, .mcp.json, etc. by hand, which loses Kanon’s cross-agent compilation and import/apply lifecycle.
• Copy a baseline into every repo, which drifts quickly.

Proposal: add explicit project overlay support so kanon apply --project <repo> can compose the central Kanon config with a repo-local partial config, then render the merged result into that project only.

Evidence from the current codebase

• The README defines source state as one kanon.yaml plus instructions/, skills/, and hooks/ in the Kanon home (README.md:14-15). There is no repo-local source layer.
• LoadConfig reads exactly one config path, defaulting to <home>/kanon.yaml (internal/core/config.go:27-45).
• TargetOptions has KanonHome, UserHome, Project, and Agent only (internal/core/types.go:73-78). Project controls destination paths, not source composition.
• The Codex adapter switches destinations when opts.Project != "": project AGENTS.md, project .codex, and project .agents/skills (internal/core/codex.go:17-24).
• The Claude adapter similarly switches destinations to project CLAUDE.md, project .claude, and project .mcp.json (internal/core/claude.go:17-25).
• Source assets are still resolved from opts.KanonHome: readInstruction(opts.KanonHome, ...) and renderSkills use ResolvePath(opts.KanonHome, ...) (internal/core/render.go:55-117).
• import --project can read project-scoped destination files, but WriteImport always writes the resulting source to <home>/kanon.yaml and assets under the Kanon home (internal/core/import.go:62-75). There is no way to write an imported project config back into the repository that owns it.

Net: Kanon can render project-scoped files, but it cannot model project-scoped source ownership.

Existing issue overlap check

This is intentionally distinct from the open generated issues I reviewed:

• Make Kanon fleet-aware: per-machine / per-role / per-OS variation via profiles + 'when:' selectors #20 adds machine/role/OS selection (when:) inside one source. It answers “which machines get this?” This issue answers “which repository owns this source layer?”
• Make Kanon first-class in ephemeral & CI environments: bootstrap, --rev pinning, and a diff drift-gate #24 handles ephemeral/CI provisioning; Add render manifests and apply provenance for auditable config rollouts #30 handles manifests/provenance. Both would compose with project overlays but do not define repo-owned source.
• Render managed-policy artifacts for enterprise fleets (Claude managed settings + Codex requirements) #27 handles admin/managed policy artifacts, not normal project-owned config.
• Grow beyond Codex + Claude: prioritized render-adapter roadmap (Gemini CLI, Cursor, opencode, Copilot CLI) #7/Render adapters: Cursor, opencode, Copilot CLI (+ Gemini import parity) #23 add more render adapters; Manage subagents (and legacy commands) as new managed-settings types — subagents first #10/Make hooks portable by rendering managed hook scripts and assets #31/Add a 'native passthrough' managed-settings type to manage permissions (and other non-portable settings) without a lossy neutral schema #18/Close the secret-management loop: import secret policies, a validate lint, and a secrets resolution backend #17 add or improve managed setting types. None address source-layer composition.

External signal

Current agent ecosystems already expect global + repository/project layers:

• OpenAI Codex documents global ~/.codex/AGENTS.md plus repository and nested AGENTS.md/AGENTS.override.md files, concatenated from root down so closer project guidance overrides earlier guidance: https://developers.openai.com/codex/guides/agents-md
• Claude Code documents project-scoped MCP servers in .mcp.json, explicitly designed to be checked into version control so team members share the same project tools: https://code.claude.com/docs/en/mcp
• GitHub Copilot supports repository-wide .github/copilot-instructions.md and path-specific .github/instructions/*.instructions.md, with personal, repository, and organization instructions all potentially applying: https://docs.github.com/en/copilot/how-tos/copilot-on-github/customize-copilot/add-custom-instructions/add-repository-instructions
• VS Code’s agent customization docs similarly describe workspace-stored instructions, AGENTS.md for multi-agent workspaces, and organization-level instructions: https://code.visualstudio.com/docs/agent-customization/custom-instructions

The pattern is clear: reusable defaults live above the repo, while repo-specific context lives with the repo. Kanon should compile both instead of forcing users to choose one owner.

Proposed design

1. Add an explicit project overlay flag

Start explicit for safety; do not auto-load arbitrary repo config by default.

kanon render --project . --overlay .kanon/project.yaml
kanon diff   --project . --overlay .kanon/project.yaml
kanon apply  --project . --overlay .kanon/project.yaml

--overlay loads a partial Kanon config after the base <home>/kanon.yaml. Overlay asset paths resolve relative to the overlay file directory, not the central Kanon home.

Suggested repo layout:

repo/
  .kanon/
    project.yaml
    instructions/repository.md
    skills/release-notes/SKILL.md
  AGENTS.md          # rendered
  CLAUDE.md          # rendered
  .mcp.json          # rendered for Claude project scope
  .codex/hooks.json  # rendered for Codex project scope

Central baseline:

# ~/.config/kanon/kanon.yaml
version: 1
instructions:
  files:
    - instructions/org-baseline.md
skills:
  - name: secure-review
mcp:
  servers:
    github:
      type: http
      url: https://mcp.githubcopilot.com/mcp/
      targets: [claude, codex]
hooks: []

Repository overlay:

# repo/.kanon/project.yaml
version: 1
instructions:
  files:
    - instructions/repository.md
skills:
  - name: release-notes
    path: skills/release-notes
mcp:
  servers:
    local-api:
      command: ./tools/mcp-local-api
      args: [--root, "${CLAUDE_PROJECT_DIR:-.}"]
      targets: [claude]
hooks:
  - name: repo-tests
    event: PostToolUse
    matcher: Edit|Write
    command: make
    args: [test]

Rendered project instructions should be ordered base then overlay, matching Codex’s global-then-project layering model.

2. Keep merge rules tiny and deterministic

Recommended MVP merge semantics:

• version must match the base schema version.
• instructions.files: append base files, then overlay files.
• skills: append by name; duplicate names across layers are an error unless a later replace: true field is added.
• mcp.servers: merge by server name; duplicate names are an error unless explicitly replaced.
• hooks: append; duplicate hook names are an error unless explicitly replaced.
• metadata: shallow merge, overlay wins.

The important part is to avoid a broad “deep merge everything” system in v1. Conflicts should be visible rather than surprising.

3. Constrain overlays to project scope

Because overlay configs can define MCP servers and hooks that run commands, they should be treated as repo-trusted input:

• Require --project when --overlay is used.
• Never let overlay-sourced settings write to user-global destinations.
• Do not auto-discover overlays unless the user passes --overlay or the central config opts in later with an allowlist.
• Keep existing unmanaged-file conflict behavior and backups.
• Reuse Close the secret-management loop: import secret policies, a validate lint, and a secrets resolution backend #17’s secret handling once it exists; until then, validate overlay configs with the same env-ref checks as the base config.

This lets a developer consciously choose to apply a repository’s agent context without letting a random checkout mutate their global agent setup.

4. Add import support for repo-owned overlays

Add a project import path that writes the discovered project context back to the repository overlay instead of centralizing it:

kanon import --project . --write-overlay .kanon/project.yaml

Behavior:

• Read existing project AGENTS.md, CLAUDE.md, .mcp.json, .codex/hooks.json, .claude/settings.json, and project skill dirs using the current project import logic.
• Write the neutralized result into repo/.kanon/project.yaml plus repo/.kanon/instructions/ and repo/.kanon/skills/.
• Leave the central ~/.config/kanon/kanon.yaml alone.

This is the adoption path for repositories that already have agent files checked in.

Use cases unlocked

1. Multi-repo product org: platform owns the org baseline; service teams own .kanon/project.yaml in each repo for service-specific runbooks, test commands, and local MCP servers.
2. Open-source maintainers: a repo can publish one neutral Kanon overlay and let contributors render Codex + Claude config consistently instead of hand-maintaining multiple agent-native files.
3. Consultancies / agencies: engineers keep their personal baseline while client repos carry project-specific constraints and tools without polluting the engineer’s global config.
4. Monorepos: start with one repo overlay, then later combine with Make Kanon fleet-aware: per-machine / per-role / per-OS variation via profiles + 'when:' selectors #20 when: selectors or a future nested overlay if subteams need narrower rules.

Suggested MVP scope

1. Add --overlay <path> to render, diff, and apply; require --project with it.
2. Add a LoadConfigLayers(basePath, overlays...) helper that tracks each layer’s root directory for path resolution.
3. Extend instruction/skill source resolution so each item resolves against its owning layer root.
4. Implement the conservative merge rules above with clear duplicate-name errors.
5. Add tests proving base+overlay instructions append in order, overlay assets resolve from the repo, duplicate MCP/server names fail, and overlay use cannot write user-global files.
6. Add import --project --write-overlay <path> as the second PR if the render/apply layering lands cleanly.

Backward compatibility

• Existing kanon.yaml files and commands are unchanged.
• No overlay is loaded unless the user passes the new flag.
• Existing --project behavior remains the same when no overlay is specified.
• The overlay format reuses the existing schema, so adoption is incremental.

[kelos-bot]

🤖 Kelos Task Status

Task kanon-triage-issues-05340d56dff9 has succeeded. ✅

[kelos-bot]

🤖 Kelos Agent @gjkim42

Kanon Triage Report

Kind: kind/api
Priority: priority/important-longterm — Valuable multi-repo/team workflow, but it is an additive API design rather than an urgent bug or security fix.
Actor: actor/human — Adds new CLI flags and config-layer merge semantics, so maintainer design review is required before implementation.

Status: STILL VALID

Evidence:

• No merged PRs were found with gh pr list --state merged --search "33", and recent commit searches for 33, overlay, and project/source terms returned no matches.
• Current CLI flags include --project, --config, --home, and --agent, but no --overlay or --write-overlay:

  kanon/internal/cli/root.go

  Lines 53 to 56 in 78cbb70

  	cmd.PersistentFlags().StringVar(&opts.home, "home", "", "Kanon source repository path (defaults to KANON_HOME or ~/.config/kanon)")
  	cmd.PersistentFlags().StringVar(&opts.configPath, "config", "", "config file path (defaults to <home>/kanon.yaml)")
  	cmd.PersistentFlags().StringVar(&opts.project, "project", "", "render project-scoped agent settings into this repository")
  	cmd.PersistentFlags().StringVar(&opts.agent, "agent", core.AgentAll, "agent to manage: all, codex, or claude")

  and

  kanon/internal/cli/root.go

  Lines 228 to 231 in 78cbb70

  	cmd.Flags().BoolVar(&opts.write, "write", false, "write imported config and files into the Kanon home")
  	cmd.Flags().BoolVar(&opts.force, "force", false, "overwrite an existing kanon.yaml during import")
  	cmd.Flags().StringVar(&opts.secretPolicy, "secret-policy", string(core.SecretPolicyKeep), "secret handling during import: keep")
  	cmd.Flags().StringVar(&opts.instructionPolicy, "instruction-policy", string(core.InstructionPolicyAuto), "instruction handling during import: auto, codex, claude, merge, or skip")

• LoadConfig still reads one config file, defaulting to <home>/kanon.yaml, with no layer loading helper:

  kanon/internal/core/config.go

  Lines 27 to 49 in 78cbb70

  	func LoadConfig(home, configPath string) (*Config, string, error) {
  	var err error
  	if home == "" {
  	home, err = DefaultHome()
  	if err != nil {
  	return nil, "", err
  	}
  	}
  	if configPath == "" {
  	configPath = filepath.Join(home, "kanon.yaml")
  	}
  	data, err := os.ReadFile(configPath)
  	if err != nil {
  	return nil, "", err
  	}
  	var cfg Config
  	if err := yaml.Unmarshal(data, &cfg); err != nil {
  	return nil, "", err
  	}
  	if cfg.Version == 0 {
  	cfg.Version = 1
  	}
  	return &cfg, configPath, nil

• TargetOptions still models destination scope only (KanonHome, UserHome, Project, Agent):

  kanon/internal/core/types.go

  Lines 73 to 78 in 78cbb70

  	type TargetOptions struct {
  	KanonHome string
  	UserHome string
  	Project string
  	Agent string
  	}

• Project rendering changes destination paths, but instruction and skill sources still resolve from opts.KanonHome:

  kanon/internal/core/codex.go

  Lines 20 to 28 in 78cbb70

  	if opts.Project != "" {
  	targetRoot = filepath.Join(opts.Project, ".codex")
  	instructionPath = filepath.Join(opts.Project, "AGENTS.md")
  	skillRoot = filepath.Join(opts.Project, ".agents", "skills")
  	}
  	instructions, err := readInstruction(opts.KanonHome, cfg.Instructions.Files)
  	if err != nil {
  	return nil, err

  ,

  kanon/internal/core/claude.go

  Lines 21 to 29 in 78cbb70

  	if opts.Project != "" {
  	targetRoot = filepath.Join(opts.Project, ".claude")
  	instructionPath = filepath.Join(opts.Project, "CLAUDE.md")
  	mcpPath = filepath.Join(opts.Project, ".mcp.json")
  	skillRoot = filepath.Join(targetRoot, "skills")
  	}
  	instructions, err := readInstruction(opts.KanonHome, cfg.Instructions.Files)
  	if err != nil {

  , and

  kanon/internal/core/render.go

  Lines 66 to 100 in 78cbb70

  	func readInstruction(home string, paths []string) ([]byte, error) {
  	var out bytes.Buffer
  	for _, rel := range paths {
  	path := ResolvePath(home, rel)
  	data, err := os.ReadFile(path)
  	if err != nil {
  	return nil, err
  	}
  	if out.Len() > 0 {
  	out.WriteString("\n\n")
  	}
  	out.Write(bytes.TrimSpace(data))
  	}
  	if out.Len() == 0 {
  	return nil, nil
  	}
  	out.WriteByte('\n')
  	return out.Bytes(), nil
  	}
  	func renderSkills(cfg *Config, opts TargetOptions, agent, targetRoot string) ([]RenderedFile, error) {
  	var files []RenderedFile
  	for _, skill := range cfg.Skills {
  	if !enabled(skill.Enabled) || !HasTarget(skill.Targets, agent) {
  	continue
  	}
  	name := skill.Name
  	if strings.TrimSpace(name) == "" {
  	return nil, fmt.Errorf("skill name cannot be empty")
  	}
  	source := skill.Path
  	if source == "" {
  	source = filepath.Join("skills", name)
  	}
  	source = ResolvePath(opts.KanonHome, source)

• Project import can read project instruction files, but --write still writes back to the Kanon home via WriteImport(target.KanonHome, ...):

  kanon/internal/core/import_assets.go

  Lines 18 to 23 in 78cbb70

  	codexPath := filepath.Join(opts.UserHome, ".codex", "AGENTS.md")
  	claudePath := filepath.Join(opts.UserHome, ".claude", "CLAUDE.md")
  	if opts.Project != "" {
  	codexPath = filepath.Join(opts.Project, "AGENTS.md")
  	claudePath = filepath.Join(opts.Project, "CLAUDE.md")
  	}

  and

  kanon/internal/core/import.go

  Lines 70 to 87 in 78cbb70

  	func WriteImport(home string, result *ImportResult, force bool) error {
  	configPath := filepath.Join(home, "kanon.yaml")
  	if _, err := os.Stat(configPath); err == nil && !force {
  	return fmt.Errorf("%s already exists; re-run import with --force to replace it", configPath)
  	} else if err != nil && !errors.Is(err, os.ErrNotExist) {
  	return err
  	}
  	for rel, data := range result.Files {
  	path := ResolvePath(home, rel)
  	if err := os.MkdirAll(filepath.Dir(path), 0o755); err != nil {
  	return err
  	}
  	if err := os.WriteFile(path, data, 0o644); err != nil {
  	return err
  	}
  	}
  	return WriteConfig(configPath, result.Config)
  	}

Duplicates found: None found

Recommendation: KEEP OPEN