agent-toolkit-cli 1.11.0__py3-none-win_amd64.whl

agent_toolkit/data/skills/integrations/linear/SKILL.md

@@ -0,0 +1,134 @@
+---
+name: linear
+description: Manage Linear issues, projects and cycles via the Linear MCP server. Use when the user wants
+  to read, triage, create or update Linear tickets, plan a sprint, audit Linear documentation, or rebalance
+  team workload.
+origin:
+  type: first-party
+---
+# Linear
+
+Structured workflow for managing Linear issues, projects and cycles through the
+official Linear MCP server (`https://mcp.linear.app/mcp`, OAuth).
+
+This skill assumes the MCP is wired into your AI tool. See
+[`docs/MCP_TEMPLATES.md`](../../../../../../docs/MCP_TEMPLATES.md) and
+`~/.local/share/agent-toolkit/mcp/linear/` for the managed template.
+
+## When to use
+
+- "Open a Linear ticket for X", "triage open bugs", "plan the next cycle".
+- Sprint/cycle planning, retrospectives, documentation audits.
+- Cross-project dependency review or workload rebalancing.
+- Any natural-language request that maps onto Linear's MCP toolset.
+
+## Prerequisites
+
+1. Linear MCP server connected via OAuth in your AI tool of choice.
+2. Workspace access to the relevant teams and projects.
+3. agent-toolkit template available at `~/.local/share/agent-toolkit/mcp/linear/`
+   (deployed by `chezmoi apply`).
+
+## Setup (per AI tool)
+
+The Linear MCP is a **streamable HTTP** endpoint with OAuth. Register it in
+your AI tool of choice using the agent-toolkit template as reference:
+
+| AI tool | Where to register |
+|---------|-------------------|
+| Claude Code | `~/.claude/mcp.json` (or via `claude mcp add`) |
+| Cursor | `~/.cursor/mcp.json` |
+| OpenCode | `~/.config/opencode/mcp.json` |
+| Windsurf | `~/.codeium/windsurf/mcp_config.json` |
+
+Copy `~/.local/share/agent-toolkit/mcp/linear/config.template.json` into the right
+location and follow the OAuth prompt the first time you call a Linear tool.
+
+> Windows / WSL note: if direct connections fail on Windows, run the MCP through
+> WSL using `npx -y mcp-remote https://mcp.linear.app/sse --transport sse-only`
+> as the command. The template includes a comment block with this fallback.
+
+## Required workflow
+
+**Follow the steps in order. Do not skip read-before-write.**
+
+### Step 1 — Clarify scope
+
+Confirm with the user:
+
+- Team / project / cycle in scope.
+- Goal (triage, planning, audit, rebalance, release planning).
+- Filters that matter (priority, label, assignee, status).
+
+### Step 2 — Pick the workflow and tools
+
+Match the goal to a workflow (see "Practical workflows" below) and identify the
+Linear MCP tools you will call. Confirm required identifiers (`issueId`,
+`projectId`, `teamKey`) before invoking write actions.
+
+### Step 3 — Execute in logical batches
+
+1. **Read first** (`list_*`, `get_*`, `search_*`) to build context.
+2. **Then write** (`create_*`, `update_*`, `create_comment`) with all required fields.
+3. **For bulk operations**, explain the grouping logic before applying changes.
+
+### Step 4 — Summarize and propose next actions
+
+Surface remaining gaps, blockers, and follow-ups (extra issues, label changes,
+re-assignments, follow-up comments).
+
+## Available MCP tools
+
+- **Issues**: `list_issues`, `get_issue`, `create_issue`, `update_issue`,
+  `list_my_issues`, `list_issue_statuses`, `list_issue_labels`,
+  `create_issue_label`
+- **Projects & teams**: `list_projects`, `get_project`, `create_project`,
+  `update_project`, `list_teams`, `get_team`, `list_users`
+- **Docs & collaboration**: `list_documents`, `get_document`,
+  `search_documentation`, `list_comments`, `create_comment`, `list_cycles`
+
+## Practical workflows
+
+- **Sprint planning** — review open issues for a team, pick top items by
+  priority, create a new cycle with assignments.
+- **Bug triage** — list critical/high bugs, rank by user impact, move top items
+  to In Progress.
+- **Documentation audit** — search docs (e.g. API auth), open labeled
+  `documentation` issues for gaps with detailed fixes.
+- **Workload balance** — group active issues by assignee, flag overloads,
+  propose redistributions.
+- **Release planning** — create a project (e.g. `v2.0 Release`) with milestones
+  (feature freeze, beta, docs, launch) and generate issues with estimates.
+- **Cross-project dependencies** — find all `blocked` issues, identify blockers,
+  create linked issues if missing.
+- **Status sweeps** — find your stale issues and add status comments based on
+  current state/blockers.
+- **Smart labeling** — analyze unlabeled issues, suggest/apply labels, create
+  missing label categories.
+- **Retrospectives** — report on the last completed cycle (completed vs pushed)
+  and open discussion issues for recurring patterns.
+
+## Boundaries
+
+- All access is via the Linear MCP. **Do not** call the Linear REST/GraphQL API
+  directly from this skill — that bypasses the auditable OAuth path.
+- No bulk destructive actions without an explicit confirmation step from the user.
+- Respect Linear API rate limits — batch reads, paginate, cache filters.
+
+## Troubleshooting
+
+- **Auth**: clear browser cookies, re-run OAuth, verify workspace permissions
+  and that API access is enabled for your account.
+- **Tool errors**: confirm your AI tool supports parallel tool calls; supply all
+  required fields; split complex requests into smaller calls.
+- **Missing data**: refresh the OAuth token, verify workspace access, check for
+  archived projects, confirm correct team selection.
+- **Performance**: respect rate limits — batch bulk ops, use specific filters,
+  cache frequent queries.
+
+## Validation
+
+- `doctor` lists the Linear MCP template under `mcp/linear/` once
+  `chezmoi apply` has run.
+- The first MCP tool call triggers the OAuth flow; from then on the AI tool
+  caches the session.

agent_toolkit/data/skills/integrations/mcp/SKILL.md

@@ -0,0 +1,88 @@
+---
+name: mcp
+description: Configure and manage MCP providers for Agent Toolkit — setup, list, doctor, and per-tool
+  deployment.
+origin:
+  type: first-party
+metadata:
+  author: ulises-jeremias
+  version: '1.0'
+  tags:
+  - mcp
+  - integrations
+  - github
+  - slack
+  - context
+---
+# MCP
+
+Wire **Model Context Protocol** servers so agents can call external tools (GitHub, ClickUp, Slack, etc.) natively. This skill wraps `agent-toolkit mcp` and the MCP definitions in `mcp/` and `~/.local/share/agent-toolkit/mcp/`.
+
+## When to use
+
+- User asks "setup MCP", "connect GitHub/ClickUp/Slack", or an agent fails with MCP not configured.
+- After `agent-toolkit install` — MCP needs auth beyond file copy.
+- `agent-toolkit doctor` reports MCP integration missing.
+
+## Prerequisites
+
+- `agent-toolkit` installed; `mcp/` definitions exist in the repo or `~/.local/share/agent-toolkit/mcp/`.
+- Auth for each provider: `gh auth login` (GitHub), `clickup auth login` (ClickUp), etc. Keys in `~/.config/agent-toolkit/` or env.
+- Target tool supports MCP (Claude Code, Cursor, OpenCode — see `mcp/README.md` and `docs/MCP.md`).
+
+## Workflow
+
+### 1. Discover available providers
+
+```bash
+agent-toolkit mcp list
+agent-toolkit mcp doctor
+cat mcp/README.md
+cat docs/MCP.md
+ls mcp/
+ls ~/.local/share/agent-toolkit/mcp/ 2>&1 | head
+```
+
+### 2. Setup a provider
+
+```bash
+agent-toolkit mcp setup --provider github
+agent-toolkit mcp setup --provider clickup
+# Or target a specific tool:
+agent-toolkit plugin sync --tools claude-code  # also syncs MCP for that tool
+```
+
+For manual config, copy from `distributions/` or `mcp/` templates to `~/.config/<tool>/mcp.json` per `docs/MCP.md` — prefer the CLI.
+
+### 3. Verify and use
+
+```bash
+agent-toolkit mcp doctor
+agent-toolkit doctor  # check Integrations section
+# In agent: try a tool call that needs MCP, e.g., gh pr view or clickup task list
+```
+
+If `doctor` flags missing auth, run `gh auth status` / `clickup auth status` and re-setup.
+
+### 4. Deploy with profiles
+
+`agent-toolkit install` copies MCP templates; `mcp setup` authenticates them. For per-project MCP (e.g., Copilot):
+
+```bash
+agent-toolkit install --tools copilot --dry-run  # shows would-copy for Copilot MCP
+```
+
+## Boundaries
+
+- Never commit secrets — MCP auth lives in `~/.config/agent-toolkit/` or `~/.config/<provider>/`, not the repo. Use `.env.example` for templates.
+- Do not hand-edit tool MCP JSON when `mcp setup` can do it — it handles path and env correctly.
+- For swarms: MCP is per-runner, not per-run. Ensure the host's MCP is configured before `swarm start`.
+
+## Delegates to
+
+| Need | Skill |
+|------|-------|
+| Repo discovery before MCP wiring | `assistant` |
+| Swarm that needs MCP tools | `swarm` |
+| GitHub PR after swarm | `github-cli-workflow` |
+| ClickUp/Slack tasks | `clickup-cli`, `slack-cli`, `linear` |

agent_toolkit/data/skills/integrations/slack-assistant/SKILL.md

@@ -0,0 +1,138 @@
+---
+name: slack-assistant
+description: Interact with Slack workspaces for reading channels/messages, sending messages, adding reactions,
+  and browsing canvases. Use when the user asks about Slack channels, messages, or notifications — NOT
+  for Slack app development (use the slack-cli skill for that).
+origin:
+  type: first-party
+metadata:
+  author: ulises-jeremias
+  version: '1.0'
+compatibility: Requires slackcli (shaharia-lab) — install via run_onchange_45 script. Authenticate with
+  `slackcli auth login` before first use.
+---
+# Slack Assistant (`slackcli`)
+
+Use the `slackcli` CLI (from [shaharia-lab/slackcli](https://github.com/shaharia-lab/slackcli))
+for Slack **workspace automation**: reading messages, sending messages, reactions, and canvases.
+
+> **Important:** This is NOT the official Slack Developer CLI (`slack`/`slack-dev`).
+> Use the `slack-cli` skill for Slack app development workflows.
+
+## Default Workspaces
+
+| Context | Workspace |
+|---|---|
+| | `` (.slack.com) |
+
+Use `--workspace=<name-or-id>` to target a specific workspace.
+Without `--workspace`, the default workspace set via `slackcli auth set-default` is used.
+
+## When to Use
+
+- User asks "what's in #channel-name" or "check the Slack channel"
+- User wants to send a message or reply to a thread
+- User asks about Slack canvases
+- User wants to add a reaction to a message
+- Workspace is .slack.com (or whichever workspace the user indicates)
+
+## Authentication
+
+```bash
+# List authenticated workspaces
+slackcli auth list
+
+# Login with a bot/user token (run once per workspace)
+slackcli auth login --token=<your-bot-token> --workspace-name="My Team"
+
+# Login with browser session tokens (no Slack app needed)
+slackcli auth parse-curl --login    # paste cURL from browser DevTools
+
+# Set default workspace
+slackcli auth set-default T1234567  # use workspace ID from auth list
+```
+
+Configuration is stored in `~/.config/slackcli/workspaces.json`.
+
+## Conversation Commands
+
+```bash
+# List all channels in the default workspace
+slackcli conversations list
+
+# List channels in a specific workspace
+slackcli conversations list --workspace=
+
+# Filter by type
+slackcli conversations list --types=public_channel
+slackcli conversations list --types=im
+
+# Read recent messages from a channel
+slackcli conversations read C1234567890
+
+# Read a specific thread
+slackcli conversations read C1234567890 --thread-ts=1234567890.123456
+
+# Read with limit and JSON output (includes ts/thread_ts for replies)
+slackcli conversations read C1234567890 --limit=50 --json
+```
+
+## Message Commands
+
+```bash
+# Send a message to a channel
+slackcli messages send --recipient-id=C1234567890 --message="Hello team!"
+
+# Send a DM to a user
+slackcli messages send --recipient-id=U9876543210 --message="Hey there!"
+
+# Reply to a thread
+slackcli messages send --recipient-id=C1234567890 \
+  --thread-ts=1234567890.123456 --message="Great idea!"
+
+# Add an emoji reaction to a message
+slackcli messages react --channel-id=C1234567890 \
+  --timestamp=1234567890.123456 --emoji=+1
+```
+
+Common emojis: `+1`, `heart`, `fire`, `eyes`, `tada`, `rocket`, `white_check_mark`
+
+## Canvas Commands
+
+```bash
+# List canvases in the workspace
+slackcli canvas list
+slackcli canvas list --channel=C1234567890
+
+# Read canvas content as markdown
+slackcli canvas read F1234567890
+
+# Read canvas in JSON format
+slackcli canvas read F1234567890 --json
+```
+
+## Multi-Workspace Usage
+
+```bash
+# Use workspace explicitly
+slackcli conversations list --workspace=
+
+slackcli conversations list
+
+# Use workspace by Slack team ID
+slackcli conversations list --workspace=T1234567
+```
+
+## Workflow for Reading a Channel
+
+1. Find the channel ID: `slackcli conversations list --workspace=| grep <name>`
+2. Read recent messages: `slackcli conversations read <channel-id> --limit=20`
+3. For threaded replies: use `--thread-ts=<ts>` from the message timestamp
+
+## Notes
+
+- Channel IDs start with `C`, user IDs start with `U`, team IDs start with `T`
+- Timestamps in Slack are Unix epoch with microseconds (e.g., `1234567890.123456`)
+- Use `--json` for programmatic processing; plain output is human-readable
+- Browser session tokens expire with the browser session — prefer bot tokens for automation
+- Run `slackcli update` to update to the latest release

agent_toolkit/data/skills/integrations/slack-cli/SKILL.md

@@ -0,0 +1,109 @@
+---
+name: slack-cli
+description: Interact with the official Slack CLI to create, run, deploy, and manage Slack apps, environments,
+  manifests, and triggers. Use when the user asks about Slack app development workflows, not workspace
+  chat automation.
+origin:
+  type: first-party
+metadata:
+  author: ulises-jeremias
+  version: '1.0'
+compatibility: Requires official Slack CLI from docs.slack.dev (not rockymadden/slack-cli), plus curl
+  and jq. See references/INSTALLATION.md.
+---
+# Slack CLI (Official Slack Developer CLI)
+
+Use the official Slack Developer CLI documented at `docs.slack.dev/tools/slack-cli/`.
+
+This CLI is for Slack **app development and platform management**.
+It is **not** the community chat automation CLI (`slack chat send`, etc.).
+
+## When to Use
+
+- Create or initialize a Slack app project
+- Log in/out and manage authorized teams for app development
+- Run and deploy Slack apps
+- Manage manifests, env vars, functions, and triggers
+- Run diagnostics with `slack doctor`
+
+## Setup
+
+If `slack` is not found, or `slack --help` does not mention app development, see [references/INSTALLATION.md](references/INSTALLATION.md).
+
+Some machines already have another `slack` binary (e.g., Slack desktop). In that case, the official CLI can be installed as `slack-dev`.
+
+Use this detection pattern first:
+
+```bash
+if slack --help 2>/dev/null | grep -q "create, run, and deploy Slack apps"; then
+  SLACK_CMD=slack
+elif slack-dev --help 2>/dev/null | grep -q "create, run, and deploy Slack apps"; then
+  SLACK_CMD=slack-dev
+else
+  echo "Official Slack CLI not found"
+fi
+```
+
+Authorize after install:
+
+```bash
+"$SLACK_CMD" login
+"$SLACK_CMD" list
+```
+
+## Core Commands
+
+```bash
+"$SLACK_CMD" version
+"$SLACK_CMD" doctor
+"$SLACK_CMD" login
+"$SLACK_CMD" logout
+"$SLACK_CMD" list
+```
+
+## Project Lifecycle
+
+```bash
+# Create a new project
+"$SLACK_CMD" create
+
+# Initialize an existing project directory
+"$SLACK_CMD" init
+
+# Run app locally
+"$SLACK_CMD" run
+
+# Deploy app
+"$SLACK_CMD" deploy
+```
+
+## App and Platform Management
+
+```bash
+"$SLACK_CMD" manifest info
+"$SLACK_CMD" manifest validate
+"$SLACK_CMD" env list
+"$SLACK_CMD" env add
+"$SLACK_CMD" trigger list
+"$SLACK_CMD" trigger create
+"$SLACK_CMD" trigger access list
+"$SLACK_CMD" activity
+"$SLACK_CMD" app list
+"$SLACK_CMD" app install
+"$SLACK_CMD" app uninstall
+```
+
+## Recommended Workflow
+
+1. `"$SLACK_CMD" login`
+2. `"$SLACK_CMD" create` or `"$SLACK_CMD" init`
+3. `"$SLACK_CMD" doctor`
+4. `"$SLACK_CMD" run`
+5. `"$SLACK_CMD" deploy`
+6. `"$SLACK_CMD" trigger list` and validate trigger behavior
+
+## Notes
+
+- Prefer official docs and command reference for exact flags.
+- Use `"$SLACK_CMD" <command> --help` before running destructive operations.
+- Never use this skill for workspace chat automation (`chat.send`, `conversations.history`, reminders, etc. via community CLI patterns).

agent_toolkit/data/skills/integrations/slack-cli/references/INSTALLATION.md

@@ -0,0 +1,42 @@
+# Official Slack CLI Installation
+
+Reference: <https://docs.slack.dev/tools/slack-cli/guides/installing-the-slack-cli-for-mac-and-linux>
+
+## Install (macOS/Linux)
+
+```bash
+curl -fsSL https://downloads.slack-edge.com/slack-cli/install.sh | bash
+```
+
+## If another `slack` binary already exists
+
+Install with an alias:
+
+```bash
+curl -fsSL https://downloads.slack-edge.com/slack-cli/install.sh | bash -s -- slack-dev
+```
+
+Then use `slack-dev` in commands.
+
+## Verify
+
+```bash
+slack version
+slack --help
+```
+
+`slack --help` should describe the CLI as:
+
+`CLI to create, run, and deploy Slack apps`
+
+## Authorize
+
+```bash
+slack login
+slack list
+```
+
+## Important
+
+This official CLI is for Slack app development and platform operations.
+It is different from community chat-focused CLIs (e.g., `slack chat send` style commands).

agent_toolkit/data/skills/loops/loop-runner/SKILL.md

@@ -0,0 +1,92 @@
+---
+name: loop-runner
+description: Execute and manage loop engineering primitives (init, run, status, audit) from an AI coding
+  session via bin/loop CLI.
+origin:
+  type: first-party
+metadata:
+  author: ulises-jeremias
+  version: '1.0'
+---
+# loop-runner
+
+> Execute and manage loop engineering primitives from an AI coding session.
+
+---
+
+## What this skill does
+
+This skill wraps the `bin/loop` CLI from
+[ai-workspace](https://github.com/ulises-jeremias/ai-workspace), exposing loop
+operations to AI coding agents without requiring the user to remember CLI flags.
+
+**Loop engineering** is the practice of designing recursive, autonomous processes
+that prompt AI agents — as opposed to prompting agents directly. Loops have
+durable state (`STATE.md`), safety gates (allowlist/deny), cost budgets, and
+rollout tiers (L1 report-only → L2 PR-gated → L3 unattended).
+
+## Capabilities
+
+| Subcommand | When to use |
+|-----------|-------------|
+| `loop init <pattern>` | Scaffold a new loop from a starter |
+| `loop run <loop>` | Execute one loop iteration |
+| `loop status` | Show all loops: tier, cadence, last run |
+| `loop audit [loop]` | Summarize past run success/cost |
+| `loop cost <loop>` | Estimate per-run token cost |
+| `loop sync` | Push escalations to knowledge/todos |
+
+## How to invoke
+
+```bash
+# Check if ai-workspace loop CLI is available
+loop status
+
+# Or invoke directly
+~/.ai-workspace/bin/loop status
+```
+
+## Routing
+
+1. Check if `~/.ai-workspace/bin/loop` exists → use it
+2. Otherwise check `AI_WORKSPACE_LOOP_BIN` env var
+3. Otherwise: guide the user to install ai-workspace
+
+## Runner hierarchy (inside bin/loop)
+
+When `./bin/loop run` dispatches a loop, it tries runners in this order:
+
+| Priority | Runner | How to enable |
+|----------|--------|---------------|
+| 1 | **runner** | `export HARNESS_RUNNER_DIR="$HOME/.local/share//dev-companion/runner"` |
+| 2 | **`claude --print`** (Claude Code CLI) | `claude` in PATH — zero setup for Claude Code users |
+| 3 | Skeleton plan | Always available |
+
+For full multi-provider support (Anthropic, OpenAI, Ollama, OpenCode), set
+`HARNESS_RUNNER_DIR` to point at the runner. Claude Code
+users can skip this — `claude --print` is used automatically.
+
+## References
+
+- [agentic-harness loop docs](https://github.com/ulises-jeremias/agentic-harness/blob/main/docs/LOOPS.md)
+- [Loop engineering patterns](https://github.com/cobusgreyling/loop-engineering)
+- [docs/LOOPS.md](../../../docs/LOOPS.md) — full reference
+
+---
+
+## Rules
+
+1. **Always start at L1** for new loops. Only graduate to L2/L3 after reviewing
+   at least 3 consecutive clean L1 runs.
+
+2. **Budget awareness** — report the estimated cost before running an expensive
+   loop (pr-babysitter, ci-sweeper). Confirm with the user.
+
+3. **Allowlist enforcement** — never take an action not in the loop's
+   `allowlist`. If uncertain: escalate (`human_escalation` exit condition).
+
+4. **Worktree hygiene** — loops create isolated git worktrees. Clean them up
+   on success; preserve on failure for postmortem.
+
+5. **Escalation first** — when in doubt, choose `human_escalation` over
+   guessing. The user can always re-run.