> For the complete documentation index, see [llms.txt](https://faction-os.gitbook.io/faction-os-docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://faction-os.gitbook.io/faction-os-docs/.spec_system/archive/phases/phase_12/prd_phase_12.md). # PRD Phase 12: Codex Packaging and Release Readiness **Status**: Complete **Sessions**: 2 **Estimated Duration**: 2-4 days **Progress**: 2/2 sessions (100%) *** ## Overview Phase 12 completes Codex integration by resolving plugin packaging and release readiness. It determines whether FactionOS should ship as a Codex plugin in addition to direct user-level hooks, then prepares final release evidence, changelog or release notes, and known limitations. Plugin packaging must not become a blocker for direct Codex hook support. If direct user-level hooks are the supported path, this phase should document that decision and close the release without unnecessary packaging work. *** ## Risk Register | Risk | Impact | Mitigation | | --------------------------------------------- | ------------------------------------ | --------------------------------------------------------------------------------------------------------- | | Codex hook payloads evolve | Handler breakage or missed events | Keep provider normalization isolated, fixture source-backed, and docs linked to OpenAI references. | | Hook trust blocks first run | User sees no Codex events | Installer prints `/hooks` instructions; doctor reports likely trust pending. | | Codex file reads are not hook-visible | Lower file-access parity than Claude | Document the difference; observe `apply_patch` and MCP filesystem calls first. | | Raw patch or MCP args leak | Privacy regression | Parse only bounded headers and summaries; add redaction tests. | | Installer corrupts user Codex hooks | Trust loss and broken user workflow | Backup first, merge only hooks JSON, remove only managed commands, test malformed and user-owned entries. | | Project-local Codex config is untrusted | Hooks do not load in some scopes | Default to user-level install; make project scope explicit and documented. | | Provider naming churn creates broad refactors | Regression risk | Keep backward-compatible aliases and change docs/source names incrementally. | | Web assumes Anthropic model tiers | Bad Codex display | Treat Codex models as external until a provider-neutral model taxonomy is added. | *** ## Non-Goals For Initial Codex Support * No hosted auth, hosted storage, analytics capture, push, tunnel, or remote execution behavior. * No automatic approval of Codex permission requests. * No bypass of Codex hook trust as the default setup path. * No mutation of Codex provider, auth, telemetry, model, profile, or OpenAI API settings. * No custom Codex slash command claims. * No attempt to reconstruct full transcripts from `transcript_path`. * No broad file, git, terminal, Docker, Worker, or hosted executor behavior. *** ## Open Questions To Resolve Before Release * Should the default `factionos init` remain Claude-only for one release, or should it prompt when both Claude and Codex homes are present? * Should `~/.factionos/settings.json` store one default `cli` or an `installedClis` list? * Should project-local `.codex/hooks.json` be supported in the first Codex release, or held until user-level install is proven? * How much Codex MCP detail should FactionOS surface: generic tool-use names only, or allowlisted compact argument labels for specific MCP servers? * Should `PreCompact` and `PostCompact` become visible mission events, or stay diagnostics-only? *** ## Packaging Decision Criteria Proceed with Codex plugin packaging only if all are true: * Direct user-level Codex hooks already install, run, diagnose, and uninstall correctly. * Plugin packaging gives a concrete maintenance, distribution, or trust-review benefit over direct hook installation. * The plugin can reuse the same hook maps, handlers, docs, and privacy rules rather than creating a second runtime path. * Plugin install, hook trust, cache refresh, and uninstall can be validated without storing secrets or raw local payloads. Document a deferral instead when direct hooks are simpler, safer, and sufficient for first-class Codex support. *** ## Release Closeout Gates Before release, record: * Final lint, typecheck, focused tests, and available CI-equivalent results. * Privacy review for install, hooks, server, web, replay, export, logs, and diagnostics. * Security review for hook trust, permission requests, backups, uninstall, and malformed Codex config handling. * Documentation review confirming Claude and Codex paths are both represented. * Release notes or changelog entries for Claude plus Codex support. * Known limitations and follow-up work. *** ## Progress Tracker | Session | Name | Status | Est. Tasks | Validated | | ------- | -------------------------------------- | -------- | ---------- | ---------- | | 01 | Codex Plugin Packaging | Complete | \~12-20 | 2026-05-31 | | 02 | Release Closeout and Rollout Readiness | Complete | \~14-22 | 2026-05-31 | *** ## Completed Sessions 1. Session 01: Codex Plugin Packaging *** ## Upcoming Sessions None. *** ## Objectives 1. Evaluate whether Codex plugin packaging provides real maintenance or trust review value beyond direct user-level hooks. 2. Build and validate a small plugin package only if it is justified. 3. Run final quality, privacy, security, docs, and uninstall checks. 4. Prepare release notes or changelog entries for Claude plus Codex support. *** ## Prerequisites * Phase 11 completed and validated. * Direct user-level Codex hook support works end to end. * Packaging decision criteria reviewed against Codex plugin capabilities. * Release notes and limitations can cite validation evidence. *** ## Technical Considerations ### Architecture Direct hooks remain the baseline supported integration path. Plugin packaging is a distribution and trust-review decision, not a separate runtime architecture. Any plugin package should reuse the same hook maps, handlers, installer boundaries, docs, and privacy rules. ### Technologies * Codex plugin manifest and bundled hook assets if packaging proceeds * Existing FactionOS CLI, hooks, docs, and tests * Final lint, typecheck, focused tests, and CI-equivalent gates ### Risks * Plugin packaging can distract from release readiness: ship it only if it improves maintenance or trust review. * Release notes can overclaim Codex parity: document known hook visibility and trust limitations. * Final uninstall and privacy checks can regress late: run them after packaging decisions and before release notes are finalized. ### Relevant Considerations * \[P03] **Stable docs are the current contract**: release notes and docs must match shipped behavior. * \[P07] **Redaction is boundary-specific**: final privacy review must include install, hooks, server, web, replay, export, logs, and diagnostics. * \[P03-apps/cli+apps/hooks] **Lifecycle state is local and file-based**: uninstall and backup behavior remain release-critical. *** ## Success Criteria Phase complete when: * [x] All 2 sessions completed and validated. * [x] Codex plugin packaging is either shipped and tested or explicitly deferred with rationale. * [x] Final lint, typecheck, focused tests, and CI-equivalent checks pass or have source-backed exceptions. * [x] Release notes or changelog entries describe first-class Claude plus Codex support and known limitations. *** ## Dependencies ### Depends On * Phase 11: Codex Hardening and Validation ### Enables * First-class release of local Codex CLI hook support. * Post-release maintenance and future provider integrations. --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://faction-os.gitbook.io/faction-os-docs/.spec_system/archive/phases/phase_12/prd_phase_12.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.