Codex Installation

Codex runs Agent Teams Lite skills inline within a single context window. The structured SDD workflow provides value for planning and implementation, though without the fresh-context benefits of true sub-agent delegation.

Prerequisites

Codex installed and configured
Git installed for cloning the repository
Access to ~/.codex/ directory

Installation Steps

Clone the repository

git clone https://github.com/gentleman-programming/agent-teams-lite.git
cd agent-teams-lite

Run the installer

./scripts/install.sh
# Choose option 4: Codex

This copies skills to ~/.codex/skills/sdd-*/You should see output like:

Installing skills for Codex...
  ✓ _shared (3 convention files)
  ✓ sdd-init
  ✓ sdd-explore
  ✓ sdd-propose
  ✓ sdd-spec
  ✓ sdd-design
  ✓ sdd-tasks
  ✓ sdd-apply
  ✓ sdd-verify
  ✓ sdd-archive

  9 skills installed → ~/.codex/skills

Add orchestrator to instructions file

Codex reads instructions from ~/.codex/agents.md (or your configured model_instructions_file).Open your instructions file:

code ~/.codex/agents.md

Append the contents from examples/codex/agents.md to your existing file.

View orchestrator instructions

The orchestrator section teaches Codex to:

Detect SDD triggers and commands
Read skill files from ~/.codex/skills/sdd-*/SKILL.md
Execute skills inline within current context
Track state between phases
Follow artifact storage policies

Key components:

Operating Mode (delegate-only principle)
Artifact Store Policy (engram/openspec/none)
Commands table
Command → Skill Mapping
Dependency graph
Engram Artifact Convention

Verify installation

Start Codex in any project:

codex

Type:

/sdd-init

Expected response:

Reading sdd-init skill from ~/.codex/skills/sdd-init/SKILL.md...

Detecting project stack...
✓ Stack detected
✓ SDD initialized

Configuration Locations

Skills Directory

~/.codex/skills/sdd-*/Contains 9 skill folders + _shared/ conventions

Instructions File

~/.codex/agents.mdOrchestrator instructions and agent configuration

Custom Instructions Path

If you’ve configured a custom instructions file:

# Check your Codex config for model_instructions_file
cat ~/.codex/config.json | grep model_instructions_file

Add the orchestrator instructions to that file instead of agents.md.

How Inline Execution Works

Codex doesn’t have a Task tool for sub-agent delegation. Skills run inline: Characteristics:

Skills execute in the same context window
No fresh context per phase
Planning phases work well
Implementation batching handled by orchestrator
More context usage than true sub-agent systems

Example Usage

Initialize SDD

You: /sdd-init

Codex: Reading sdd-init skill...
       
       Detecting project characteristics...
       ✓ Language: Python
       ✓ Framework: FastAPI
       ✓ Database: PostgreSQL + SQLAlchemy
       
       Checking for persistence backend...
       ✓ Engram MCP server detected
       
       SDD initialized:
       - Project: my-api
       - Artifact store: engram
       
       Ready to start building.

Start a New Feature

You: /sdd-new add-webhook-support

Codex: Exploring codebase for webhook-related functionality...
       
       Reading sdd-explore skill...
       ✓ No existing webhook handlers found
       ✓ Event system detected in events.py
       ✓ Redis available for delivery queue
       
       Reading sdd-propose skill...
       
       Creating proposal:
       
       Intent:
       Add webhook delivery system for event notifications
       
       Scope:
       - Webhook CRUD endpoints
       - Event subscription model
       - Background delivery worker (Redis queue)
       - Retry logic with exponential backoff
       
       Approach:
       - FastAPI endpoints for webhook management
       - SQLAlchemy models for subscriptions
       - Celery tasks for async delivery
       - Webhook signature verification (HMAC)
       
       Rollback:
       - Remove webhook tables
       - Remove Celery tasks
       - Remove delivery queue
       
       Artifact stored: sdd/add-webhook-support/proposal
       
       Ready to continue with specs and design?

Continue Through Phases

You: /sdd-continue add-webhook-support

Codex: Next needed: specs and design
       
       Reading sdd-spec skill...
       Creating specifications...
       
       ✓ 5 requirements defined (SHALL statements)
       ✓ 11 scenarios with Given/When/Then
       ✓ Stored: sdd/add-webhook-support/spec
       
       Reading sdd-design skill...
       Creating technical design...
       
       ✓ Database schema (webhooks, deliveries tables)
       ✓ API routes (/webhooks CRUD + /webhooks/{id}/test)
       ✓ Celery task architecture
       ✓ Retry strategy (exponential backoff, max 5 attempts)
       ✓ Stored: sdd/add-webhook-support/design
       
       Next: Run /sdd-continue again to create task breakdown

Fast-Forward Planning

You: /sdd-ff add-webhook-support

Codex: Running all planning phases...
       
       [Already complete: proposal, spec, design]
       
       Reading sdd-tasks skill...
       
       Breaking down into implementation tasks:
       
       Phase 1: Data Models (3 tasks)
       ✓ 1.1 Create Webhook model
       ✓ 1.2 Create WebhookDelivery model
       ✓ 1.3 Create database migration
       
       Phase 2: API Endpoints (4 tasks)
       ✓ 2.1 POST /webhooks (create)
       ✓ 2.2 GET /webhooks (list)
       ✓ 2.3 DELETE /webhooks/{id}
       ✓ 2.4 POST /webhooks/{id}/test (manual trigger)
       
       Phase 3: Delivery System (3 tasks)
       ✓ 3.1 Implement Celery task
       ✓ 3.2 Add retry logic
       ✓ 3.3 Integrate with event system
       
       Total: 10 tasks
       Stored: sdd/add-webhook-support/tasks
       
       All planning complete. Run /sdd-apply to implement.

Artifact Storage

engram (Recommended)
openspec
none

# Auto-detected if Engram MCP server is available
artifact_store:
  mode: engram

Codex can use Engram’s MCP server for persistent storage:Naming convention:

title:     sdd/add-webhook-support/proposal
topic_key: sdd/add-webhook-support/proposal
type:      architecture
project:   my-api

Recovery:

1. mem_search(query: "sdd/add-webhook-support/proposal", project: "my-api")
2. mem_get_observation(id)

# Only when explicitly requested
artifact_store:
  mode: openspec

Creates file-based artifacts:

openspec/
├── config.yaml
├── specs/
└── changes/
    └── add-webhook-support/
        ├── proposal.md
        ├── specs/
        ├── design.md
        └── tasks.md

# Ephemeral mode - default fallback
artifact_store:
  mode: none

No persistence. Results returned inline.

Verification Checklist

Check skills directory

ls ~/.codex/skills/sdd-*/

Should show 9 directories:

sdd-apply/  sdd-design/  sdd-init/  sdd-spec/
sdd-archive/  sdd-explore/  sdd-propose/  sdd-tasks/  sdd-verify/

Check shared conventions

ls ~/.codex/skills/_shared/

Should show:

engram-convention.md
openspec-convention.md
persistence-contract.md

Verify instructions file

cat ~/.codex/agents.md | grep -i "sdd orchestrator"

Should return matches if orchestrator instructions are present.

Test SDD command

codex
# In Codex prompt:
# /sdd-init

Should recognize the command and read the sdd-init skill.

Troubleshooting

Command not recognized

Problem: Codex doesn’t recognize /sdd-initSolutions:

Verify orchestrator instructions are in ~/.codex/agents.md (or your custom instructions file)
Check file permissions allow reading
Restart Codex to reload configuration
Try alternative phrasing: “Initialize SDD” or “Set up spec-driven development”

Skills not found

Problem: Codex can’t read skill filesSolutions:

Verify skills are in ~/.codex/skills/sdd-*/
Check each skill directory has SKILL.md file
Ensure file permissions allow reading
Check orchestrator instructions reference correct path

Instructions not loading

Problem: Orchestrator behavior not activeSolutions:

Verify instructions file location (check Codex config)
Ensure file is named agents.md or matches model_instructions_file setting
Check file is readable: cat ~/.codex/agents.md
Restart Codex after making changes

Context issues on large features

Problem: Errors about context lengthSolutions:

Use /sdd-explore first to understand scope
Break large features into smaller changes
Consider using Claude Code or OpenCode for large features
Use none artifact mode to reduce context usage

Limitations

Codex runs skills inline rather than as true sub-agents. This means:

No fresh context per phase
Higher context usage
May hit context limits on large features
Planning phases work well
Implementation may need manual intervention on complex changes

For the best sub-agent experience with fresh context windows, consider:

Claude Code - Full sub-agent support
OpenCode - Full sub-agent support with slash commands

Next Steps

Quick Start

Learn the SDD workflow

Commands Reference

Complete command documentation

Engram Setup

Install recommended persistence

OpenSpec Mode

File-based artifact storage

Get Started

Installation

Guides

Commands

Prerequisites

Installation Steps

Configuration Locations

Skills Directory

Instructions File

Custom Instructions Path

How Inline Execution Works

Example Usage

Initialize SDD

Start a New Feature

Continue Through Phases

Fast-Forward Planning

Artifact Storage

Verification Checklist

Troubleshooting

Limitations

Next Steps

Quick Start

Commands Reference

Engram Setup

OpenSpec Mode

Build docs developers (and LLMs) love

Get Started

Installation

Guides

Commands

​Prerequisites

​Installation Steps

​Configuration Locations

Skills Directory

Instructions File

​Custom Instructions Path

​How Inline Execution Works

​Example Usage

​Initialize SDD

​Start a New Feature

​Continue Through Phases

​Fast-Forward Planning

​Artifact Storage

​Verification Checklist

​Troubleshooting

​Limitations

​Next Steps

Quick Start

Commands Reference

Engram Setup

OpenSpec Mode

Build docs developers (and LLMs) love

Prerequisites

Installation Steps

Configuration Locations

Custom Instructions Path

How Inline Execution Works

Example Usage

Initialize SDD

Start a New Feature

Continue Through Phases

Fast-Forward Planning

Artifact Storage

Verification Checklist

Troubleshooting

Limitations

Next Steps