---
name: start
description: Use when starting a new feature or fix from a Jira ticket (ID, URL, or description). Fetches ticket context, creates branches and worktrees, and begins implementation automatically.
---

# /start - Initialize Feature & Begin Work (Humand Tech Plugin)

Start a new feature by fetching ticket context from Jira, creating branches, and immediately beginning implementation.

## Plugin-first adaptation

```bash
eval "$(bash "${CLAUDE_SKILL_DIR}/../../scripts/workflow-setup.sh" <workspace_root>)"
```

- Use `$REPOS_FILE`, `$LOCAL_CONFIG_FILE`, `$TEAMS_FILE` from `workflow-setup.sh`.

After running `workflow-setup.sh`, if `LOCAL_CONFIG_FILE` is empty, use **AskUserQuestion** before proceeding:

```
⚠️ No local-config.json found — I can't resolve repo paths without it.

[1] Run /initial-setup now (takes ~2 min, only needed once)
[2] Skip and continue anyway (some steps may fail)
```

If the user chooses **[1]**: invoke `/initial-setup` and stop this skill.  
If the user chooses **[2]**: continue, substituting `$LOCAL_CONFIG_FILE` references with best-effort guesses or skipping repo-dependent steps gracefully.

- Runtime checks:

```bash
bash "$PLUGIN_ROOT/scripts/check-runtime.sh" <repo_or_worktree_path> -- npm install
# or: ... -- pnpm install
```

## Superpowers-first hooks

- Planning and setup decisions: use `writing-plans` discipline.
- If implementation begins in same session: enforce `test-driven-development`.

## Path Resolution

- Read `$REPOS_FILE` for all repo metadata: platform, dependency order, role, GitHub path, base branch, lint/type-check commands, PR labels, etc.
- Read `$LOCAL_CONFIG_FILE` to resolve local repo paths. Each repo key maps to a relative path from this workspace root.
- Read `$TEAMS_FILE` to validate ticket prefixes and resolve squad names.

## Multi-Feature Storage

- **No local state is written.** The branch and worktree created by this skill are the sole record of the feature. `/commit`, `/pr`, and `/status` discover feature state from `git branch --show-current` and `git worktree list` at invocation time.

## Workflow

### 1. Identify the Ticket

The user may invoke `/start` with a ticket ID, URL, or bare description. Extract the ticket key if present.

- `/start SQSH-1234` → ticket key is `SQSH-1234`
- `/start https://humand.atlassian.net/browse/SQSH-1234` → ticket key is `SQSH-1234`
- `/start` with no argument → ask: `What ticket are you working on? (ID, URL, or "none")`

### 2. Fetch Ticket Details via Atlassian MCP (Preferred)

**Always try Atlassian MCP first.** Fetch the Jira cloud ID, then the ticket:

```
getAccessibleAtlassianResources()  → get cloudId
getJiraIssue(cloudId, issueIdOrKey: "SQSH-1234")
```

From the ticket, extract:

- **Title** and **description** (requirements, acceptance criteria)
- **Issue type** → auto-map to branch type: Bug → `fix`, Story → `feat`, Task → `chore`, Sub-task → inherit from parent
- **Parent ticket** — if the ticket description is thin (less than ~2 sentences of useful context), fetch the parent for full requirements
- **Figma URL** — check `customfield_10107` and the description body for figma.com links

If MCP is unavailable or fails, try the **REST API fallback** (global cascade from AGENTS.md):

```bash
RESP=$(curl -s -w "\n%{http_code}" \
  -u "$JIRA_EMAIL:$JIRA_API_TOKEN" \
  -H "Accept: application/json" \
  "https://humand.atlassian.net/rest/api/3/issue/$TICKET_KEY?fields=summary,issuetype,description,parent,customfield_10107")
HTTP_CODE=$(echo "$RESP" | tail -1)
ISSUE_BODY=$(echo "$RESP" | sed '$d')
```

Use the REST API result the same way as MCP: extract title, description, issue type, parent, Figma URL. If the REST API also fails (missing env vars or HTTP != 200), fall back to asking the user:

- Ticket title
- Ticket description / acceptance criteria (optional)
- Figma URL (optional)

### 3. Determine Setup (Single Prompt)

Using the fetched ticket data, present a **single confirmation prompt** with smart defaults:

```
Ticket: SQSH-1234 — Fix rounded edge on profile avatar
Type: Bug → fix
Parent: SQSH-1200 — Profile page redesign

Proposed setup:
  Branch: fix/SQSH-1234-fix-rounded-edge-on-profile-avatar
  Type: fix
  Repos: humand-web

Confirm or adjust:

1. Type: [fix] (1=fix, 2=feat, 3=chore, 4=docs, 5=test, 6=style)

2. Branch description: [fix-rounded-edge-on-profile-avatar]
   Enter custom description or press enter to accept

3. Repositories (comma-separated numbers):
   {numbered list from $REPOS_FILE, sorted by dependency_order, showing name + role}
   Default: [inferred from ticket context]

4. Working mode:
   [1] Worktree (default) — creates a separate directory, keeps your main checkout untouched
   [2] In-place — checks out the branch in the existing repo directory

5. Start implementing?
   [1] Yes — begin coding after setup (default)
   [2] No — just create branches and context, I'll code myself

Example: "1, 1, 3, 1, 1" or just press enter to accept defaults
```

**Smart defaults for repos:** Read `$REPOS_FILE` and use `platform_keywords` + `platform_to_repos` to infer repos from the ticket title/description. Match keywords against the ticket text, map to platform, then resolve to repo names. If unclear, don't pre-select — ask the user.

### Parsing User Response

- Accept answers separated by commas or on multiple lines
- For type: accept number (1-6) or text (fix, feat, etc.); empty = accept default
- For description: empty = accept default; otherwise use their text in kebab-case
- For repos: empty = accept default; otherwise comma-separated numbers
- For working mode: accept 1 (worktree) or 2 (in-place); empty = worktree (default)
- For implementation: accept 1 (yes) or 2 (no); empty = yes (default)
- If ticket is "none", "no", or "n", set ticket to null
- If only one repo is selected, this becomes a single-repo workflow

### 4. Branch Name Format

```
<type>/<TICKET>-<description>
```

The description is derived from the ticket title:

1. Take the ticket title (e.g., "Fix rounded edge")
2. Strip special characters (keep only alphanumeric and spaces)
3. Replace spaces with dashes
4. Convert to lowercase
5. Prefix with the ticket ID (preserve original case)

Examples:

- Ticket `SQSH-1234` + title "Fix rounded edge" → `fix/SQSH-1234-fix-rounded-edge`
- No ticket + custom "add user auth" → `feat/no-ticket-add-user-auth`

### 5. Create Branches

For each selected repository, resolve its path from `$LOCAL_CONFIG_FILE` and read its `base_branch` from `$REPOS_FILE`.

#### Pre-check collisions with active features (required)

Before branch creation, check for worktree collisions using git:

```bash
git -C <main_repo_path> worktree list --porcelain
```

If a worktree already exists for a branch other than the repo's base branch, the main checkout is occupied — recommend worktree mode to the user.

#### Worktree mode (default)

Create a git worktree as a sibling directory. The worktree directory name follows the convention `<repo>--<branch-description>`, where `<branch-description>` is the part after `<type>/` in the branch name.

```bash
cd <repo_path>
git fetch origin
git worktree add ../<repo>--<branch-description> origin/<base_branch> -b <branch_name>
```

Example: repo `humand-web` with branch `fix/SQSH-1234-fix-rounded-edge` creates worktree at `../humand-web--SQSH-1234-fix-rounded-edge`.

The worktree path becomes the working directory for all subsequent operations (edits, commits, pushes) in this feature.

After creating each worktree, sync local env files from the source repo to avoid missing-variable runtime issues in dev servers (for example unresolved `%VITE_*%` placeholders):

```bash
# still in <repo_path>
for env_file in .env .env.local .env.development .env.development.local .env.production .env.production.local; do
  if [ -f "$env_file" ] && [ ! -f "../<repo>--<branch-description>/$env_file" ]; then
    cp "$env_file" "../<repo>--<branch-description>/$env_file"
  fi
done
```

After creating each worktree, install dependencies in that worktree path when applicable (based on `package_manager` from `repos.json`):

For `npm`/`pnpm` repos, run installs through the shared runtime guard. It only attempts `nvm use` when a mismatch is detected.

```bash
# npm repos
bash "$PLUGIN_ROOT/scripts/check-runtime.sh" <worktree_path> -- npm install

# pnpm repos
bash "$PLUGIN_ROOT/scripts/check-runtime.sh" <worktree_path> -- pnpm install

cd <worktree_path>

# maven repos
mvn -q -DskipTests dependency:resolve

# go repos
go mod download
```

If install fails, report the error and continue with other repos; do not delete the created branch/worktree.
If env sync fails, report the error and continue with other repos; do not delete the created branch/worktree.

#### In-place mode

Check out the branch directly in the existing repo directory (classic behavior):

```bash
cd <repo_path>
git fetch origin
git checkout <base_branch>
git pull origin <base_branch>
git checkout -b <branch_name>
```

**Pre-check for in-place mode:** If the repo has uncommitted changes, warn the user and ask to stash or abort before switching branches.

### 6. Setup Confirmation (Brief)

Output a short confirmation:

```
Branch created: fix/SQSH-1234-fix-rounded-edge
  humand-web (from develop)

Ticket: SQSH-1234 — Fix rounded edge on profile avatar
Context saved.
```

If the user chose **not** to implement (option 2 in step 3), stop here and say:

```
Branches are ready. Run /commit when you have changes to commit.
```

Do NOT proceed to step 7.

If the user chose to implement (option 1 or default), **immediately proceed to step 7** — do NOT stop here. Append `Beginning implementation...` to the confirmation.

### 7. Begin Implementation

After setup is complete, **immediately start working on the ticket**. Do not wait for user input. (This entire step is skipped if the user chose not to implement in step 3.)

#### 7a. Understand the Requirements

Compile the full picture from the gathered context:

- Ticket title + description + acceptance criteria
- Parent ticket context (if fetched)
- Figma URL (if available — when present and user chose to implement, use it to run the Figma subagent in step 7c)

#### 7b. Explore, Plan

Navigate the selected repos to understand the relevant code:

- **Before coding, load repo guidance files (required):**
  - Apply this at the start of every feature for every selected repo
  - Read and follow `AGENTS.md`, `CLAUDE.md`, and `.claude/` directories in each selected repo when present
- Search for files, components, or modules related to the ticket
- Read the relevant source files to understand current implementation
- Identify what needs to change and where

#### 7c. Implement Figma Design (optional, soft delegation)

If the feature context has a **figma_url** and the user chose to implement (step 3), delegate to the **`humand-design:implement-figma`** skill. Do not implement from Figma in the main thread.

**Required:**

- **Invoke** the skill `humand-design:implement-figma` by name. Pass the Figma URL and the resolved target repo path (the `path` from feature context for the UI repo).
- **Do NOT** call any Figma MCP tools (`get_design_context`, `get_screenshot`, `get_metadata`, etc.) in this (main) thread. All Figma MCP usage must happen inside the subagent the router selects (`figma-react`, `figma-react-native`, or `figma-material-hu`).

**Steps:**

1. Pick the UI repo from the feature context (single selected repo, or prefer `humand-web` / `humand-backoffice` / `humand-mobile` / `material-hu` if multiple are present — match the ticket scope).
2. Resolve `targetRepoPath` from `feature-contexts/<id>.json` (worktree path or in-place path) for that repo.
3. Invoke `humand-design:implement-figma` with the figma_url and `targetRepoPath`. The router will identify the repo via git remote inside that path (handles worktree directory names like `humand-web--SQRN-1234-foo`) and pick the subagent (`figma-react`, `figma-react-native`, or `figma-material-hu`).
4. When the skill returns, show its summary and file list, then continue with 7d.

**If `humand-design` is not installed**, skip this step silently with a one-line hint: "Install `humand-design` to auto-implement Figma designs." Then continue with 7d.

If there is no figma_url, skip this step and go to 7d.

#### 7d. Execute remaining implementation (Features & Logic)

- Outline a brief implementation plan (a few bullet points). If the figma subagent ran, treat its output as the layout part; plan covers logic, integrations, wiring.
- Start making the changes (logic, integrations, wiring). If anything is ambiguous or there are multiple valid approaches, ask the user before proceeding.
- If new i18n keys or copy changes are introduced in product repos, include `hu-translations` in scope and perform translation work there (never in app repos).

This is the main work phase — treat it the same as if the user had described the task manually. Use all available tools (read, search, edit, terminal) to implement the feature or fix.

## Translation Quality (Mandatory)

- **No placeholders ever**: Do not use placeholder text in non-source locales (e.g. copying English to all locales just to pass checks).
- **Always use `hu-translations`**: Any translation key add/update must be done in `hu-translations`.
- **Always propagate**: After editing Spanish source keys, run `/sync-translations` from `hu-translations` to propagate all locales.
- **Always validate**: Run `npm run i18n:check` in `hu-translations` before handoff.
- **If blocked** (tooling/service issue): stop and ask the user; do not silently leave placeholder translations.

## Error Handling

- If branch already exists: Ask user to confirm checkout or create new name
- If repo has uncommitted changes (in-place mode): Warn and ask to stash or abort
- If worktree directory already exists: Ask user to reuse it, remove it, or pick a new name
- If selected in-place path has an active worktree on another branch: warn and require explicit confirmation (recommend worktree mode)
- If git fetch fails: Report network/auth error
- If runtime check fails for npm/pnpm repos: report expected vs current versions and the auto-fix attempt result; if unresolved, ask user to run `nvm use`
- If a repo is not in `repos.json`: Warn and skip, or use defaults (base_branch=develop)
- If Atlassian MCP is unavailable: Fall back to asking the user for ticket details

## Notes

- Branch name is shared across ALL selected repos
- hu-translations is opt-in, not auto-included
- Always fetch and pull base branch before creating feature branch
- Single-repo and multi-repo use the same flow; the only difference is how many repos are in the context
- The skill does NOT stop after branch creation — it continues into implementation
- **Worktree mode** is the default — it avoids disrupting uncommitted work on the main checkout. The worktree is a sibling directory of the original repo.
- All skills (`/commit`, `/pr`, `/status`) resolve the active feature from `git branch --show-current` in CWD and `git worktree list` per repo — no context files are read or written.
- Worktree cleanup is the developer's responsibility after the feature is merged (e.g., `git worktree remove <path>` from the main repo). A future `/cleanup` skill may automate this.
