docs: add architecture record for codex-plugin-multi#29
Conversation
Captures the load-bearing architectural decisions made during the early development of this repo so future contributors can understand why the implementation differs from a simple upstream port of openai/codex-plugin-cc. Topics covered: - Containment vs. scope as orthogonal dimensions (the most important architectural choice) - ModeProfile as the single source of mode defaults (model tier, permission mode, disallowed tools, containment, scope, dispose, context-stripping, add-dir) - One JobRecord shape across foreground/background/status/result paths - Distinct identity types (job_id vs target session IDs vs resume chains vs PID ownership) - Shared-library checks need behavior tests, not only byte identity - Upstream relationship to openai/codex-plugin-cc Doc was written during fix/022-followups development but never committed before PR #23 merged. This commit lands it on main as a standalone docs addition. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
|
![gemini-code-assist[bot]](https://avatars.githubusercontent.com/in/956858?s=60&v=4){kind=small}
There was a problem hiding this comment.
Code Review
This pull request introduces a new architecture record for the project, outlining key design principles such as the separation of containment and scope, the centralized management of mode defaults via ModeProfile, and the use of distinct identity types. The review feedback suggests including the missing schema_allowed field in the ModeProfile documentation and providing a rationale for the current approach to shared libraries, which involves maintaining multiple copies of logic instead of extracting them into a single shared library.
|
|
||
| Every mode-correlated setting lives in the `ModeProfile` table: model tier, | ||
| permission mode, disallowed tools, containment, scope, dispose default, | ||
| context-stripping, and add-dir behavior. Dispatcher libraries receive a profile |
There was a problem hiding this comment.
The list of mode-correlated settings is missing schema_allowed, which is a functional field defined in the ModeProfile implementation (see plugins/claude/scripts/lib/mode-profiles.mjs). Including it ensures the architecture record remains an exhaustive reference for the "single source of mode defaults."
| context-stripping, and add-dir behavior. Dispatcher libraries receive a profile | |
| context-stripping, add-dir behavior, and schema-allowed status. Dispatcher libraries receive a profile |
| Claude and Gemini share many library copies. Byte identity is useful, but it is | ||
| not sufficient: two copies can be equally broken. Shared-library checks also | ||
| require clean imports, production consumers, and behavior tests. |
There was a problem hiding this comment.
The document notes that Claude and Gemini "share many library copies." This implementation pattern (maintaining multiple copies of the same logic) conflicts with the organization's general rule to extract shared logic into a common library. The architecture record should clarify the rationale for this duplication (e.g., for plugin isolation) or reflect a plan to align with the shared library rule.
References
- When the same logic is implemented in multiple files, extract it into a shared library and add a test to ensure the files remain synchronized.
1 participant
Summary
Adds
docs/architecture-record.md— a 72-line record of the load-bearing architectural decisions made during early development of this repo, so future contributors can understand why the implementation differs from a simple upstream port ofopenai/codex-plugin-cc.Why now
The doc was written during
fix/022-followupsdevelopment (PR #23) but never committed before that branch merged. Landing it as a standalone docs PR rather than rolling it into a feature PR keeps it reviewable on its own terms.Topics covered
ModeProfileas the single source of mode defaults — model tier, permission mode, disallowed tools, containment, scope, dispose default, context-stripping, add-dir behavior all live in one place, preventing cross-mode driftJobRecordshape — foreground output, background result files,status,result, and the result-handling docs all use the same schemajob_id(minted by the companion), target session IDs (read from CLI output), resume chains (target session continuity), and PID ownership (for safe cancellation) are kept separateopenai/codex-plugin-cc— what we keep, what we deliberately differ onTest plan
Relations
Related to: #23 (the merged PR during which this doc was drafted)