setup-ftr

What this skill does

<purpose>
Initialize the `for-the-record` plugin within `~/.things/`. Creates the docs directory, registers the collection in the registry, writes preferences, and sets up empty index files.
</purpose>

<steps>

  <step id="load-config" number="1">
    <description>Load Configuration</description>

    <load-config>
      <action>Resolve the user's home directory.</action>
      <command language="bash" output="home" tool="Bash">echo $HOME</command>
      <constraint>Never pass `~` to the Read tool.</constraint>

      <read path="<home>/.things/config.json" output="config" />
      <if condition="config-missing">Tell the user: "Run `/things:setup-things` first to initialize .things/." Then stop.<exit /></if>

      <if condition="reconfigure-argument">
        <read path="<home>/.things/for-the-record/preferences.json" output="existing-prefs" />
        <action>Show current settings as defaults throughout.</action>
      </if>
    </load-config>
  </step>

  <step id="create-directories" number="2">
    <description>Create Plugin Directories</description>

    ```bash
    mkdir -p <home>/.things/for-the-record/docs
    mkdir -p <home>/.things/for-the-record/discussions
    ```
  </step>

  <step id="gather-preferences" number="3">
    <description>Gather Preferences</description>

    <ask-user-question>
      <question>What level of detail should documents capture by default?</question>
      <option label="Concise (Recommended)">Key points, decisions, and outcomes — compact and scannable</option>
      <option label="Detailed">Full reasoning chains, code blocks, all alternatives discussed — maximum context preservation</option>
    </ask-user-question>

    <ask-user-question>
      <question>Should documents auto-generate tags from content?</question>
      <option label="Yes (Recommended)">Automatically suggest tags from technologies, keywords, and existing tag vocabulary</option>
      <option label="No">I'll add tags manually each time</option>
    </ask-user-question>

    <ask-user-question>
      <question>Should verbatim discussions be automatically pruned after a number of days?</question>
      <option label="No retention limit (Recommended)">Keep all discussions indefinitely</option>
      <option label="30 days">Auto-prune discussions older than 30 days</option>
      <option label="90 days">Auto-prune discussions older than 90 days</option>
      <option-with-text-input>Custom number of days</option-with-text-input>
    </ask-user-question>
  </step>

  <step id="write-preferences" number="4">
    <description>Write Preferences</description>

    <write path="<home>/.things/for-the-record/preferences.json">

    ```json
    {
      "default_detail_level": "<concise|detailed>",
      "auto_tag": <true|false>,
      "discussion_retention_days": <number or null>
    }
    ```

    </write>
  </step>

  <step id="write-index-files" number="5">
    <description>Write Empty Index Files</description>

    <if condition="index.json missing">
    <write path="<home>/.things/for-the-record/index.json">

    ```json
    {
      "version": 1,
      "last_updated": "<current_date>",
      "total_items": 0,
      "items": []
    }
    ```

    </write>
    </if>

    <if condition="tags.json missing">
    <write path="<home>/.things/for-the-record/tags.json">

    ```json
    {
      "last_updated": "<current_date>",
      "tags": {}
    }
    ```

    </write>
    </if>
  </step>

  <step id="register-collection" number="6">
    <description>Register Collection in Registry</description>

    <read path="<home>/.things/registry.json" output="registry" />

    <action>Add (or update) the `for-the-record/docs` and `for-the-record/discussions` collection entries.</action>

    <schema name="collection-entry">

    ```json
    {
      "for-the-record/docs": {
        "plugin": "for-the-record",
        "description": "Structured documentation captured from conversations and context",
        "tags_field": "frontmatter.tags",
        "item_structure": {
          "directory_per_item": false,
          "file_pattern": "*.md"
        },
        "index_schema": {
          "required_fields": {
            "filename": "string",
            "title": "string",
            "date": "date",
            "tags": "string[]"
          },
          "optional_fields": {
            "description": "string",
            "detail_level": "string",
            "source_type": "string"
          }
        },
        "master_index": "for-the-record/index.json",
        "rebuild_command": "python3 ${PLUGIN_PATH:for-the-record@brenna-plugs}/scripts/rebuild-index.py ${THINGS_PATH}"
      }
    }
    ```

    </schema>

    <schema name="discussions-collection">

    ```json
    {
      "for-the-record/discussions": {
        "plugin": "for-the-record",
        "description": "Verbatim conversation captures preserved without summarization",
        "tags_field": "frontmatter.tags",
        "item_structure": {
          "directory_per_item": false,
          "file_pattern": "*.md"
        },
        "index_schema": {
          "required_fields": {
            "filename": "string",
            "title": "string",
            "date": "date",
            "tags": "string[]"
          },
          "optional_fields": {
            "description": "string",
            "source_type": "string"
          }
        },
        "master_index": "for-the-record/index.json",
        "rebuild_command": "python3 ${PLUGIN_PATH:for-the-record@brenna-plugs}/scripts/rebuild-index.py ${THINGS_PATH}"
      }
    }
    ```

    </schema>

    <action>Merge both into `registry.json`'s `collections` object and write the file.</action>
  </step>

  <step id="update-environment" number="7">
    <description>Update Environment Tracking</description>

    <action>Read `config.json`, find the current hostname's environment entry, and add `"for-the-record"` to its `plugins` array if not already present. Write back.</action>
  </step>

  <step id="git-workflow" number="8">
    <description>Handle Git Workflow</description>

    <git-workflow>
      <action>Read git workflow from `config.json` (`git.workflow`).</action>

      <if condition="workflow-auto">Automatically `git add`, `git commit -m "setup: for-the-record"`, and `git push`.</if>
      <if condition="workflow-ask">
        <ask-user-question>
          <question>Commit and push the for-the-record setup?</question>
          <option>Yes -- commit and push</option>
          <option>Commit only</option>
          <option>No -- I'll handle git myself</option>
        </ask-user-question>
      </if>
      <if condition="workflow-manual">Tell the user the setup is complete and they can commit when ready.</if>
    </git-workflow>
  </step>

  <step id="confirm" number="9">
    <description>Confirm Setup</description>

    <completion-message>
    for-the-record is ready!

    - Docs directory: `<home>/.things/for-the-record/docs/`
    - Discussions directory: `<home>/.things/for-the-record/discussions/`
    - Detail level: `<default_detail_level>`
    - Auto-tagging: `<auto_tag>`
    - Discussion retention: `<discussion_retention_days or "unlimited">`
    - Collections registered: `for-the-record/docs`, `for-the-record/discussions`

    Start capturing:
    - `/add-doc-ftr <topic>` -- Capture a document from conversation context
    - `/add-doc-ftr <topic> --detailed` -- Capture with maximum detail
    - `/capture-discussion` -- Capture a verbatim discussion (no summarization)
    - `/import-ftr <path>` -- Import existing documentation files from any directory
    </completion-message>
  </step>

</steps>