codex-specifications

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

1. Read project instructions first: AGENTS.md and .agent/CONTEXT.md when present.
2. Check existing specs in sdd/specs/ and proposals in sdd/proposals/ for prior decisions.
3. Prefer the local SDD template and workflow:
   • Template: sdd/templates/spec.md
   • Workflow reference: .claude/commands/sdd-spec.md
4. 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
---

5. Include a codebase contract with verified file paths, classes, and method signatures.
6. 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
7. 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",
)