Skip to content

Commit 3781556

Browse files
Habib0x0Habib0x0
committed
docs: add Codex command syntax ($spec-driven: prefix) to all examples
- README commands tables now show both Claude Code / and Codex $spec-driven: syntax - docs/commands/index.md tables include both platforms - docs/getting-started/quick-start.md shows both syntaxes for each step - docs/getting-started/installation.md adds command syntax mapping table
1 parent ecf6da8 commit 3781556

4 files changed

Lines changed: 103 additions & 63 deletions

File tree

‎README.md‎

Lines changed: 34 additions & 26 deletions
Original file line numberDiff line numberDiff line change
@@ -12,48 +12,56 @@ This plugin guides you through three phases:
1212

1313
## Commands
1414

15+
Commands use `/` prefix in Claude Code and `$spec-driven:` prefix in Codex.
16+
1517
### Core Workflow
16-
| Command | Description |
17-
|---------|-------------|
18-
| `/spec-brainstorm` | Brainstorm a feature idea before spec creation |
19-
| `/spec <feature-name>` | Start a new feature spec with interactive 3-phase workflow |
20-
| `/spec-bugfix <bug-name>` | Start a new bugfix spec with defect analysis and regression prevention |
21-
| `/spec-refine` | Refine requirements/design for current spec |
22-
| `/spec-tasks` | Regenerate tasks from updated spec |
23-
| `/spec-status` | Show spec progress, task completion, and dependency status |
24-
| `/spec-validate` | Validate spec completeness and consistency |
18+
| Claude Code | Codex | Description |
19+
|-------------|-------|-------------|
20+
| `/spec-brainstorm` | `$spec-driven:spec-brainstorm` | Brainstorm a feature idea before spec creation |
21+
| `/spec <name>` | `$spec-driven:spec <name>` | Start a new feature spec with interactive 3-phase workflow |
22+
| `/spec-bugfix <name>` | `$spec-driven:spec-bugfix <name>` | Start a new bugfix spec with defect analysis and regression prevention |
23+
| `/spec-refine` | `$spec-driven:spec-refine` | Refine requirements/design for current spec |
24+
| `/spec-tasks` | `$spec-driven:spec-tasks` | Regenerate tasks from updated spec |
25+
| `/spec-status` | `$spec-driven:spec-status` | Show spec progress, task completion, and dependency status |
26+
| `/spec-validate` | `$spec-driven:spec-validate` | Validate spec completeness and consistency |
2527

2628
### Research & Navigation
27-
| Command | Description |
28-
|---------|-------------|
29-
| `/research` | Deep parallel research before planning — searches docs, web, and codebase |
30-
| `/zoom-out` | Map modules, interfaces, and callers for unfamiliar code |
31-
| `/ubiquitous-language` | Extract domain terms into a canonical glossary with flagged ambiguities |
29+
| Claude Code | Codex | Description |
30+
|-------------|-------|-------------|
31+
| `/research` | `$spec-driven:research` | Deep parallel research before planning — searches docs, web, and codebase |
32+
| `/zoom-out` | `$spec-driven:zoom-out` | Map modules, interfaces, and callers for unfamiliar code |
33+
| `/ubiquitous-language` | `$spec-driven:ubiquitous-language` | Extract domain terms into a canonical glossary with flagged ambiguities |
3234

3335
### Implementation
34-
| Command | Description |
35-
|---------|-------------|
36-
| `/spec-exec` | Run one autonomous implementation iteration |
37-
| `/spec-loop` | Loop implementation until all tasks complete |
36+
| Claude Code | Codex | Description |
37+
|-------------|-------|-------------|
38+
| `/spec-exec` | `$spec-driven:spec-exec` | Run one autonomous implementation iteration |
39+
| `/spec-loop` | `$spec-driven:spec-loop` | Loop implementation until all tasks complete |
3840

3941
### Post-Completion (Optional)
40-
| Command | Description |
41-
|---------|-------------|
42-
| `/spec-accept` | Run user acceptance testing for formal sign-off |
43-
| `/spec-docs` | Generate documentation from spec and implementation |
44-
| `/spec-release` | Generate release notes and deployment checklist |
45-
| `/spec-verify` | Run post-deployment smoke tests |
46-
| `/spec-retro` | Run a retrospective on a completed spec |
47-
| `/spec-complete` | Run full post-completion pipeline (accept → docs → release → retro) |
42+
| Claude Code | Codex | Description |
43+
|-------------|-------|-------------|
44+
| `/spec-accept` | `$spec-driven:spec-accept` | Run user acceptance testing for formal sign-off |
45+
| `/spec-docs` | `$spec-driven:spec-docs` | Generate documentation from spec and implementation |
46+
| `/spec-release` | `$spec-driven:spec-release` | Generate release notes and deployment checklist |
47+
| `/spec-verify` | `$spec-driven:spec-verify` | Run post-deployment smoke tests |
48+
| `/spec-retro` | `$spec-driven:spec-retro` | Run a retrospective on a completed spec |
49+
| `/spec-complete` | `$spec-driven:spec-complete` | Run full post-completion pipeline (accept → docs → release → retro) |
4850

4951
## Usage
5052

5153
### Starting a New Spec
5254

55+
**Claude Code:**
5356
```
5457
/spec user-authentication
5558
```
5659

60+
**Codex:**
61+
```
62+
$spec-driven:spec user-authentication
63+
```
64+
5765
This will:
5866
1. Create `.claude/specs/user-authentication/` directory
5967
2. Gather requirements interactively (2-3 rounds of questions)

‎docs/commands/index.md‎

Lines changed: 36 additions & 29 deletions
Original file line numberDiff line numberDiff line change
@@ -1,49 +1,56 @@
11
# Command reference
22

3-
All plugin commands are slash commands used within a Claude Code session. Execution scripts (`spec-loop.sh`, `spec-exec.sh`, etc.) are run from the terminal in your project root.
3+
Commands use `/` prefix in Claude Code and `$spec-driven:` prefix in Codex. Execution scripts (`spec-loop.sh`, `spec-exec.sh`, etc.) are run from the terminal in your project root.
4+
5+
| Claude Code | Codex | Description |
6+
|-------------|-------|-------------|
7+
| `/spec` | `$spec-driven:spec` | Start a new feature spec |
8+
| `/spec-brainstorm` | `$spec-driven:spec-brainstorm` | Brainstorm a feature idea |
9+
| `/spec-bugfix` | `$spec-driven:spec-bugfix` | Start a bugfix spec |
10+
| `/spec-status` | `$spec-driven:spec-status` | Check spec progress |
411

512
## Planning commands
613

7-
| Command | Description | Example usage |
8-
|---------|-------------|---------------|
9-
| `/spec-brainstorm` | Free-form conversation to refine a vague idea before formalizing a spec. Optionally brings in domain expert consultants. | `/spec-brainstorm user notifications` |
10-
| `/spec <name>` | Start a new feature spec with the three-phase workflow (Requirements, Design, Tasks). | `/spec user-authentication` |
11-
| `/spec-bugfix <name>` | Start a new bugfix spec with defect analysis, root cause, and regression-safe tasks. | `/spec-bugfix email-validation-plus-sign` |
12-
| `/spec-refine` | Update requirements or design for the current spec. Changes cascade to design and task regeneration. | `/spec-refine` |
13-
| `/spec-tasks` | Regenerate `tasks.md` from the current design, useful after design changes. | `/spec-tasks` |
14+
| Claude Code | Codex | Description | Example |
15+
|-------------|-------|-------------|---------|
16+
| `/spec-brainstorm` | `$spec-driven:spec-brainstorm` | Brainstorm a feature idea with optional expert consultants. | `/spec-brainstorm user notifications` |
17+
| `/spec <name>` | `$spec-driven:spec <name>` | Start a new feature spec (Requirements, Design, Tasks). | `/spec user-authentication` |
18+
| `/spec-bugfix <name>` | `$spec-driven:spec-bugfix <name>` | Start a bugfix spec with regression prevention. | `/spec-bugfix email-validation-plus-sign` |
19+
| `/spec-refine` | `$spec-driven:spec-refine` | Update requirements or design; cascades to tasks. | `/spec-refine` |
20+
| `/spec-tasks` | `$spec-driven:spec-tasks` | Regenerate `tasks.md` from current design. | `/spec-tasks` |
1421

1522
## Status and validation commands
1623

17-
| Command | Description | Example usage |
18-
|---------|-------------|---------------|
19-
| `/spec-status` | Show current progress: task counts, completion percentages, and dependency status. | `/spec-status` |
20-
| `/spec-validate` | Validate spec completeness and consistency: EARS notation, design coverage, task traceability, no circular dependencies. | `/spec-validate` |
24+
| Claude Code | Codex | Description | Example |
25+
|-------------|-------|-------------|---------|
26+
| `/spec-status` | `$spec-driven:spec-status` | Show progress, task counts, dependency status. | `/spec-status` |
27+
| `/spec-validate` | `$spec-driven:spec-validate` | Validate EARS notation, coverage, traceability. | `/spec-validate` |
2128

2229
## Execution commands
2330

24-
| Command | Description | Example usage |
25-
|---------|-------------|---------------|
26-
| `/spec-exec` | Run one autonomous implementation iteration: pick a task, implement, wire, test, commit. | `/spec-exec` |
27-
| `/spec-loop` | Trigger the loop script from inside Claude Code. Runs until all tasks are verified. | `/spec-loop` |
31+
| Claude Code | Codex | Description | Example |
32+
|-------------|-------|-------------|---------|
33+
| `/spec-exec` | `$spec-driven:spec-exec` | Run one implementation iteration. | `/spec-exec` |
34+
| `/spec-loop` | `$spec-driven:spec-loop` | Loop until all tasks are verified. | `/spec-loop` |
2835

2936
## Post-implementation commands
3037

31-
| Command | Description | Example usage |
32-
|---------|-------------|---------------|
33-
| `/spec-accept` | Run user acceptance testing. Traces every EARS criterion to a verified task. Outputs ACCEPTED or REJECTED. | `/spec-accept` |
34-
| `/spec-docs` | Generate documentation (API reference, user guide, runbook) from the spec and implementation. | `/spec-docs` |
35-
| `/spec-release` | Generate release notes, changelog, and deployment checklist. Optionally creates a git tag and GitHub release. | `/spec-release` |
36-
| `/spec-verify` | Run post-deployment smoke tests against a live URL. Exits 0 on PASS, 1 on FAIL. | `/spec-verify` |
37-
| `/spec-retro` | Run a structured retrospective on a completed spec. | `/spec-retro` |
38-
| `/spec-complete` | Run the full post-completion pipeline: accept → docs → release → retro. | `/spec-complete` |
38+
| Claude Code | Codex | Description | Example |
39+
|-------------|-------|-------------|---------|
40+
| `/spec-accept` | `$spec-driven:spec-accept` | Acceptance testing against EARS criteria. | `/spec-accept` |
41+
| `/spec-docs` | `$spec-driven:spec-docs` | Generate docs from spec and implementation. | `/spec-docs` |
42+
| `/spec-release` | `$spec-driven:spec-release` | Release notes, changelog, deployment checklist. | `/spec-release` |
43+
| `/spec-verify` | `$spec-driven:spec-verify` | Post-deployment smoke tests against a URL. | `/spec-verify` |
44+
| `/spec-retro` | `$spec-driven:spec-retro` | Retrospective on a completed spec. | `/spec-retro` |
45+
| `/spec-complete` | `$spec-driven:spec-complete` | Full pipeline: accept → docs → release → retro. | `/spec-complete` |
3946

4047
## Research and navigation commands
4148

42-
| Command | Description | Example usage |
43-
|---------|-------------|---------------|
44-
| `/research` | Deep research before planning. Launches parallel agents to search docs, web, and codebase. | `/research how does our auth middleware work` |
45-
| `/zoom-out` | Map modules, interfaces, and callers for unfamiliar code. | `/zoom-out` |
46-
| `/ubiquitous-language` | Extract domain terms into a canonical glossary with flagged ambiguities. | `/ubiquitous-language` |
49+
| Claude Code | Codex | Description | Example |
50+
|-------------|-------|-------------|---------|
51+
| `/research` | `$spec-driven:research` | Deep parallel research before planning. | `/research how does our auth middleware work` |
52+
| `/zoom-out` | `$spec-driven:zoom-out` | Map modules, interfaces, and callers. | `/zoom-out` |
53+
| `/ubiquitous-language` | `$spec-driven:ubiquitous-language` | Extract domain glossary. | `/ubiquitous-language` |
4754

4855
## Script equivalents
4956

‎docs/getting-started/installation.md‎

Lines changed: 14 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -43,9 +43,22 @@ The plugin also works with Codex via the manifest at `.codex-plugin/plugin.json`
4343
codex plugin marketplace add Habib0x0/spec-driven-plugin
4444
```
4545

46+
### Command Syntax
47+
48+
Codex commands use `$spec-driven:` prefix instead of `/`:
49+
50+
| Claude Code | Codex |
51+
|-------------|-------|
52+
| `/spec <name>` | `$spec-driven:spec <name>` |
53+
| `/spec-brainstorm` | `$spec-driven:spec-brainstorm` |
54+
| `/spec-bugfix <name>` | `$spec-driven:spec-bugfix <name>` |
55+
| `/spec-status` | `$spec-driven:spec-status` |
56+
| `/spec-exec` | `$spec-driven:spec-exec` |
57+
| `/spec-loop` | `$spec-driven:spec-loop` |
58+
4659
### Usage in Codex
4760

48-
Codex does not use slash commands. Invoke the skill by typing one of its default prompts:
61+
Invoke the skill by typing one of its default prompts:
4962

5063
| Prompt | Action |
5164
| --- | --- |

‎docs/getting-started/quick-start.md‎

Lines changed: 19 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -4,12 +4,16 @@ This guide walks through creating a spec from scratch and running the first impl
44

55
## Step 1: Start a new spec
66

7-
Run the `/spec` command with a feature name:
8-
7+
**Claude Code:**
98
```
109
/spec user-authentication
1110
```
1211

12+
**Codex:**
13+
```
14+
$spec-driven:spec user-authentication
15+
```
16+
1317
The command will ask you 2-3 rounds of questions about scope, user roles, key behaviors, edge cases, and non-functional requirements. Then the spec-planner agent (opus tier) writes formal requirements and design:
1418

1519
1. **Requirements** — It asks clarifying questions, identifies user roles, and writes user stories with EARS acceptance criteria
@@ -28,23 +32,31 @@ Your spec files are created at:
2832

2933
## Step 2: Check the spec status
3034

31-
Before running implementation, review what was created:
32-
35+
**Claude Code:**
3336
```
3437
/spec-status
3538
```
3639

40+
**Codex:**
41+
```
42+
$spec-driven:spec-status
43+
```
44+
3745
This shows task completion, dependency status, and which tasks are pending, in progress, or verified.
3846

3947
## Step 3: Run the first implementation iteration
4048

41-
Run one autonomous implementation cycle:
42-
49+
**Claude Code:**
4350
```
4451
/spec-exec
4552
```
4653

47-
The agent picks the highest-priority pending task, implements it, verifies it, updates `tasks.md`, and commits. Run it again for the next task, or use `/spec-loop` to run all tasks automatically.
54+
**Codex:**
55+
```
56+
$spec-driven:spec-exec
57+
```
58+
59+
The agent picks the highest-priority pending task, implements it, verifies it, updates `tasks.md`, and commits. Run it again for the next task, or use `/spec-loop` (Claude Code) / `$spec-driven:spec-loop` (Codex) to run all tasks automatically.
4860

4961
!!!tip
5062
If you have only one spec in `.claude/specs/`, the `--spec-name` argument is auto-detected. With multiple specs, pass `--spec-name <name>` explicitly.

0 commit comments

Comments
 (0)