How alexroadcaster/product-agent-os works
Purpose and Package Boundary
Product-Agent OS is a local Codex plugin that governs AI-assisted engineering through durable planning, evidence, approval, and lifecycle artifacts. Its working package is plugins/product-agent-os/, declared by plugins/product-agent-os/.codex-plugin/plugin.json; optional MCP configuration is isolated in plugins/product-agent-os/.mcp.json. It is not a hosted service or autonomous deployment platform.
Operator and CLI Entry Points
Codex invokes packaged skills from plugins/product-agent-os/skills/, notably project-lifecycle-orchestrator, workspace-discovery-auditor, and implementation-planner. Python CLI entry points under plugins/product-agent-os/scripts/ drive major flows: run_first_project_analysis.py, render_infrastructure.py, scan_project_code_graph.py, run_codex_runtime_runner.py, and run_self_learning_loop.py. Documentation entry points are README.md and docs/product-agent-os/index.md.
Control Plane and Lifecycle
The system turns project intent into a controlled delivery route: read-only audit → risk/maturity routing → requirements and plan → staged artifacts → approval → focused implementation → verification/review → learning. Root control-plane files are the durable state boundary: AGENTS.md, REQUIREMENTS.md, PLAN.md, TEST.md, EVALS.md, and RUNLOG.md. Lifecycle state is also recorded in .codex/product-agent-os/lifecycle-state.json.
Infrastructure Staging and Safe Mutation
Templates are packaged in plugins/product-agent-os/assets/templates/ and rendered into an external staging directory rather than directly into a target workspace. plugins/product-agent-os/scripts/render_infrastructure.py produces proposals; plugins/product-agent-os/scripts/merge_infrastructure.py and plugins/product-agent-os/scripts/product_agent_os/merge_infrastructure.py validate manifests, paths, workspace binding, approval evidence, and rollback data before target writes. This is the main mutation trust boundary.
Analysis, Methodology, and Graph Intelligence
Workspace discovery and methodology selection are implemented in plugins/product-agent-os/scripts/product_agent_os/discovery.py, methodology_audit.py, and methodology_synthesis.py. They classify evidence as unverified until supported by current checks or owner decisions. The graph subsystem—centered on project_code_graph.py, project_graph_analysis.py, and project_graph_queries.py—scans source, docs, contracts, schemas, and tests to produce read order, hotspots, impact, and affected-test orientation. Generated graph/cockpit outputs are explicitly non-canonical views.
Runtime, Evidence, and Safety Gates
The deterministic Codex runtime route runner lives in plugins/product-agent-os/scripts/codex_runtime_runner/cli.py, with context loading, contracts, guards, redaction, routes, and state separated into sibling modules. It does not call a model or start live infrastructure. Fixture and transcript evaluation flows use run_fixture_eval.py, run_transcript_eval.py, and local assets under plugins/product-agent-os/assets/fixtures/. Approval-gated boundaries include target writes, live browser/server execution, external providers, canonical graph mutation, Git/release actions, and automation activation.
Generated Views, Learning, and Documentation
First-run cockpit, status, and offline artifact rendering are implemented by analysis_artifact_renderer.py, status_dashboard.py, and offline_artifact_export.py; outputs aid orientation but do not replace source or command evidence. The manual-only learning loop uses self_learning_state.py, self_learning_metrics.py, and self_learning_candidates.py. MkDocs source content is under docs/, with tracked generated site output in site/; docs infrastructure is configured by mkdocs.yml.
Main entry points: project_code_graph.py Project code graph · implementation-planner Requirements and plan · merge_infrastructure.py Validated merge gate · discovery.py Discovery and methodology
Components 18
Plugin package
Local Codex plugin boundary.
- Plugin manifest
plugins/product-agent-os/.codex-plugin/plugin.json - Optional MCP config
plugins/product-agent-os/.mcp.json - Codex skills · Lifecycle, discovery, and planning skills invoked by Codex.
- CLI workflows · First analysis, rendering, graph scan, runtime, and learning commands.
- Documentation site · Docs source is published as tracked generated site output.
Control plane
Durable delivery lifecycle.
- Canonical control artifacts · AGENTS, requirements, plan, tests, evals, and run log form the control-plane boundary.
- Lifecycle state
.codex/product-agent-os/lifecycle-state.json
Analysis and planning
Read-only discovery and project intelligence.
- Discovery and methodology · Classifies workspace evidence, maturity, risk, and methodology.
plugins/product-agent-os/scripts/product_agent_os/discovery.py - Requirements and plan · Turns audited intent into an implementation route.
plugins/product-agent-os/skills/implementation-planner - Project code graph · Scans source, docs, contracts, schemas, and tests for impact and read order.
plugins/product-agent-os/scripts/product_agent_os/project_code_graph.py - Cockpit and rendered views · Status, offline artifacts, and graph views aid orientation only.
plugins/product-agent-os/scripts/product_agent_os/analysis_artifact_renderer.py
Runtime and assurance
Deterministic execution, evaluation, and learning.
- Codex runtime runner · Loads context and applies contracts, guards, redaction, routes, and state without model or live infrastructure calls.
plugins/product-agent-os/scripts/codex_runtime_runner/cli.py - Fixture and transcript evaluation
plugins/product-agent-os/scripts/run_fixture_eval.py - Manual learning loop · Produces metrics and improvement candidates without automated activation.
Staged mutation
Approval-gated target workspace writes.
- Infrastructure templates
- External staging directory · Rendered proposals remain outside the target workspace.
- Validated merge gate · Checks manifest, paths, workspace binding, approval evidence, and rollback data.
plugins/product-agent-os/scripts/merge_infrastructure.py - Target workspace · Receives writes only after approval and merge validation.
Connections 19
- Plugin manifest → Codex skills: packages
- Optional MCP config → Codex skills: optionally configures
- Codex skills → CLI workflows: invoke workflows
- Codex skills → Discovery and methodology: start audit
- Discovery and methodology → Requirements and plan: routes by risk and maturity
- Requirements and plan → Canonical control artifacts: records
- Canonical control artifacts → Lifecycle state: drives lifecycle
- Project code graph → Requirements and plan: supplies impact evidence
- CLI workflows → Project code graph: scans project
- Project code graph → Cockpit and rendered views: renders non-canonical views
- Canonical control artifacts → Codex runtime runner: provides route context
- Codex runtime runner → Fixture and transcript evaluation: verified by
- Fixture and transcript evaluation → Manual learning loop: feeds manual candidates
- Manual learning loop → Canonical control artifacts: records approved learning
- Infrastructure templates → External staging directory: render proposals
- External staging directory → Validated merge gate: submit staged manifest
- Canonical control artifacts → Validated merge gate: provides approval evidence
- Validated merge gate → Target workspace: approved writes
- Documentation site → Codex skills: documents use