OpenSpec (OPSX) - Spec-Driven AI Development

OPSX (OpenSpec) transforms vague requirements into verifiable constraints, eliminating AI improvisation. It is a structured requirements-to-implementation pipeline that ensures code changes follow a disciplined, auditable process.

Core Philosophy

The problem with traditional AI coding: you describe a requirement, and the AI might misinterpret it, freestyle features, or miss edge cases.

The OPSX solution:

1. Convert requirements into explicit constraints (not fuzzy descriptions)
2. Generate a zero-decision plan from those constraints (every step is executable without human judgment)
3. Implement strictly according to the plan

Command Pipeline

/ccg:spec-init       → Initialize OPSX environment + Profile system
        ↓
/ccg:spec-research   → Parallel exploration → Constraint set (OPSX proposal)
        ↓
/ccg:spec-plan       → Multi-model analysis → Disambiguate → Zero-decision plan
        ↓
/ccg:spec-impl       → Execute per plan + archive
        ↓
/ccg:spec-review     → Dual-model independent review (usable anytime)

Command Reference

/ccg:spec-init

Purpose: Initialize the OPSX environment for your project.

What it does:

• Sets up the Profile system (project-level constraint templates)
• Auto-detects the project’s tech stack
• Verifies multi-model MCP tool availability
• Creates the .ccg/spec/ directory structure (if not present)

Tip

spec-init only needs to run once per project. Subsequent spec commands do not require re-initialization.

/ccg:spec-research

Purpose: Transform vague requirements into a verifiable constraint set.

Execution flow:

1. Parses the user’s requirement description
2. Calls Codex + Gemini in parallel to explore the codebase
3. Identifies related modules, dependencies, and constraints
4. Outputs a structured OPSX proposal (constraints, preconditions, acceptance criteria)

Output format:

## Constraint Set

1. [MUST] JWT token expiry must be configurable
2. [MUST] Refresh token mechanism required
3. [SHOULD] Support token revocation
4. [MUST NOT] Pass tokens in URL parameters

/ccg:spec-plan

Purpose: Generate a zero-decision executable plan from the constraint set.

Execution flow:

1. Reads the constraints output from spec-research
2. Multi-model analysis of inter-constraint dependencies
3. Disambiguates (every ambiguous point is made explicit)
4. Generates a step-by-step implementation plan

What “zero-decision” means: Every step in the plan is specific enough that the executor — whether human or AI — needs zero judgment calls. Just execute.

/ccg:spec-impl

Purpose: Execute code changes strictly according to the plan.

Execution flow:

1. Reads plan.md
2. Implements step by step
3. After each step, verifies whether constraints are satisfied
4. On completion, archives results into the task directory

Caution

spec-impl follows the plan strictly and will not improvise unplanned features. If you discover the plan has gaps, return to spec-plan to amend it rather than freestyling during implementation.

/ccg:spec-review

Purpose: Dual-model cross-review of code changes.

Execution flow:

1. Codex and Gemini independently review the code changes
2. Each outputs findings (Critical / Warning / Info)
3. Findings are merged and deduplicated into a unified review report

Standalone use: spec-review can be used at any time — it does not require running the full spec pipeline first. It is essentially a dual-model code review tool.

Relationship to /ccg:go

The full-collaborate strategy in /ccg:go uses a similar pipeline internally (analyze, plan, implement, review). The key differences:

	/ccg:go	OPSX Commands
Best for	One-shot fast execution	Fine-grained control at each stage
Flow	Automatically chained	Manually stepped
Intervention	At HARD STOP points only	Between every command
Use case	Most development tasks	High-risk / high-precision requirements

Tip

If you need to review and adjust between each phase (e.g., a high-risk database migration), use OPSX commands step by step. If you trust the engine’s judgment, go with /ccg:go.