ArcKit Codex CLI Extension

Standalone OpenAI Codex CLI extension for ArcKit -- The Enterprise Architecture Governance Harness.

Auto-generated: Files in this directory are generated from plugin commands by python scripts/converter.py. Do not edit them directly -- edit the source in arckit-claude/commands/ and re-run the converter.

Prerequisites

1. ChatGPT Plan: Codex CLI is included with ChatGPT Plus, Pro, Business, Edu, or Enterprise plans
2. Codex CLI installed: Follow installation instructions
3. Git repository: ArcKit works best inside a git repository

Installation

Option 1: CLI (Recommended)

The ArcKit CLI scaffolds a complete project with skills, agents, and MCP config in one step:

# Install the CLI
pip install git+https://github.com/tractorjuice/arc-kit.git
# Or with uv
uv tool install arckit-cli --from git+https://github.com/tractorjuice/arc-kit.git

# Create a new project
arckit init my-project --ai codex
cd my-project
codex

That's it -- no environment variables, no config files. Codex auto-discovers skills from .agents/skills/.

This creates a project with:

• .agents/skills/ -- ArcKit command skills plus 4 reference skills, auto-discovered by Codex
• .codex/agents/ -- 10 agent configs (research, datascout, gov reuse, grants, cloud providers, framework)
• .codex/hooks/ -- ArcKit lifecycle hooks for context injection, secret checks, file guardrails, and MCP approval policy
• .codex/config.toml -- 5 MCP servers, agent roles, and hook wiring
• .arckit/templates/ -- document templates
• .arckit/templates-custom/ -- project-specific template overrides
• .arckit/schemas/ -- handoff schemas for research and scoring workflows
• .arckit/scripts/ -- helper scripts

Option 2: Codex Plugin Bundle

Install ArcKit as a Codex plugin from the standalone marketplace repository:

codex plugin marketplace add tractorjuice/arckit-codex

Enable Codex lifecycle hooks in your user or project config:

[features]
hooks = true
plugin_hooks = true

Restart Codex, open the plugin directory, choose ArcKit Plugins, then install and enable ArcKit. The plugin manifest points to bundled skills, MCP server config, and hooks/hooks.json.

Option 3: Standalone Extension (manual)

This repo can also be used as a standalone extension installed once and shared across projects.

Step 1: Skills (commands)

Copy the skills/ directory into your project or home directory:

# Per-project (auto-discovered from repo root)
cp -r /path/to/arckit-codex/skills/* .agents/skills/

# Or global (auto-discovered from $HOME)
cp -r /path/to/arckit-codex/skills/* ~/.agents/skills/

This makes ArcKit commands available as $arckit-* skills plus 4 reference skills.

Step 2: MCP Servers and Agents

Merge the contents of config.toml into your project Codex configuration:

# If you don't have a project config yet, copy directly
mkdir -p .codex
cp /path/to/arckit-codex/config.toml .codex/config.toml

# If you already have a config, manually merge the [mcp_servers], [agents], and [hooks] sections

Copy the agent prompt files referenced by config.toml:

mkdir -p .codex/agents
cp -r /path/to/arckit-codex/agents/* .codex/agents/

Step 3: Lifecycle Hooks

Copy the Codex hook runner referenced by config.toml:

mkdir -p .codex/hooks
cp /path/to/arckit-codex/hooks/arckit-codex-hook.mjs .codex/hooks/

The hook wiring in config.toml enables:

• SessionStart context injection for ArcKit projects and recent session memory
• UserPromptSubmit secret detection and ArcKit context injection when $arckit-* skills are invoked
• UserPromptSubmit artifact graph context for $arckit-health, $arckit-traceability, $arckit-analyze, $arckit-search, $arckit-impact, $arckit-navigator, and $arckit-graph-report
• PreToolUse guardrails for apply_patch, Edit, Write, and simple Bash writes to credential files
• PreToolUse ARC artifact filename enforcement and vendors/scores.json validation
• PostToolUse provenance stamping and docs/manifest.json maintenance for changed project artifacts
• PermissionRequest auto-approval for ArcKit knowledge MCP servers
• Stop session memory capture in .arckit/memory/sessions.md

For deterministic research workflows, also copy the bundled schemas and validator:

mkdir -p .arckit/schemas .arckit/scripts
cp -r /path/to/arckit-codex/schemas/* .arckit/schemas/
cp /path/to/arckit-codex/scripts/validate-handoff.mjs .arckit/scripts/

MCP servers require no API keys except for Google Developer Knowledge (GOOGLE_API_KEY) and Data Commons (DATA_COMMONS_API_KEY). AWS Knowledge and Microsoft Learn work without authentication.

Skills

ArcKit commands are available as skills, invoked with $arckit-<command> in Codex CLI. Additionally, 4 reference skills provide domain knowledge.

Reference Skills

Skill	Invocation	Description
architecture-workflow	$architecture-workflow	ArcKit command sequencing, workflow paths, project onboarding, and "what comes next" guidance
mermaid-syntax	$mermaid-syntax	Mermaid diagram syntax for all diagram types (flowchart, sequence, C4, Gantt, ER, etc.), styling, theming, and troubleshooting
plantuml-syntax	$plantuml-syntax	PlantUML syntax including C4-PlantUML, sequence, class, activity, deployment diagrams, and layout patterns
wardley-mapping	$wardley-mapping	Wardley Mapping concepts: evolution stages, gameplay patterns, doctrine, build vs buy, quantitative scoring

Command Skill Examples

The examples below cover the most common workflows. The generated skills/arckit-*/ directories are the source of truth for the full command set.

Foundation and Governance

$arckit-plan           # Project plan with GDS Agile Delivery phases
$arckit-principles     # Architecture principles
$arckit-stakeholders   # Stakeholder analysis with Power-Interest Grid
$arckit-risk           # Risk register (HM Treasury Orange Book)
$arckit-sobc           # Strategic Outline Business Case (Green Book 5-case)
$arckit-strategy       # Architecture strategy
$arckit-start          # Guided project onboarding
$arckit-init           # Initialize project structure

Requirements and Data

$arckit-requirements       # Business, functional, non-functional requirements
$arckit-data-model         # Data model with ERD and GDPR compliance
$arckit-data-mesh-contract # Federated data product contract (ODCS v3.0.2)
$arckit-dpia               # Data Protection Impact Assessment
$arckit-platform-design    # Platform Design Toolkit (8 PDT canvases)
$arckit-glossary           # Domain glossary

Research and Procurement

$arckit-research        # Market research with build vs buy analysis
$arckit-datascout       # External data source discovery
$arckit-aws-research    # AWS service research via MCP
$arckit-azure-research  # Azure service research via MCP
$arckit-gcp-research    # Google Cloud research via MCP
$arckit-wardley         # Wardley mapping
$arckit-roadmap         # Multi-year strategic roadmap
$arckit-evaluate        # Vendor scoring against requirements
$arckit-sow             # RFP statement of work
$arckit-gcloud-search   # G-Cloud framework search
$arckit-gcloud-clarify  # Supplier clarification questions
$arckit-dos             # Digital Outcomes and Specialists procurement
$arckit-finops          # Cloud financial operations

Delivery and Quality

$arckit-adr             # Architecture Decision Records (MADR format)
$arckit-diagram         # C4 architecture diagrams
$arckit-dfd             # Data flow diagrams
$arckit-backlog         # Sprint-ready GDS backlog from requirements
$arckit-hld-review      # High-level design review
$arckit-dld-review      # Detailed design review
$arckit-analyze         # Cross-artifact quality analysis
$arckit-traceability    # Traceability matrix
$arckit-devops          # DevOps pipeline design
$arckit-mlops           # MLOps pipeline design
$arckit-operationalize  # Operational readiness
$arckit-servicenow      # ServiceNow CMDB export
$arckit-trello          # Trello board export
$arckit-framework       # Structured framework generation
$arckit-health          # Architecture health check
$arckit-presentation    # Executive presentation
$arckit-pages           # Documentation site generation
$arckit-template-builder # Custom template creation
$arckit-maturity-model  # Architecture maturity assessment

Compliance and Governance Reporting

$arckit-principles-compliance  # Principles compliance (RAG evidence)
$arckit-conformance            # Architecture conformance review
$arckit-service-assessment     # GDS Service Standard assessment
$arckit-secure                 # Secure by Design review
$arckit-mod-secure             # MOD Secure by Design assessment
$arckit-jsp-936                # JSP 936 AI assurance documentation
$arckit-tcop                   # Technology Code of Practice compliance
$arckit-atrs                   # Algorithmic Transparency Record
$arckit-ai-playbook            # UK Government AI Playbook alignment
$arckit-story                  # Programme story for governance reporting
$arckit-customize              # Template customization

OKF Interoperability

$arckit-export-okf  # Export ArcKit artifacts as an OKF-compatible Markdown bundle
$arckit-import-okf  # Import OKF bundles as reviewable research notes

Agents (Experimental)

Agents run as autonomous sub-processes to handle research-intensive tasks. They require the Codex multi-agent feature flag to be enabled.

Status: The Codex CLI multi-agent system is experimental. Agent configuration is provided in config.toml under the [agents] section. Enable via the Codex multi-agent feature flag.

Agent	Description
arckit-research	Market research, vendor evaluation, build vs buy analysis, TCO comparison, UK Digital Marketplace search
arckit-datascout	External data source discovery -- APIs, datasets, open data portals, commercial data providers
arckit-aws-research	AWS service research via AWS Knowledge MCP (service matching, Well-Architected guidance, Security Hub controls)
arckit-azure-research	Azure service research via Microsoft Learn MCP (service matching, Well-Architected guidance, Security Benchmark controls)
arckit-gcp-research	Google Cloud research via Google Developer Knowledge MCP (service matching, Architecture Framework guidance)
arckit-gov-code-search	Focused semantic search across UK government repositories
arckit-gov-landscape	Domain landscape mapping across UK government repositories and organisations
arckit-gov-reuse	UK government code reuse assessment by capability
arckit-grants	UK grant and funding opportunity research
arckit-framework	Transform project artifacts into a structured framework with phased organization, overview document, and executive guide

Each agent has a system prompt (agents/arckit-{name}.md) and a TOML configuration (agents/arckit-{name}.toml).

MCP Servers

Five Model Context Protocol servers are configured in config.toml to provide cloud platform, data, and UK government repository knowledge:

Server	URL	Auth Required
aws-knowledge	https://knowledge-mcp.global.api.aws	No
microsoft-learn	https://learn.microsoft.com/api/mcp	No
google-developer-knowledge	https://developerknowledge.googleapis.com/mcp	Yes (GOOGLE_API_KEY)
datacommons-mcp	https://api.datacommons.org/mcp	Yes (DATA_COMMONS_API_KEY)
govreposcrape	https://govreposcrape-api-1060386346356.us-central1.run.app/mcp	No

Differences from Claude Code

Feature	Claude Code (Plugin)	Codex CLI (Extension)
Command format	/arckit:principles	$arckit-principles
Command location	arckit-claude/commands/	arckit-codex/skills/arckit-*/
Skills	Supported (plugin skills/)	Supported (.agents/skills/, auto-discovered)
Agents	Supported (Task tool)	Experimental (multi-agent flag)
MCP servers	Supported (plugin config)	Supported (config.toml)
Hooks	Supported (plugin hooks/)	Supported (hooks/hooks.json and config.toml)
Approval modes	Automatic	--auto, --read-only, --network
Template paths	${CLAUDE_PLUGIN_ROOT}/templates/ defaults, .arckit/templates-custom/ overrides	.arckit/templates/ defaults, .arckit/templates-custom/ overrides
Installation	Marketplace plugin	CLI (arckit init --ai codex) or manual file copy

File Structure

arckit-codex/
├── README.md              # This file
├── VERSION                # Extension version (tracks plugin)
├── .codex-plugin/
│   └── plugin.json        # Codex plugin manifest
├── .mcp.json              # Codex plugin MCP server configuration
├── config.toml            # MCP servers, hooks, and agent configuration
├── hooks/
│   ├── hooks.json         # Codex plugin lifecycle configuration
│   └── arckit-codex-hook.mjs
├── skills/                # ArcKit command skills + 4 reference skills
│   ├── arckit-requirements/
│   │   ├── SKILL.md       # Command prompt with frontmatter
│   │   └── agents/
│   │       └── openai.yaml  # allow_implicit_invocation: false
│   ├── arckit-principles/
│   ├── ...                # More command skills
│   ├── architecture-workflow/  # Reference skill
│   ├── mermaid-syntax/         # Reference skill
│   ├── plantuml-syntax/        # Reference skill
│   └── wardley-mapping/        # Reference skill
├── prompts/               # Command prompts (deprecated, use skills instead)
├── agents/                # 10 agent configs + system prompts
│   ├── arckit-research.md
│   ├── arckit-research.toml
│   └── ...
├── templates/             # Document templates
├── config/                # Shared document type metadata
├── schemas/               # Handoff schemas and scoring rubrics
├── scripts/               # Helper scripts, validators, bash, python
└── docs/
    └── guides/            # Command usage guides

ArcKit Codex CLI Extension -- Generated by scripts/converter.py