--- 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" )" ``` - **`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="" 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 `../`. - 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 /.git test -w ``` 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/.git ``` 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