Available Commands¶

The CLI has six public commands. Agent integrations distribute 28 commands: Claude uses /codexspec:<name>, and Codex uses $codexspec:<name>. The tables below use Claude's spelling for readability.

CLI Commands¶

Command	Purpose
`codexspec init`	Initialize or refresh a project for Claude, Codex, or both
`codexspec check`	Check installed tools and dependencies
`codexspec version`	Display version and system information
`codexspec config`	View or modify project configuration
`codexspec list-commands`	List available agent commands by category
`codexspec show-blueprint`	Print the shared worktree's blueprint without changing it

Core Workflow Commands¶

Command	Purpose
`/codexspec:constitution`	Create/update project principles with cross-artifact validation
`/codexspec:specify`	Discuss, confirm, and persist feature requirements
`/codexspec:blueprint`	Prepare or maintain confirmed pending blueprint requirements
`/codexspec:generate-spec`	Compile confirmed requirements into a traceable specification; auto-review
`/codexspec:spec-to-design`	Define architecture, components, interfaces, and decisions; auto-review
`/codexspec:design-to-plan`	Plan implementation phases, ordering, and verification; auto-review
`/codexspec:plan-to-tasks`	Produce verifiable tasks with upstream coverage; auto-review and analyze
`/codexspec:implement-tasks`	Execute tasks, verify outcomes, review and repair
`/codexspec:auto-dev`	Autonomously develop confirmed blueprint requirements in document order

Artifact Review Commands¶

Command	Purpose
`/codexspec:review-spec`	Check specification fidelity and internal quality
`/codexspec:review-design`	Check design fidelity, feasibility, and planning readiness
`/codexspec:review-plan`	Check plan fidelity, feasibility, and implementation readiness
`/codexspec:review-tasks`	Check task fidelity, dependencies, executability, and verification

Requirements, Existing Code, and Debugging¶

Command	Purpose
`/codexspec:clarify`	Resolve requirement ambiguity, updating requirements before the specification
`/codexspec:analyze`	Check end-to-end traceability and conform downstream artifacts to authority
`/codexspec:checklist`	Generate a requirements-quality checklist
`/codexspec:tasks-to-issues`	Convert existing tasks into actionable GitHub issues
`/codexspec:debug`	Investigate root causes before applying a fix
`/codexspec:reverse-spec`	Survey existing architecture, draft module artifacts, or report baseline drift

Project Knowledge Commands¶

Command	Purpose
`/codexspec:distill`	Capture reusable knowledge or review candidates in the local workspace
`/codexspec:evolve`	Compile vetted knowledge into an upstream contribution draft
`/codexspec:onboard`	Seed candidate conventions and evidenced constraints from existing code

Git and Code Review Commands¶

Command	Purpose
`/codexspec:commit-staged`	Generate messages from staged changes; preview or execute an authorized commit
`/codexspec:pr`	Generate a structured PR/MR description
`/codexspec:release-notes`	Maintain a changelog entry and generate a release body from Git history
`/codexspec:review-code`	Review selected changes as a defect gate; use `--audit` for path quality

Utility Commands¶

Command	Purpose
`/codexspec:config`	Interactively create/view/modify/reset project configuration
`/codexspec:quick`	Run a compact Requirements-First SDD workflow for small changes

The old Python/React review entries are plugin compatibility artifacts, not part of the 28-command installation catalog. Use review-code with its applicable language/framework standards; use --audit for a path assessment.

Command Reference¶

`/codexspec:constitution`¶

Create or update the project constitution. The constitution defines architectural principles, technology stack, code standards, and governance rules that guide all subsequent development decisions.

Syntax:

/codexspec:constitution [principles description]

Arguments:

Argument	Required	Description
`principles description`	No	Description of principles to include (will be prompted if not provided)

What it does:

Creates .codexspec/memory/constitution.md if not exists
Updates existing constitution with new principles
Validates cross-artifact consistency with templates
Generates Sync Impact Report showing changes and affected files
Includes constitutionality review for dependent templates

What it creates:

.codexspec/
└── memory/
    └── constitution.md    # Project governance document

Example:

You: /codexspec:constitution Focus on code quality, testing standards, and clean architecture

AI:  Creating constitution...

     ✓ Created .codexspec/memory/constitution.md
     Version: 1.0.0

     Sync Impact Report:
     - plan-template-*.md: ✅ aligned
     - spec-template-*.md: ✅ aligned
     - tasks-template-*.md: ✅ aligned

     Core Principles:
     1. Code Quality First
     2. Test-Driven Development
     3. Clean Architecture

     Suggested commit: docs: create constitution v1.0.0

Tips:

Define principles early in the project for consistent decision-making
Include both technical and process principles
Review constitution before major feature development
Constitution changes trigger cross-artifact validation

`/codexspec:specify`¶

Clarify requirements through interactive Q&A, confirm the resulting summary, and persist it for later sessions.

Syntax:

/codexspec:specify [your idea or requirement]

Arguments:

Argument	Required	Description
`your idea or requirement`	No	Initial description of what you want to build (will be prompted if not provided)

What it does:

Asks clarifying questions to understand your idea
Explores edge cases you might not have considered
Co-creates high-quality requirements through dialogue
Focuses on "what" and "why", not technical implementation
Assigns stable IDs to confirmed needs, constraints, decisions, exclusions, and open questions
Records user evidence and a confirmation log
Creates the feature workspace and requirements.md

What it creates:

.codexspec/specs/{feature-id}-{feature-name}/requirements.md

Only confirmed items become authoritative requirements. Open questions remain explicitly open. This is the Confirmation Gate for requirements: nothing is binding until you explicitly confirm the final summary.

Example:

You: /codexspec:specify I want to build a task management app

AI:  Great! Let me help you clarify the requirements.

     First, who are the target users for this app?
     - Individual professionals
     - Small teams
     - Enterprise organizations
     - All of the above

You: Small teams, mainly software development teams

AI:  Got it. For small dev teams:
     - Do you need real-time collaboration features?
     - Should tasks support sub-tasks or just flat lists?
     - Any integration requirements (GitHub, Slack, etc.)?

You: Real-time is important. Sub-tasks yes. GitHub integration would be nice.

AI:  [Continues exploring requirements...]

     Summary of clarified requirements:
     - Target: Small dev teams (5-20 people)
     - Core: Tasks with sub-tasks, real-time updates
     - Integration: GitHub (optional)
     - Priority: Real-time collaboration > Sub-tasks > GitHub

     Ready to generate the spec document?
     Use /codexspec:generate-spec to create spec.md

Tips:

Use for initial requirement exploration
Don't worry about being complete—refinement is iterative
Ask questions if the AI makes assumptions
Review the summary before generating spec

`/codexspec:blueprint`¶

Use blueprint when you want to prepare several confirmed requirements before development, and auto-dev to develop that queue:

/codexspec:blueprint Add a confirmed requirement for task reminders
/codexspec:auto-dev

Blueprint discovery resolves user-owned direction, choices, and constraints before a requirement enters the queue. The shared .codexspec/blueprint.md uses pending, in_progress, and completed states. You can append, replace, delete, or reorder pending requirements; active and completed entries are read-only to blueprint maintenance.

Auto-dev follows document order, resumes an in-progress feature before starting another, and re-reads the queue after each completion so newly appended pending work can join the run. It performs the SDD stages, implementation, verification, review, and repair within the confirmed requirements. Calling auto-dev enables its automation independently of workflow.auto_next and does not change that setting.

Both commands share worktree-for-codexspec-auto-dev on branch codexspec/auto-dev. They can operate concurrently under the shared ownership and write protections; requirements are developed sequentially in that workspace. Product decisions that cannot be resolved from confirmed requirements stop the run with evidence rather than prompting during normal autonomous execution.

Inspect the current shared blueprint without changing it:

codexspec show-blueprint

`/codexspec:generate-spec`¶

Compile confirmed requirements into a traceable specification; auto-review.

Syntax:

/codexspec:generate-spec

Arguments:

Argument	Required	Description
Feature path	No	Explicit feature directory, `requirements.md`, or target `spec.md`; required when resolution is ambiguous

What it does:

Reads confirmed requirements from the selected feature workspace
Supports legacy workspaces containing only spec.md, with an explicit traceability warning
Generates comprehensive spec.md with:
Feature overview and goals
User stories with acceptance criteria
Functional requirements (REQ-XXX format)
Non-functional requirements (NFR-XXX format)
Edge cases and handling approaches
Out of scope items
Adds Sources references back to requirement IDs
Stops for user confirmation instead of resolving authority conflicts by assumption
Automatically reviews and may repair evidence-backed defects for at most two rounds

What it creates:

.codexspec/
└── specs/
    └── 2026-0613-1200ab-task-management/
        └── spec.md

Example:

You: /codexspec:generate-spec

AI:  Generating specification...

     ✓ Created .codexspec/specs/2026-0613-1200ab-task-management/spec.md

     Sections included:
     - Overview: Task management for small dev teams
     - 4 User Stories with acceptance criteria
     - 12 Functional Requirements (REQ-001 to REQ-012)
     - 3 Non-Functional Requirements (NFR-001 to NFR-003)
     - 5 Edge Cases documented
     - Out of Scope: Mobile apps, Enterprise SSO

     Next steps:
     - Review the spec with /codexspec:review-spec
     - Or proceed to /codexspec:spec-to-design

`/codexspec:spec-to-design`¶

Read the confirmed requirements.md and spec.md, project principles, and relevant repository facts. Produce design.md with components, interfaces, data flow, alternatives, and decisions linked to upstream requirements. Run review-design automatically. Stop when a design choice would change confirmed intent or requires a new user decision.

/codexspec:spec-to-design <feature-dir>

`/codexspec:design-to-plan`¶

Convert the confirmed design into an implementation plan. Run spec-to-design first to define architecture, components, interfaces, and technology choices.

/codexspec:design-to-plan [design.md | spec.md | feature-directory]

Read requirements.md, spec.md, design.md, and the constitution. Plan implementation phases, ordering, and verification; reference the design instead of redesigning the system. Each plan component carries Covers: REQ-xxx; Design: <design component>.

Write plan.md and run review-plan. With auto_next enabled, a passing review advances to plan-to-tasks. Decisions that change confirmed intent require user confirmation. An explicit path takes precedence over the current feature branch; ambiguous features require selection. Legacy features without design.md retain the existing fallback to spec.md.

`/codexspec:plan-to-tasks`¶

Break down the technical plan into actionable tasks with explicit coverage and verifiable outcomes.

Syntax:

/codexspec:plan-to-tasks [path_to_spec.md path_to_plan.md]

Arguments:

Argument	Required	Description
`paths`	No	Paths to spec and plan (auto-detected if not provided)

What it does:

Creates tasks with one verifiable outcome; a task may touch multiple related files
Uses test-first ordering only when required by the plan, constitution, confirmed needs, or risk
Marks tasks [P] only when they are genuinely independent
Specifies exact file paths for each task
Adds Covers links to plan and requirement IDs

What it creates:

.codexspec/
└── specs/
    └── 2026-0613-1200ab-task-management/
        └── tasks.md    # Task breakdown

Task Structure:

### Task 2.1: Write Tests for Entity A [P]
- **Type**: Testing
- **Files**: `tests/test_entity_a.py`
- **Description**: Write unit tests for Entity A
- **Dependencies**: Task 1.3
- **Est. Complexity**: Low

Example:

You: /codexspec:plan-to-tasks

AI:  Breaking down plan into tasks...

     ✓ Created tasks.md
     Total: 24 tasks
     Parallelizable: 8 tasks (33%)

     Phase 1: Foundation (4 tasks)
     Phase 2: Core Implementation - TDD (10 tasks)
     Phase 3: Integration (4 tasks)
     Phase 4: Interface Layer (3 tasks)
     Phase 5: Testing & Documentation (3 tasks)

     Execution Order:
     Phase 1 → [Phase 2 tasks in parallel groups] → Phase 3 → Phase 4 → Phase 5

     Checkpoints defined at each phase boundary.

Tips:

Each task should produce one verifiable outcome and may touch tightly related files
Test tasks precede implementation only when test-first is required
[P] marks truly independent parallelizable tasks
Review dependencies before implementation

After writing tasks, run review-tasks. A PASS or PASS_WITH_WARNINGS triggers analyze once; the analysis does not add a completion gate. Task coverage includes the confirmed requirements, specification, design, and plan.

`/codexspec:implement-tasks`¶

Execute tasks, verify outcomes, review and repair.

/codexspec:implement-tasks <feature-dir>

Four artifact reviewers check fidelity, coverage, feasibility, and internal quality: review-spec, review-design, review-plan, and review-tasks. They run automatically after generation and can also be invoked manually. Reports distinguish verified defects from non-gating risk advisories and design opportunities, with a compatibility score.

review-code provides a separate change-scoped defect gate and an explicit whole-code quality assessment:

/codexspec:review-code --feature <feature-dir>
/codexspec:review-code --uncommitted
/codexspec:review-code --audit src/

Default review covers the complete feature-branch delta, including committed, staged, unstaged, and untracked non-ignored changes. You can explicitly select committed, uncommitted, or one-commit evidence. --feature attaches requirements context without narrowing Git scope. --audit assesses the named paths and produces an advisory scorecard rather than a completion verdict.

Reviews load shared standards from .codexspec/review-code/, selecting relevant behavior dimensions and language/framework checks. Findings require concrete evidence, reachable triggers, selected-change attribution, and impact. The reviewer reports defects and substantiated maintenance suggestions without editing files; the repair caller independently verifies them.

Implementation uses test-first for code tasks and direct implementation with appropriate checks for documentation/configuration. After repairs, incremental re-review can reuse unaffected coverage; final acceptance requires a fresh complete-feature PASS, completed coverage and verification, and zero admitted P0–P3 defects. Substantiated maintenance suggestions are reported separately.

workflow.auto_maintenance defaults to true and controls whether repair callers also apply verified, compatible maintenance improvements. Turning it off still reports those suggestions and does not waive defects or required checks. It is separate from stage advancement and is not an implement-tasks argument.

For root-cause-first debugging:

/codexspec:debug Investigate intermittent failures when saving a task

Debug follows investigation → pattern analysis → single-hypothesis verification → failing-test-first fix. Implementation escalates when repairs are stuck, a non-trivial correctness defect needs tracing, or the same root-cause class recurs across review rounds. Three failed fixes trigger architectural reassessment.

Use checklist to assess requirement clarity, completeness, and consistency:

/codexspec:checklist Check the authentication requirements for completeness

See the command reference for review selectors, arguments, and detailed procedures.

`/codexspec:auto-dev`¶

Autonomously develop confirmed blueprint requirements in document order.

See blueprint.

/codexspec:auto-dev

`/codexspec:review-spec`¶

Validate the specification against confirmed requirements and its own internal quality.

Syntax:

/codexspec:review-spec [path_to_spec.md]

Arguments:

Argument	Required	Description
`path_to_spec.md`	No	Path to spec file (auto-detected if not provided)

What it does:

Checks fidelity to confirmed requirements.md entries
Checks internal consistency, clarity, and verifiability
Treats a missing template section as a defect only when authoritative content requires it
Requires each defect to include Evidence, Location, Mismatch, Impact, and Remediation
Separates Risk Advisories / Design Opportunities from defects
Generates status plus a compatibility score derived from classified findings

Shared review contract:

Category	Meaning
Fidelity defect	Conflicts with or omits an authoritative source
Intrinsic defect	Internally contradictory, infeasible, or unverifiable
Advisory	Optional improvement without evidence of a current defect

Status is PASS, PASS_WITH_WARNINGS, NEEDS_REVISION, or BLOCKED. Advisories never change status or score.

Example:

You: /codexspec:review-spec

AI:  Overall Status: NEEDS_REVISION
     Compatibility Score: 79/100

     Warning SPEC-001
     Evidence: CON-002 requires a measurable response-time limit.
     Location: spec.md, REQ-006
     Mismatch: "Respond quickly" has no measurable threshold.
     Impact: Acceptance cannot be verified.
     Remediation: Ask the user to confirm a threshold, update requirements.md,
                  then synchronize REQ-006.

     Risk Advisories / Design Opportunities:
     - None

Tips:

Run before /codexspec:spec-to-design
Treat BLOCKED and NEEDS_REVISION as not ready to proceed
Do not promote advisories into requirements
Re-run after making fixes

`/codexspec:review-design`¶

Review design.md against confirmed requirements and the specification for fidelity, feasibility, and readiness for planning. Report evidence-backed defects separately from optional design opportunities; use the same artifact statuses and bounded repair rules as the other artifact reviewers.

/codexspec:review-design <feature-dir>

`/codexspec:review-plan`¶

Review the technical implementation plan for fidelity, feasibility, and justified technical decisions.

Syntax:

/codexspec:review-plan [path_to_plan.md]

Arguments:

Argument	Required	Description
`path_to_plan.md`	No	Path to plan file (auto-detected if not provided)

What it does:

Verifies Covers links and required spec coverage
Checks applicable constitution rules and repository facts
Flags unjustified complexity only when it creates a concrete cost or conflict
Requires evidence fields for every defect and merges findings with the same root cause
Reports optional architecture improvements as advisories
Uses the shared status and compatibility-score contract

Example:

You: /codexspec:review-plan

AI:  Overall Status: PASS
     Compatibility Score: 100/100
     Verified defects: none

     Risk Advisories / Design Opportunities:
     - A caching layer may become useful if production measurements exceed
       the confirmed latency target. It is not required by the current plan.

Tips:

Run before /codexspec:plan-to-tasks
Resolve evidence-backed defects before task generation
Keep speculative architecture ideas in the advisory section
Verify tech stack aligns with team skills

Planning implements the confirmed design.md; it does not reopen architecture choices. Review checks the plan’s design references as well as its requirements coverage.

`/codexspec:review-tasks`¶

Validate the task breakdown for coverage, verifiable outcomes, correct ordering, and feasible dependencies.

Syntax:

/codexspec:review-tasks [path_to_tasks.md]

Arguments:

Argument	Required	Description
`path_to_tasks.md`	No	Path to tasks file (auto-detected if not provided)

What it does:

Checks all required plan items and requirements have task coverage
Validates test-first ordering only where an authoritative source requires it
Verifies each task has one outcome that can be checked
Validates dependencies (no cycles, correct ordering)
Reviews parallelization markers
Validates file paths
Requires evidence fields for every defect
Reports optional process refinements as advisories
Uses the shared status and compatibility-score contract

Example:

You: /codexspec:review-tasks

AI:  Overall Status: NEEDS_REVISION
     Compatibility Score: 79/100

     Warning TASK-001
     Evidence: Task 2.5 declares a dependency on Task 2.4.
     Location: tasks.md, Task 2.5
     Mismatch: Task 2.5 is also marked [P].
     Impact: Parallel execution can start before its prerequisite completes.
     Remediation: Remove [P] or remove the dependency if the plan proves independence.

Tips:

Run before /codexspec:implement-tasks
Test-order findings are defects only when testing is required by an authoritative source
Check parallelization markers are accurate
Verify file paths match project structure

`/codexspec:clarify`¶

Scan an existing specification for ambiguities and gaps. Use this for iterative refinement after initial spec creation.

Syntax:

/codexspec:clarify [path_to_spec.md]

Arguments:

Argument	Required	Description
`path_to_spec.md`	No	Path to spec file (auto-detected if not provided)

What it does:

Scans requirements and spec using focused ambiguity categories
Asks targeted clarification questions (max 5)
Updates requirements.md first after user confirmation, then synchronizes spec.md
Integrates with review-spec findings if available

Ambiguity Categories:

Category	What it Detects
Completeness Gaps	Missing sections, empty content, absent acceptance criteria
Specificity Issues	Vague terms ("fast", "scalable"), undefined constraints
Behavioral Clarity	Error handling gaps, undefined state transitions
Measurability Problems	Non-functional requirements without metrics

Example:

You: /codexspec:clarify

AI:  Scanning spec.md for ambiguities...

     Found issues in 3 categories.

     ## Question 1/5: Specificity

     **Context**: NFR-001 states "System should respond quickly"

     **Question**: What is the target response time?

     | Option | Description | Impact |
     |--------|-------------|--------|
     | A | < 100ms for all operations | High performance requirement |
     | B | < 500ms for reads, < 1s for writes | Balanced approach |
     | Custom | Provide a different answer | - |

     **Recommendation**: Option B - balanced for typical web app

You: B

AI:  ✓ Updated NFR-001: Response time < 500ms reads, < 1s writes
     Added to Clarifications section in spec.md

Tips:

Use when spec.md exists but needs refinement
Integrates with /codexspec:review-spec findings
Maximum 5 questions per session
Run multiple times for complex specifications

`/codexspec:analyze`¶

specify starts or revisits requirement discovery. Only explicit confirmation makes the requirement summary binding.
clarify resolves ambiguity in existing requirements/specification: up to five questions per run across four categories. It updates requirements.md first, then synchronizes spec.md.
analyze checks the complete requirements → spec → design → plan → tasks chain. It automatically applies deterministic fixes to downstream artifacts when their correction follows from upstream authority; it never edits requirements.md. Unresolved findings are reported. It runs automatically after a passing task review and is informational rather than an implementation gate.

/codexspec:clarify <feature-dir>
/codexspec:analyze <feature-dir>

Without requirements.md, legacy analysis starts at spec.md, discloses the missing discussion evidence, and reports findings without modifying artifacts. A missing legacy design.md also does not prevent analysis.

`/codexspec:checklist`¶

Generate quality checklists for validating requirements completeness, clarity, and consistency. These are "unit tests for requirements writing."

Syntax:

/codexspec:checklist [focus_area]

Arguments:

Argument	Required	Description
`focus_area`	No	Domain focus (e.g., "ux", "api", "security", "performance")

What it does:

Generates checklists organized by quality dimensions
Creates checklists in FEATURE_DIR/checklists/ directory
Items focus on requirement quality, not implementation testing

Quality Dimensions:

Requirement Completeness: Are all necessary requirements present?
Requirement Clarity: Are requirements specific and unambiguous?
Requirement Consistency: Do requirements align without conflicts?
Acceptance Criteria Quality: Are success criteria measurable?
Scenario Coverage: Are all flows/cases addressed?
Edge Case Coverage: Are boundary conditions defined?
Non-Functional Requirements: Performance, Security, Accessibility specified?
Dependencies & Assumptions: Are they documented?

Example Checklist Types:

ux.md - Visual hierarchy, interaction states, accessibility
api.md - Error formats, rate limiting, authentication
security.md - Data protection, threat model, breach response
performance.md - Metrics, load conditions, degradation

Example:

You: /codexspec:checklist security

AI:  Generating security checklist...

     ✓ Created .codexspec/specs/2026-0613-1200ab-task-management/checklists/security.md

     ## Security Requirements Quality Checklist

     ### Authentication Requirements
     - [ ] CHK001 - Are authentication requirements defined for all protected endpoints? [Completeness]
     - [ ] CHK002 - Is password complexity explicitly specified? [Clarity]
     - [ ] CHK003 - Are session timeout requirements quantified? [Measurability]

     ### Data Protection
     - [ ] CHK004 - Are data encryption requirements specified at rest? [Completeness]
     - [ ] CHK005 - Are data encryption requirements specified in transit? [Completeness]
     - [ ] CHK006 - Is PII handling explicitly documented? [Clarity]

     Total: 15 items across 4 categories

Tips:

Checklists validate requirement quality, not implementation correctness
Use for requirements review and improvement
Create domain-specific checklists for focused validation
Run before proceeding to technical planning

`/codexspec:tasks-to-issues`¶

Convert tasks from tasks.md into GitHub issues for project tracking and collaboration.

Syntax:

/codexspec:tasks-to-issues

Arguments:

Argument	Required	Description
None	-	Converts all tasks from the current feature

What it does:

Parses task IDs, descriptions, dependencies, and file paths
Creates GitHub issues with structured body
Adds labels based on task type (setup, implementation, testing, documentation)
Links dependencies between issues
Reports created issues with URLs

Prerequisites:

Git repository with GitHub remote
GitHub CLI (gh) installed and authenticated
tasks.md file exists

Example:

You: /codexspec:tasks-to-issues

AI:  Converting tasks to GitHub issues...

     Repository: github.com/example/taskman

     Creating issues:
     ✓ #42: Task 1.1 - Setup Project Structure (setup)
     ✓ #43: Task 2.1 - Write Tests for Task Entity (testing)
     ✓ #44: Task 2.2 - Implement Task Entity (implementation)
     ...

     Summary:
     - Issues created: 24
     - Labels applied: setup(4), implementation(12), testing(5), documentation(3)
     - Dependencies linked: 18

     View issues: https://github.com/example/taskman/issues

Tips:

Requires GitHub CLI authentication (gh auth login)
Only works with GitHub repositories
Creates issues in the repository's default configuration
Check for duplicates before running

Verify the target repository against its remote and obtain explicit authorization before creating issues. A generated task list does not by itself authorize publishing.

`/codexspec:debug`¶

Investigate root causes before applying a fix.

See Workflow.

/codexspec:debug Investigate intermittent failures when saving a task

`/codexspec:reverse-spec`¶

Two entry points serve different goals:

Command	Use it to	Output/boundary
`onboard [path]`	Seed reusable project knowledge from an existing codebase	Candidate conventions and narrowly evidenced constraints in the profile; code remains read-only
`reverse-spec [path]`	Understand existing architecture or compare code with confirmed intent	Draft artifacts or a drift report; code remains read-only

/codexspec:onboard src/
/codexspec:reverse-spec
/codexspec:reverse-spec src/auth

Onboard infers conventions from observable code and proposes constraints only from explicit prohibitions. Convention candidates take local effect immediately; constraint candidates require an in-session persist/edit/drop decision. It preserves existing knowledge and does not invent past decision rationale or experiential pitfalls from a cold scan.

Reverse-spec has three modes:

Overview: no path, or repository root, produces a thin architecture design.md and slices.md for choosing modules to inspect.
Generate: a module path without a confirmed baseline produces draft spec.md, design.md, and open/inferred requirements.
Reconcile: a module with a confirmed baseline produces reconcile.md, reporting undocumented behavior, unimplemented specifications, and semantic mismatches against confirmed spec/design, with requirements governing intent.

Inferred drafts require human confirmation before becoming a baseline. Reconciliation reports the proposed direction—fix code, update documents, or decide intent—and does not automatically apply it.

`/codexspec:distill`¶

Capture reusable cross-feature knowledge in .codexspec/profile/ and review pending candidates without hand-editing their Markdown files.

Syntax:

/codexspec:distill [interaction segment]
/codexspec:distill review

Manual review:

/codexspec:distill review, or a direct invocation with no new segment to extract, opens an offline HTML page served only from 127.0.0.1. Its header names the project directory the session will write to, so two reviews open side by side cannot be confused.
The page supports structured revision, Vetted, discard, defer, consolidation, a complete staged summary, and explicit Apply all. A revision or merge must show its exact final Markdown preview before the same action can be staged; the page states which of the three preview states each record is in — not previewed, matching the current edits, or changed since the preview — before you use a decision control.
Every action that removes record files asks for a second confirmation that states the consequence: discarding a record names the file that applying will delete, merging a cluster names how many member records it will delete, and discarding the draft names how many staged decisions will be dropped.
A record cannot become vetted without both human approval and outcome-verification evidence. The page shows, before you choose Vetted, whether a record's stored evidence already satisfies that requirement.
The queue groups records by what has been decided and shows how many of the pending records are already settled. Staging a decision moves to the next undecided record; a switch in the header turns that off.
The page is operable from the keyboard — press ? to see the keys. No single key applies the batch, cancels the session, or discards the draft.
Staged decisions use a recoverable project draft excluded from Git. Only one writable review is active per project.
A structurally damaged draft is retained with an actionable diagnostic and is removed only through an explicit discard action.
Apply rechecks source hashes and rejects the entire batch if any record changed; it never overwrites a concurrent edit or reports partial success.
All page assets ship with CodexSpec. The page uses no CDN, remote model call, or telemetry.
If no browser can be opened, the command prints the token-protected local URL. Request explicit text mode when a browser is unsuitable; it uses the same validation and write path.

Auto-distill remains non-interactive and non-blocking: it never opens the page, starts text review, or waits for a saved draft.

`/codexspec:evolve`¶

evolve selects only vetted knowledge useful beyond the project, compiles a command/skill draft, and obtains explicit approval before pushing or opening a contribution PR for human review.

/codexspec:evolve

`/codexspec:onboard`¶

Seed candidate conventions and evidenced constraints from existing code.

See reverse-spec.

/codexspec:onboard src/

`/codexspec:commit-staged`¶

/codexspec:commit-staged -p
/codexspec:pr --spec <feature-dir>/spec.md
/codexspec:release-notes --from <ref> --to HEAD
/codexspec:tasks-to-issues <feature-dir>

commit-staged analyzes the exact staging area and generates a Conventional Commits message; -p previews without committing. The calling workflow chooses and stages files. Authorized execution uses the guarded runtime, rechecking that committed content matches the analysis. Agent commit guidance applies in ordinary conversation, SDD, blueprint, and auto-dev workflows; command availability alone does not invoke it or authorize a commit.
pr generates a structured GitHub PR or GitLab MR description from the diff. --spec optionally adds feature context from a spec.md file path, or a feature directory name or prefix resolved to that file. Default output is text for use in the hosting platform.
release-notes derives a Keep a Changelog entry and release body from Git history. The default section is [Unreleased]; --version uses a supplied label. It does not stage, commit, bump versions, tag, publish, or create a release.
tasks-to-issues creates GitHub issues from existing tasks, including dependencies and acceptance criteria. It requires an authenticated GitHub CLI and verifies that the issue repository matches the configured remote.

Direct commit preview and authorized in-place commits require Python 3.11+ and Git; the runtime is installed with CLI projects and bundled with the Claude plugin. Contentful agent-created merges also use staged analysis. History-only merges retain Git's default message while validating the tree and parents; fast-forwards create no commit.

The shared helper at .codexspec/scripts/commit-staged-helper.py (or the plugin-bundled copy) requires Python 3.11+ and Git, invokes no LLM, preserves Git hooks, and rejects staged content that changed after analysis. One-time initialization supplies this runtime; workspace routing, blueprint, and auto-dev still require the CLI.

`/codexspec:pr`¶

Generate a structured GitHub Pull Request / GitLab Merge Request description from the git diff. Optionally integrates spec.md for SDD-traced context.

Syntax:

/codexspec:pr [--target-branch <branch>] [--sections <list>] [--spec <id-or-path>] [--output <file>]

Arguments:

Argument	Required	Description
`--target-branch <branch>`	No	Branch to compare against (default: `origin/main`)
`--sections <list>`	No	Comma-separated subset of `summary, changes, testing, verify, checklist, notes` (default: `all`)
`--spec <id-or-path>`	No	Opt-in spec integration: a feature id (e.g., `2025-0321-1430k7-auth`) resolved under `.codexspec/specs/`, or an explicit `path/to/spec.md`. Omit to generate from git only
`--output <file>`	No	Save the description to a file instead of the terminal

What it does:

Collects git context (current branch, remote URL, commits ahead, file changes, full diff, commit messages) against the target branch
Auto-detects the platform from the remote URL: GitHub → "Pull Request", GitLab → "Merge Request", other/none → defaults to GitHub terminology with a warning
Loads .codexspec/memory/constitution.md when present and aligns the description with documentation/code-review standards
Honors language.commit (then language.output, then English) for the description language; technical terms (API, JWT, PR, MR) stay in English where appropriate
When --spec is provided, adds a Context section with user stories and requirements pulled from spec.md; otherwise generates purely from the diff
Emits sections per --sections (Summary, Changes, Testing, Verification Steps, Pre-merge Checklist, Notes / Breaking Changes)

Example:

You: /codexspec:pr --spec 2026-0613-1200ab-task-management

AI:  Generating Pull Request description...

     Platform: GitHub (github.com/example/taskman)
     Branch:   feature/task-management  →  origin/main
     Commits:  8 ahead

     ## Pull Request: Task management for small dev teams

     ### Context
     - User stories and REQ-* pulled from spec.md

     ### Summary
     - Adds task CRUD, sub-tasks, and real-time updates

     ### Changes
     - src/taskman/models/task.py (new)
     - src/taskman/api/tasks.py (new)
     - ...

     ### Verification Steps
     1. `uv run pytest`
     2. `uv run codexspec check`

Tips:

Skip --spec for small bug fixes or changes with no formal specification
Combine with /codexspec:commit-staged to produce both a commit message and a PR description from the same work
See the PR description generator case study for a worked, end-to-end example of this command (including how spec.md context is wired in)

`/codexspec:release-notes`¶

/codexspec:commit-staged -p
/codexspec:pr --spec <feature-dir>/spec.md
/codexspec:release-notes --from <ref> --to HEAD
/codexspec:tasks-to-issues <feature-dir>

commit-staged analyzes the exact staging area and generates a Conventional Commits message; -p previews without committing. The calling workflow chooses and stages files. Authorized execution uses the guarded runtime, rechecking that committed content matches the analysis. Agent commit guidance applies in ordinary conversation, SDD, blueprint, and auto-dev workflows; command availability alone does not invoke it or authorize a commit.
pr generates a structured GitHub PR or GitLab MR description from the diff. --spec optionally adds feature context from a spec.md file path, or a feature directory name or prefix resolved to that file. Default output is text for use in the hosting platform.
release-notes derives a Keep a Changelog entry and release body from Git history. The default section is [Unreleased]; --version uses a supplied label. It does not stage, commit, bump versions, tag, publish, or create a release.
tasks-to-issues creates GitHub issues from existing tasks, including dependencies and acceptance criteria. It requires an authenticated GitHub CLI and verifies that the issue repository matches the configured remote.

Direct commit preview and authorized in-place commits require Python 3.11+ and Git; the runtime is installed with CLI projects and bundled with the Claude plugin. Contentful agent-created merges also use staged analysis. History-only merges retain Git's default message while validating the tree and parents; fast-forwards create no commit.

Release-note options¶

Commands	Reference
`--version <X.Y.Z>`	Supplied version label; otherwise `[Unreleased]`
`--from <ref>`	Start ref; otherwise latest reachable tag, then an anchorable changelog version, then full history
`--to <ref>`	End ref; default `HEAD`
`--output <file>`	Write release body to this file; otherwise terminal output
`--spec <feature>`	Optional feature context; an unresolved feature is reported and generation continues from Git

`/codexspec:review-code`¶

Review the selected Git change as a strict defect gate before merge. The default target includes the complete feature delta; explicit selectors can review committed, uncommitted, or one-commit evidence without accepting path filters.

Default review mode:

The default command is now a change-scoped defect gate, not a broad quality scorecard.
Positional paths are no longer valid. Use --audit when you intentionally want the advisory path scorecard.

Defect-gate syntax:

/codexspec:review-code
/codexspec:review-code --committed [--base <branch>] [--feature <feature-dir>] [--focus <instructions>]
/codexspec:review-code --uncommitted [--feature <feature-dir>] [--focus <instructions>]
/codexspec:review-code --commit <sha> [--parent <n>] [--feature <feature-dir>] [--focus <instructions>]
/codexspec:review-code [--committed] --incremental-from <fingerprint> [--feature <feature-dir>]

Every defect-gate form also accepts --decided-by reviewer|ask, which overrides review.decided_by for that run.

The gate inventories every selected artifact, assesses applicable requirements, and runs five passes in order: Scope, System Contract, Behavior, Risk, and Verification. It records source-backed cross-module contracts and semantic review partitions, and every validated repeatable root cause triggers a bounded search for related occurrences before the round finishes. The six report sections are followed by one machine-readable <review-code-result> envelope using schema_version: "3". The envelope carries target identity, coverage, and objective post-repair obligations; the caller retains those neutral obligations for a fresh complete review without passing repair reasoning or prior correctness conclusions. The verdict is exactly PASS, FAIL, or INCONCLUSIVE: every P0-P3 finding produces FAIL, while missing mandatory evidence or incomplete coverage produces INCONCLUSIVE.

Incremental rounds. After a repair, --incremental-from <fingerprint> re-reviews only what changed since that earlier result: the changed files, the review partitions and contracts they touch, and the carried-over obligations. Coverage of unchanged, unaffected files is reused, and the reviewer may still report any defect it finds elsewhere. An incremental PASS never completes a feature: implement-tasks runs a complete review first, incremental reviews after each repair, and one fresh complete review as the final acceptance. Review records are written outside the repository, under your user cache directory (~/.cache/codexspec/review/ or %LOCALAPPDATA%\codexspec\review\); only the report and the envelope appear in the conversation.

Decision mode. review.decided_by in .codexspec/config.yml decides who rules on a finding whose trigger lies outside the project's real operating context, such as an input the project never receives. With the default reviewer, the review behaves exactly as before. With ask, the review reports such an item as a pending scenario decision instead of failing on it, and implement-tasks asks you once: fix it, or accept that the scenario is out of scope. Your answer is recorded in requirements.md as a confirmed CON or OUT entry, so later rounds do not raise it again.

You: /codexspec:review-code --feature .codexspec/specs/2026-0714-example

AI:  ## Verdict
     **PASS** — all required review and verification completed with no findings.

Applicable standards and maintenance. Every review reads the shared rules and the selected mode, assesses all seven dimensions, and loads detailed checks only when the actual behavior, contract, or dependency makes them relevant. Language and framework checks can also be activated by unchanged dependencies discovered during tracing. Current maintenance problems need concrete evidence and a compatible, local improvement; speculative future complexity and style thresholds alone do not justify repairs. The existing defect envelope remains version 3; a separate <review-code-maintenance> version 1 companion reports suggestions bound to the same target fingerprint. Standalone review only reports them. implement-tasks verifies and applies them according to workflow.auto_maintenance (default true). Repairs continue while substantive progress occurs and obey the existing stop guards. There is no fixed round cap; final acceptance requires a fresh complete review.

Boolean CLI switches accept case-insensitive on/true/1/yes and off/false/0/no, including surrounding whitespace. A bare boolean switch toggles the destination checkout's current value; stored YAML values are booleans.

codexspec init installs shared review resources into .codexspec/review-code/ for Claude Code and Codex. --force refreshes shipped resources while preserving extension files with different paths. Installing the CLI alone does not create project files. Plugin-only review uses the same resources from the host-resolved plugin root when the project has no installed resource tree.

Path quality audit¶

Use the explicit audit branch to review complete current file contents for idiomatic clarity, correctness, robustness, architecture, and constitution alignment. This scorecard is advisory and cannot complete implement-tasks.

Syntax:

/codexspec:review-code --audit [paths...]

Arguments:

Argument	Required	Description
`path...`	No	One or more source files or directories to review (space-separated). Defaults to `src/` if omitted

What it does:

Detects the primary language(s) from file extensions and runs a per-language pass for mixed-language targets
Runs static analysis tools when their config is present (ruff/mypy, eslint/tsc, go vet/gofmt, cargo check/cargo clippy, shellcheck); skips gracefully and reports degraded coverage otherwise
Scores four dimensions: Idiomatic Clarity & Simplicity, Correctness & Explicit Contracts, Runtime Robustness & Resource Discipline, and Architecture & Design Integrity
Injects mandatory subsections for detected frameworks (e.g., Hooks Compliance for React, Ownership & Borrowing for Rust, Goroutine & Context Discipline for Go, Memory & Lifetime Safety for C/C++, Execution Safety for Shell)
Cross-references findings against .codexspec/memory/constitution.md when present; if absent, the constitution axis is dropped and its weight is redistributed
Classifies findings by severity: CRITICAL, HIGH, MEDIUM, LOW (LOW suggestions are capped at a 5-point total deduction)

Example:

You: /codexspec:review-code --audit src/

AI:  # Code Review Report

     ## Summary
     - Overall Status: Needs Work
     - Quality Score: 78/100
     - Detected Language: Python

     ## Static Analysis Results
     | Tool   | Status | Issues | Details                |
     |--------|--------|--------|------------------------|
     | ruff   | Warn   | 3      | Unused imports, line length |
     | mypy   | Pass   | 0      | No type errors         |

     ## Detailed Findings
     ### Critical Issues (CRITICAL)
     - [ ] [CODE-001] src/auth/service.py:42 - bare `except Exception:` swallows the original cause
       Impact: Original error context is lost during debugging.
       Suggestion: narrow the exception and re-raise with `raise ... from err`.

     ### Suggestions (LOW)
     - [ ] [CODE-004] src/auth/service.py:120 - manual loop where a comprehension suffices

     ## Recommendations
     1. Priority 1: Fix CODE-001 before merge.
     2. Priority 2: Apply LOW suggestions opportunistically.

Tips:

Pass multiple paths to review a focused slice, e.g., src/ tests/
The score is advisory; CRITICAL/HIGH findings are the actionable signal

`/codexspec:config`¶

Manage project configuration interactively (create/view/modify/reset). This is the slash-command counterpart to the codexspec config CLI, ideal for Plugin Marketplace installs.

Syntax:

/codexspec:config [--view]

Arguments:

Argument	Required	Description
`--view`	No	Display the current configuration without modifying it. With no arguments, opens the interactive management menu

What it does:

Targets .codexspec/config.yml exclusively
--view (or the "View current config" menu option) prints the file in a readable format; reports "Configuration Not Found" if absent
Interactive mode, when a config exists, offers: View, Modify, Reset to defaults, Cancel
If no config exists, runs the creation flow that writes a minimal, output-only config (interaction/document/commit resolve to output, then en, so an output-only file is fully functional)
Lets you set each language dimension independently (output, interaction, document, commit) and toggle workflow options such as auto_next

What it creates/edits:

.codexspec/config.yml

Example:

You: /codexspec:config

AI:  ## Configuration Manager

     Configuration file found at .codexspec/config.yml.
     What would you like to do?
     - View current config
     - Modify config
     - Reset to defaults
     - Cancel

You: Modify config

AI:  Select a dimension to change:
     - Output language (base)
     - Interaction language
     - Document language
     - Commit-message language
     - workflow.auto_next
     - workflow.auto_distill
     - workflow.auto_maintenance
     - workflow.worktrees (default on; checkout-local)
     - review.decided_by

You: Output language (base) → zh-CN

AI:  ✓ Updated language.output: "zh-CN"
     (interaction and document fall back to output, then en.)

Tips:

Use /codexspec:config --view to inspect the current state before changing anything
A fresh or reset config writes only output; set interaction/document only when they should differ from output
For scripted changes in a terminal, prefer the codexspec config CLI (--set-lang, --set-interaction-lang, --set-document-lang, --set-commit-lang, --auto-next)

The interactive menu also manages workflow.auto_distill, workflow.auto_maintenance, workflow.worktrees, and review.decided_by. Configuration changes follow checkout-local worktree routing.

`/codexspec:quick`¶

Run a streamlined Requirements-First SDD flow for small changes.

Syntax:

/codexspec:quick [describe a small requirement]

Arguments:

Argument	Required	Description
`describe a small requirement`	No	Short description of the small, well-bounded change (you will be prompted if not provided)

What it does:

Assesses scope (files touched, module span, new dependencies, unresolved product decisions) and, if the change is broad or has multiple independent outcomes, recommends the standard flow
Creates a feature workspace and requirements.md using the same timestamp convention as /codexspec:specify
Resolves only ambiguities that materially change implementation; presents a concise confirmed summary (NEED-*, relevant CON-*/DEC-*, OUT-*, unresolved OPEN-*)
Holds at the Confirmation Gate: nothing is generated until you confirm the summary
Chains the generation commands against the new feature directory: /codexspec:generate-spec, /codexspec:design-to-plan, /codexspec:plan-to-tasks, /codexspec:implement-tasks
Defers to each generation command's own auto-review loop; pauses and asks the user if a review needs a new product or architecture decision
Reports the feature directory, artifact paths, review outcomes, implementation verification, and unresolved advisories separately

What it creates:

.codexspec/specs/{timestamp}-{feature-name}/
├── requirements.md
├── spec.md
├── plan.md
└── tasks.md

Example:

You: /codexspec:quick Add a "remember me" checkbox to the login form

AI:  Scope check: 1 component, 1 form field, no new dependencies. Quick is appropriate.

     Confirmed requirements:
     - NEED-1: "Remember me" checkbox on the login form (default unchecked)
     - DEC-1: Persist a long-lived refresh token only when checked
     OUT-1: SSO / social login (unchanged)

     Confirm this summary to start the automated flow. [y/N]

You: y

AI:  Running generate-spec → design-to-plan → plan-to-tasks → implement-tasks ...

     ✓ Feature dir: .codexspec/specs/2026-0713-0915ab-remember-me/
     ✓ All reviews PASS_WITH_WARNINGS or higher
     ✓ Implementation verified
     Open advisories: none

Tips:

Reserve Quick for genuinely small, single-outcome changes; otherwise run /codexspec:specify and the standard flow
Confirmation is still required — Quick never infers a product decision to keep automation moving
If any generation review returns NEEDS_REVISION/BLOCKED, Quick stops and hands control back to you

Available Commands¶

CLI Commands¶

Core Workflow Commands¶

Artifact Review Commands¶

Requirements, Existing Code, and Debugging¶

Project Knowledge Commands¶

Git and Code Review Commands¶

Utility Commands¶

Command Reference¶

/codexspec:constitution¶

/codexspec:specify¶

/codexspec:blueprint¶

/codexspec:generate-spec¶

/codexspec:spec-to-design¶

/codexspec:design-to-plan¶

/codexspec:plan-to-tasks¶

/codexspec:implement-tasks¶

/codexspec:auto-dev¶

/codexspec:review-spec¶

/codexspec:review-design¶

/codexspec:review-plan¶

/codexspec:review-tasks¶

/codexspec:clarify¶

/codexspec:analyze¶

/codexspec:checklist¶

/codexspec:tasks-to-issues¶

/codexspec:debug¶

/codexspec:reverse-spec¶

/codexspec:distill¶

/codexspec:evolve¶

/codexspec:onboard¶

/codexspec:commit-staged¶

/codexspec:pr¶

/codexspec:release-notes¶

Release-note options¶

/codexspec:review-code¶

Path quality audit¶

/codexspec:config¶

/codexspec:quick¶

`/codexspec:constitution`¶

`/codexspec:specify`¶

`/codexspec:blueprint`¶

`/codexspec:generate-spec`¶

`/codexspec:spec-to-design`¶

`/codexspec:design-to-plan`¶

`/codexspec:plan-to-tasks`¶

`/codexspec:implement-tasks`¶

`/codexspec:auto-dev`¶

`/codexspec:review-spec`¶

`/codexspec:review-design`¶

`/codexspec:review-plan`¶

`/codexspec:review-tasks`¶

`/codexspec:clarify`¶

`/codexspec:analyze`¶

`/codexspec:checklist`¶

`/codexspec:tasks-to-issues`¶

`/codexspec:debug`¶

`/codexspec:reverse-spec`¶

`/codexspec:distill`¶

`/codexspec:evolve`¶

`/codexspec:onboard`¶

`/codexspec:commit-staged`¶

`/codexspec:pr`¶

`/codexspec:release-notes`¶

`/codexspec:review-code`¶

`/codexspec:config`¶

`/codexspec:quick`¶