codex-cli: /specify not really working

[dlukt]

Created a constitution.

Then

/specify
Public: list recent recipes globally; list by language; view details; search.
Auth: create/edit recipe; vote; favorite; comment; report; profile (my recipes); notifications center + notification settings.
Admin: moderation queue & actions, dashboards, recipe/comment management, users, ES stopwords/synonyms, reindex, audit log.

 ---
▌ description: Create or update the feature specification from a natural language feature description.
▌ ---
▌
▌ The user input to you can be provided directly by the agent or as a command argument - you **MUST** consider it before proceeding
▌ with the prompt (if not empty).
▌
▌ User input:
▌
▌ $ARGUMENTS
▌
▌ The text the user typed after `/specify` in the triggering message **is** the feature description. Assume you always have it
▌ available in this conversation even if `$ARGUMENTS` appears literally below. Do not ask the user to repeat it unless they provided
▌ an empty command.
▌
▌ Given that feature description, do this:
▌
▌ 1. Run the script `.specify/scripts/bash/create-new-feature.sh --json "$ARGUMENTS"` from repo root and parse its JSON output for
▌ BRANCH_NAME and SPEC_FILE. All file paths must be absolute.
▌   **IMPORTANT** You must only ever run this script once. The JSON is provided in the terminal as output - always refer to it to
▌ get the actual content you're looking for.
▌ 2. Load `.specify/templates/spec-template.md` to understand required sections.
▌ 3. Write the specification to SPEC_FILE using the template structure, replacing placeholders with concrete details derived from
▌ the feature description (arguments) while preserving section order and headings.
▌ 4. Report completion with branch name, spec file path, and readiness for the next phase.
▌
▌ Note: The script creates and checks out the new branch and initializes the spec file before writing.
▌

• Updated Plan
  └ □ Run create-new-feature script to obtain branch and spec path
    □ Draft specification content from template using feature description
    □ Write spec file and verify; report completion

• Ran .specify/scripts/bash/create-new-feature.sh --json "$ARGUMENTS"
  └ Usage: .specify/scripts/bash/create-new-feature.sh [--json] <feature_description>

• Updated Plan
  └ Script invocation failed because no feature description argument was provided, so we cannot proceed.
    ✔ Run create-new-feature script to obtain branch and spec path
    □ Draft specification content from template using feature description
    □ Write spec file and verify; report completion

> - Running .specify/scripts/bash/create-new-feature.sh --json "$ARGUMENTS" failed because the feature description argument was
  empty, so the script returned its usage message and exited.
  - Without that input the script cannot create a branch or spec stub, so no specification work can start.

  Please rerun /specify with the full feature description (or share it here), and I’ll regenerate the spec from there.

▌ ---
▌ description: Create or update the feature specification from a natural language feature description.
▌ ---
▌
▌ The user input to you can be provided directly by the agent or as a command argument - you **MUST** consider it before proceeding
▌ with the prompt (if not empty).
▌
▌ User input:
▌
▌ $ARGUMENTS
▌
▌ The text the user typed after `/specify` in the triggering message **is** the feature description. Assume you always have it
▌ available in this conversation even if `$ARGUMENTS` appears literally below. Do not ask the user to repeat it unless they provided
▌ an empty command.
▌
▌ Given that feature description, do this:
▌
▌ 1. Run the script `.specify/scripts/bash/create-new-feature.sh --json "$ARGUMENTS"` from repo root and parse its JSON output for
▌ BRANCH_NAME and SPEC_FILE. All file paths must be absolute.
▌   **IMPORTANT** You must only ever run this script once. The JSON is provided in the terminal as output - always refer to it to
▌ get the actual content you're looking for.
▌ 2. Load `.specify/templates/spec-template.md` to understand required sections.
▌ 3. Write the specification to SPEC_FILE using the template structure, replacing placeholders with concrete details derived from
▌ the feature description (arguments) while preserving section order and headings.
▌ 4. Report completion with branch name, spec file path, and readiness for the next phase.
▌
▌ Note: The script creates and checks out the new branch and initializes the spec file before writing.
▌

• Ran echo "$ARGUMENTS"
  └

> - Attempted to run .specify/scripts/bash/create-new-feature.sh --json "$ARGUMENTS", but the feature description argument was
  empty.
  - Without a description the script exits with its usage message, so no branch or spec stub was created.

  Please rerun /specify with the actual feature description (any natural-language summary of the feature). Once I have that, I can
  run the script and draft the specification.

[dlukt]

ChatGPT 5 had this to say:

Great idea. Forking spec-kit and adding a “codex profile” is the cleanest way to make /specify reliable with codex-cli. The two issues you linked show the core failure: codex often doesn’t pass the post-command text as $ARGUMENTS, so the stock flow runs the create script with an empty description and bails. ([GitHub]1)

Here’s a focused plan that fixes it without breaking other agents.

What’s going wrong (in one line)

• The current prompt+script chain assumes the feature text arrives as $ARGUMENTS; with codex-cli it’s frequently empty, so .specify/scripts/bash/create-new-feature.sh --json "$ARGUMENTS" prints usage and exits. ([GitHub]2)

Minimal, safe changes to spec-kit (proposed PR)

1. Add a codex profile with resilient input handling

   • New dir: .specify/profiles/codex/ with profile-specific system prompts where /specify:

     • Treats either $ARGUMENTS or STDIN as the feature description.
     • If both are empty, tries to parse the last user message quoted block (triple backticks) from the chat transcript (codex usually includes the message in the tool pane).

   • Default profile remains unchanged; select via SPEC_KIT_PROFILE=codex.

2. Make the create-new-feature.sh script accept fallback inputs

   • Current: create-new-feature.sh [--json] <feature_description>

   • Proposed:

     • Support --stdin (read full description from STDIN).
     • If <feature_description> is empty and STDIN has content → use STDIN.
     • Add --desc-file <path> as another fallback.
     • Preserve JSON output contract (BRANCH_NAME, SPEC_FILE) so upstream steps don’t change.

3. Update the /specify agent prompt (only in codex profile)

   • Run the script once as now, but choose the right input:

     • If $ARGUMENTS non-empty → create-new-feature.sh --json "$ARGUMENTS".
     • Else if <<FEATURE>> block was parsed from the triggering message → pipe it:
       printf '%s' "$FEATURE" | create-new-feature.sh --json --stdin
     • Else fail with a short explicit error (“no description found”) rather than asking the user to repeat.

4. Add front-matter detection in /specify template (optional QoL)

   • Accept and preserve a --- YAML header if present; codex sometimes prepends it. This avoids “empty feature” false-negatives when the first lines are metadata.

5. Monorepo path correctness (nice to have)

   • Reuse existing workarounds but ensure the codex profile computes spec paths relative to the workspace root or .git top, not the editor CWD. (Related complaints are common.) ([GitHub]3)

Test plan (keeps regressions out)

• BATS tests for the script:

  • with arg text
  • with STDIN only
  • with --desc-file
  • with arg+STDIN (arg wins)
  • empty inputs → non-zero exit & “no description” message

• Golden prompt tests for codex profile:

  • Transcript fixture where $ARGUMENTS is empty but the message body contains the description.
  • Verify only one script invocation occurs and JSON keys are parsed.

• Backward compat: run existing profile tests; no change expected.

Dev ergonomics in your fork

• Env switcher:

  export SPEC_KIT_PROFILE=codex   # falls back to 'default' if unset

• Script usage (after change):

  .specify/scripts/bash/create-new-feature.sh --json "Feature text…"
  # or
  printf '%s' "Feature text…" | .specify/scripts/bash/create-new-feature.sh --json --stdin
  # or
  .specify/scripts/bash/create-new-feature.sh --json --desc-file /tmp/desc.txt

Documentation snippet to add to README

codex-cli users: If /specify says your description is empty, switch to the codex profile:
SPEC_KIT_PROFILE=codex /specify <your text>
The codex profile will accept text from arguments, STDIN, or the last message block. It still runs the standard create-new-feature.sh once and uses its JSON output.

Why this solves 626 & 640

• In /specify command doesn't work well with codex cli #626 the command rejects because it never sees a description → STDIN/last-message fallback fixes it. ([GitHub]1)
• In codex-cli: /specify not really working #640 the trace shows $ARGUMENTS is literally empty, script prints usage → accepting STDIN or parsing the chat block prevents the early exit and continues with branch/spec creation. ([GitHub]2)

Optional extras (if you want to go further)

• Add a /specify.machine.yaml alongside the Markdown and let the agent fill that too; codex tends to be more reliable with YAML targets (no Markdown parsing ambiguity). (We can provide a JSON Schema and a tiny validator.)
• Provide a VS Code task “Spec: new feature (clipboard)” that pipes selection/clipboard into --stdin, so even if the chat UI drops args, the script still works.

If you want, I can sketch the exact diff for create-new-feature.sh and the profile prompt snippets for a PR description, but the outline above is enough to unblock your fork and make codex-cli happy while remaining upstream-friendly.

[localden]

The challenge here is that OpenAI Codex doesn't support passing arguments to custom slash commands.

See: openai/codex#2890

Seems like the fix is being rolled out, so this should hopefully be a non-issue soon.