| name | codex-specifications |
| description | Create and refine specification files for Codex-driven implementation through CodeToolkit. |
Codex Specifications Skill
Use this skill when a user wants a bugfix or feature implemented from a
specification file, or when a Codex coding task needs a clear spec before
execution.
Workflow
- Read project instructions first:
AGENTS.md and .agent/CONTEXT.md when present.
- Check existing specs in
sdd/specs/ and proposals in sdd/proposals/ for prior decisions.
- Prefer the local SDD template and workflow:
- Template:
sdd/templates/spec.md
- Workflow reference:
.claude/commands/sdd-spec.md
- Create or update a spec with frontmatter that Codex can consume:
---
type: bugfix
repo: ai-parrot
test_command: pytest tests/ -q
files_in_scope:
- packages/ai-parrot/src/parrot/
- packages/ai-parrot/tests/
definition_of_done:
- failing test added
- bug fixed
- all tests passing
---
- Include a codebase contract with verified file paths, classes, and method signatures.
- Keep implementation details precise enough for an autonomous coding provider:
- Problem statement
- Current behavior
- Expected behavior
- Files in scope
- Constraints
- Acceptance criteria
- Validation command
- Known risks
- Call
code.implement_spec only after the spec is explicit, scoped, and testable.
Guardrails
- Do not re-open resolved SDD brainstorm questions.
- Do not invent imports, classes, or packages. Verify them in the repository.
- Do not ask Codex to make broad unrelated refactors.
- Do not omit a validation command when a relevant test target is known.
- Treat Codex output as a patch proposal until tests and review confirm it.
Example
await code_toolkit.implement_spec(
spec_file="specs/bugfix-auth-timeout.md",
repo_path="/workspace/project",
test_command="pytest tests/auth -q",
)
