---
name: eck:create-feature
version: "0.8.2"
description: "Create a feature with a project-scoped identifier, tracker issue, register it in lifecycle.json, and optionally activate it."
disable-model-invocation: false
---

# Create Feature

Create a new feature with a <KEY>-XXX identifier, optionally create a tracker issue, register it in `.claude/lifecycle.json`, and choose to activate it or keep it in the backlog.

> Streamlined feature creation: name it, track it, activate or queue — one command.

---

## Visual Framework

Follow these conventions for all terminal output displayed to the user via the Bash tool.

### Output Mode Awareness

Before producing output, read the user's preferred output mode:

```bash
ECK_HOME="${ECK_HOME:-$HOME/.claude/evolv-coder-kit}"
cat $ECK_HOME/user-preferences.json 2>/dev/null
```

Extract the `outputMode` field and adapt verbosity:

- **guided** — Add explanatory prose after key steps. Describe what is happening and why.
- **standard** (default) — Balanced. Show steps with brief context for non-obvious decisions.
- **concise** — Steps and summary box only. No prose, no explanations.

If the file is missing or `outputMode` is absent, use **standard**.

### ANSI Colors

Declare these variables at the top of **every** Bash tool call (shell state does not persist between calls):

```bash
source $ECK_HOME/colors.sh
```

Every color sequence **must** end with `${RESET}`. No exceptions.

### Stage Banners

Mark major stage transitions with a bold banner. One blank line before and after.

```bash
echo ""
printf '%b\n' "${ORANGE}${BOLD}STAGE NAME${RESET}"
echo ""
```

### Status Symbols

| Symbol | Meaning          | Color       |
| ------ | ---------------- | ----------- |
| `[*]`  | Active / running | `${CYAN}`   |
| `[x]`  | Completed        | `${GREEN}`  |
| `[!]`  | Error            | `${RED}`    |
| `[-]`  | Skipped          | `${DIM}`    |
| `[>]`  | In progress      | `${YELLOW}` |
| `[ ]`  | Pending          | `${DIM}`    |

No emoji in output. Use only these bracket symbols for status.

### Summary Boxes

Display at checkpoints and at the end of the skill. One blank line before and after.

### Error Format

```bash
printf '%b\n' "${RED}[!]${RESET} Error message here"
printf '%b\n' "    ${DIM}Recovery guidance here.${RESET}"
```

### Spacing Rules

- One blank line before and after stage banners and summary boxes.
- No blank lines within step lists.
- Maximum output line width: 70 characters.

---

## Task Registration

| Stage | Subject                | Active Form         | Statusline     |
| ----- | ---------------------- | ------------------- | -------------- |
| 1     | Stage 1: Gather        | Gathering details   | Gather (1/5)   |
| 2     | Stage 2: Register      | Registering feature | Register (2/5) |
| 3     | Stage 3: Track         | Creating tracker    | Track (3/5)    |
| 4     | Stage 4: Scaffold Docs | Scaffolding docs    | ScafDocs (4/5) |
| 5     | Stage 5: Activate      | Activating feature  | Activate (5/5) |

### Statusline Stage Updates

At the **start** of each stage, update the statusline:

```bash
bash $ECK_HOME/update-stage.sh "{Statusline text from table}"
```

At **skill completion** (success or error), reset:

```bash
bash $ECK_HOME/update-stage.sh
```

---

---

## Usage

```
/eck:create-feature "User Authentication"
/eck:create-feature "Email Templates" --issue 55
/eck:create-feature "Billing API" --no-issue       # skip tracker
/eck:create-feature "Search" --no-activate          # keep in backlog
/eck:create-feature                                 # interactive
```

### Flags

| Flag                   | Description                                                  |
| ---------------------- | ------------------------------------------------------------ |
| `--issue <n>`          | Link to existing tracker issue number (skips issue creation) |
| `--description <text>` | Brief description of the feature                             |
| `--priority <n>`       | Backlog priority (lower = higher priority)                   |
| `--no-issue`           | Skip automatic tracker issue creation                        |
| `--no-docs`            | Skip docs folder creation                                    |
| `--no-activate`        | Keep in backlog without activating                           |

---

## Stage 2/3 Ordering

Read `TRACKER_TYPE` from `.claude/project-constants.md`.

- If `TRACKER_TYPE ∈ {JIRA, Linear}` and `--no-issue` is not set: run **Stage 3 first**. Capture the tracker key from the primitive response (`.key` for JIRA, `.identifier` for Linear). Return to Stage 2 and call `manage-features.js create --id "$TRACKER_KEY" --name "$FEATURE_NAME"`. This is the "tracker-first" path (AC-1, AC-2).
- If `TRACKER_TYPE = GitHub`, or `TRACKER_TYPE = none`, or `--no-issue` is set: run **Stage 2 first** (auto-generates `<PROJECT_KEY>-N`). Then run Stage 3 if applicable, and on GitHub specifically, write back the issue `number` via `update-lifecycle.js register --issue` (AC-3, AC-12).

**Error surface on tracker-first midway failure (AC-5):** if Stage 3 succeeded but Stage 2 fails (e.g., `DUPLICATE_ID`), print via `output:error-handler`: the tracker key, the tracker URL, and the raw stderr from `manage-features.js`, then exit 1. No automatic rollback of the tracker issue.

---

## Stage 1: Gather

```bash
ECK_HOME="${ECK_HOME:-$HOME/.claude/evolv-coder-kit}"
source $ECK_HOME/colors.sh
bash $ECK_HOME/update-stage.sh "Gather (1/5)"
```

### Inputs

- `$ARGUMENTS` — feature name and flags
- `.claude/project-constants.md` — project key, tracker type

### Activities

1. Parse `$ARGUMENTS` for feature name and flags.

2. **If no feature name provided**, prompt interactively via AskUserQuestion:

   ```
   What feature would you like to add to the backlog?

   Enter a short name (e.g., "User Authentication", "Email Templates"):
   ```

3. **If no `--description` flag**, optionally prompt:

   ```
   Optional: Brief description of this feature (press Enter to skip):
   ```

4. Display gathered info:
   ```
   [x] Feature: {FEATURE_NAME}
       Description: {DESCRIPTION or "none"}
       Priority: {PRIORITY or "none"}
   ```

### Outputs

- Feature name resolved
- Optional: description, priority

### Exit Criteria

- Feature name is non-empty
- All optional fields resolved (or explicitly skipped)

---

## Stage 2: Register

```bash
ECK_HOME="${ECK_HOME:-$HOME/.claude/evolv-coder-kit}"
source $ECK_HOME/colors.sh
bash $ECK_HOME/update-stage.sh "Register (2/5)"
```

### Inputs

- Feature name, description, priority from Stage 1
- `TRACKER_KEY` — set by Stage 3 if JIRA/Linear ran first; otherwise empty

### Activities

**Dispatcher:** At the top of this stage, check the tracker ordering:

- If `TRACKER_TYPE ∈ {JIRA, Linear}` and `--no-issue` is not set:
  - If Stage 3 has not yet run: **jump to Stage 3 first**, then return here.
  - If Stage 3 already ran and `TRACKER_KEY` is set: proceed with `--id $TRACKER_KEY` below.
  - If Stage 3 already ran but `TRACKER_KEY` is empty (tracker failed): STOP — tracker failure already aborted.
- Otherwise (GitHub, none, or `--no-issue`): proceed with auto-ID path.

1. Create the feature in `manage-features.js` to get the <KEY>-XXX identifier:

   **For JIRA/Linear path (tracker ran first — pass `--id`):**

   ```bash
   ECK_HOME="${ECK_HOME:-$HOME/.claude/evolv-coder-kit}"
   source $ECK_HOME/colors.sh
   FEAT_RESULT=$(node $ECK_HOME/manage-features.js create \
     --id "$TRACKER_KEY" \
     --name "$FEATURE_NAME" \
     ${DESCRIPTION:+--description "$DESCRIPTION"} \
     ${PRIORITY:+--priority "$PRIORITY"} 2>/tmp/mf_stderr)
   MF_EXIT=$?
   if [ $MF_EXIT -ne 0 ]; then
     MF_STDERR=$(cat /tmp/mf_stderr)
     printf '%b\n' "${RED}[!]${RESET} Tracker issue created but feature registration failed."
     printf '%b\n' "    Tracker key: ${TRACKER_KEY}"
     printf '%b\n' "    Tracker URL:  ${TRACKER_URL}"
     printf '%b\n' "    Error: ${MF_STDERR}"
     printf '%b\n' "    ${DIM}The tracker issue was NOT rolled back.${RESET}"
     bash $ECK_HOME/update-stage.sh
     exit 1
   fi
   FEATURE_ID=$(echo "$FEAT_RESULT" | jq -r '.id')
   FEATURE_SLUG=$(echo "$FEAT_RESULT" | jq -r '.slug')
   ```

   **For GitHub/none/--no-issue path (auto-ID):**

   ```bash
   ECK_HOME="${ECK_HOME:-$HOME/.claude/evolv-coder-kit}"
   source $ECK_HOME/colors.sh
   FEAT_RESULT=$(node $ECK_HOME/manage-features.js create \
     --name "$FEATURE_NAME" \
     ${DESCRIPTION:+--description "$DESCRIPTION"} \
     ${PRIORITY:+--priority "$PRIORITY"} 2>/dev/null)
   if [ $? -ne 0 ]; then
     printf '%b\n' "${RED}[!]${RESET} Failed to create feature"
     printf '%b\n' "    ${DIM}Check manage-features.js output for details.${RESET}"
     bash $ECK_HOME/update-stage.sh
     exit 1
   fi
   FEATURE_ID=$(echo "$FEAT_RESULT" | jq -r '.id')
   FEATURE_SLUG=$(echo "$FEAT_RESULT" | jq -r '.slug')
   ```

2. Register the feature in lifecycle.json:

   ```bash
   ECK_HOME="${ECK_HOME:-$HOME/.claude/evolv-coder-kit}"
   source $ECK_HOME/colors.sh
   if [ -n "$DESCRIPTION" ] && [ -n "$PRIORITY" ]; then
     node $ECK_HOME/update-lifecycle.js register "$FEATURE_ID" --description "$DESCRIPTION" --priority "$PRIORITY"
   elif [ -n "$DESCRIPTION" ]; then
     node $ECK_HOME/update-lifecycle.js register "$FEATURE_ID" --description "$DESCRIPTION"
   elif [ -n "$PRIORITY" ]; then
     node $ECK_HOME/update-lifecycle.js register "$FEATURE_ID" --priority "$PRIORITY"
   else
     node $ECK_HOME/update-lifecycle.js register "$FEATURE_ID"
   fi
   ```

3. Check if feature already existed (idempotent register):
   - If already exists, display: `[x] Feature already registered: ${FEATURE_ID} (updated)`
   - If new, display: `[x] Feature registered: ${FEATURE_ID} (${FEATURE_SLUG})`

### Outputs

- `FEATURE_ID` set to <KEY>-XXX value
- `FEATURE_SLUG` set to kebab-case slug
- Feature registered in lifecycle.json with `backlog` state

### Exit Criteria

- `FEATURE_ID` is set and non-empty
- Feature exists in lifecycle.json

---

## Stage 3: Track

```bash
ECK_HOME="${ECK_HOME:-$HOME/.claude/evolv-coder-kit}"
source $ECK_HOME/colors.sh
bash $ECK_HOME/update-stage.sh "Track (3/5)"
```

### Inputs

- `FEATURE_ID`, `FEATURE_SLUG`, display name from Stage 2 (or pending Stage 2 on JIRA/Linear path)
- `--issue <n>` flag (if present, link existing issue)
- `--no-issue` flag (if present, skip tracker)
- `.claude/project-constants.md` — `TRACKER_TYPE` setting

### Activities

1. **If `--no-issue` flag is present**, skip this stage:
   - Display: `[-] Skipped tracker issue (--no-issue)`
   - Jump to Stage 4.

2. **If `--issue <n>` was provided**, link that issue number:
   - Store issue number for lifecycle registration
   - Display: `[x] Linked existing issue: #${ISSUE_NUMBER}`
   - Jump to Stage 4.

3. **Otherwise, create tracker issue** (default behavior):

   **If `TRACKER_TYPE = JIRA`:**

   This stage runs BEFORE Stage 2. Use the `tracker:issue-create` primitive routed to the JIRA backend:

   ```
   ISSUE_RESULT = tracker/jira-official:issue-create(
     project_key: PROJECT_KEY,
     issue_type: "Epic",
     summary: FEATURE_NAME,
     description: DESCRIPTION
   )
   ```

   Extract the tracker key:

   ```bash
   ECK_HOME="${ECK_HOME:-$HOME/.claude/evolv-coder-kit}"
   source $ECK_HOME/colors.sh
   TRACKER_KEY=$(echo "$ISSUE_RESULT" | jq -r '.key')
   TRACKER_URL=$(echo "$ISSUE_RESULT" | jq -r '.self // ""')
   ```

   If issue creation fails, abort with tracker error — do NOT proceed to Stage 2.

   Display: `[x] JIRA epic: ${TRACKER_KEY}`

   Return to Stage 2, passing `TRACKER_KEY`.

   **If `TRACKER_TYPE = Linear`:**

   This stage runs BEFORE Stage 2. Use the `tracker:issue-create` primitive routed to the Linear backend:

   ```
   ISSUE_RESULT = tracker/linear-official:issue-create(
     team_id: TEAM_ID,
     title: FEATURE_NAME,
     description: DESCRIPTION,
     labels: ["epic"]
   )
   ```

   Extract the tracker identifier:

   ```bash
   ECK_HOME="${ECK_HOME:-$HOME/.claude/evolv-coder-kit}"
   source $ECK_HOME/colors.sh
   TRACKER_KEY=$(echo "$ISSUE_RESULT" | jq -r '.identifier')
   TRACKER_URL=$(echo "$ISSUE_RESULT" | jq -r '.url // ""')
   ```

   If issue creation fails, abort with tracker error — do NOT proceed to Stage 2.

   Display: `[x] Linear issue: ${TRACKER_KEY}`

   Return to Stage 2, passing `TRACKER_KEY`.

   **If `TRACKER_TYPE = GitHub`:**

   This stage runs AFTER Stage 2 (FEATURE_ID is already set). First create the label idempotently, then create the issue:

   ```bash
   ECK_HOME="${ECK_HOME:-$HOME/.claude/evolv-coder-kit}"
   source $ECK_HOME/colors.sh
   gh label create epic --description "Feature epic" --color 0E8A16 2>/dev/null || true
   ISSUE_RESULT=$(tracker/gh-cli:issue-create \
     --title "$FEATURE_NAME" \
     --label "epic" \
     --body "${DESCRIPTION:-Feature: $FEATURE_NAME}")
   ```

   Extract the issue number:

   ```bash
   ECK_HOME="${ECK_HOME:-$HOME/.claude/evolv-coder-kit}"
   source $ECK_HOME/colors.sh
   NUMBER=$(echo "$ISSUE_RESULT" | jq -r '.number')
   TRACKER_URL=$(echo "$ISSUE_RESULT" | jq -r '.url // ""')
   ```

   If issue creation fails, log warning and continue without issue number:

   ```bash
   printf '%b\n' "${YELLOW}[>]${RESET} Tracker issue creation failed — continuing without issue"
   ```

   Write back issue number to both stores (AC-3, AC-12):

   ```bash
   ECK_HOME="${ECK_HOME:-$HOME/.claude/evolv-coder-kit}"
   source $ECK_HOME/colors.sh
   node $ECK_HOME/update-lifecycle.js register "$FEATURE_ID" --issue "$NUMBER"
   REPO=$(gh repo view --json nameWithOwner -q .nameWithOwner 2>/dev/null || true)
   node $ECK_HOME/manage-features.js set-remote "$FEATURE_ID" \
     --type github \
     --url "$TRACKER_URL" \
     --issue-number "$NUMBER" \
     ${REPO:+--repo "$REPO"}
   ```

   Display: `[x] GitHub issue: #${NUMBER}`
   - If `<TRACKER_TYPE>` is not configured, skip silently (no tracker = no issue).

4. Display: `[x] Tracker: ${ISSUE_NUMBER:+#${ISSUE_NUMBER}}${ISSUE_NUMBER:-none}`

### Outputs

- Optional: `TRACKER_KEY` set if JIRA/Linear ran first (passed to Stage 2)
- Optional: `ISSUE_NUMBER` set if tracker issue was created or linked

### Exit Criteria

- Tracker stage completed (issue created, linked, or intentionally skipped)

---

## Stage 4: Scaffold Docs

```bash
ECK_HOME="${ECK_HOME:-$HOME/.claude/evolv-coder-kit}"
source $ECK_HOME/colors.sh
bash $ECK_HOME/update-stage.sh "ScafDocs (4/5)"
```

### Inputs

- `FEATURE_ID`, `FEATURE_SLUG`, issue number, display name from prior stages
- `--no-docs` flag (if present, skip this stage)
- `.claude/project-constants.md` — `DOC_PLATFORM` setting

### Activities

1. **If `--no-docs` flag is present**, skip this stage:
   - Display: `[-] Skipped docs folder (--no-docs)`
   - Jump to Stage 5.

2. **Read `DOC_PLATFORM`** from `.claude/project-constants.md`:
   - If `DOC_PLATFORM` is `confluence`, skip local folder creation (Confluence pages are created by `/eck:design`):
     - Display: `[-] Docs folder skipped (Confluence project)`
     - Jump to Stage 5.

3. **Compute folder name using FEATURE_ID and FEATURE_SLUG:**

   ```bash
   ECK_HOME="${ECK_HOME:-$HOME/.claude/evolv-coder-kit}"
   source $ECK_HOME/colors.sh
   DOCS_DIR="docs/features/${FEATURE_ID}-${FEATURE_SLUG}"
   ```

4. **Create the docs folder and README stub:**

   ```bash
   ECK_HOME="${ECK_HOME:-$HOME/.claude/evolv-coder-kit}"
   source $ECK_HOME/colors.sh
   mkdir -p "$DOCS_DIR"

   cat > "$DOCS_DIR/README.md" << READMEEOF
   # ${FEATURE_ID}: ${FEATURE_NAME}

   **Status:** Planned
   **Issue:** ${ISSUE_NUMBER:+#${ISSUE_NUMBER}}${ISSUE_NUMBER:-none}
   **Created:** $(date -u +%Y-%m-%d)

   ${DESCRIPTION:-TBD}
   READMEEOF
   ```

5. Display: `[x] Docs folder: ${DOCS_DIR}/`

### Outputs

- `docs/features/${FEATURE_ID}-${FEATURE_SLUG}/README.md` created (or skipped for Confluence/--no-docs)

### Exit Criteria

- Docs folder exists on disk with a valid README stub (or was intentionally skipped)

---

## Stage 5: Activate

```bash
ECK_HOME="${ECK_HOME:-$HOME/.claude/evolv-coder-kit}"
source $ECK_HOME/colors.sh
bash $ECK_HOME/update-stage.sh "Activate (5/5)"
```

### Inputs

- `FEATURE_ID`, `FEATURE_SLUG` from Stage 2
- `--no-activate` flag (if present, skip activation prompt)
- Current `active_feature` from lifecycle.json

### Activities

Record the start time for activity duration tracking:

```bash
ECK_HOME="${ECK_HOME:-$HOME/.claude/evolv-coder-kit}"
source $ECK_HOME/colors.sh
STAGE5_START=$(date +%s)
```

**Step 1 — Q_ACTIVATE**

1. **If `--no-activate` flag is present**, skip activation:
   - Display: `[-] Skipped activation (--no-activate)`
   - Status remains `backlog`
   - Jump to backlog summary (step 7 below). No branch or worktree is created (AC-17, AC-24).

2. **Check for an existing active feature:**

   ```bash
   ECK_HOME="${ECK_HOME:-$HOME/.claude/evolv-coder-kit}"
   source $ECK_HOME/colors.sh
   CURRENT_ACTIVE=$(jq -r '.active_feature // empty' "$CLAUDE_PROJECT_DIR/.claude/lifecycle-state.json" 2>/dev/null)
   [ -z "$CURRENT_ACTIVE" ] && CURRENT_ACTIVE=$(jq -r '.active_feature // empty' "$CLAUDE_PROJECT_DIR/.claude/lifecycle.json" 2>/dev/null)
   ```

3. **Prompt the user via AskUserQuestion (Q_ACTIVATE):**
   - **If an active feature exists (`CURRENT_ACTIVE` is non-empty):**

     ```
     A feature is currently active: <CURRENT_ACTIVE>

     What would you like to do with the new feature "<FEATURE_ID> (<FEATURE_NAME>)"?

     Options:
       1 - Park <CURRENT_ACTIVE> and activate <FEATURE_ID>
       2 - Keep <FEATURE_ID> in backlog
     ```

   - **If no active feature exists:**

     ```
     New feature created: <FEATURE_ID> (<FEATURE_NAME>)

     Options:
       1 - Activate <FEATURE_ID> now
       2 - Keep in backlog
     ```

4. **If user chose backlog (option 2):** jump to step 7 (backlog summary). No branch or worktree is created (AC-17, AC-24).

---

**Step 2 — Compute BRANCH_NAME** (activate path only)

```bash
ECK_HOME="${ECK_HOME:-$HOME/.claude/evolv-coder-kit}"
source $ECK_HOME/colors.sh
BRANCH_NAME="feat/${FEATURE_ID}-${FEATURE_SLUG}"
```

---

**Step 3 — Attempt branch creation** (activate path only)

```bash
ECK_HOME="${ECK_HOME:-$HOME/.claude/evolv-coder-kit}"
source $ECK_HOME/colors.sh
GIT_STDERR=$(git -C "$CLAUDE_PROJECT_DIR" checkout -b "$BRANCH_NAME" dev 2>&1)
GIT_EXIT=$?
```

**If checkout succeeded (`GIT_EXIT = 0`):**

```bash
ECK_HOME="${ECK_HOME:-$HOME/.claude/evolv-coder-kit}"
source $ECK_HOME/colors.sh
node $ECK_HOME/update-lifecycle.js register "$FEATURE_ID" --branch "$BRANCH_NAME"
printf '%b\n' "${GREEN}[x]${RESET} Branch created: ${BRANCH_NAME}"
BRANCH_CREATED=true
```

**If checkout failed (`GIT_EXIT != 0`)** — present Q_BRANCH_RECOVERY via AskUserQuestion:

```
Branch creation failed: {GIT_STDERR}

How would you like to proceed?

Options:
  a - Park the active feature, retry branch creation on a clean tree
  b - Stash uncommitted changes (git stash -u) and retry
  c - Skip branch creation — activate feature on current branch
```

On option (a) — park and retry:

```bash
ECK_HOME="${ECK_HOME:-$HOME/.claude/evolv-coder-kit}"
source $ECK_HOME/colors.sh
node $ECK_HOME/update-lifecycle.js deactivate "$CURRENT_ACTIVE" 2>/dev/null || true
GIT_STDERR2=$(git -C "$CLAUDE_PROJECT_DIR" checkout -b "$BRANCH_NAME" dev 2>&1)
GIT_EXIT2=$?
if [ $GIT_EXIT2 -eq 0 ]; then
  node $ECK_HOME/update-lifecycle.js register "$FEATURE_ID" --branch "$BRANCH_NAME"
  printf '%b\n' "${GREEN}[x]${RESET} Branch created: ${BRANCH_NAME}"
  BRANCH_CREATED=true
else
  printf '%b\n' "${YELLOW}[>]${RESET} Retry failed — continuing without branch"
  BRANCH_CREATED=false
fi
```

On option (b) — stash and retry:

```bash
ECK_HOME="${ECK_HOME:-$HOME/.claude/evolv-coder-kit}"
source $ECK_HOME/colors.sh
git -C "$CLAUDE_PROJECT_DIR" stash -u
GIT_STDERR2=$(git -C "$CLAUDE_PROJECT_DIR" checkout -b "$BRANCH_NAME" dev 2>&1)
GIT_EXIT2=$?
if [ $GIT_EXIT2 -eq 0 ]; then
  node $ECK_HOME/update-lifecycle.js register "$FEATURE_ID" --branch "$BRANCH_NAME"
  printf '%b\n' "${GREEN}[x]${RESET} Branch created: ${BRANCH_NAME}"
  BRANCH_CREATED=true
else
  printf '%b\n' "${YELLOW}[>]${RESET} Retry failed — continuing without branch"
  BRANCH_CREATED=false
fi
```

On option (c) — skip branch:

```bash
ECK_HOME="${ECK_HOME:-$HOME/.claude/evolv-coder-kit}"
source $ECK_HOME/colors.sh
printf '%b\n' "${YELLOW}[>]${RESET} Skipping branch creation — activating on current branch"
BRANCH_CREATED=false
```

Note: when option (c) is chosen or retry fails, do NOT call `register --branch`. The `branch` field is left absent in the registry (not written as `null`). Skip Q_WORKTREE entirely.

---

**Step 4 — Q_WORKTREE** (only reached if `BRANCH_CREATED = true`)

Present AskUserQuestion:

```
Create a git worktree for isolated development?

Worktree path: .claude/worktrees/{BRANCH_NAME}

Options:
  1 - Yes, create worktree (recommended)
  2 - No, continue without worktree
```

**If user chose no (option 2):** skip to step 5. No worktree created, no EnterWorktree call (AC-24).

**If user chose yes (option 1):**

Check and update `.gitignore` (AC-19):

```bash
ECK_HOME="${ECK_HOME:-$HOME/.claude/evolv-coder-kit}"
source $ECK_HOME/colors.sh
grep -qxF '/.claude/worktrees/' "$CLAUDE_PROJECT_DIR/.gitignore" 2>/dev/null \
  || printf '\n/.claude/worktrees/\n' >> "$CLAUDE_PROJECT_DIR/.gitignore"
```

Create the worktree (AC-20):

```bash
ECK_HOME="${ECK_HOME:-$HOME/.claude/evolv-coder-kit}"
source $ECK_HOME/colors.sh
WORKTREE_PATH=".claude/worktrees/${BRANCH_NAME}"
WT_STDERR=$(git -C "$CLAUDE_PROJECT_DIR" worktree add "$WORKTREE_PATH" "$BRANCH_NAME" 2>&1)
WT_EXIT=$?
if [ $WT_EXIT -ne 0 ]; then
  printf '%b\n' "${YELLOW}[>]${RESET} Worktree creation failed — continuing without worktree"
  printf '%b\n' "    ${DIM}${WT_STDERR}${RESET}"
  WORKTREE_CREATED=false
else
  printf '%b\n' "${GREEN}[x]${RESET} Worktree: ${WORKTREE_PATH}"
  WORKTREE_CREATED=true
fi
```

---

**Step 5 — Activate lifecycle** (always reached on activate path, before EnterWorktree)

```bash
ECK_HOME="${ECK_HOME:-$HOME/.claude/evolv-coder-kit}"
source $ECK_HOME/colors.sh
node $ECK_HOME/update-lifecycle.js activate "$FEATURE_ID"
STAGE5_END=$(date +%s)
DURATION=$((STAGE5_END - STAGE5_START))
node $ECK_HOME/log-activity.js \
  --skill create-feature \
  --feature "$FEATURE_ID" \
  --outcome success \
  --summary "Created ${FEATURE_ID}" \
  --step activate \
  --duration "$DURATION"
```

Display activate summary (step 6 below).

---

**Step 6 — Activate summary and EnterWorktree**

Display:

```
[x] Feature activated: ${FEATURE_NAME}
```

If another feature was parked: `[x] Parked: {previous_feature_name}`

Display summary box:

```
Feature Created

Feature         {FEATURE_NAME}
ID              {FEATURE_ID}
Issue           #{issue_number} (or "none")
Docs            {docs_folder_path} (or "skipped")
Created         {ISO date, e.g. 2026-03-13}
Priority        {priority} (or "unset")
Status          active

Next: /eck:spec {FEATURE_ID}
```

Reset statusline:

```bash
ECK_HOME="${ECK_HOME:-$HOME/.claude/evolv-coder-kit}"
source $ECK_HOME/colors.sh
bash $ECK_HOME/update-stage.sh
```

**EnterWorktree handoff** (AC-21) — only if `WORKTREE_CREATED = true`:

Invoke the EnterWorktree tool with:

```
{ "path": ".claude/worktrees/${BRANCH_NAME}" }
```

If EnterWorktree is unavailable in context (subagent), print instead (AC-22):

```
Worktree created at .claude/worktrees/${BRANCH_NAME}.
Continue with: cd .claude/worktrees/${BRANCH_NAME} && claude --continue
```

Return — session CWD is now the worktree if EnterWorktree succeeded.

---

**Step 7 — Backlog summary**

Display alternate summary box:

```
Feature Created

Feature         {FEATURE_NAME}
ID              {FEATURE_ID}
Issue           #{issue_number} (or "none")
Docs            {docs_folder_path} (or "skipped")
Created         {ISO date, e.g. 2026-03-13}
Priority        {priority} (or "unset")
Status          backlog

Next: /eck:select-feature to start working on it
```

Log activity:

```bash
ECK_HOME="${ECK_HOME:-$HOME/.claude/evolv-coder-kit}"
source $ECK_HOME/colors.sh
STAGE5_END=$(date +%s)
DURATION=$((STAGE5_END - STAGE5_START))
node $ECK_HOME/log-activity.js \
  --skill create-feature \
  --feature "$FEATURE_ID" \
  --outcome success \
  --summary "Created ${FEATURE_ID}" \
  --step activate \
  --duration "$DURATION"
```

Reset statusline:

```bash
ECK_HOME="${ECK_HOME:-$HOME/.claude/evolv-coder-kit}"
source $ECK_HOME/colors.sh
bash $ECK_HOME/update-stage.sh
```

### Outputs

- Feature registered in lifecycle.json
- Feature activated (if user chose activation)
- User sees summary with next-step guidance

### Exit Criteria

- Feature exists in lifecycle.json
- Feature is active or in backlog based on user choice
- User sees summary with clear next step

---

## Error Handling

- If `manage-features.js create` fails, show the error output and STOP — no <KEY>-XXX means no registration
- If `update-lifecycle.js register` fails, show the error output and STOP
- If tracker issue creation fails on JIRA/Linear, abort before Stage 2 — do not proceed
- If tracker issue creation fails on GitHub, log warning and continue without issue number
- If JIRA/Linear tracker succeeded but `manage-features.js create --id` fails, print tracker key + URL + error via output:error-handler, then exit 1 (AC-5). No rollback.
- If `activate` fails, log error but feature remains registered in backlog
- If no lifecycle.json exists, one is created automatically by the register command
- At completion (success or error), always reset statusline
