agent-toolkit-cli 1.0.3__py3-none-any.whl

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

@@ -0,0 +1,134 @@
+---
+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).
+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_cli-1.0.3.data/data/agent_toolkit/data/skills/integrations/slack-cli/SKILL.md

@@ -0,0 +1,105 @@
+---
+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.
+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_cli-1.0.3.data/data/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_cli-1.0.3.data/data/agent_toolkit/data/skills/loops/loop-runner/SKILL.md

@@ -0,0 +1,90 @@
+---
+name: loop-runner
+description: Execute and manage loop engineering primitives (init, run, status, audit) from an AI coding session via bin/loop CLI.
+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.

agent_toolkit_cli-1.0.3.data/data/agent_toolkit/data/skills/ops/docs-generator/SKILL.md

@@ -0,0 +1,81 @@
+---
+name: docs-generator
+description: >-
+  WHAT — Generate or update documentation from code: README.md from repo structure,
+  CHANGELOG.md from git history, API reference from OpenAPI/GraphQL schemas,
+  and AGENTS.md starters for new projects.
+metadata:
+  author: ulises-jeremias
+  version: "1.0"
+  tags: [docs, readme, changelog, api-reference, agents]
+---
+
+# Docs Generator (WHAT)
+
+Generate or refresh documentation from the actual code, schema, and git history.
+Never invent — always derive from evidence in the repo.
+
+## When to use
+
+- README is missing, stale, or doesn't reflect the current stack
+- CHANGELOG needs to be generated from merged PRs or git log
+- API spec (OpenAPI/GraphQL) exists but human-readable docs don't
+- New repo needs an AGENTS.md to onboard AI assistants
+
+## Out of scope
+
+- Does NOT write code — documentation only
+- Does NOT commit or push — delegate to **`github-cli-workflow`**
+- Does NOT update external systems (Confluence, Notion) — use their respective skills
+
+## Workflow
+
+### README.md generation
+
+1. Inspect repo: `package.json` / `pyproject.toml` / `Cargo.toml` for name, description, stack
+2. Read `Makefile` / `justfile` / `package.json scripts` for commands
+3. Read `.github/workflows/` for CI structure
+4. Draft README with: Purpose, Stack, Prerequisites, Quick Start, Development, Testing, Contributing
+5. Apply **`output-handshake`** before writing
+
+### CHANGELOG.md generation
+
+```bash
+# Conventional commits format
+git log --oneline --no-merges --pretty="format:%h %s" $(git describe --tags --abbrev=0)..HEAD
+
+# Group by type: feat / fix / docs / chore / refactor / perf / test
+# Format: ## [Unreleased] with subsections per type
+```
+
+Draft changelog section and ask user to confirm version before finalizing.
+
+### API reference generation
+
+- OpenAPI spec → readable endpoint table with params, responses, auth
+- GraphQL schema → type reference with fields and descriptions
+- Always note the spec version and date in the generated doc
+
+### AGENTS.md starter
+
+Use the template from `~/.local/share//skills-catalog.yaml` patterns:
+
+- Purpose and stack
+- Repository inspection order
+- What AI assistants may and must not do
+- Key commands (build, test, lint)
+- Links to key docs
+
+## Anti-patterns
+
+- Do not guess stack or commands — read from actual config files
+- Do not generate CHANGELOG from unstaged changes
+- Do not overwrite existing README without showing diff first
+
+## Delegates to
+
+| Need | Skill |
+|------|-------|
+| Push and create PR with generated docs | **`github-cli-workflow`** |
+| Confirm output destination | **`output-handshake`** |
+| Repo discovery | **`assistant`** |

agent_toolkit_cli-1.0.3.data/data/agent_toolkit/data/skills/ops/llm-cost-advisor/SKILL.md

@@ -0,0 +1,83 @@
+---
+name: llm-cost-advisor
+description: >-
+  WHAT — Recommend the most cost-effective LLM provider for a given task type.
+  Shows estimated cost per run across available providers and integrates with
+  devcompanion llm-status to show what is actually available.
+metadata:
+  author: ulises-jeremias
+  version: "1.0"
+  tags: [llm, cost, provider, optimization]
+---
+
+# LLM Cost Advisor (WHAT)
+
+Recommend the right provider for the task at hand — balancing quality, cost, and privacy.
+
+## When to use
+
+- User asks "which model should I use for X?"
+- Before scheduling expensive loops (pr-babysitter, ci-sweeper)
+- When dev-companion jobs are unexpectedly expensive
+- When choosing between local and cloud providers for sensitive work
+
+## Out of scope
+
+- Does NOT configure providers — that's done via env vars and `loadenv`
+- Does NOT run LLM calls — it advises, the runner executes
+
+## Workflow
+
+**Step 1 — Check available providers:**
+
+```bash
+devcompanion llm-status
+```
+
+**Step 2 — Classify the task:**
+
+| Task type | Recommended tier | Why |
+|-----------|-----------------|-----|
+| Interactive code review, planning, debugging | Claude Sonnet / GPT-4o | Reasoning quality matters |
+| Batch labeling, summarization, triage | Claude Haiku / GPT-4o-mini | High volume, lower stakes |
+| Private/sensitive codebase work | Ollama or OpenCode | Stays local, zero cost |
+| Loop L1 (observation only) | Haiku / GPT-4o-mini | Low stakes, runs daily |
+| Loop L2 (PR creation) | Sonnet | Creates external artifacts |
+| Loop L3 (unattended) | Sonnet + verifier | Autonomous — quality critical |
+
+**Step 3 — Show cost estimate:**
+
+| Provider | Model | Est. per run | Monthly (1/day) | Monthly (96/day) |
+|----------|-------|-------------|-----------------|-----------------|
+| Anthropic | claude-3-5-sonnet | ~$0.05 | ~$1.50 | ~$144 |
+| Anthropic | claude-3-haiku | ~$0.005 | ~$0.15 | ~$14.40 |
+| OpenAI | gpt-4o | ~$0.04 | ~$1.20 | ~$115 |
+| OpenAI | gpt-4o-mini | ~$0.003 | ~$0.09 | ~$8.64 |
+| Ollama | (local) | $0 | $0 | $0 |
+| OpenCode | (local) | $0 | $0 | $0 |
+
+*Estimates based on ~2K input + ~1K output tokens per typical run.*
+
+**Step 4 — Recommend with reasoning:**
+
+Give a clear recommendation: "For daily CNA issue triage (L1, observation only), use
+claude-3-haiku — ~$0.15/month vs $1.50/month for Sonnet, with no quality difference
+for labeling and summarization tasks."
+
+## Budget gate reminder
+
+If the user is setting up loops, remind them to add `limits.max_cost_usd` to their job
+definitions to enable the runner's hard budget enforcement:
+
+```json
+"limits": {
+  "timeout_sec": 300,
+  "max_cost_usd": 0.50
+}
+```
+
+## Anti-patterns
+
+- Do not recommend cloud providers for repos marked confidential — suggest Ollama/OpenCode
+- Do not recommend Haiku for L3 unattended loops — quality failures cascade
+- Do not skip the `llm-status` check — recommend only available providers

agent_toolkit_cli-1.0.3.data/data/agent_toolkit/data/skills/ops/triage/SKILL.md

@@ -0,0 +1,117 @@
+---
+name: triage
+description: Workstation health triage — validate tooling, directory layout, and run doctor with remediation suggestions.
+metadata:
+  author: ulises-jeremias
+  version: "1.1"
+---
+
+# Workstation Triage ()
+
+Use when the user reports workstation issues, install problems, tool failures, or needs a health check before starting work.
+
+## Prerequisites
+
+Run this skill on the **local workstation** where the user is experiencing issues. Do not run it on a remote server unless the user confirms the remote has the setup.
+
+Verify `doctor` is installed:
+
+```bash
+command -v doctor
+```
+
+If missing, install via chezmoi (`chezmoi apply`) or direct installation.
+
+## Output modes
+
+Use the mode that matches the user's need:
+
+| Mode | Command | When to use |
+|------|---------|-------------|
+| **Colored** (default) | `doctor` | Interactive terminal session — human-readable colored output |
+| **Markdown** | `doctor --issue` | GitHub issues, Slack threads, tickets — paste-ready block |
+| **JSON** | `doctor --json` | Automation scripts, CI parsing — single-line machine-readable |
+
+### Markdown output (`--issue`)
+
+Always use `doctor --issue` (not the default) when the output will be shared in:
+- GitHub issues or PR comments
+- Slack messages
+- Support tickets
+- Any written async communication
+
+### JSON output (`--json`)
+
+Use `doctor --json` only when:
+- A script or automation pipeline needs to parse the result
+- You need a single-line summary for programmatic handling
+- Requires `python3` in PATH
+
+## Profile and check groups
+
+The doctor's behavior is controlled by `~/.config//profile.env`. Checks can be selectively enabled/disabled via environment variables:
+
+| Variable | Default | Effect |
+|----------|---------|--------|
+| `DOTS_WORKSTATION_DOCTOR_GROUP_CORE` | `true` | Core tools: `git`, `curl`, `wget`, `jq`, `rg`, `fd`, `zsh`, `gh` |
+| `DOTS_WORKSTATION_DOCTOR_GROUP_NODE` | `true` | Node.js: `fnm`, `node` |
+| `DOTS_WORKSTATION_DOCTOR_GROUP_PYTHON` | `true` | Python: `uv`, `python3` |
+| `DOTS_WORKSTATION_DOCTOR_GROUP_DOCKER` | `true` | Docker: `docker` |
+| `DOTS_WORKSTATION_DOCTOR_GROUP_AI` | `true` | LLM API key presence flags (ANTHROPIC_API_KEY, OPENAI_API_KEY, GEMINI_API_KEY) |
+| `DOTS_WORKSTATION_DOCTOR_GROUP_SKILLS_PRODUCTIVITY` | `false` | Optional productivity tool group |
+| `DOTS_WORKSTATION_DOCTOR_SKILL_JIRA` | `false` | JIRA skill integration check |
+| `DOTS_WORKSTATION_DOCTOR_SKILL_CONFLUENCE` | `false` | Confluence skill integration check |
+
+> **Note:** Profile variables are read from `~/.config//profile.env`. If the file is missing, defaults apply.
+
+## Directory checks
+
+The doctor validates the presence and structure of:
+- `~/.local/share//prompts`
+- `~/.local/share//skills`
+- `~/.local/share//templates`
+- `~/.local/share//mcp/github`
+- `~/.local/share//mcp/clickup`
+- `~/.local/share//mcp/notion`
+- `~/.local/share//mcp/slack`
+
+## Remediation guidance
+
+Propose fixes in order of lowest risk first:
+
+1. **Missing directories** → run `chezmoi apply` to bootstrap the full installation
+2. **Missing commands** → use the respective skill's installation instructions (e.g., `uv` via `curl -LsSf https://astral.sh/uv/install.sh`)
+3. **Auth failures** → run `gh auth login`, `clickup auth login`, or `glab auth login` as appropriate
+4. **Profile/group mismatches** → edit `~/.config//profile.env` and run `chezmoi apply`
+5. **API key missing** → guide user to set the appropriate env var in their shell profile
+
+## Common issues
+
+### doctor exits 1 (NON-COMPLIANT)
+
+Run with `--issue` to get the full markdown checklist. Address failures in this order:
+1. Install any missing core commands
+2. Run `chezmoi apply` to restore directory structure
+3. Re-authenticate CLIs (`gh`, `clickup`, `glab`)
+4. Verify `~/.config//profile.env` matches the intended profile
+
+### doctor --json requires python3
+
+If `python3` is not available, fall back to `doctor --issue` and parse the markdown manually.
+
+### doctor: Missing dependency: easyoptions.sh
+
+The `easyoptions.sh` library is missing from `~/.local/lib/`. Re-run `chezmoi apply` to restore it, or check if the installation is incomplete.
+
+## Skill boundaries
+
+- This skill **does not fix issues automatically** — it diagnoses and proposes remediation steps.
+- This skill **does not modify** `profile.env` or authentication state — user must approve and execute fixes.
+- For **chezmoi-managed configuration issues**, pair with the **`dev-companion`** or direct chezmoi guidance.
+- For **CI/build failures** on a project repo, use **`build-error-resolver`** instead of this skill.
+
+## References
+
+- `doctor --help` — full option list
+- `~/.config//profile.env` — check group configuration
+- `~/.local/lib//easy-options/easyoptions.sh` — dependency library