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:

```powershell
@'
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:

```diff
 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:

```toml
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`:

```diff
-Тебя вызывают, чтобы основная модель (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:

```powershell
@'
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:

```powershell
$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:

```powershell
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.