============
Installation
============

Recommended Installer
=====================

``llm-workflow`` now provides one installer command for generated platform
artifacts:

.. code-block:: bash

   llm-workflow <build|install|clean|doctor> <codex|claude|opencode|grok|all>

Install the package in editable mode for development:

.. code-block:: bash

   pip install -e ".[dev]"

This provides the ``llm-workflow`` command-line entry point.

Examples:

.. code-block:: bash

   llm-workflow build all
   llm-workflow install codex
   llm-workflow install claude --yes
   llm-workflow install opencode
   llm-workflow install grok
   llm-workflow doctor all
   llm-workflow clean codex

``install`` runs ``build`` first. Symlink installs are the default; pass
``--copy`` for snapshot installs. User config edits require confirmation unless
``--yes`` is supplied. ``doctor`` is read-only.

Generated artifacts are written to ``build/`` and are not committed.

Prerequisites
-------------

- Python 3.11+
- ``PyYAML`` (installed by ``pip install -e ".[dev]"``)
- The target platform CLI, as needed: ``codex``, ``claude``, ``opencode``,
  or ``grok``

Canonical Skills
================

The source of truth for skills is ``llm_workflow/skills/<skill-id>/``:

.. code-block:: text

   llm_workflow/
     skills/
       review-tests/
         skill.yml
         instructions.md

The installer generates platform-specific artifacts for Codex, Claude Code,
OpenCode, and Grok from this canonical source.

Generated Platform Artifacts
============================

Each generated artifact contains the canonical skill instructions plus a
platform orchestration adapter.

- ``full`` means the platform can run the intended workflow natively.
- ``degraded`` means the artifact is installable but includes explicit fallback
  guidance.
- ``unsupported`` skills are skipped for that platform.

Multi-persona skills use this hierarchy:

1. Full platform-native team orchestration when available.
2. Platform-native subagents when available.
3. Sequential single-agent fallback, where each persona runs in the current
   session and its markdown output is recorded before continuing.

Default input files are rendered per platform:

- Claude Code: ``.claude/<skill>.md``
- Codex: ``.codex/<skill>.md``
- OpenCode: ``.opencode/<skill>.md``
- Grok: ``.grok/<skill>.md``

Migrated skills also check the legacy ``.claude/<skill>.md`` path after the
platform default.

.. _compatibility-matrix:

Compatibility Matrix
--------------------

.. list-table::
   :header-rows: 1
   :widths: 22 12 12 12 12 30

   * - Skill
     - Claude Code
     - Codex
     - OpenCode
     - Grok
     - Notes
   * - ``code-review-response``
     - full
     - full
     - full
     - full
     - Standalone, no external dependencies
   * - ``complexity``
     - full
     - full
     - full
     - full
     - Needs ``radon`` (Python) and/or ``gocyclo`` (Go); does not auto-install
   * - ``review-tests``
     - full
     - full
     - full
     - full
     - Standalone, no external dependencies
   * - ``cprompt``
     - full
     - full
     - full
     - full
     - Writes prompt file, prints prompt, and attempts clipboard copy
   * - ``thermo-nuclear``
     - full
     - full
     - full
     - full
     - Strict single-agent maintainability review; writes report artefact
   * - ``debate``
     - full
     - degraded
     - degraded
     - degraded
     - External model routing falls back only after user confirmation
   * - ``council``
     - full
     - degraded
     - degraded
     - degraded
     - Multi-persona review with sequential fallback
   * - ``pre-mortem``
     - full
     - degraded
     - degraded
     - degraded
     - Failure-focused multi-persona review
   * - ``shred-it``
     - full
     - degraded
     - degraded
     - degraded
     - Research-backed adversarial idea review
   * - ``team-review-tests``
     - full
     - degraded
     - degraded
     - degraded
     - Test-quality multi-persona review
   * - ``team-review-impl``
     - full
     - degraded
     - degraded
     - degraded
     - Spec-driven implementation review

Legacy Manual Installation
==========================

.. _claude-code-install:

Claude Code Installation
========================

Prerequisites
-------------

- `Claude Code <https://claude.com/claude-code>`_ CLI installed and configured
- Git (for cloning the repository)

**Skill-specific prerequisites:**

- `HydraMCP <https://www.npmjs.com/package/hydramcp>`_ or another model router
  enables external-model ``debate`` personas. If unavailable, the generated
  skill asks before continuing as a within-model debate.
- **Agent teams** enable full Claude multi-persona orchestration for
  ``council``, ``pre-mortem``, ``shred-it``, ``team-review-tests``, and
  ``team-review-impl``. If unavailable, generated artifacts describe the
  sequential fallback.
- ``complexity`` needs ``radon`` for Python and/or ``gocyclo`` for Go. The
  skill reports missing tools and does not auto-install them.

Installation Steps
------------------

1. **Clone the repository**

   .. code-block:: bash

      git clone https://github.com/yourusername/llm-workflow.git
      cd llm-workflow

2. **Register the local marketplace**

   Add the marketplace to your Claude Code settings. Edit
   ``~/.claude/settings.json`` and add:

   .. code-block:: json

      {
        "enabledPlugins": {
          "wf@wf-marketplace": true
        },
        "extraKnownMarketplaces": {
          "wf-marketplace": {
            "source": {
              "source": "directory",
              "path": "/path/to/llm-workflow/plugin"
            }
          }
        }
      }

   Replace ``/path/to/llm-workflow`` with the actual path where you cloned
   the repository.

3. **Verify installation**

   Restart Claude Code. The ``wf`` skills should now be available. You can
   verify by invoking a skill directly:

   .. code-block:: text

      /wf:code-review-response
      /wf:debate

.. _agent-teams-setup:

Agent Teams Setup
-----------------

The ``council`` and ``pre-mortem`` skills require Claude Code's **experimental
agent teams** feature. This allows multiple Claude agent instances to work as
a team, each with their own independent context window.

.. warning::

   **Agent teams is experimental.** The API may change without notice in future
   Claude Code updates. If these skills break after an update, check the
   `agent teams documentation <https://code.claude.com/docs/en/agent-teams>`_
   for API changes.

Enabling Agent Teams
^^^^^^^^^^^^^^^^^^^^

Agent teams are **disabled by default**. Enable them by adding the environment
variable to your Claude Code settings.

Edit ``~/.claude/settings.json`` and add the ``CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS``
environment variable:

.. code-block:: json

   {
     "env": {
       "CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS": "1"
     }
   }

This merges with any existing settings. A full ``settings.json`` with plugin
and agent teams enabled looks like:

.. code-block:: json

   {
     "env": {
       "CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS": "1"
     },
     "enabledPlugins": {
       "wf@wf-marketplace": true
     },
     "extraKnownMarketplaces": {
       "wf-marketplace": {
         "source": {
           "source": "directory",
           "path": "/path/to/llm-workflow/plugin"
         }
       }
     }
   }

Alternatively, you can set the environment variable in your shell profile
(``~/.bashrc``, ``~/.zshrc``, etc.):

.. code-block:: bash

   export CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1

The ``settings.json`` approach is recommended because it ensures agent teams
are consistently available across all Claude Code sessions.

Verifying Agent Teams
^^^^^^^^^^^^^^^^^^^^^

After enabling, restart Claude Code and run:

.. code-block:: text

   /wf:council

If agent teams are properly enabled, the skill will proceed to parse input.
If not, you will see an error indicating that agent teams tools are
unavailable.

Display Modes
^^^^^^^^^^^^^

Agent teams support different display modes for teammate output. Configure
via ``settings.json``:

.. code-block:: json

   {
     "env": {
       "CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS": "1"
     }
   }

Or use the ``--teammate-mode`` flag when starting Claude Code:

- ``auto`` (default) — uses split panes in tmux/iTerm2, in-process otherwise
- ``in-process`` — all teammates run in your main terminal
- ``tmux`` — forces split-pane mode (requires tmux or iTerm2)

.. note::

   Split-pane mode is **not supported** in VS Code terminal, Windows Terminal,
   or Ghostty. Use ``in-process`` mode in those environments.

Agent Teams Caveats
^^^^^^^^^^^^^^^^^^^

Be aware of the following limitations when using the ``council``,
``pre-mortem``, and ``team-review-tests`` skills:

**Cost and performance:**

- Each judge runs as a **separate Claude agent instance** with its own context
  window. A 3-judge council costs ~6 agent turns; a 4-judge pre-mortem costs
  ~12 agent turns; a 3-judge team-review-tests costs ~9 agent turns.
- Token usage is significantly higher than the ``debate`` skill, which uses
  a single host session with ``ask_model`` calls.
- Use these skills for important decisions, not routine reviews.

**Session constraints:**

- **One team per session** — Claude Code supports a single agent team per
  session. Do not run council, pre-mortem, or team-review-tests while another
  team is active.
- **No nested teams** — teammates cannot spawn their own teams.
- **No session resumption** — ``/resume`` and ``/rewind`` do not restore
  in-process teammates. If the session is interrupted, you must re-run the
  skill.

**Known issues:**

- **Delegate mode is broken** — when the lead delegates to teammates,
  permission restrictions propagate and prevent teammates from working. The
  council and pre-mortem skills work around this by having the lead coordinate
  directly without using delegate mode.
- **Task status lag** — teammates sometimes fail to mark tasks complete,
  which can cause the lead to wait unnecessarily.
- **Slow shutdown** — teammates finish current work before shutting down.
  Team cleanup may take a few seconds.

**Permissions:**

- All teammates start with the **lead's permission mode**. Individual
  teammate permissions can be changed after spawning but not at spawn time.
- If the lead runs with ``--dangerously-skip-permissions``, all teammates
  do too.

Updating
--------

To update to the latest version:

.. code-block:: bash

   cd /path/to/llm-workflow
   git pull origin master

The plugin will automatically pick up the updated skill definitions.

Uninstalling
------------

To remove the plugin, edit ``~/.claude/settings.json`` and:

1. Remove the ``"wf@wf-marketplace": true`` entry from ``enabledPlugins``
2. Remove the ``"wf-marketplace"`` entry from ``extraKnownMarketplaces``
3. Optionally remove the ``CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS`` env var
   if no longer needed

Then restart Claude Code.

.. _grok-install:

Grok Installation
=================

The installer generates Grok skills for every ``full`` or ``degraded`` skill
in the compatibility matrix and installs them under ``~/.grok/skills/``.

Multi-persona degraded skills prefer Grok ``spawn_subagent`` and otherwise run
persona turns sequentially in the current session. Context embedding does not
require ``smart_read``; platforms without that tool use native read-and-summarise.

Prerequisites
-------------

- Grok Build CLI available for verification (optional for install)
- Write access to ``~/.grok/skills/``

Install
-------

.. code-block:: bash

   llm-workflow install grok
   llm-workflow doctor grok

This builds ``build/grok/skills/<skill-id>/SKILL.md`` and symlinks each
installable skill into ``~/.grok/skills/``. Use ``--copy`` for snapshot
installs.

Invocation
----------

Restart or open a Grok session after installing. Skills appear as slash
commands named after the skill id:

.. code-block:: text

   /review-tests
   /council
   /cprompt

Grok also supports automatic invocation from the skill description and
``when-to-use`` metadata.

Default input files
-------------------

Multi-input skills look for:

1. An explicit path provided by the user
2. ``.grok/<skill>.md`` in the repository root
3. Legacy ``.claude/<skill>.md``

Codex coexistence
-----------------

Codex installs into ``~/.agents/skills/``. Grok also scans that directory.
If the same skill names exist in both places, prefer the Grok adapter under
``~/.grok/skills/`` for Grok sessions, or remove Codex copies with:

.. code-block:: bash

   llm-workflow clean codex

Uninstall
---------

.. code-block:: bash

   llm-workflow clean grok

.. _codex-install:

Codex Installation
==================

The installer generates Codex skills for every ``full`` or ``degraded`` skill
in the compatibility matrix. Multi-persona degraded skills use subagents when
the runtime exposes them and otherwise run persona turns sequentially in the
current session.

Prerequisites
-------------

- `Codex CLI <https://developers.openai.com/codex/>`_ installed and configured
- Git (for cloning the repository)

Installation Methods
--------------------

Codex scans for skills in several locations. Choose the scope that fits your
workflow:

.. list-table::
   :header-rows: 1
   :widths: 15 35 50

   * - Scope
     - Location
     - Use case
   * - Repo
     - ``$REPO_ROOT/.agents/skills/``
     - Shared with collaborators via version control
   * - User
     - ``$HOME/.agents/skills/``
     - Personal skills available in all projects
   * - Codex home
     - ``$HOME/.codex/skills/``
     - Installed via ``$skill-installer``

Option A: Symlink (recommended for development)
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Symlink the compatible skills into your user skills directory. This keeps
them up to date when you ``git pull``.

.. code-block:: bash

   # Create the user skills directory
   mkdir -p ~/.agents/skills

   # Symlink the compatible skills
   ln -s /path/to/llm-workflow/plugin/skills/code-review-response \
         ~/.agents/skills/code-review-response
   ln -s /path/to/llm-workflow/plugin/skills/review-tests \
         ~/.agents/skills/review-tests

Replace ``/path/to/llm-workflow`` with the actual path where you cloned
the repository.

Option B: Copy into a repository
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Copy the skill directories into a specific repo so collaborators get them
automatically:

.. code-block:: bash

   # From your target repository root
   mkdir -p .agents/skills

   cp -r /path/to/llm-workflow/plugin/skills/code-review-response \
         .agents/skills/code-review-response
   cp -r /path/to/llm-workflow/plugin/skills/review-tests \
         .agents/skills/review-tests

Option C: Copy to Codex home
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Copy directly into the Codex skills directory:

.. code-block:: bash

   cp -r /path/to/llm-workflow/plugin/skills/code-review-response \
         ~/.codex/skills/code-review-response
   cp -r /path/to/llm-workflow/plugin/skills/review-tests \
         ~/.codex/skills/review-tests

Verifying Codex Installation
-----------------------------

Restart Codex after installing. The skills should appear when you invoke
them with the ``$`` prefix:

.. code-block:: text

   $code-review-response
   $review-tests

Codex also supports implicit triggering — describing a task that matches
the skill's description will activate it automatically.

Disabling a Codex Skill
------------------------

To disable a skill without removing it, add an entry to
``~/.codex/config.toml``:

.. code-block:: toml

   [[skills.config]]
   path = "/home/you/.agents/skills/review-tests/SKILL.md"
   enabled = false

Updating Codex Skills
---------------------

- **Symlink installs** update automatically when you ``git pull`` the
  repository.
- **Copied installs** must be re-copied after pulling updates.

Uninstalling Codex Skills
-------------------------

Remove the skill directory from whichever location you installed to:

.. code-block:: bash

   # User skills
   rm -rf ~/.agents/skills/code-review-response
   rm -rf ~/.agents/skills/review-tests

   # Or Codex home
   rm -rf ~/.codex/skills/code-review-response
   rm -rf ~/.codex/skills/review-tests

Then restart Codex.