setup-things

What this skill does

<purpose>
Initialize the `~/.things/` data directory that all brenna-plugs career plugins depend on. This creates the config, collection registry, shared resource directories, and optional git remote.

When an existing `config.yml` is detected, this skill migrates ALL plugin configs to the new per-plugin format automatically - the user should NOT need to run individual plugin setup commands for config migration.

See `references/config-schema.md` for config schemas and `references/registry-schema.md` for registry schema.
</purpose>

<steps>

  <step id="check-existing" number="1">
    <description>Check for Existing Configuration</description>

    <load-config>
    Resolve the user's home directory (run `echo $HOME` via Bash). Use this absolute path for all file operations below -- never pass `~` to the Read tool.

    <constraint>The convention path is `<home>/.things/`. No bootstrap file is needed.</constraint>

    Check in this order:

    1. Check if `<home>/.things/config.json` exists
       <if condition="config-json-exists">Show current settings and ask (via AskUserQuestion) if they want to reconfigure.</if>

    2. Check if `<home>/.things/config.yml` exists
       <if condition="config-yml-exists">
       This is a legacy YAML config. Set `migrating_from_yaml = true`.
       Read config.yml and extract ALL data - this will be used to pre-populate everything.
       Skip to Step 2 (git sync check).
       </if>

    3. <if condition="directory-exists-but-no-config">Skip to Step 4 (directory init).</if>
    4. <if condition="neither-exists">Fresh setup (continue to Step 2).</if>

    <if condition="reconfiguring">Show current settings as defaults throughout.</if>
    </load-config>
  </step>

  <step id="check-git-sync" number="2">
    <description>Check Git Sync Status</description>

    <critical-safety-check>
    Before making any changes to `.things`, check if it's a git repository and verify sync status with remote.
    </critical-safety-check>

    Check if `.things` is a git repository:

    ```bash
    cd <home>/.things && git rev-parse --git-dir >/dev/null 2>&1 && echo "is-repo" || echo "not-repo"
    ```

    <if condition="is-git-repo">

    Run these checks and display results prominently in output:

    ```bash
    # Check for uncommitted changes
    cd <home>/.things && git status --porcelain

    # Fetch remote (if remote exists)
    cd <home>/.things && git fetch 2>/dev/null

    # Check local vs remote status
    cd <home>/.things && git status -sb
    ```

    <output>
    ```
    Git Sync Status for ~/.things/
    ├─ Repository: ✓ (git initialized)
    ├─ Remote: <remote_url or "none">
    ├─ Branch: <branch_name>
    ├─ Local commit: <short_sha> <commit_message>
    ├─ Remote commit: <short_sha> <commit_message>
    ├─ Sync status:
    │  └─ <one of:>
    │     • ✓ Up to date with remote
    │     • ⚠ Behind remote by N commits (PULL REQUIRED)
    │     • ⚠ Ahead of remote by N commits (PUSH PENDING)
    │     • ⚠ Diverged from remote (MERGE REQUIRED)
    │     • ℹ No remote configured
    └─ Uncommitted changes: <none or list of modified files>
    ```
    </output>

    <if condition="has-uncommitted-changes">
    WARNING: You have uncommitted changes in `.things`.
       - The migration will preserve your files but may conflict with uncommitted work
       - Recommendation: Commit or stash changes before proceeding
    </if>

    <if condition="behind-remote">
    WARNING: Your local `.things` is behind the remote by N commits.
       - Running migration without pulling could cause you to lose remote changes
       - Recommendation: Pull from remote first, then run migration
    </if>

    <if condition="diverged-from-remote">
    WARNING: Your local and remote `.things` have diverged.
       - This will require manual merge resolution
       - Recommendation: Resolve divergence before running migration
    </if>

    <if condition="ahead-of-remote">
    INFO: You have N unpushed commits locally.
       - These will be preserved during migration
       - Remember to push after migration completes
    </if>

    </if>

    <if condition="not-git-repo">
    <output>
    ```
    Git Sync Status for ~/.things/
    └─ Repository: ✗ (not initialized)
       └─ Git will be initialized during setup if you configure a remote
    ```
    </output>
    </if>
  </step>

  <step id="detect-username" number="3">
    <description>Detect GitHub Username</description>

    ```bash
    gh api user -q .login 2>/dev/null || git config user.name
    ```

    <if condition="migrating_from_yaml">Use the `github_username` from config.yml as the default.</if>

    Use AskUserQuestion to confirm the detected username with the user.
  </step>

  <step id="init-directory" number="4">
    <description>Initialize .things/ Directory</description>

    Create the directory structure:

    ```bash
    mkdir -p <home>/.things/shared/people
    mkdir -p <home>/.things/shared/roles
    mkdir -p <home>/.things/shared/contexts
    mkdir -p <home>/.things/shared/companies
    mkdir -p <home>/.things/tags
    ```

    <output-path>`<home>/.things/.gitignore`</output-path>

    <template name="gitignore">

    ```
    *.tmp
    .DS_Store
    local.json
    ```

    </template>

    <output-path>`<home>/.things/local.json`</output-path>

    <schema name="local-json">
    Machine-specific overrides, gitignored:

    ```json
    {}
    ```

    </schema>
  </step>

  <step id="gather-git-settings" number="5">
    <description>Gather Git Remote Settings</description>

    <if condition="migrating_from_yaml">
    Use values from config.yml: `things_repo` (remote), `things_branch` (branch), `git_workflow` (workflow).
    Show the extracted values to the user and use AskUserQuestion to confirm:
    - "I found these git settings in your existing config. Look correct?"
    - Options: "Yes, use these" / "No, let me change them"
    <if condition="user-wants-changes">Ask the individual questions below.</if>
    <if condition="user-confirms">Skip to git init phase.</if>
    </if>

    <if condition="fresh-setup">
    Use AskUserQuestion:

    Do you want to sync your .things directory to a git remote?
    <options>
    - Yes -- I have a repo ready
    - Yes -- create one for me (I'll give you the details)
    - No -- local only for now
    </options>

    <if condition="wants-git-remote">
    Use AskUserQuestion to ask for:
    - Remote URL (e.g., `[email protected]:username/my-things.git`)
    - Branch (default: `main`)
    </if>

    Use AskUserQuestion:

    How do you want to manage git for your things?
    <options>
    - `auto` -- automatically commit and push after changes
    - `ask` -- ask me each time whether to commit/push
    - `manual` -- I'll handle git myself
    </options>
    </if>

    <phase name="git-init" number="1">
    Initialize git (if not already a repo):

    ```bash
    cd <home>/.things
    git init
    git remote add origin <remote_url>  # if configured
    git checkout -b <branch>
    ```
    </phase>
  </step>

  <step id="gather-profile" number="6">
    <description>Gather Professional Profile</description>

    <if condition="migrating_from_yaml">
    Use values from config.yml: `author_name`, `current_role`, `target_roles`, `career_direction`, `building_skills`, `aspirational_skills`.
    Show extracted profile to user and use AskUserQuestion to confirm:
    - "I found this professional profile in your existing config. Look correct?"
    - Options: "Yes, use this" / "No, let me update it"
    <if condition="user-wants-changes">Ask the individual questions below.</if>
    <if condition="user-confirms">Skip to next step.</if>
    </if>

    <if condition="fresh-setup">
    Use AskUserQuestion for each:

    What's your name? (for blog posts, logs, and attribution)

    What's your current role/title?

    What are you targeting professionally? (Select all that apply)
    <options>
    - Promotion to a specific role
    - Lateral move to