Codex Spec Interviewer is a requirements-engineering skill for AI agents that converts loosely defined requests into structured, verifiable implementation plans before any code is written. It performs a source-backed interview by scanning a repository’s AGENTS.md file, existing Architecture Decision Records (ADRs), and the codebase itself to surface and challenge assumptions early. The output is a durable -spec.md file containing testable acceptance criteria, validation commands, and rollout risks, along with a dedicated Codex execution prompt formatted as high-context handoff instructions for coding agents.

The skill supports three workflow modes. Compact is intended for low-risk, small feature edits and prioritises speed. Standard is the default mode for bugfixes, refactors, and typical feature work. Deep is reserved for complex, repository-wide migrations and significant architectural shifts. Each mode calibrates the depth of questioning and documentation accordingly.

Architectural gating is built in: any change the skill classifies as architecturally significant is blocked from proceeding to code until a corresponding ADR is produced, preventing consequential decisions from disappearing into chat history. This makes the skill appropriate when a team wants AI-assisted development to remain auditable and aligned with existing architectural conventions. It is not a code-generation tool itself; it produces specifications that a separate coding agent consumes.

Use cases

Convert a vague feature request like 'add a billing dashboard' into a scoped, testable implementation spec

Automatically generate an ADR for any change the skill classifies as architecturally significant

Run a deep-mode interview before a repo-wide migration to surface risks and edge cases

Produce a Codex execution prompt that a downstream coding agent can follow without scope creep

Use compact mode to quickly spec a small, low-risk edit without full requirements overhead

Capture rollout risks and validation commands alongside acceptance criteria in a single spec file

When to use it

When a coding agent needs a structured, source-backed spec before starting implementation

When architectural decisions must be recorded as ADRs rather than left in chat history

When working on complex or repo-wide migrations that require deep assumption-challenging

When acceptance criteria and rollout risks need to be explicit before code review begins

When not to use it

When the goal is direct code generation rather than specification

When no repository context (AGENTS.md, ADRs, codebase) is available for the skill to scan

When the task requires runtime tool calls or data queries rather than requirements engineering

When a project has no interest in maintaining ADRs or structured spec files