From 6aa05b1adbb1cc28bb60df0c5477b1502f75f01d Mon Sep 17 00:00:00 2001 From: Shahovalov MIkhail Date: Fri, 17 Jul 2026 01:06:25 +0300 Subject: [PATCH] =?UTF-8?q?docs:=20=D1=81=D0=BF=D1=80=D0=BE=D0=B5=D0=BA?= =?UTF-8?q?=D1=82=D0=B8=D1=80=D0=BE=D0=B2=D0=B0=D1=82=D1=8C=20Codex-=D0=B0?= =?UTF-8?q?=D0=B3=D0=B5=D0=BD=D1=82=20=D0=BF=D0=BE=D0=B8=D1=81=D0=BA=D0=B0?= =?UTF-8?q?=20SDK?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- ...6-07-17-codex-sdk-research-agent-design.md | 75 +++++++++++++++++++ 1 file changed, 75 insertions(+) create mode 100644 docs/superpowers/specs/2026-07-17-codex-sdk-research-agent-design.md diff --git a/docs/superpowers/specs/2026-07-17-codex-sdk-research-agent-design.md b/docs/superpowers/specs/2026-07-17-codex-sdk-research-agent-design.md new file mode 100644 index 0000000..5060936 --- /dev/null +++ b/docs/superpowers/specs/2026-07-17-codex-sdk-research-agent-design.md @@ -0,0 +1,75 @@ +# Codex SDK Research Agent Design + +## Goal + +Adapt the project-scoped `kompas-sdk-research` custom agent for Codex while +leaving the Claude Code agent unchanged. The Codex agent must be optimized for +fast, read-heavy searches in the local KOMPAS SDK Markdown knowledge base and +must not modify the workspace. + +## Configuration + +The Codex agent remains in `.codex/agents/kompas-sdk-research.toml` and uses: + +```toml +name = "kompas-sdk-research" +model = "gpt-5.6-terra" +model_reasoning_effort = "medium" +sandbox_mode = "read-only" +``` + +`gpt-5.6-terra` fits exploration, documentation scans, and distilled support +work. Medium reasoning is used because SDK questions can require correlating +several interfaces, overloads, constants, and COM call-chain details. + +## Agent Responsibilities + +The agent searches only local project and installed SDK reference material: + +- `docs/Kompas3D_SDK/` is the canonical source for COM API5/API7 documentation. +- SDK headers under the installed KOMPAS SDK may be read when exact constant + values need confirmation. +- The agent must not browse the web, edit files, implement features, or build + geometry in KOMPAS-3D. +- KsAPI is outside the Markdown knowledge base and must be reported as outside + scope instead of guessed. + +The parent agent delegates non-trivial SDK lookups before implementation. It +remains responsible for validating interop-specific discrepancies through +reflection over `libs/kompas-interop/*.dll` when needed. + +## Prompt Adaptation + +Remove Claude-specific references to Haiku and Opus from the Codex TOML. Keep +the existing domain guidance, but express it in provider-neutral Codex terms. +The description must make proactive delegation triggers clear without claiming +that the agent uses tools or model behavior specific to Claude Code. + +The response contract remains concise and evidence-oriented: + +1. Relevant interface, method, property, enum, or constant. +2. Automation syntax and COM syntax when parameter ordering matters. +3. Parameter and return-value meanings, including units and side effects. +4. Related overloads or interfaces when relevant. +5. Source article path and its `sources` frontmatter entry. +6. A warning when generated .NET interop names may differ from SDK docs. + +## Isolation and Compatibility + +The Claude definition in `.claude/agents/kompas-sdk-research.md` is not changed. +The two versions intentionally use different configuration formats and model +selection while sharing the same research methodology. + +The Codex agent's read-only behavior is enforced by `sandbox_mode`, not merely +requested in prose. No exact Claude-style tool allowlist is copied into the +Codex configuration. + +## Verification + +After editing the TOML: + +- parse it as TOML; +- confirm the required fields and selected model settings; +- confirm `sandbox_mode = "read-only"`; +- search the Codex file for stale `Haiku`, `Opus`, and Claude-specific wording; +- confirm the Claude agent file is unchanged.