---
# Stage identity per spec Section 6.1
stage: 3
stage_id: "03"
title: "Branch Setup"
workflow: specify
estimated_tokens: 2000

# Context specification
context:
  static:
    persona: "meticulous requirements analyst extracting precise requirements"
    purpose: "Create feature branch and initialize spec directory"
  dynamic:
    - key: feature_dir
      source: cli_arg
    - key: feature
      source: cli_arg
    - key: jira
      source: cli_arg

# Pre-validation checks
pre_validation:
  - check: stage_02_completed
    condition: "state.specify.current_stage == '02-input-collection'"
    message: "Stage 02 (Input Collection) must be completed first"
    recovery: "civyk-hatch specify --stage=2"
  - check: feature_provided
    condition: "feature is not empty"
    message: "Feature description is required"
    recovery: "civyk-hatch specify --stage=2"

# Execution flow with step types
execution_flow:
  - step: 1
    type: action
    name: generate_short_name
    instruction: "Analyze feature description and create 2-4 word short name (action-noun format)"
    output_variable: short_name
  - step: 2
    type: action
    name: find_branch_number
    instruction: "Check remote/local branches and specs directories for highest existing number"
    output_variable: branch_number
  - step: 3
    type: action
    name: create_feature
    instruction: "Execute civyk-hatch create-feature command with feature, jira, short-name, number"
    output_variable: feature_info

# Guardrails
guardrails:
  enforcement: active
  allowed_tools:
    - civyk-repoix
    - Read
    - Bash
    - Glob
  forbidden_actions:
    - "Delete existing branches"
    - "Force push to remote"
  read_only: false

# Post-validation checks
post_validation:
  - check: branch_created
    description: "Git branch was created and checked out"
    severity: error
  - check: spec_dir_created
    description: "Spec directory was created"
    severity: error
  - check: state_initialized
    description: "State file was initialized"
    severity: warning

# Output specification
output:
  state_update:
    specify.current_stage: "03-branch-setup"
  completion_command: "civyk-hatch update-stage specify 03 --status completed"

# Next stage
next:
  stage: 4
  stage_id: "04"
  command: "civyk-hatch specify --stage=4"
  is_terminal: false
version: 1.0.0
---
{{include:ai-cache-enforcement.md}}

# Stage 3: Branch Setup

You are a {persona}.

Create the feature branch and initialize the spec directory.

**This is the final setup stage.** After this:

- A new git branch is created and checked out
- The spec folder (`specs/<feature-name>/`) is created
- State tracking begins (`.state/state.json`)
- Subsequent stages work within the feature context

---

## Step 1: Generate Short Name

Analyze the feature description and create a 2-4 word short name:

**Guidelines:**

- Use action-noun format: "add-user-auth", "fix-payment-bug"
- Preserve technical terms: OAuth2, API, JWT
- Keep concise but descriptive

**Examples:**

- "Add user authentication" -> `user-auth`
- "Implement OAuth2 for API" -> `oauth2-api-integration`
- "Create analytics dashboard" -> `analytics-dashboard`
- "Fix payment timeout bug" -> `fix-payment-timeout`

---

## Step 2: Find Next Branch Number

Check all sources for the highest existing number:

```bash
# Fetch latest
git fetch --all --prune

# Check remote branches
git ls-remote --heads origin | grep -E 'refs/heads/[0-9]+-<short-name>$'

# Check local branches
git branch | grep -E '^[* ]*[0-9]+-<short-name>$'

# Check specs directories
ls specs/ | grep -E '^[0-9]+-<short-name>$'
```

Use N+1 for the new branch number.

---

## Step 3: Run Create Feature Command

Execute the civyk-hatch create-feature command (cross-platform):

```bash
civyk-hatch create-feature "{{feature}}" --json --number N+1 \
  --jira "{{jira}}" --short-name "{{short_name}}"
```

**Parse JSON output** for branch and folder paths.

JSON output format:

```json
{
  "success": true,
  "folder": "specs/001-C12345-7890-user-auth",
  "branch": "feature/001-C12345-7890-user-auth",
  "state_file": "specs/001-C12345-7890-user-auth/.state/state.json",
  "feature_num": "001",
  "short_name": "user-auth"
}
```

---

## Output

After running `create-feature`, output:

```text
[ok] Branch created
  - Branch: <branch from JSON output>
  - Spec dir: <folder from JSON output>
```

---

## NEXT

```bash
civyk-hatch specify --stage=4 --feature-dir="{FEATURE_DIR}"
```
