This guide explains how to use the common AI rules (.ai-rules/) with GitHub Copilot and Codex.
codingbuddy integrates with GitHub Copilot / Codex in two ways:
.codex/rules/system-prompt.md- Codex system prompt (always-on instructions)- MCP Server - codingbuddy MCP tools for workflow management
End users access rules only through MCP tools. No local rule files needed.
Important: Whether Codex (GitHub Copilot) supports the
roots/listMCP capability has not been confirmed. WithoutCODINGBUDDY_PROJECT_ROOT, the server cannot locate your project'scodingbuddy.config.json, causing settings such aslanguageto use default values. Always set this environment variable to your project's absolute path. If Codex supports${workspaceFolder}variable expansion, you can use it instead of an absolute path.
Contributors to the codingbuddy repository can use direct file references:
Project Root/
├── .codex/
│ └── rules/
│ └── system-prompt.md # References .ai-rules
└── packages/rules/.ai-rules/ # Single Source of Truth
Single Source of Truth: packages/rules/.ai-rules/
- All Agent definitions, rules, skills managed only in
.ai-rules/ .codex/rules/system-prompt.mdacts as a pointer only- No duplication, only references
Create .github/copilot-instructions.md:
# GitHub Copilot Custom Instructions
## Common AI Rules
This project uses shared rules from `.ai-rules/` directory.
### Workflow (PLAN/ACT/EVAL)
Refer to `.ai-rules/rules/core.md` for detailed workflow guidance.
### Tech Stack & Project Structure
- See `.ai-rules/rules/project.md` for complete project setup
- Refer to project's package.json
- Layered architecture: app → widgets → features → entities → shared
### Coding Standards
- See `.ai-rules/rules/augmented-coding.md`
- TDD for core logic, test-after for UI
- SOLID principles, 90%+ test coverage
- No mocking, test real behavior
### Specialist Knowledge
- Refer to `.ai-rules/agents/*.json` for domain-specific guidanceThis project includes a pre-configured .codex/rules/system-prompt.md file.
Included features:
- Common AI rules reference from
.ai-rules/ - PLAN/ACT/EVAL workflow modes
- Keyword Invocation support
- TDD and code quality guidelines
- Specialist agents reference
File location: .codex/rules/system-prompt.md
See docs/codex-adapter-configuration.md for detailed configuration guide.
.codex/
└── rules/
└── system-prompt.md # Codex system prompt (pre-configured)
.github/
└── copilot-instructions.md # GitHub Copilot instructions (optional)
.ai-rules/ # Common rules for all AI tools
├── rules/
│ ├── core.md
│ ├── project.md
│ └── augmented-coding.md
├── agents/
│ └── *.json
└── adapters/
└── codex.md # This guide
See the MCP configuration in the End Users section above.
Project root resolution priority (in mcp.service.ts):
CODINGBUDDY_PROJECT_ROOTenvironment variable (highest priority)roots/listMCP capability (support unconfirmed in Codex)findProjectRoot()automatic detection (fallback)
System prompt providing context for Codex:
- Common AI rules reference from
.ai-rules/ - PLAN/ACT/EVAL workflow modes
- Keyword Invocation support
- TDD and code quality guidelines
- Specialist agents reference
File location: .codex/rules/system-prompt.md
For detailed setup instructions, see:
- Quick Start: docs/codex-adapter-configuration.md
- Keyword Invocation: docs/keyword-invocation.md
You: Implement new feature following our TDD workflow
Copilot: [References .ai-rules/rules/augmented-coding.md]
[Follows project structure from .ai-rules/rules/project.md]
Copilot will use context from:
.ai-rules/rules/project.mdfor naming conventions.ai-rules/rules/augmented-coding.mdfor code quality patterns- Existing codebase structure
For the full list of available tools, see docs/codex-adapter-configuration.md.
Key tools:
| Tool | Description |
|---|---|
parse_mode |
MANDATORY. Parse PLAN/ACT/EVAL/AUTO keywords and return mode-specific rules, agent, and context |
search_rules |
Search for rules and guidelines |
get_project_config |
Get project configuration including tech stack, architecture, conventions, and language settings |
set_project_root |
CODINGBUDDY_PROJECT_ROOT env var or --project-root CLI flag instead |
recommend_skills |
Recommend skills based on user prompt with multi-language support |
get_skill |
Get skill content by name (returns full skill definition including instructions) |
list_skills |
List all available skills with optional filtering by priority |
get_agent_details |
Get detailed profile of a specific AI agent |
get_agent_system_prompt |
Get complete system prompt for a specialist agent |
prepare_parallel_agents |
Prepare multiple specialist agents with system prompts for execution (recommended for Codex — use for sequential specialist analysis) |
dispatch_agents |
Get Task-tool-ready dispatch parameters for agents (optimized for Claude Code Task tool; in Codex, prefer prepare_parallel_agents) |
generate_checklist |
Generate contextual checklists based on file patterns and domains (security, a11y, performance, testing, code-quality, SEO) |
analyze_task |
Analyze a task for risk assessment, relevant checklists, specialist recommendations, and workflow suggestions |
get_code_conventions |
Get project code conventions from config files (tsconfig, eslint, prettier) |
suggest_config_updates |
Analyze the project and suggest config updates based on detected changes (new frameworks, dependencies, patterns) |
read_context |
Read current context document (docs/codingbuddy/context.md) with verbosity control |
update_context |
MANDATORY at mode end. Update context document with decisions, notes, progress, findings |
cleanup_context |
Manually trigger context document cleanup (summarizes older sections to reduce size) |
Codex does not have a Task tool for spawning background subagents. When parse_mode returns parallelAgentsRecommendation, execute specialists sequentially.
The MCP server automatically detects Codex as the client and returns a sequential execution hint in parallelAgentsRecommendation.hint. No manual configuration is needed.
parse_mode returns parallelAgentsRecommendation
↓
Call prepare_parallel_agents with recommended specialists
↓
For each specialist (sequentially):
- Announce: "🔍 Analyzing from [icon] [specialist-name] perspective..."
- Apply the specialist's system prompt as analysis context
- Analyze the target code/design from that specialist's viewpoint
- Record findings
↓
Consolidate all specialist findings into unified summary
parse_mode({ prompt: "EVAL review auth implementation" })
→ parallelAgentsRecommendation:
specialists: ["security-specialist", "accessibility-specialist", "performance-specialist"]
prepare_parallel_agents({
mode: "EVAL",
specialists: ["security-specialist", "accessibility-specialist", "performance-specialist"]
})
→ agents[]: each has systemPrompt
Sequential analysis:
1. 🔒 Security: Apply security-specialist prompt, analyze, record findings
2. ♿ Accessibility: Apply accessibility-specialist prompt, analyze, record findings
3. ⚡ Performance: Apply performance-specialist prompt, analyze, record findings
Present: Consolidated findings from all 3 specialists
When parse_mode returns a dispatchReady field, use it directly without calling prepare_parallel_agents:
parse_mode returns dispatchReady
↓
Use dispatchReady.primaryAgent.dispatchParams.prompt as primary analysis context
↓
For each dispatchReady.parallelAgents[] (sequentially):
- Apply dispatchParams.prompt as specialist analysis context
- Analyze from that specialist's viewpoint
- Record findings
↓
Consolidate all findings
Key fields:
dispatchReady.primaryAgent.dispatchParams.prompt— Primary agent system prompt. Use as the main analysis context.dispatchReady.parallelAgents[].dispatchParams.prompt— Each specialist's system prompt. Apply as analysis context for sequential execution.subagent_type— Claude Code Task tool parameter. Ignore in Codex.
Known limitation: Codex cannot execute specialists in parallel. The
parallelAgents[]array is consumed sequentially. True parallel execution requires Claude Code's Task tool.Fallback: If
dispatchReadyis not present in theparse_moderesponse, callprepare_parallel_agentsMCP tool to retrieve specialist system prompts.
Start Message:
🚀 Running N specialist analyses sequentially...
→ [icon] [specialist-name]
→ [icon] [specialist-name]
→ [icon] [specialist-name]
Per-Specialist:
🔍 Analyzing from [icon] [specialist-name] perspective...
[Analysis content]
Completion Message:
📊 Specialist Analysis Complete:
[icon] [Specialist Name]:
[findings summary]
[icon] [Specialist Name]:
[findings summary]
When prepare_parallel_agents returns failedAgents:
⚠️ Some agents failed to load:
✗ performance-specialist: Profile not found
Continuing with 3/4 agents...
Strategy:
- Continue with successfully loaded agents
- Report failures clearly to user
- Document which agents couldn't be loaded in final report
| Icon | Specialist |
|---|---|
| 🔒 | security-specialist |
| ♿ | accessibility-specialist |
| ⚡ | performance-specialist |
| 📏 | code-quality-specialist |
| 🧪 | test-strategy-specialist |
| 🏛️ | architecture-specialist |
| 📚 | documentation-specialist |
| 🔍 | seo-specialist |
| 🎨 | design-system-specialist |
| 📨 | event-architecture-specialist |
| 🔗 | integration-specialist |
| 📊 | observability-specialist |
| 🔄 | migration-specialist |
| 🌐 | i18n-specialist |
Specialist execution is recommended when parse_mode returns a parallelAgentsRecommendation field:
| Mode | Default Specialists | Use Case |
|---|---|---|
| PLAN | architecture-specialist, test-strategy-specialist | Validate architecture and test approach |
| ACT | code-quality-specialist, test-strategy-specialist | Verify implementation quality |
| EVAL | security-specialist, accessibility-specialist, performance-specialist, code-quality-specialist | Comprehensive multi-dimensional review |
Each workflow mode activates different specialist agents:
- PLAN mode: Architecture and test strategy specialists validate design
- ACT mode: Code quality and test strategy specialists verify implementation
- EVAL mode: Security, accessibility, performance, and code quality specialists provide comprehensive review
Important: Specialists from one mode do NOT carry over to the next mode. Each mode has its own recommended specialist set.
When using Copilot Workspace:
- It automatically reads
.github/copilot-instructions.md - Can reference
.ai-rules/files for detailed context - Applies rules across all generated code
- ✅ Better code suggestions aligned with project standards
- ✅ Consistent with other AI tools (Cursor, Claude, etc.)
- ✅ Leverages GitHub's integration
- ✅ Easy to maintain
- GitHub Copilot has shorter context compared to chat-based tools
- Instructions must be concise
- Best used as reference + code completion, not full workflow execution
- Update
.ai-rules/rules/*.mdfor universal rule changes - Keep
.github/copilot-instructions.mdconcise (Copilot's context limit) - Link to detailed rules in
.ai-rules/rather than duplicating
Industry standard format compatible with all AI tools (Codex, Cursor, Claude Code, Kiro, etc.):
# AGENTS.md
This project uses codingbuddy MCP server to manage AI Agents.
## Quick Start
...See AGENTS.md in project root for details.
Codex accesses codingbuddy skills through three patterns:
- Auto-recommend — AI calls
recommend_skillsbased on intent detection - Browse and select — User calls
list_skillsto discover, thenget_skillto load - Slash-command — User types
/<command>, AI maps toget_skill
Method 1: MCP Tool Chain (End Users — Recommended)
The AI should follow this chain when a skill might apply:
recommend_skills({ prompt: "user's message" })— Get skill recommendationsget_skill("skill-name")— Load the recommended skill's full content- Follow the skill instructions in the response
Example flow:
User: "There is a bug in the authentication logic"
→ AI calls recommend_skills({ prompt: "There is a bug in the authentication logic" })
→ Response: { recommendations: [{ skillName: "systematic-debugging", ... }], nextAction: "Call get_skill..." }
→ AI calls get_skill("systematic-debugging")
→ AI follows the systematic-debugging skill instructions
Method 2: File Reference (Monorepo Contributors Only)
cat .ai-rules/skills/<skill-name>/SKILL.md
⚠️ This method only works when.ai-rules/directory exists locally (monorepo development). It will fail silently when codingbuddy is installed via npm (npx codingbuddy).Note:
parse_modealready embeds matched skill content inincluded_skills— no separateget_skillcall needed when using mode keywords (PLAN/ACT/EVAL/AUTO).
Use list_skills to browse available skills before deciding which one to load:
AI calls list_skills()
→ Returns all skills with names, descriptions, and priority scores
# With filtering:
AI calls list_skills({ minPriority: 1, maxPriority: 3 })
→ Returns only skills within priority range
→ AI selects the most relevant skill
→ AI calls get_skill("selected-skill-name")
Tip: Use
recommend_skillswhen you want AI to automatically pick the best skill. Uselist_skillswhen you want to manually browse and select.
Codex has no native slash-command skill invocation. When a user types /<command>, the AI must call get_skill — this is Codex's equivalent of Claude Code's built-in Skill tool.
Rule: When user input matches /<command>, call get_skill("<skill-name>") and follow the returned instructions. This table is a curated subset — use list_skills() to discover all available skills.
| User Types | MCP Call |
|---|---|
/debug or /debugging |
get_skill("systematic-debugging") |
/tdd |
get_skill("test-driven-development") |
/brainstorm |
get_skill("brainstorming") |
/plan or /write-plan |
get_skill("writing-plans") |
/execute or /exec |
get_skill("executing-plans") |
/design or /frontend |
get_skill("frontend-design") |
/refactor |
get_skill("refactoring") |
/security or /audit |
get_skill("security-audit") |
/pr |
get_skill("pr-all-in-one") |
/review or /pr-review |
get_skill("pr-review") |
/parallel or /agents |
get_skill("dispatching-parallel-agents") |
/subagent |
get_skill("subagent-driven-development") |
For unrecognized slash commands, call recommend_skills({ prompt: "<user's full message>" }) to find the closest match.
Disambiguation:
/plan(with slash prefix) triggersget_skill("writing-plans").PLAN(without slash, at message start) triggersparse_mode. Similarly,/executetriggersget_skill("executing-plans")whileACTtriggersparse_mode. The slash prefix is the distinguishing signal.
Codex lacks session hooks that automatically enforce skill invocation (unlike Claude Code). The AI must detect intent patterns and call recommend_skills proactively — without waiting for the user to explicitly request a skill.
Rule: When the user's message suggests a skill would help, call recommend_skills at the start of the response — before any other action. The recommend_skills engine matches trigger patterns across multiple languages and is the authoritative source of truth.
Common trigger examples (not exhaustive):
| User Intent Signal | Likely Skill |
|---|---|
| Bug report, error, "not working", exception | systematic-debugging |
| "Brainstorm", "build", "create", "implement" | brainstorming |
| "Test first", TDD, write tests before code | test-driven-development |
| "Plan", "design", implementation approach | writing-plans |
| PR, commit, code review workflow | pr-all-in-one |
User: "I need to plan the implementation for user authentication"
→ AI calls recommend_skills({ prompt: "plan implementation for user authentication" })
→ Loads writing-plans via get_skill
→ Follows skill instructions to create structured plan
Note: When the user message starts with a mode keyword (
PLAN,ACT,EVAL,AUTO),parse_modealready handles skill matching automatically viaincluded_skills— no separaterecommend_skillscall is needed.
Highlighted skills (use list_skills() for the complete list):
brainstorming- Explore requirements before implementationtest-driven-development- TDD workflowsystematic-debugging- Debug methodicallywriting-plans- Create implementation plansexecuting-plans- Execute plans with checkpointssubagent-driven-development- In-session plan executiondispatching-parallel-agents- Handle parallel tasksfrontend-design- Build production-grade UIpr-all-in-one- Unified commit and PR workflow
Unified commit and PR workflow that:
- Auto-commits uncommitted changes (grouped logically)
- Creates or updates PRs with smart issue linking
- Supports multiple languages (en/ko/bilingual)
/pr-all-in-one [target-branch] [issue-id]
Examples:
/pr-all-in-one- PR to default branch, issue from branch name/pr-all-in-one develop- PR to develop branch/pr-all-in-one PROJ-123- PR with specific issue ID/pr-all-in-one main PROJ-123- PR to main with issue ID
Create .claude/pr-config.json in your project root (this is the canonical path used by the pr-all-in-one skill across all AI tools). Required settings:
defaultTargetBranch: Target branch for PRsissueTracker:jira,github,linear,gitlab, orcustomissuePattern: Regex pattern for issue ID extractionprLanguage:en,ko, orbilingual
See packages/rules/.ai-rules/skills/pr-all-in-one/configuration-guide.md for all options.
If no config file exists, the skill guides you through interactive setup:
- Select PR target branch
- Choose issue tracker
- Set PR description language
- (Optional) Configure issue URL template
SKILL.md- Main workflow documentationconfiguration-guide.md- Detailed config optionsissue-patterns.md- Supported issue tracker patternspr-templates.md- PR description templates
Use get_skill('pr-all-in-one') MCP tool to access the full skill documentation. This works in all environments (end users and monorepo contributors alike), unlike direct file access which only works when .ai-rules/ exists locally.
codingbuddy uses a fixed-path context document (docs/codingbuddy/context.md) to persist decisions across mode transitions.
| Mode | Behavior |
|---|---|
| PLAN / AUTO | Resets (clears) existing content and starts fresh |
| ACT / EVAL | Appends new section to existing content |
parse_modeautomatically reads/creates the context document- Review
contextDocumentin the response for previous decisions - Before completing each mode: call
update_contextto persist current work
| Tool | Purpose |
|---|---|
read_context |
Read current context document |
update_context |
Persist decisions, notes, progress, findings |
cleanup_context |
Summarize older sections to reduce document size |
Unlike Claude Code, Codex has no hooks or enforcement mechanisms to ensure update_context is called. The AI must voluntarily remember to call update_context before concluding each mode. Without this call, decisions and progress from the current mode will be lost across sessions or context compaction.
AUTO mode enables autonomous PLAN -> ACT -> EVAL cycling until quality criteria are met.
Use the AUTO keyword (or localized versions) at the start of your message:
| Language | Keyword |
|---|---|
| English | AUTO |
| Korean | AUTO |
| Japanese | 自動 |
| Chinese | 自动 |
| Spanish | AUTOMATICO |
AUTO implement user authentication with JWT
- PLAN Phase: Creates implementation plan with quality criteria
- ACT Phase: Executes implementation following TDD workflow
- EVAL Phase: Evaluates quality against exit criteria
- Loop/Exit: Continues cycling until:
- Success:
Critical = 0 AND High = 0 - Failure: Max iterations reached (default: 3)
- Success:
Severity and review-cycle canonical sources: The
Critical/Highlevels above are the Code Review Severity scale defined in../rules/severity-classification.md. The PR approval loop (CI gate → review → fix → re-review → approve) is specified in../rules/pr-review-cycle.md. Follow those canonical sources rather than re-deriving severity or approval criteria from this adapter.
When using GitHub Copilot Chat with AUTO mode:
- Copilot references
.ai-rules/rules/core.mdfor workflow - Applies
.ai-rules/rules/augmented-coding.mdTDD principles - Uses project structure from
.ai-rules/rules/project.md
Configure in codingbuddy.config.json:
module.exports = {
auto: {
maxIterations: 3
}
};- Large feature implementations requiring multiple refinement cycles
- Complex refactoring with quality verification
- Bug fixes needing comprehensive testing
- Code quality improvements with measurable criteria
Codex limitation: AUTO mode has no enforcement mechanism in Codex. See Known Limitations for details.
Codex environment does not support several features available in Claude Code:
| Feature | Status | Workaround |
|---|---|---|
| Task tool (background subagents) | ❌ Not available | Use prepare_parallel_agents for sequential execution |
Native Skill tool (/skill-name) |
❌ Not available | Use MCP tool chain: recommend_skills → get_skill |
| Background subagent execution | ❌ Not available | All specialist analyses run sequentially in the main thread |
| Session hooks (PreToolUse, etc.) | ❌ Not available | Rely on .codex/rules/system-prompt.md for always-on instructions |
| Autonomous loop mechanism | ❌ Not available | AUTO mode depends on Codex AI voluntarily looping |
| Context compaction hooks | ❌ Not available | Manually call update_context before ending each mode |
dispatch_agents full usage |
Returns Claude Code-specific dispatchParams; use prepare_parallel_agents instead |
|
roots/list MCP capability |
Set CODINGBUDDY_PROJECT_ROOT env var explicitly |
|
restart_tui |
❌ Not applicable | Claude Code TUI-only tool; not functional in Codex |
| Proactive skill detection | ❌ No hooks | AI must call recommend_skills voluntarily based on intent |
| Slash command native support | ❌ Not available | Map /<command> to get_skill calls (see Skills section) |
analyze_task auto-invocation |
❌ No hooks | AI must call at PLAN start voluntarily |
AUTO mode documents autonomous PLAN → ACT → EVAL cycling. In Codex, this depends entirely on the AI model voluntarily continuing the loop — there is no enforcement mechanism like Claude Code's hooks. Results may vary:
- The AI may stop after one iteration instead of looping
- Quality exit criteria (
Critical = 0 AND High = 0) are advisory, not enforced - For reliable multi-iteration workflows, prefer manual
PLAN→ACT→EVALcycling
- Ensure
.ai-rules/directory exists with all common rules - Configure MCP server with
CODINGBUDDY_PROJECT_ROOT:// Codex MCP configuration { "mcpServers": { "codingbuddy": { "command": "npx", "args": ["-y", "codingbuddy"], "env": { "CODINGBUDDY_PROJECT_ROOT": "/absolute/path/to/your/project" } } } }
- Verify
.codex/rules/system-prompt.mdreferences.ai-rules/correctly - Start a Codex session — MCP tools are now available
- Use PLAN/ACT/EVAL/AUTO workflow via
parse_modeMCP tool
Documentation based on MCP server source code analysis and Codex/GitHub Copilot public documentation. Runtime verification in a live Copilot + MCP environment has not yet been performed.
| Level | Meaning |
|---|---|
| ✅ Code-verified | Server-side code confirms the feature exists and returns expected data |
| ✅ Documented | Workflow documented based on design; runtime behavior not yet tested |
| Depends on Codex/Copilot capabilities not documented in public docs | |
| ❌ Not supported | Feature confirmed unavailable in Codex environment |
| Pattern | Status | Notes |
|---|---|---|
| MCP Tool Access | ✅ Code-verified | 19 tools registered in handlers; 18 applicable to Codex (restart_tui is Claude Code-only) |
| PLAN/ACT/EVAL Modes | ✅ Code-verified | parse_mode returns mode-specific rules, agent, context, and dispatchReady |
| Keyword Invocation | Depends on Copilot reliably calling parse_mode when mode keywords are detected |
|
| Skills (MCP Tools) | ✅ Code-verified | recommend_skills → get_skill tool chain returns correct data |
| Specialist Agents Execution | ✅ Documented | Sequential workflow with prepare_parallel_agents; not runtime-tested in Copilot |
| AUTO Mode | Depends on Copilot voluntarily continuing PLAN → ACT → EVAL loop | |
| Context Document Management | ✅ Code-verified | read_context, update_context, cleanup_context tools exist and function |
roots/list MCP Capability |
Not confirmed in Codex/GitHub Copilot public documentation | |
| Known Limitations | ✅ Documented | Task tool, hooks, AUTO mode, background subagent, dispatch_agents limitations |
| Task Tool / Background Subagent | ❌ Not supported | Sequential execution only; no parallel subagent spawning |
To fully verify these patterns, test in VS Code with GitHub Copilot + codingbuddy MCP:
- Type
PLAN design auth→ Copilot callsparse_mode(check MCP logs withMCP_DEBUG=1) - Type
EVAL review code→ Copilot callsparse_modewith EVAL mode - Type
/debug→ Copilot callsget_skill("systematic-debugging") - Type
AUTO implement feature→ Copilot attempts PLAN→ACT→EVAL loop - Verify
prepare_parallel_agentsreturns specialist prompts correctly - Verify
update_contextpersists across mode transitions - Test
CODINGBUDDY_PROJECT_ROOTenv var resolution