3.3 KiB
| id | date | status | supersedes | superseded-by | affected-paths | affected-components | migration_confidence | migration_source |
|---|---|---|---|---|---|---|---|---|
| 0019 | 2026-07-03 | Superseded | 0031 | medium | docs/memory-system/03-architecture-decisions.md### ADR-019 — Global os-orchestration plugin supersedes per-project orchestration text |
0019 — Global os-orchestration plugin supersedes per-project orchestration text
Context
Session orchestration guidance (how Claude Code should delegate vs execute directly) had accumulated in two incompatible places. (1) A permissive global plugin (os-orchestration, moved into cc-os from a standalone ~/dev/cc-plugins/orchestration/ repo) injects ORCHESTRATION.md as SessionStart additionalContext carrying the rule: "do single-file/≤2-tool-call ops directly; delegate only when work is parallelizable across independent files, spans many files, or needs isolated/large context." (2) cc-os's own CLAUDE.md carried a stricter per-project override: "Delegate all file I/O and shell commands to subagents via the Agent tool. No exceptions by default." The two rules contradicted each other and lived in different places, creating confusion about which one applies when.
Decision
Adopt the plugin's permissive rule as the canonical global default. cc-os relinquishes its stricter local override entirely. Every project now follows the plugin's behavior: single-file/≤2-tool-call ops are executed directly; larger or cross-file work is delegated. The os-orchestration plugin is migrated into cc-os (plugins/os-orchestration/) following the same pattern as os-vault (git-tracked, symlinked into ~/.claude/plugins/, registered via local-plugins marketplace).
- Rationale: One authoritative orchestration rule, maintained in one place (the plugin, under version control), is simpler than per-project copy-paste text that drifts. The permissive rule reflects actual practice (small direct edits are efficient; large multi-file refactors warrant delegation). Consolidation into a global plugin means all projects get the same behavior without duplication, and the rule can be evolved once and picked up everywhere.
Consequences
cc-os adopts the os-orchestration plugin's permissive delegation rule (execute small single-file ops directly, delegate larger/cross-file work) as the sole global default, removing cc-os's own stricter per-project override that previously contradicted it. The plugin was migrated into cc-os git tracking following the os-vault pattern, giving one authoritative, version-controlled orchestration rule applied consistently across all projects.
Alternatives rejected
- Keep cc-os's stricter override as a local addition on top of the global plugin: would recreate the incompatibility problem; cc-os would be a special case instead of a normal project.
- Make the strict version the global default instead: reverses the decision in favor of the permissive rule. The permissive approach scales better (most tasks fit the single-file/≤2-tool threshold); strict delegation adds ceremony for no gain on small work. The plugin's default was chosen by the user for good reason.
- Cross-references: ADR-016 (os-vault plugin sourced from cc-os git repo, establishing the git-tracked plugin pattern), ADR-018 (plugin marketplace mechanics for local plugins).