Detailed mapping of every reference framework concept to its Codexkit equivalent.
Reference Framework is a TypeScript-based agent framework for reference system with custom runtimes, plugin systems, and a SQLite memory database. Codexkit achieves the same goals using Codex CLI native primitives — no custom code, no runtime dependencies.
The core insight: everything reference framework builds in TypeScript, Codex CLI already provides as a first-class feature. Codexkit is configuration, not code.
| # | Reference Framework Concept | Reference Framework Implementation | Codexkit Equivalent | Codexkit Implementation | Notes |
|---|---|---|---|---|---|
| 1 | Agent definitions | 9 TypeScript agent files with system prompts, model configs, permissions | Profiles + Custom Agents | 6 profiles in config.toml + 11 agent .toml files |
Profiles bundle model+sandbox+approval; agents add role-specific prompts |
| 2 | Agent system prompts | Inline TypeScript strings | AGENTS.md + agent .toml files | AGENTS.md (repo root) + .codex/agents/*.toml |
Layered: AGENTS.md is base, agent files are additive |
| 3 | Agent model selection | Per-agent model field in TypeScript |
Profile model field |
[profiles.<name>].model in config.toml |
CLI flag --model overrides |
| 4 | Agent permissions | Custom permission system in TypeScript | Sandbox + Approval policy | sandbox_mode and approval_policy fields per profile |
Native Codex CLI sandboxing |
| 5 | Slash commands | 18 TypeScript command handlers | Skills-first workflows + prompts | $wf-* skills + .codex/prompts/*.md (41 templates) |
Skills are primary; /prompts:<name> remains compatibility fallback |
| 6 | Command routing | TypeScript router with argument parsing | Codex skill invocation | $skill-name invocation; legacy /prompts:* fallback |
No custom routing needed |
| 7 | Skills system | 50+ TypeScript skill definitions | SKILL.md files | .codex/skills/*/SKILL.md (98 shipped skills) |
Loaded on demand by name |
| 8 | Skill loading | Dynamic TypeScript imports | Codex skill discovery | $skill-name invocation in conversation |
Native Codex CLI pattern |
| 9 | Memory database | SQLite + FTS5 full-text search | Context + memory docs | .codex/context/*.md + .codex/memory/ |
Human-maintained, version-controlled |
| 10 | Memory retrieval | SQL queries against SQLite DB | Direct file reading | Agent reads context docs as needed | Simpler, more transparent |
| 11 | Memory persistence | SQLite WAL mode, automatic saves | Git version control | Context docs committed to repo | Team-visible, auditable |
| 12 | DCP (context pruning) | Custom TypeScript context manager | /compact + AGENTS rules |
Token budget discipline in AGENTS.md | Native Codex CLI feature |
| 13 | Plugin system | TypeScript hook + tool plugins | Hooks + MCP | Shell hooks + MCP server configs | No custom plugin runtime |
| 14 | Plugin hooks | TypeScript event emitters | Shell hooks | .codex/hooks/*.sh (9 lifecycle hooks) |
Simpler, debuggable |
| 15 | Plugin tools | Custom TypeScript tool definitions | MCP servers | .codex/mcp/*.toml.example |
Standard protocol, not custom |
| 16 | Config system | legacy-config.json + TypeScript schemas |
config.toml | .codex/config.toml (layered TOML) |
Codex CLI native format |
| 17 | Config layering | Single file with overrides | 3-layer config | Project → User → CLI flags | Native Codex CLI layering |
| 18 | Bead workflow tracking | Custom workflow state machine | Git + context docs | Worklog + decision-log in context/ |
No custom state machine |
| 19 | Session management | TypeScript session state | Codex CLI sessions | Native session handling + hooks | No custom session code |
| 20 | Agent switching | Runtime agent hot-swap | Profile switching | codex --profile <name> |
CLI flag, not runtime swap |
Reference Framework had 9 agents, each a TypeScript class with system prompt, model selection, and permission configuration:
reference framework agents:
├── coder.ts → default profile
├── explorer.ts → explore profile
├── planner.ts → plan profile + planner agent
├── reviewer.ts → review profile + reviewer agent
├── debugger.ts → build profile (debugging via skills)
├── writer.ts → default profile (writing via prompts)
├── tester.ts → build profile (testing via skills)
├── architect.ts → plan profile (architecture via skills)
└── deployer.ts → ship profile + shipper agent
Codexkit collapses 9 agents into 6 profiles + shipped custom agent roles because:
- Many agents differed only in model/permissions → profiles handle this
- Role-specific behavior → custom agent system prompts
- Specialized tasks → skills (loaded on demand, not permanent agents)
Reference Framework had 18 slash commands implemented as TypeScript handlers:
reference framework commands → codexkit skills-first workflows and legacy prompts:
├── /init → /prompts:init
├── /plan → /prompts:plan (compatibility shim only)
├── /create → $wf-feature-delivery (legacy: /prompts:create)
├── /start → /prompts:create (now includes claim + branch)
├── /code → (covered by build profile)
├── /test → (covered by $test-strategy skill)
├── /debug → (covered by $debugging skill)
├── /review → /prompts:review-codebase
├── /refactor → (covered by $refactoring skill)
├── /verify → $wf-feature-delivery (legacy: /prompts:verify)
├── /ship → $wf-feature-delivery (legacy: /prompts:ship)
├── /pr → /prompts:pr
├── /lfg → /prompts:lfg
├── /status → (covered by context/current-priorities.md)
├── /memory → (covered by context/ docs)
├── /config → (handled by config.toml)
├── /help → (handled by AGENTS.md workflow reference)
└── /compact → (native Codex CLI feature)
Codexkit maps the workflow into 41 prompts because:
- Some commands map to profile switches, not prompts
- Some commands map to skills, invoked within any session
- Some commands map to native Codex CLI features
Reference Framework had 50+ TypeScript skill definitions with dynamic loading.
Codexkit provides 96 shipped skills as Markdown playbooks:
reference framework skills → codexkit SKILL.md files:
├── code-analysis/* → $repo-orientation
├── planning/* → $task-planning
├── implementation/* → $safe-implementation
├── testing/* → $test-strategy
├── bug-finding/* → $bug-triage
├── debugging/* → $debugging
├── refactoring/* → $refactoring
├── review/* → $code-review
├── verification/* → $verification
├── documentation/* → $docs-handoff
├── git/* → $git-pr-prep
├── dependency-mgmt/* → $dependency-upgrades
└── (50+ others) → Covered by AGENTS.md rules + prompts
The expansion from 50+ to 98 shipped skills reflects a different packaging model: Codexkit keeps reusable procedures as markdown playbooks, while AGENTS.md still absorbs broad operational rules such as security, scope discipline, and verification policy.
Reference Framework used SQLite + FTS5 for a searchable memory database with automatic ingestion.
Codexkit uses 8 curated context/session Markdown files:
reference framework memory → codexkit context:
├── project_facts table → architecture.md
├── coding_standards table → conventions.md
├── active_tasks table → current-priorities.md
├── decisions table → decision-log.md
├── session_logs table → worklog.md
└── full-text search → Agent reads files directly
Trade-offs:
- ✅ Version-controlled, team-visible, human-readable
- ✅ No database dependencies, no migration scripts
- ✅ Works offline, no corruption risks
⚠️ Manual curation required (but this is a feature: curated > auto-ingested)⚠️ No full-text search (but files are small enough to read fully)
Reference Framework had a custom plugin system with TypeScript hook and tool plugins.
Codexkit uses standard protocols:
reference framework plugins → codexkit equivalents:
├── hook plugins → .codex/hooks/*.sh (shell scripts)
├── tool plugins → MCP servers (config in config.toml)
├── plugin registry → (not needed — hooks are files, MCP is config)
├── plugin lifecycle → Codex CLI manages MCP server lifecycle
└── plugin API → MCP protocol (standard, not custom)
Reference Framework used legacy-config.json with TypeScript validation schemas.
Codexkit uses layered TOML:
reference framework config → codexkit config:
├── legacy-config.json → .codex/config.toml
├── agent configs (inline) → [profile.*] sections
├── model configs (inline) → profile.model field
├── permission configs → profile.sandbox + profile.approval
├── plugin configs → [mcp.*] sections + [hooks] section
└── user overrides → ~/.codex/config.toml (user-level)
For teams migrating from reference framework to Codexkit:
- Export important facts from SQLite memory →
context/architecture.md - Extract coding standards from memory →
context/conventions.md - Map active task records →
context/current-priorities.md - Review decision records →
context/decision-log.md - Identify which of the 9 agents you actively use → map to profiles
- Identify which slash commands you use → verify prompt coverage
- List custom plugins → find MCP equivalents or convert to hooks
- Test each profile:
codex --profile <name>with a sample task - Remove reference framework dependencies from the project
| Reference Framework Feature | Why Not in Codexkit |
|---|---|
| Custom TypeScript runtime | Codex CLI is the runtime |
| SQLite memory database | Context docs are simpler and version-controlled |
| 50+ granular skills | 96 shipped skills + AGENTS.md rules cover the same ground |
| Plugin API | MCP is the standard protocol |
| Hot-reload agent switching | Profile switching via CLI flag is sufficient |
| Automatic memory ingestion | Manual curation produces higher-quality context |
| Custom tool definitions | Codex CLI built-in tools + MCP cover all needs |