spec-setup

Workflow Spec Setup Command

Overview

Initialize .workflow/project-tech.json and .ccw/specs/*.md with comprehensive project understanding by delegating analysis to cli-explore-agent, then interactively configure project guidelines through a multi-round questionnaire.

Dual File System:

• project-tech.json: Auto-generated technical analysis (stack, architecture, components)
• specs/*.md: User-maintained rules and constraints (created and populated interactively)

Design Principle: Questions are dynamically generated based on the project's tech stack, architecture, and patterns -- not generic boilerplate.

Note: This command may be called by other workflow commands. Upon completion, return immediately to continue the calling workflow without interrupting the task flow.

Usage

$spec-setup                 # Initialize (skip if exists)
$spec-setup --regenerate    # Force regeneration of project-tech.json
$spec-setup --skip-specs    # Initialize project-tech only, skip spec initialization and questionnaire
$spec-setup --reset         # Reset specs content before questionnaire

Execution Process

Input Parsing:
   |- Parse --regenerate flag -> regenerate = true | false
   |- Parse --skip-specs flag -> skipSpecs = true | false
   +- Parse --reset flag -> reset = true | false

Decision:
   |- BOTH_EXIST + no --regenerate + no --reset -> Exit: "Already initialized"
   |- EXISTS + --regenerate -> Backup existing -> Continue analysis
   |- EXISTS + --reset -> Reset specs, keep project-tech -> Skip to questionnaire
   +- NOT_FOUND -> Continue full flow

Full Flow:
   |- Step 1: Parse input and check existing state
   |- Step 2: Get project metadata (name, root)
   |- Step 3: Invoke cli-explore-agent (subagent)
   |   |- Structural scan (get_modules_by_depth.sh, find, wc)
   |   |- Semantic analysis (Gemini CLI)
   |   |- Synthesis and merge
   |   +- Write .workflow/project-tech.json
   |- Step 4: Initialize Spec System (if not --skip-specs)
   |   |- Check if specs/*.md exist
   |   |- If NOT_FOUND -> Run ccw spec init
   |   +- Run ccw spec rebuild
   |- Step 5: Multi-Round Interactive Questionnaire (if not --skip-specs)
   |   |- Check if guidelines already populated -> Ask: "Append / Reset / Cancel"
   |   |- Load project context from project-tech.json
   |   |- Round 1: Coding Conventions (coding_style, naming_patterns)
   |   |- Round 2: File & Documentation Conventions (file_structure, documentation)
   |   |- Round 3: Architecture & Tech Constraints (architecture, tech_stack)
   |   |- Round 4: Performance & Security Constraints (performance, security)
   |   +- Round 5: Quality Rules (quality_rules)
   |- Step 6: Write specs/*.md (if not --skip-specs)
   +- Step 7: Display Summary

Output:
   |- .workflow/project-tech.json (+ .backup if regenerate)
   +- .ccw/specs/*.md (scaffold or configured, unless --skip-specs)