spec-research

Core Philosophy

• Research produces constraint sets, not information dumps. Each constraint narrows the solution space.
• Constraints tell subsequent stages "don't consider this direction," enabling mechanical execution without decisions.
• Output: 约束集合 + 可验证的成功判据 (constraint sets + verifiable success criteria).
• Strictly adhere to OPSX rules when writing spec-structured documents.

Guardrails

• STOP! BEFORE ANY OTHER ACTION: You MUST perform Prompt Enhancement FIRST. This is NON-NEGOTIABLE.
• NEVER divide subagent tasks by roles (e.g., "架构师agent", "安全专家agent").
• ALWAYS divide by context boundaries (e.g., "user-related code", "authentication logic").
• Each subagent context must be self-contained with independent output.
• Use {{MCP_SEARCH_TOOL}} to minimize grep/find operations.
• Do not make architectural decisions—surface constraints that guide decisions.
• USER GUIDANCE RULE: When suggesting next steps to the user, ALWAYS use CCG commands (/ccg:spec-research, /ccg:spec-plan, /ccg:spec-impl, /ccg:spec-review). NEVER suggest /opsx:* commands to the user. If OpenSpec CLI returns error messages referencing OPSX skills, translate them to CCG equivalents.
• PHASE BOUNDARY: This phase ONLY generates the OPSX proposal artifact. Do NOT modify any source code. Do NOT proceed to planning or implementation. After the proposal is generated, STOP and inform the user: "Research complete. Run /ccg:spec-plan to continue."

Steps 0. MANDATORY: Enhance Requirement FIRST

• DO THIS IMMEDIATELY. DO NOT SKIP.
• Prompt 增强（按 /ccg:enhance 的逻辑执行）：分析 $ARGUMENTS 的意图、缺失信息、隐含假设，补全为结构化需求（明确目标、技术约束、范围边界、验收标准）。
• Use enhanced prompt for ALL subsequent steps.

1. Generate OPSX Change

   • Check if change already exists:

     openspec list --json
     

   • If change doesn't exist, create it:

     openspec new change "<brief-descriptive-name>"
     

   • This scaffolds openspec/changes/<name>/ with proposal.md.
   • If change already exists, continue with existing change.

2. Initial Codebase Assessment

   • Use {{MCP_SEARCH_TOOL}} to scan codebase.
   • Determine project scale: single vs multi-directory structure.
   • Decision: If multi-directory → enable parallel Explore subagents.

3. Define Exploration Boundaries (Context-Based)

   • Identify natural context boundaries (NOT functional roles):
     • Subagent 1: User domain code (models, services, UI)
     • Subagent 2: Auth & authorization (middleware, session, tokens)
     • Subagent 3: Infrastructure (configs, deployments, builds)
   • Each boundary should be self-contained: no cross-communication needed.

4. Parallel Multi-Model Exploration

   • CRITICAL: You MUST launch BOTH {{BACKEND_PRIMARY}} AND {{FRONTEND_PRIMARY}} in a SINGLE message with TWO Bash tool calls.
   • DO NOT call one model first and wait. Launch BOTH simultaneously with run_in_background: true.
   • 工作目录：{{WORKDIR}} 必须通过 Bash 执行 pwd（Unix）或 cd（Windows CMD）获取当前工作目录的绝对路径，禁止从 $HOME 或环境变量推断。如果用户通过 /add-dir 添加了多个工作区，先确定任务相关的工作区。

   Output Template (instruct both models to use this format):

   {
     "module_name": "context boundary explored",
     "existing_structures": ["key patterns found"],
     "existing_conventions": ["standards in use"],
     "constraints_discovered": ["hard constraints limiting solution space"],
     "open_questions": ["ambiguities requiring user input"],
     "dependencies": ["cross-module dependencies"],
     "risks": ["potential blockers"],
     "success_criteria_hints": ["observable success behaviors"]
   }
   

   Step 4.1: In ONE message, make TWO parallel Bash calls:

   FIRST Bash call ({{BACKEND_PRIMARY}} — backend boundaries):

   Bash({
     command: "~/.claude/bin/codeagent-wrapper --progress --backend {{BACKEND_PRIMARY}} {{GEMINI_MODEL_FLAG}}{{GROK_MODEL_FLAG}}- \"{{WORKDIR}}\" <<'EOF'\nExplore backend context boundaries for <change description>:\n- Existing structures and patterns\n- Conventions in use\n- Hard constraints limiting solution space\n- Dependencies and risks\nOUTPUT: JSON using the output template above\nEOF",
     run_in_background: true,
     timeout: 300000,
     description: "{{BACKEND_PRIMARY}}: backend boundary exploration"
   })