bkit-codex - Vibecoding Kit (OpenAI Codex Edition)

PDCA methodology + Context Engineering for AI-native development

bkit-codex is an OpenAI Codex CLI extension that transforms how you build software with AI. It provides structured development workflows, automatic documentation, and intelligent code assistance through the PDCA (Plan-Do-Check-Act) methodology and Context Engineering architecture.

What is Context Engineering?

Context Engineering is the systematic curation of context tokens for optimal LLM inference -- going beyond simple prompt crafting to build entire systems that consistently guide AI behavior.

Traditional Prompt Engineering:
  "The art of writing good prompts"

Context Engineering:
  "The art of designing systems that integrate prompts, tools, and state
   to provide LLMs with optimal context for inference"

bkit is a practical implementation of Context Engineering, providing a systematic context management system across multiple AI coding platforms.

bkit-codex's Context Engineering Architecture

bkit-codex implements Context Engineering through three interconnected layers:

Layer	Components	Count	Purpose
Domain Knowledge	Skills	26	Structured expert knowledge activated on-demand via progressive disclosure
Behavioral Rules	AGENTS.md	2 files	Global + Project rules with MUST/ALWAYS/NEVER enforcement
State Management	MCP Tools + Lib Modules	16 + 75 fn	PDCA status tracking, intent detection, template management, memory persistence

Architecture

3-Tier Context Strategy

+------------------------------------------------------------------+
|                    Tier 1: AGENTS.md                              |
|                    (Always Loaded)                                |
|                                                                  |
|  Global AGENTS.md (~3.8 KB)    Project AGENTS.md (~2.0 KB)      |
|  - Session initialization      - Level-specific guidance         |
|  - 3 Core Principles           - Key skills reference            |
|  - PDCA workflow rules          - Response format rules           |
|  - MCP tools reference          - PDCA status location            |
|  - Code quality standards                                        |
|                                                                  |
|  Total: ~5.8 KB / 32 KB limit (18% used, 82% available)         |
+------------------------------------------------------------------+
                              |
                              v
+------------------------------------------------------------------+
|                    Tier 2: SKILL.md                               |
|                    (On-Demand Loading)                            |
|                                                                  |
|  Phase 1: name + description only (metadata scan)                |
|  Phase 2: Full SKILL.md body (when skill is activated)           |
|  Progressive Disclosure minimizes context usage                  |
+------------------------------------------------------------------+
                              |
                              v
+------------------------------------------------------------------+
|                    Tier 3: references/                            |
|                    (Deep Dive on Request)                         |
|                                                                  |
|  ~30 reference files (templates, patterns, checklists)           |
|  Loaded only when AI explicitly requests a reference file        |
+------------------------------------------------------------------+

Architecture Paradigm Shift

bkit-claude-code (Hook-Driven, 100% Auto)
  Hook Event --> Script (stdin/stdout) --> decision: allow/block
  = System controls the AI

bkit-codex (Instruction-Driven, ~70% Auto)
  AGENTS.md Rule --> AI reads --> AI calls MCP Tool --> MCP returns guidance
  = AI voluntarily follows rules

Component Map

bkit-codex/
|-- .agents/skills/          # 26 Codex Agent Skills
|   |-- bkit-rules/          # Core rules reference
|   |-- pdca/                # PDCA workflow management
|   |-- bkit-templates/      # Template selection
|   |-- starter/             # Beginner guidance
|   |-- dynamic/             # Fullstack guidance
|   |-- enterprise/          # Enterprise guidance
|   |-- development-pipeline/# 9-phase overview
|   |-- phase-1-schema/ ... phase-9-deployment/
|   |-- code-review/         # Code quality analysis
|   |-- zero-script-qa/      # Log-based testing
|   |-- mobile-app/          # React Native, Flutter, Expo
|   |-- desktop-app/         # Electron, Tauri
|   |-- codex-learning/      # Codex CLI guide
|   +-- bkend-*/             # bkend.ai ecosystem (5 skills)
|
|-- packages/mcp-server/     # MCP Server (zero external dependencies)
|   |-- index.js             # STDIO transport (JSON-RPC 2.0)
|   |-- src/server.js        # Request dispatcher
|   |-- src/tools/           # 16 MCP tool implementations
|   +-- src/lib/             # Core library (~75 functions)
|       |-- core/            # config, cache, file, path
|       |-- pdca/            # status, level, phase, automation, template
|       |-- intent/          # language, trigger, ambiguity
|       +-- task/            # classification, creator
|
|-- AGENTS.md                # Project AGENTS.md (sample)
|-- agents.global.md         # Global AGENTS.md (install to ~/.codex/)
|-- bkit.config.json         # Centralized configuration
|-- install.sh               # Unix/Mac installer
|-- install.ps1              # Windows installer
|-- docs/                    # Documentation
+-- .github/workflows/       # CI/CD (npm publish)

Features

PDCA Methodology -- Structured development with automatic documentation and phase enforcement
16 MCP Tools -- Session management, intent detection, PDCA workflow, template generation, memory persistence
26 Agent Skills -- Domain-specific knowledge with progressive disclosure to save context tokens
9-Stage Development Pipeline -- From schema design to deployment
3 Project Levels -- Starter (static), Dynamic (fullstack), Enterprise (microservices)
8-Language Support -- EN, KO, JA, ZH, ES, FR, DE, IT with auto-detection
Zero Dependencies -- MCP server built with pure Node.js (no node_modules)
Level-Specific Templates -- Enterprise design template with 11 sections (security, observability, cost analysis)
Ambiguity Detection -- Scores user prompts 0-100 and generates clarifying questions when needed
Session Memory -- Persistent context across sessions via docs/.bkit-memory.json
Evaluator-Optimizer Pattern -- Automatic gap analysis and fix cycles (max 5 iterations, 90% threshold)
Cross-Platform Install -- One-line installation for Unix/Mac and Windows

Quick Start

Note: bkit-codex is designed for OpenAI Codex CLI. For Claude Code, see bkit-claude-code. For Gemini CLI, see bkit-gemini.

Prerequisites

OpenAI Codex CLI v0.100.0 or later
Node.js v20+
Git

Installation

Unix / macOS (Recommended)

curl -fsSL https://raw.githubusercontent.com/popup-studio-ai/bkit-codex/main/install.sh | bash

Windows (PowerShell)

irm https://raw.githubusercontent.com/popup-studio-ai/bkit-codex/main/install.ps1 | iex

Manual Installation

# 1. Clone into project
git clone --depth 1 https://github.com/popup-studio-ai/bkit-codex.git .bkit-codex

# 2. Link skills
mkdir -p .agents/skills
for skill in .bkit-codex/.agents/skills/*/; do
  ln -sf "../../.bkit-codex/.agents/skills/$(basename $skill)" ".agents/skills/$(basename $skill)"
done

# 3. Copy AGENTS.md
cp .bkit-codex/AGENTS.md ./AGENTS.md

# 4. Configure MCP server
mkdir -p .codex
cat > .codex/config.toml << 'EOF'
[mcp_servers.bkit]
command = "node"
args = ["./.bkit-codex/packages/mcp-server/index.js"]
startup_timeout_sec = 10
tool_timeout_sec = 30
required = true
EOF

# 5. Create PDCA directories
mkdir -p docs/01-plan/features docs/02-design/features docs/03-analysis docs/04-report

Verify Installation

# Check skills are linked
ls .agents/skills/

# Check MCP config
cat .codex/config.toml

# Start Codex and invoke bkit
$pdca status

Usage

PDCA Workflow

$pdca plan <feature>     # Create plan document
$pdca design <feature>   # Create design document
$pdca do <feature>       # Implementation guide
$pdca analyze <feature>  # Run gap analysis
$pdca iterate <feature>  # Auto-fix with Evaluator-Optimizer pattern
$pdca report <feature>   # Generate completion report
$pdca status             # Check current PDCA status
$pdca next               # Guide to next PDCA step

Project Initialization

$starter      # Static website (Starter level)
$dynamic      # Fullstack with BaaS (Dynamic level)
$enterprise   # Microservices with K8s (Enterprise level)

Development Pipeline

$development-pipeline    # 9-phase pipeline overview
$phase-1-schema          # Schema & terminology definition
$phase-2-convention      # Coding conventions
$phase-3-mockup          # UI/UX mockups
$phase-4-api             # API design
$phase-5-design-system   # Design system
$phase-6-ui-integration  # UI integration
$phase-7-seo-security    # SEO & security
$phase-8-review          # Code review
$phase-9-deployment      # Deployment

Quality & Learning

$code-review             # Code quality analysis
$zero-script-qa          # Log-based testing (Zero Script QA)
$codex-learning          # Codex CLI configuration guide

PDCA Workflow

The core development cycle that bkit enforces:

Plan ──> Design ──> Do ──> Check ──> Act ──> Report
  │                          │         │
  │    (design required)     │    (if < 90%)
  │                          │         │
  X──── skip to Do ────X     +─────────+
                              iteration loop
                              (max 5 cycles)

Phase	Action	Deliverable
Plan	Define goals, scope, success criteria	`docs/01-plan/features/{feature}.plan.md`
Design	Architecture, data model, API spec	`docs/02-design/features/{feature}.design.md`
Do	Implementation with pre/post-write checks	Source code matching design
Check	Gap analysis (design vs. implementation)	`docs/03-analysis/{feature}.analysis.md`
Act	Auto-fix gaps until match rate >= 90%	Updated source code
Report	Completion report with metrics	`docs/04-report/{feature}.report.md`

Key Rules

Design is mandatory: You cannot skip from Plan directly to Do
Pre-write check: MCP tool validates design document existence before code changes
Post-write guidance: MCP tool suggests gap analysis after significant changes (50+ lines)
Iteration loop: Check and Act repeat until match rate reaches 90% (max 5 iterations)

Project Levels

Automatic detection based on project directory structure:

Level	Description	Stack	Auto-Detection	Pipeline Phases
Starter	Static websites, portfolios	HTML, CSS, JS	Default (no special files)	1 → 2 → 3 → 6 → 9
Dynamic	Fullstack applications	Next.js, BaaS	`docker-compose.yml`, `.mcp.json`, `api/`	1 → 2 → 3 → 4 → 5 → 6 → 7 → 9
Enterprise	Microservices architecture	K8s, Terraform, MSA	`kubernetes/`, `terraform/` directories	All 9 phases

MCP Tools (16)

The MCP server provides 16 tools via JSON-RPC 2.0 over STDIO with zero external dependencies:

Tool	Category	Purpose
`bkit_init`	Session	Initialize session, detect level, load PDCA status
`bkit_analyze_prompt`	Intent	Detect language, match triggers, score ambiguity (8 languages)
`bkit_get_status`	PDCA	Retrieve current PDCA status with recommendations
`bkit_pre_write_check`	PDCA	Pre-write compliance check (design document existence)
`bkit_post_write`	PDCA	Post-write guidance (gap analysis suggestions)
`bkit_complete_phase`	PDCA	Mark phase complete, validate transition, advance to next
`bkit_pdca_plan`	Template	Generate plan document template with level-specific sections
`bkit_pdca_design`	Template	Generate design template (Starter/Dynamic/Enterprise variants)
`bkit_pdca_analyze`	Template	Generate gap analysis template
`bkit_pdca_next`	PDCA	Recommend next PDCA action based on current state
`bkit_classify_task`	Utility	Classify task size (quick_fix / minor_change / feature / major_feature)
`bkit_detect_level`	Utility	Detect project level from directory structure
`bkit_select_template`	Utility	Select template by phase and level
`bkit_check_deliverables`	Utility	Verify phase deliverables exist
`bkit_memory_read`	Memory	Read session memory
`bkit_memory_write`	Memory	Write session memory

Skills (26)

Skill	Category	Trigger Examples
pdca	Core	`$pdca plan`, `$pdca design`, `$pdca analyze`
bkit-rules	Core	Core rules (auto-applied via AGENTS.md)
bkit-templates	Core	"plan template", "design template"
starter	Level	"static site", "portfolio", "beginner"
dynamic	Level	"login", "fullstack", "authentication"
enterprise	Level	"microservices", "k8s", "terraform"
development-pipeline	Pipeline	"where to start", "development order"
phase-1-schema	Pipeline	"schema", "data model", "terminology"
phase-2-convention	Pipeline	"coding rules", "conventions"
phase-3-mockup	Pipeline	"mockup", "wireframe", "prototype"
phase-4-api	Pipeline	"API design", "REST endpoints"
phase-5-design-system	Pipeline	"design system", "component library"
phase-6-ui-integration	Pipeline	"frontend integration", "API client"
phase-7-seo-security	Pipeline	"SEO", "security hardening"
phase-8-review	Pipeline	"architecture review", "gap analysis"
phase-9-deployment	Pipeline	"CI/CD", "production deployment"
code-review	Quality	"review code", "check quality"
zero-script-qa	Quality	"test logs", "QA without scripts"
mobile-app	Platform	"React Native", "Flutter", "iOS app"
desktop-app	Platform	"Electron", "Tauri", "desktop app"
codex-learning	Learning	"learn Codex", "Codex CLI setup"
bkend-quickstart	bkend.ai	"bkend setup", "first project"
bkend-data	bkend.ai	"table", "CRUD", "schema", "filter"
bkend-auth	bkend.ai	"signup", "login", "JWT", "session"
bkend-storage	bkend.ai	"file upload", "presigned URL", "CDN"
bkend-cookbook	bkend.ai	"tutorial", "example project", "todo app"

Skills use progressive disclosure -- only metadata is loaded initially, with full instructions injected when activated.

Language Support

bkit automatically detects your language from trigger keywords in 8 languages:

Language	Trigger Keywords
English	static website, beginner, API design, verify, analyze
Korean	정적 웹, 초보자, API 설계, 검증, 분석
Japanese	静的サイト, 初心者, API設計, 確認, 分析
Chinese	静态网站, 初学者, API设计, 验证, 分析
Spanish	sitio web estatico, principiante, verificar
French	site web statique, debutant, verifier
German	statische Website, Anfanger, prufen
Italian	sito web statico, principiante, verificare

Configuration

MCP Server (`.codex/config.toml`)

[mcp_servers.bkit]
command = "node"
args = ["./.bkit-codex/packages/mcp-server/index.js"]
startup_timeout_sec = 10
tool_timeout_sec = 30
required = true

bkit Config (`bkit.config.json`)

{
  "pdca": {
    "matchRateThreshold": 90,
    "maxIterations": 5,
    "statusFile": "docs/.pdca-status.json",
    "memoryFile": "docs/.bkit-memory.json"
  },
  "taskClassification": {
    "thresholds": { "quickFix": 10, "minorChange": 50, "feature": 200 }
  },
  "conventions": {
    "naming": {
      "components": "PascalCase",
      "functions": "camelCase",
      "constants": "UPPER_SNAKE_CASE",
      "files": "kebab-case"
    }
  },
  "supportedLanguages": ["en", "ko", "ja", "zh", "es", "fr", "de", "it"]
}

Relationship to bkit-claude-code

bkit-codex is a port of bkit-claude-code, adapted for OpenAI Codex CLI compatibility. Key differences:

Aspect	bkit-claude-code	bkit-codex
Platform	Claude Code	OpenAI Codex CLI
Automation	Hook-Driven (100% auto)	Instruction-Driven (~70% auto)
Context file	CLAUDE.md	AGENTS.md
Skills format	YAML frontmatter	SKILL.md + openai.yaml
Agent system	16 dedicated agents	SKILL.md descriptions
State management	Hook scripts	MCP tools
Hooks	10 hook events (45 scripts)	N/A (rules in AGENTS.md)
Team orchestration	CTO-Led Agent Teams	N/A
Functions	241 (5 lib modules)	75 (4 lib modules)
Commands	Slash commands (`/pdca`)	Skill invocation (`$pdca`)
Dependencies	Node.js modules	Zero external dependencies

What's Preserved

3 Core Principles (Automation First, No Guessing, Docs = Code)
PDCA workflow with phase transition validation
3-Level system (Starter / Dynamic / Enterprise)
9-Phase development pipeline
8-language trigger support
PDCA document templates
State file format (docs/.pdca-status.json)

What's Different

No hook system -- enforcement relies on AGENTS.md rules + MCP tool guidance
No team orchestration -- Codex CLI doesn't support agent spawning
Reduced function set (75 of 241) -- excluded hook I/O, team management, Claude Code-specific modules
Skills use Codex-native SKILL.md format with openai.yaml manifest

Documentation

Installation Guide -- Detailed setup instructions
Architecture -- System design and context strategy
Migration Guide -- Migrating from bkit-claude-code
Skills API -- All 26 skills reference
MCP API -- All 16 MCP tools reference
Changelog -- Version history

Contributing

We welcome contributions! Please see CONTRIBUTING.md for guidelines.

Quick Contribution Guide

Fork the repository
Create a feature branch from main
Make changes following code style guidelines
Run tests: node --test packages/mcp-server/tests/
Submit a pull request

Key Rules

Zero dependencies: MCP server must use pure Node.js only
Consistent patterns: All tools follow { handler, definition } pattern
8-language triggers: Include triggers in all 8 supported languages
JSDoc comments: Required for all public functions in lib/

Branch Protection

Only admin team members can merge to main
All changes require pull request review
Version releases are managed through Git tags

License

Licensed under the Apache License, Version 2.0. See LICENSE for details.

Support

Issues: GitHub Issues
Email: contact@popupstudio.ai

Made with AI by POPUP STUDIO

Name		Name	Last commit message	Last commit date
Latest commit History 3 Commits
.agents/skills		.agents/skills
.github/workflows		.github/workflows
docs		docs
packages/mcp-server		packages/mcp-server
scripts		scripts
tests/install		tests/install
.gitignore		.gitignore
AGENTS.md		AGENTS.md
CHANGELOG.md		CHANGELOG.md
CONTRIBUTING.md		CONTRIBUTING.md
LICENSE		LICENSE
README.md		README.md
agents.global.md		agents.global.md
bkit.config.json		bkit.config.json
install.ps1		install.ps1
install.sh		install.sh
uninstall.ps1		uninstall.ps1
uninstall.sh		uninstall.sh

License

popup-studio-ai/bkit-codex

Folders and files

Latest commit

History

Repository files navigation

bkit-codex - Vibecoding Kit (OpenAI Codex Edition)

What is Context Engineering?

bkit-codex's Context Engineering Architecture

Architecture

3-Tier Context Strategy

Architecture Paradigm Shift

Component Map

Features

Quick Start

Prerequisites

Installation

Unix / macOS (Recommended)

Windows (PowerShell)

Manual Installation

Verify Installation

Usage

PDCA Workflow

Project Initialization

Development Pipeline

Quality & Learning

PDCA Workflow

Key Rules

Project Levels

MCP Tools (16)

Skills (26)

Language Support

Configuration

MCP Server (.codex/config.toml)

bkit Config (bkit.config.json)

Relationship to bkit-claude-code

What's Preserved

What's Different

Documentation

Contributing

Quick Contribution Guide

Key Rules

Branch Protection

License

Support

About

Topics

Resources

License

Contributing

Uh oh!

Stars

Watchers

Forks

Releases 1

Packages 0

Contributors 2

Uh oh!

Languages

MCP Server (`.codex/config.toml`)

bkit Config (`bkit.config.json`)

Packages