/new

description: Create new spec and start research phase
argument-hint: <spec-name> [goal description] [--skip-research] [--specs-dir <path>]
allowed-tools: [Bash, Write, Task, AskUserQuestion]

Create New Spec

You are creating a new specification and starting the research phase.

Parse Arguments

From `$ARGUMENTS`, extract:

• **name**: The spec name (required, must be kebab-case, first argument)
• **goal**: Everything after the name except flags (optional)
• **--skip-research**: If present, skip research and start with requirements
• **--specs-dir <path>**: Create spec in specified directory (must be in configured specs_dirs array)

Examples:

• `/ralph-specum:new user-auth` -> name="user-auth", goal=none
• `/ralph-specum:new user-auth Add OAuth2 login` -> name="user-auth", goal="Add OAuth2 login"
• `/ralph-specum:new user-auth --skip-research` -> name="user-auth", goal=none, skip research
• `/ralph-specum:new api-auth --specs-dir ./packages/api/specs` -> create in specified dir

Multi-Directory Resolution

This command uses the path resolver for multi-directory support:

# Source path resolver (conceptually - commands don't execute bash directly)
# These functions are available via the path-resolver.sh helper:

ralph_get_specs_dirs()    # Returns all configured spec directories
ralph_get_default_dir()   # Returns first specs_dir (default for new specs)
ralph_find_spec(name)     # Find spec by name, returns full path
ralph_list_specs()        # List all specs as "name|path" pairs
ralph_resolve_current()   # Resolve .current-spec to full path

--specs-dir Validation

When `--specs-dir` is provided: 1. Call `ralph_get_specs_dirs()` to get configured directories 2. Check if provided path matches one of the configured directories 3. If NOT in configured list: Error "Invalid --specs-dir: '$path' is not in configured specs_dirs" 4. If valid: Use this path as the spec root instead of default

--specs-dir Validation Logic:

1. Extract --specs-dir value from $ARGUMENTS
2. Get configured dirs: dirs = ralph_get_specs_dirs()
3. Normalize paths (remove trailing slashes)
4. Check: specsDir in dirs?
   - YES: Use specsDir for spec creation
   - NO: Error "Invalid --specs-dir: '$specsDir' is not in configured specs_dirs. Configured: $dirs"

Spec Directory Resolution

Spec Directory Logic:

1. Check if --specs-dir in $ARGUMENTS
   - YES: Validate against configured specs_dirs, use if valid
   - NO: Use ralph_get_default_dir() (first configured dir, defaults to ./specs)

2. Determine spec base path:
   specsDir = validated --specs-dir OR ralph_get_default_dir()
   basePath = "$specsDir/$name"

3. For .current-spec:
   - If specsDir == "./specs" (default): Write bare name
   - If specsDir != "./specs" (non-default): Write full path "$specsDir/$name"

Capture Goal

<mandatory> The goal MUST be captured before proceeding:

1. If goal text was provided in arguments, use it 2. If NO goal text provided, use AskUserQuestion to ask: "What is the goal for this spec? Describe what you want to build or achieve." 3. Store the goal verbatim in .progress.md under "Original Goal" </mandatory>

Validation

1. Verify spec name is provided 2. Verify spec name is kebab-case (lowercase, hyphens only) 3. If --specs-dir provided, validate against configured specs_dirs 4. Determine target directory: specsDir = (validated --specs-dir) OR ralph_get_default_dir() 5. Check if `$specsDir/$name/` already exists. If so, ask user if they want to resume or overwrite

Initialize

1. Determine spec directory and base path:

   specsDir = (validated --specs-dir) OR ralph_get_default_dir()
   basePath = "$specsDir/$name"
   defaultDir = ralph_get_default_dir()

2. Create directory structure:

   mkdir -p "$basePath"

3. Update active spec tracker based on root directory:

   # Write to .current-spec in default specs dir
   if [ "$specsDir" = "$defaultDir" ]; then
       echo "$name" > "$defaultDir/.current-spec"     # Bare name for default root
   else
       echo "$basePath" > "$defaultDir/.current-spec" # Full path for non-default root
   fi

4. Ensure gitignore entries exist for spec state files:

   # Add .current-spec and .progress.md to .gitignore if not already present
   if [ -f .gitignore ]; then
     grep -q "specs/.current-spec" .gitignore || echo "specs/.current-spec" >> .gitignore
     grep -q "\*\*/\.progress\.md" .gitignore || echo "**/.progress.md" >> .gitignore
   else
     echo "specs/.current-spec" > .gitignore
     echo "**/.progress.md" >> .gitignore
   fi

5. Create or merge `.ralph-state.json` through the locked helper, using the resolved `basePath` and preserving any unknown fields:

   phase="research"
   nextPhase="requirements"
   if [[ "$ARGUMENTS" =~ (^|[[:space:]])--skip-research($|[[:space:]]) ]]; then
     phase="requirements"
     nextPhase="design"
   fi
   python3 "${CLAUDE_PLUGIN_ROOT}/hooks/scripts/locked-state.py" merge \
     --state "$basePath/.ralph-state.json" \
     --set "source=spec" \
     --set "name=$name" \
     --set "basePath=$basePath" \
     --set "phase=$phase" \
     --set "taskIndex=0" \
     --set "totalTasks=0" \
     --set "taskIteration=1" \
     --set "maxTaskIterations=5" \
     --set "globalIteration=1" \
     --set "maxGlobalIterations=100"

6. Create initial `.progress.md` with the captured goal:

   ---
   spec: $name
   basePath: $basePath
   phase: $phase
   task: 0/0
   updated: <current timestamp>
   ---

   # Progress: $name

   ## Original Goal

   $goal

   ## Completed Tasks

   _No tasks completed yet_

   ## Current Task

   Starting $phase phase

   ## Learnings

   _Discoveries and insights will be captured here_

   ## Blockers

   - None currently

   ## Next

   Complete $phase, then proceed to $nextPhase

Resolve Goal Interview

Read `${CLAUDE_PLUGIN_ROOT}/references/goal-interview.md`