# alexroadcaster/product-agent-os architecture

> Architecture diagram of the GitHub repository alexroadcaster/product-agent-os, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-08-01). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/alexroadcaster/product-agent-os
- Repository: https://github.com/alexroadcaster/product-agent-os

## Overview

#### 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: [`plugins/product-agent-os/scripts/product_agent_os/project_code_graph.py`](https://github.com/alexroadcaster/product-agent-os/blob/main/plugins/product-agent-os/scripts/product_agent_os/project_code_graph.py) (Project code graph), [`plugins/product-agent-os/skills/implementation-planner`](https://github.com/alexroadcaster/product-agent-os/tree/main/plugins/product-agent-os/skills/implementation-planner) (Requirements and plan), [`plugins/product-agent-os/scripts/merge_infrastructure.py`](https://github.com/alexroadcaster/product-agent-os/blob/main/plugins/product-agent-os/scripts/merge_infrastructure.py) (Validated merge gate), [`plugins/product-agent-os/scripts/product_agent_os/discovery.py`](https://github.com/alexroadcaster/product-agent-os/blob/main/plugins/product-agent-os/scripts/product_agent_os/discovery.py) (Discovery and methodology)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_package["Plugin package"]
  node_plugin_manifest["Plugin manifest<br/>plugin descriptor<br/>[plugin.json]"]
  node_mcp_config["Optional MCP config<br/>[.mcp.json]"]
  node_skills["Codex skills<br/>skill entry points"]
  node_cli_scripts["CLI workflows<br/>Python CLI"]
  node_documentation["Documentation site<br/>MkDocs source and output"]
end

subgraph group_control["Control plane"]
  node_control_artifacts["Canonical control artifacts<br/>durable project files"]
  node_lifecycle_state["Lifecycle state<br/>state record"]
end

subgraph group_analysis["Analysis and planning"]
  node_discovery_methodology["Discovery and methodology<br/>audit pipeline<br/>[discovery.py]"]
  node_implementation_plan["Requirements and plan<br/>planning stage"]
  node_code_graph{{"Project code graph<br/>graph intelligence"}}
  node_generated_views["Cockpit and rendered views<br/>non-canonical outputs"]
end

subgraph group_runtime["Runtime and assurance"]
  node_runtime_runner["Codex runtime runner<br/>deterministic route runner<br/>[cli.py]"]
  node_evaluation["Fixture and transcript evaluation<br/>local evaluation"]
  node_learning_loop["Manual learning loop<br/>learning workflow"]
end

subgraph group_mutation["Staged mutation"]
  node_templates["Infrastructure templates<br/>packaged templates"]
  node_staging["External staging directory<br/>proposal staging"]
  node_merge_gate{{"Validated merge gate<br/>safe mutation"}}
  node_target_workspace["Target workspace<br/>external workspace"]
end

node_plugin_manifest -->|"packages"| node_skills
node_mcp_config -.->|"optionally configures"| node_skills
node_skills -->|"invoke workflows"| node_cli_scripts
node_skills -->|"start audit"| node_discovery_methodology
node_discovery_methodology -->|"routes by risk and maturity"| node_implementation_plan
node_implementation_plan -->|"records"| node_control_artifacts
node_control_artifacts -->|"drives lifecycle"| node_lifecycle_state
node_code_graph -->|"supplies impact evidence"| node_implementation_plan
node_cli_scripts -->|"scans project"| node_code_graph
node_code_graph -->|"renders non-canonical views"| node_generated_views
node_control_artifacts -->|"provides route context"| node_runtime_runner
node_runtime_runner -->|"verified by"| node_evaluation
node_evaluation -->|"feeds manual candidates"| node_learning_loop
node_learning_loop -.->|"records approved learning"| node_control_artifacts
node_templates -->|"render proposals"| node_staging
node_staging -->|"submit staged manifest"| node_merge_gate
node_control_artifacts -->|"provides approval evidence"| node_merge_gate
node_merge_gate -->|"approved writes"| node_target_workspace
node_documentation -.->|"documents use"| node_skills

click node_plugin_manifest "https://github.com/alexroadcaster/product-agent-os/blob/main/plugins/product-agent-os/.codex-plugin/plugin.json"
click node_mcp_config "https://github.com/alexroadcaster/product-agent-os/blob/main/plugins/product-agent-os/.mcp.json"
click node_lifecycle_state "https://github.com/alexroadcaster/product-agent-os/blob/main/.codex/product-agent-os/lifecycle-state.json"
click node_discovery_methodology "https://github.com/alexroadcaster/product-agent-os/blob/main/plugins/product-agent-os/scripts/product_agent_os/discovery.py"
click node_implementation_plan "https://github.com/alexroadcaster/product-agent-os/tree/main/plugins/product-agent-os/skills/implementation-planner"
click node_code_graph "https://github.com/alexroadcaster/product-agent-os/blob/main/plugins/product-agent-os/scripts/product_agent_os/project_code_graph.py"
click node_generated_views "https://github.com/alexroadcaster/product-agent-os/blob/main/plugins/product-agent-os/scripts/product_agent_os/analysis_artifact_renderer.py"
click node_runtime_runner "https://github.com/alexroadcaster/product-agent-os/blob/main/plugins/product-agent-os/scripts/codex_runtime_runner/cli.py"
click node_evaluation "https://github.com/alexroadcaster/product-agent-os/blob/main/plugins/product-agent-os/scripts/run_fixture_eval.py"
click node_merge_gate "https://github.com/alexroadcaster/product-agent-os/blob/main/plugins/product-agent-os/scripts/merge_infrastructure.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_plugin_manifest,node_mcp_config,node_skills,node_cli_scripts,node_documentation toneBlue
class node_control_artifacts,node_lifecycle_state toneAmber
class node_discovery_methodology,node_implementation_plan,node_code_graph,node_generated_views toneMint
class node_runtime_runner,node_evaluation,node_learning_loop toneRose
class node_templates,node_staging,node_merge_gate,node_target_workspace toneIndigo
```

## Components

### Plugin package

Local Codex plugin boundary.

- [Plugin manifest](https://github.com/alexroadcaster/product-agent-os/blob/main/plugins/product-agent-os/.codex-plugin/plugin.json): plugin descriptor · `plugins/product-agent-os/.codex-plugin/plugin.json`
- [Optional MCP config](https://github.com/alexroadcaster/product-agent-os/blob/main/plugins/product-agent-os/.mcp.json): MCP config · `plugins/product-agent-os/.mcp.json`
- **Codex skills**: skill entry points · Lifecycle, discovery, and planning skills invoked by Codex.
- **CLI workflows**: Python CLI · First analysis, rendering, graph scan, runtime, and learning commands.
- **Documentation site**: MkDocs source and output · Docs source is published as tracked generated site output.

### Control plane

Durable delivery lifecycle.

- **Canonical control artifacts**: durable project files · AGENTS, requirements, plan, tests, evals, and run log form the control-plane boundary.
- [Lifecycle state](https://github.com/alexroadcaster/product-agent-os/blob/main/.codex/product-agent-os/lifecycle-state.json): state record · `.codex/product-agent-os/lifecycle-state.json`

### Analysis and planning

Read-only discovery and project intelligence.

- [Discovery and methodology](https://github.com/alexroadcaster/product-agent-os/blob/main/plugins/product-agent-os/scripts/product_agent_os/discovery.py): audit pipeline · Classifies workspace evidence, maturity, risk, and methodology. · `plugins/product-agent-os/scripts/product_agent_os/discovery.py`
- [Requirements and plan](https://github.com/alexroadcaster/product-agent-os/tree/main/plugins/product-agent-os/skills/implementation-planner): planning stage · Turns audited intent into an implementation route. · `plugins/product-agent-os/skills/implementation-planner`
- [Project code graph](https://github.com/alexroadcaster/product-agent-os/blob/main/plugins/product-agent-os/scripts/product_agent_os/project_code_graph.py): graph intelligence · 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](https://github.com/alexroadcaster/product-agent-os/blob/main/plugins/product-agent-os/scripts/product_agent_os/analysis_artifact_renderer.py): non-canonical outputs · 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](https://github.com/alexroadcaster/product-agent-os/blob/main/plugins/product-agent-os/scripts/codex_runtime_runner/cli.py): deterministic route 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](https://github.com/alexroadcaster/product-agent-os/blob/main/plugins/product-agent-os/scripts/run_fixture_eval.py): local evaluation · `plugins/product-agent-os/scripts/run_fixture_eval.py`
- **Manual learning loop**: learning workflow · Produces metrics and improvement candidates without automated activation.

### Staged mutation

Approval-gated target workspace writes.

- **Infrastructure templates**: packaged templates
- **External staging directory**: proposal staging · Rendered proposals remain outside the target workspace.
- [Validated merge gate](https://github.com/alexroadcaster/product-agent-os/blob/main/plugins/product-agent-os/scripts/merge_infrastructure.py): safe mutation · Checks manifest, paths, workspace binding, approval evidence, and rollback data. · `plugins/product-agent-os/scripts/merge_infrastructure.py`
- **Target workspace**: external workspace · Receives writes only after approval and merge validation.

## Connections

- 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