kompas3d-mcp/docs/superpowers/plans/2026-07-17-codex-sdk-research-agent.md

Codex SDK Research Agent Implementation Plan

For agentic workers: REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (- [ ]) syntax for tracking.

Goal: Turn the project-scoped kompas-sdk-research definition into a Codex-native, explicitly modeled, read-only documentation research agent.

Architecture: Keep the existing single custom-agent TOML and its KOMPAS SDK research methodology. Add Codex session overrides for model, reasoning effort, and sandboxing, and remove copied Claude-specific model terminology without changing .claude/agents/kompas-sdk-research.md.

Tech Stack: Codex custom-agent TOML, PowerShell, Python 3 tomllib, ripgrep, Git.

Global Constraints

• Use model = "gpt-5.6-terra".
• Use model_reasoning_effort = "medium".
• Use sandbox_mode = "read-only".
• Keep docs/Kompas3D_SDK/ as the canonical COM API5/API7 documentation source.
• Do not add web research, workspace editing, KOMPAS geometry construction, or KsAPI research to the agent.
• Leave .claude/agents/kompas-sdk-research.md unchanged.
• The parent task remains responsible for interop reflection checks when documentation and generated .NET names may differ.

---

Task 1: Adapt and verify the Codex custom agent

Files:

• Modify: .codex/agents/kompas-sdk-research.toml
• Verify unchanged: .claude/agents/kompas-sdk-research.md

Interfaces:

• Consumes: Codex standalone custom-agent fields name, description, developer_instructions, model, model_reasoning_effort, and sandbox_mode.

• Produces: project agent kompas-sdk-research running with gpt-5.6-terra, medium reasoning, and a read-only sandbox.

• Step 1: Run the pre-change configuration check and confirm it fails

Run:

@'
import pathlib
import tomllib

path = pathlib.Path('.codex/agents/kompas-sdk-research.toml')
data = tomllib.loads(path.read_text(encoding='utf-8'))
text = path.read_text(encoding='utf-8')

assert data['model'] == 'gpt-5.6-terra'
assert data['model_reasoning_effort'] == 'medium'
assert data['sandbox_mode'] == 'read-only'
assert not {'Haiku', 'Opus', 'Claude'} & set(text.replace('(', ' ').replace(')', ' ').split())
'@ | python -

Expected: FAIL with KeyError: 'model' because the Codex-specific model fields have not been added yet.

• Step 2: Add Codex-native model and isolation settings

Apply this exact header change:

 name = "kompas-sdk-research"
+model = "gpt-5.6-terra"
+model_reasoning_effort = "medium"
+sandbox_mode = "read-only"
 description = "..."

Replace the description value with this exact single-line TOML string:

description = "ОБЯЗАТЕЛЬНО делегируй этому read-only субагенту ЛЮБОЙ поиск по справке COM API КОМПАС в MD-базе docs/Kompas3D_SDK/ — НЕ ищи по справке в основной задаче. Срабатывает ПРОАКТИВНО, без явной просьбы пользователя: как только при планировании или реализации фичи понадобилась сигнатура метода (Automation/COM), значения перечисления (Obj3dType, ksHoleTypeEnum, ST_MIX_*, стили линий…), нужный интерфейс под задачу, единицы измерения или цепочка вызовов — СНАЧАЛА делегируй исследование этому агенту, ПОТОМ пиши код. Агент возвращает сжатую выжимку, а основная задача при необходимости перепроверяет спорные детали рефлексией по libs/kompas-interop/*.dll. Триггеры: «нужна сигнатура …», «какие значения enum …», «каким интерфейсом сделать X через API КОМПАС», «что возвращает <метод>», «как через COM API построить …», «найди в справке КОМПАС». НЕ для построения геометрии в КОМПАС и НЕ для KsAPI (Qt/C++ — в MD-базе его нет)."

Replace the copied provider-specific sentence in developer_instructions:

-Тебя вызывают, чтобы основная модель (Opus) не тратила контекст на поиск:
+Тебя вызывают, чтобы основная задача не тратила контекст на поиск:

Keep the remaining SDK database structure, lookup rules, response contract, and reflection warning unchanged.

• Step 3: Parse the TOML and verify the selected Codex settings

Run:

@'
import pathlib
import tomllib

path = pathlib.Path('.codex/agents/kompas-sdk-research.toml')
data = tomllib.loads(path.read_text(encoding='utf-8'))

assert data['name'] == 'kompas-sdk-research'
assert data['model'] == 'gpt-5.6-terra'
assert data['model_reasoning_effort'] == 'medium'
assert data['sandbox_mode'] == 'read-only'
assert data['description']
assert data['developer_instructions']
print('Codex agent configuration: OK')
'@ | python -

Expected: Codex agent configuration: OK.

• Step 4: Check for stale Claude terminology and unintended changes

Run:

$matches = rg -n "Haiku|Opus|Claude" '.codex/agents/kompas-sdk-research.toml'
if ($LASTEXITCODE -eq 0) { $matches; throw 'Stale Claude terminology remains' }
if ($LASTEXITCODE -ne 1) { throw 'ripgrep failed' }
git diff --check
git diff --exit-code -- '.claude/agents/kompas-sdk-research.md'
git diff -- '.codex/agents/kompas-sdk-research.toml'

Expected: no stale-term output, git diff --check succeeds, the Claude-file diff is empty, and the final diff contains only the planned Codex-agent changes.

• Step 5: Commit the Codex agent and implementation plan

Run:

git add -- '.codex/agents/kompas-sdk-research.toml' 'docs/superpowers/plans/2026-07-17-codex-sdk-research-agent.md'
git commit -m "chore: настроить Codex-агент поиска SDK"

Expected: one commit containing only the Codex agent definition and this implementation plan. Existing unrelated workspace changes remain unstaged.