Skip to content

codex.md

Latest commit

 

History

History
97 lines (61 loc) · 3.48 KB

codex.md

File metadata and controls

97 lines (61 loc) · 3.48 KB
Raw

Using This Framework with Codex

This framework was originally written around GitHub Copilot agents and Copilot slash commands. It can still be used effectively in Codex, but the setup and user experience are a little different.

What Changes in Codex

  • Copilot .prompt.md files do not map cleanly to Codex slash commands, so src/prompts/init-sdd.prompt.md should be treated as Copilot-specific
  • The reusable replacement for /init-sdd is the skill at src/skills/init-sdd/SKILL.md
  • For specialist workflows, prefer explicit agent invocation such as @Strategist, @Orchestrator, @Architect, @Coder, @PR Reviewer, @QA, and @Security
  • In environments that do not support @Agent mentions directly, use plain language like "use the Strategist agent" or "act as the Orchestrator"

In practice, the biggest UX difference is this:

  • Copilot: you can start with /init-sdd
  • Codex: you start by invoking the init-sdd skill or by explicitly addressing an agent

Recommended Setup

Keep specs/ repo-local, just like in the Copilot workflow. Those artifacts are project-specific and should live with the code.

For the reusable behavior:

  1. Copy the skills you want from src/skills/ into your Codex skills location, or otherwise register them in the Codex environment you use
  2. Reuse src/skills/init-sdd/SKILL.md as the Codex-friendly replacement for the Copilot-only /init-sdd prompt
  3. Keep the agent definitions from src/agents/ available in whatever Codex agent mechanism your setup supports

If your Codex environment supports custom agent definitions, use the TOML variants in src/agents/*.agent.toml as the preferred Codex-oriented source. The Markdown .agent.md files remain useful for Copilot and as human-readable references.

Suggested Repo-Level Approach

Use this repository as the source of truth and copy over only what the target Codex setup needs:

  • src/skills/ for reusable skills
  • src/agents/*.agent.toml for Codex-oriented agent definitions
  • specs/ for templates and generated artifacts

Treat src/prompts/ as optional and primarily for Copilot-compatible environments.

Typical Codex Flow

Bootstrap a repo

Use the init-sdd skill instead of /init-sdd.

Example phrasing:

Use the init-sdd skill to bootstrap this repository for spec-driven development.

Explore an idea

Explicitly invoke the Strategist:

@Strategist Help me think through a new notifications epic.

Route work

Explicitly invoke the Orchestrator:

@Orchestrator Build feature X from epic Y.

Implement

Use the Coder only after spec, plan, and tasks exist:

@Coder Implement task T3 from specs/feature-name/tasks.md.

UX Expectations

When moving from Copilot to Codex, expect these differences:

  • You will be more explicit about which agent you want
  • The init-sdd bootstrap is skill-driven rather than slash-command-driven
  • The workflow is the same, but the entry points are more conversational and less command-like

Recommended Mental Model

Think of the framework this way in Codex:

  • Skills provide reusable workflows and checklists
  • Agents provide focused roles such as Strategist, Orchestrator, Architect, and Coder
  • specs/ remains the source of truth across both Copilot and Codex

If you want the least-friction transition from Copilot to Codex, start by using:

  • init-sdd as a skill
  • @Strategist for exploration
  • @Orchestrator for routing
  • @Architect for spec, plan, and tasks
  • @Coder for implementation