---
name: initial-setup
description: Use once when setting up the plugin for the first time — configures local repo paths, validates prerequisites, and initializes workflow state
---

# /initial-setup - Developer Environment Setup (Humand Tech Plugin)

Walk through first-time setup of the Humand multi-repo workflow and ensure all sibling repos are properly configured.

## Plugin-first adaptation

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

- **`workflow-setup.sh`**: exports `PLUGIN_ROOT`, `WORKSPACE_ROOT`, `STATE_HOME`, `CONFIG_HOME`, and resolved config paths (`REPOS_FILE`, `TEAMS_FILE`, `LOCAL_CONFIG_FILE`, `BUNDLED_LOCAL_CONFIG_EXAMPLE_FILE`).

| Path | Use |
|------|-----|
| repos config | `$REPOS_FILE` |
| teams config | `$TEAMS_FILE` |
| local config | `$LOCAL_CONFIG_FILE` |
| local config example | `$BUNDLED_LOCAL_CONFIG_EXAMPLE_FILE` |
| runtime audit | `bash "$PLUGIN_ROOT/scripts/audit-runtime.sh" "$WORKSPACE_ROOT"` |

## Superpowers-first guard

Use `verification-before-completion`: only report setup success after checks actually run.

## Workflow

**IMPORTANT: Always start with step 1, regardless of whether `local-config.json` exists or not. Do not skip ahead.**

### 1. Legacy Migration (humand-dev-workflow)

Use **AskUserQuestion** to ask:

```
Did you previously use the humand-dev-workflow repo for the Humand workflow?
[1] Yes — I have it cloned locally
[2] No — this is a fresh install
```

If **No**: skip to step 2.

If **Yes**: ask for the local path:

```
Where is humand-dev-workflow cloned? (e.g. ~/Code/humand/humand-dev-workflow)
```

Then copy `local-config.json` manually:

```bash
legacy_path="<path-user-provided>"
config_home="${HUMAND_WORKFLOW_CONFIG_HOME:-${XDG_CONFIG_HOME:-$HOME/.config}/humand-tech-workflow}"
mkdir -p "$config_home"

# Try .cursor location first, then repo root
for candidate in "$legacy_path/.cursor/local-config.json" "$legacy_path/local-config.json"; do
  if [ -f "$candidate" ]; then
    cp "$candidate" "$config_home/local-config.json"
    echo "Migrated local-config.json from $candidate"
    break
  fi
done
```

Report result to the user. If no `local-config.json` found, tell the user they will need to create one in step 4. If it fails, show the error and continue — migration is best-effort and non-blocking.

> **Note:** Feature contexts, current-feature, and history are no longer stored locally — git and GitHub are the source of truth. Only `local-config.json` needs to be migrated.

After a successful migration, re-eval `workflow-setup.sh` so `LOCAL_CONFIG_FILE` picks up the migrated config:

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

### 2. Check Prerequisites

Verify required tools are installed:

```bash
gh --version
git --version
jq --version
```

If `gh` is not authenticated, prompt:

```
GitHub CLI is not authenticated. Run: gh auth login
```

### 3. Verify Jira / Atlassian MCP

Check that Atlassian MCP is available for ticket info (used by /start, /pr, etc.):

- Call **getAccessibleAtlassianResources** (or **atlassianUserInfo**). If the call succeeds, report: `Jira/Atlassian MCP: OK`.
- If the tool is unavailable or returns an error, use **AskUserQuestion**:

  ```
  Jira/Atlassian MCP is not available. Ticket lookup will fall back to manual input.
  Configure Atlassian MCP in Claude Code to enable issue fetch (humand.atlassian.net).
  Continue anyway? [y/n]
  ```

Include Jira MCP status in the final summary (step 9).

### 4. Create or Sync local-config.json

After `workflow-setup.sh`, treat **user** local config as present if `LOCAL_CONFIG_FILE` is non-empty.

If it is empty (file does not exist), build the config in memory from the bundled example — **do not write to disk yet**. Show the user the full JSON for review:

```
Here is the local-config.json that will be created:

{
  "repos": {
    "humand-main-api":  "../humand-main-api",
    "material-hu":      "../material-hu",
    "humand-web":       "../humand-web",
    "humand-backoffice": "../humand-backoffice",
    "humand-mobile":    "../humand-mobile",
    "hu-translations":  "../hu-translations",
    ...
  }
}

Do these paths look correct? (yes / provide corrections)
```

Accept corrections inline (e.g. "humand-web: ~/projects/humand-web"). Once the user confirms, write the file:

```bash
# write confirmed JSON to disk
cat > "$CONFIG_HOME/local-config.json" << 'JSON'
{ ... confirmed content ... }
JSON
```

Then re-eval `workflow-setup.sh` so `LOCAL_CONFIG_FILE` resolves to the new file.

If `LOCAL_CONFIG_FILE` was already set, use it for reads/writes in later steps.

If a user config **already** existed before seeding, sync missing repo keys from `REPOS_FILE`:

- For each repo key in `repos.json` missing in `local-config.json`, add default sibling path `../<repo-name>`.
- Keep existing user-defined paths unchanged.
- Report which keys were added automatically.

If you only seeded a new file in this run, still perform the sync step above, then continue to step 4.

### 5. Validate Repo Paths

For each repo key in `REPOS_FILE`, ensure `local-config.json.repos[repoKey]` exists.  
Then, for each configured repo path, verify:

1. Directory exists and is a git repo
2. Write permissions are available (non-blocking check)

```bash
for each repo in repos.json:
  test -d <repo_path>/.git
  test -w <repo_path>
```

Report results:

```
Repo path validation:

  humand-main-api:   ../humand-main-api    OK
  material-hu:       ../material-hu         OK
  humand-web:        ../humand-web          OK
  humand-backoffice: ../humand-backoffice   OK
  humand-mobile:     ../humand-mobile       MISSING
  hu-translations:   ../hu-translations     OK
  humand-cerberus:   ../humand-cerberus     MISSING

Write access (non-blocking):

  humand-web:        WRITE OK
  humand-main-api:   NO WRITE (you can still continue)
```

For missing repos, ask:

```
humand-mobile not found at ../humand-mobile

[1] Clone it now (from HumandDev/humand-mobile)
[2] Enter a different path
[3] Skip this repo (remove from local-config.json)
```

If cloning, run:

```bash
git clone git@github.com:HumandDev/<repo>.git <path>
```

If write access is missing:

- Report it as warning only (do not block setup)
- Suggest fixing local permissions before running `/commit` or `/pr`
- Continue with setup

### 6. Verify repos.json Coverage

Check that every repo in `local-config.json` has an entry in `REPOS_FILE` with the required fields (`base_branch`, `package_manager`, `lint_cmd`, `pr_base`, `pr_labels`).

Report any repos missing from `$REPOS_FILE` and prompt the user to add them.

### 7. Verify hu-translations Has sync-translations Skill

Check that hu-translations has the sync-translations skill:

Check that hu-translations has the `sync-translations` skill available. If missing, warn the user — the skill is added by [hu-translations PR #1215](https://github.com/HumandDev/hu-translations/pull/1215).

### 8. Runtime Audit (Node/npm repos)

Run the shared runtime audit to detect mismatched Node/npm versions in configured npm/pnpm repos:

```bash
bash "$PLUGIN_ROOT/scripts/audit-runtime.sh" "$WORKSPACE_ROOT"
```

If any repo fails:

- Show current vs expected versions from the checker output
- Clarify that the checker already attempted `nvm use` automatically; if still failing, ask the user to run `nvm use` manually (or switch runtime manager)
- Do not block setup completion, but keep it as a warning in the summary

### 9. Summary

```
Setup complete!

  local-config.json:    configured
  Repos found:          22/22
  repos.json coverage:  22/22 repos have config
  Write access:         20/22 writable (2 warnings)
  Legacy migration:     skipped (or: migrated from ~/Code/humand/humand-dev-workflow)
  Runtime audit:        ok=14 fail=4 skipped=0
  Prerequisites:        gh, git, jq all available
  Jira/Atlassian MCP:   OK (or: not configured)

Pending actions for you:
  {list any legacy file deletions that need committing}
```

Then offer `/start`:

```
Would you like me to run /start to begin a new feature?
```

If the user accepts, immediately invoke `/start`. If they decline, stop.

## Notes

- This skill is safe to re-run at any time to verify the setup
- It never pushes or commits to any repo -- it only creates/deletes local files and reports what the user needs to commit
- Missing repos can be skipped; they just won't appear in /start's repo selection
