spec-init

Core Philosophy

• OPSX provides the specification framework; CCG adds multi-model collaboration.
• This phase ensures all tools are ready before any development work begins.
• Fail fast: detect missing dependencies early rather than mid-workflow.

Guardrails

• Detect OS (Linux/macOS/Windows) and adapt commands accordingly.
• Do not proceed to next step until current step completes successfully.
• Provide clear, actionable error messages when a step fails.
• Respect user's existing configurations; avoid overwriting without confirmation.

Steps

1. Detect Operating System

   • Identify OS using uname -s (Unix) or environment variables (Windows).
   • Inform user which OS was detected.

2. Check and Install OpenSpec (OPSX)

   • IMPORTANT: OpenSpec CLI command is openspec, NOT opsx
   • Verify if OpenSpec is available:

     npx @fission-ai/openspec --version
     

   • If not found, install globally:

     npm install -g @fission-ai/openspec@latest
     

   • After installation, verify again:

     openspec --version
     

   • If openspec command not found after global install, use npx:

     npx @fission-ai/openspec --version
     

   • Note: Always use openspec (not opsx) for CLI commands.

3. Initialize OPSX for Current Project

   • 重要：所有命令必须在当前工作目录下执行，禁止 cd 到其他路径。如不确定当前目录，先执行 pwd 确认。
   • Check if already initialized:

     ls -la openspec/ .claude/skills/openspec-* 2>/dev/null || echo "Not initialized"
     

   • If not initialized, run interactive setup (v1.2+ auto-detects AI tools):

     npx @fission-ai/openspec init
     

   • Profile Selection (v1.2+):
     • core profile (default): 4 essential workflows (propose, explore, apply, archive)
     • custom profile: Pick any subset of workflows
     • To change profile later: openspec config profile
   • Verify initialization:
     • Check openspec/ directory exists
     • Check .claude/skills/ contains openspec-* skills
     • Check .claude/commands/opsx/ contains OPSX commands
   • Report any errors with remediation steps.

4. Validate Multi-Model MCP Tools

   • Check codeagent-wrapper availability: ~/.claude/bin/codeagent-wrapper --version
   • 工作目录：{{WORKDIR}} 必须通过 Bash 执行 pwd（Unix）或 cd（Windows CMD）获取当前工作目录的绝对路径，禁止从 $HOME 或环境变量推断。如果用户通过 /add-dir 添加了多个工作区，先确定任务相关的工作区。
   • Test {{BACKEND_PRIMARY}} backend:

     echo "echo test" | ~/.claude/bin/codeagent-wrapper --backend {{BACKEND_PRIMARY}} {{GEMINI_MODEL_FLAG}}{{GROK_MODEL_FLAG}}{{KIMI_MODEL_FLAG}}{{OPENCODE_MODEL_FLAG}}- "{{WORKDIR}}"
     

   • Test {{FRONTEND_PRIMARY}} backend:

     echo "echo test" | ~/.claude/bin/codeagent-wrapper --backend {{FRONTEND_PRIMARY}} {{GEMINI_MODEL_FLAG}}{{GROK_MODEL_FLAG}}{{KIMI_MODEL_FLAG}}{{OPENCODE_MODEL_FLAG}}- "{{WORKDIR}}"
     

   • For each unavailable tool, display warning with installation instructions.

5. Summary Report Display status table:

   Component                 Status
   ─────────────────────────────────
   OpenSpec (OPSX) CLI       ✓/✗
   Project initialized       ✓/✗
   OPSX Skills               ✓/✗
   codeagent-wrapper         ✓/✗
   {{BACKEND_PRIMARY}} backend             ✓/✗
   {{FRONTEND_PRIMARY}} backend            ✓/✗
   

   Next Steps (Use CCG Encapsulated Commands)

   1. Start Research: /ccg:spec-research "description"
   2. Plan & Design: /ccg:spec-plan
   3. Implement: /ccg:spec-impl (Includes auto-review & archive)

   Standalone Tools (Available Anytime)

   • Code Review: /ccg:spec-review (Independent dual-model review)

Reference

• OpenSpec (OPSX) CLI: npx @fission-ai/openspec --help
• Profile Management: openspec config profile
• CCG Workflow: npx ccg-workflow
• 后端/前端模型 MCP: Bundled with codeagent-wrapper
• Node.js >= 18.x required for OpenSpec