# Geekbot Run

> >

- **Type:** Skill
- **Install:** `agentstack add skill-geekbot-com-geekbot-cli-geekbot-run`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [geekbot-com](https://agentstack.voostack.com/s/geekbot-com)
- **Installs:** 0
- **Category:** [Agent Skills](https://agentstack.voostack.com/c/agent-skills)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [geekbot-com](https://github.com/geekbot-com)
- **Source:** https://github.com/geekbot-com/geekbot-cli/tree/main/skills/geekbot-run

## Install

```sh
agentstack add skill-geekbot-com-geekbot-cli-geekbot-run
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# Geekbot — AI-Powered Standup & Poll Management

## Overview

This skill wraps the `geekbot` CLI to let users manage async team rituals
conversationally. It handles two broad workflows:

- **Manager workflows** — create standups/polls from templates, edit configs,
  manage members and schedules, analyse team engagement from report data
- **Reporter workflows** — draft standup reports with AI assistance, carry
  over unresolved blockers, calibrate tone from history, post reports

The CLI produces structured JSON output with machine-readable error codes,
making it reliable for agent-driven automation.

## Prerequisites

Before any operation, verify the CLI is available and authenticated.

Run `check-cli.sh` on first invocation. If it fails:

- **CLI not found**: Install via `npm install -g geekbot-cli` (requires
  Bun >= 1.3.5 runtime). Note: `npx geekbot-cli` also requires Bun on
  PATH — it is not a Node.js fallback.
- **Auth not configured**: Guide the user to run `geekbot auth login`,
  which uses the OAuth 2.1 authorization-code + PKCE flow with a
  `http://127.0.0.1:/callback` loopback redirect and writes the
  resulting `cli_*` token to the OS keychain. As a fallback they can use
  `geekbot auth setup --api-key ` with a dashboard API key, or set
  `GEEKBOT_API_KEY` as an environment variable.

Do not attempt any Geekbot operation until both checks pass.

## Asking the User

Some steps in this skill need to ask the user for input. Render each
question with whatever interaction primitive your harness provides —
the question content is identical either way.

- **`[PICKER]`** — a small fixed set of mutually-exclusive options
  (2–4). If your harness exposes a structured single-select question
  tool (e.g. Claude Code's `AskUserQuestion`, or any equivalent picker
  UI), use it. Otherwise present the same options as a numbered list
  in chat.
- **`[PICKER, top-N + Other]`** — same as `[PICKER]` but the candidate
  set may exceed 4 (e.g. "pick one of these 12 standups"). Pre-filter
  to the 3 most likely options and add an "Other" choice that lets the
  user name the rest in chat.
- **`[CONFIRM]`** — a yes/edit/cancel decision before a destructive or
  externally-visible action. Treat as `[PICKER]` with options
  *Approve / Edit / Cancel*.
- **`[CHAT]`** — open-ended question. Always ask in plain prose; a
  picker doesn't fit.

Tags appear inline in the workflow docs at the point where the
question is asked. Untagged "ask the user" prose is conversational by
default. Do not name `AskUserQuestion` (or any other tool) directly in
prompts to the user — pick the right primitive silently based on your
harness.

## How the CLI Works

The CLI follows a noun-verb pattern: `geekbot   [options]`.

Every command returns a JSON envelope on stdout:

```
Success: { "ok": true,  "data": ,  "error": null,  "metadata": {...} }
Error:   { "ok": false, "data": null,  "error": { "code", "message", "retryable", "suggestion" }, "metadata": {...} }
```

Always check the `ok` field first. On errors, the `error.suggestion` field
often contains the exact fix — including listing valid IDs when a resource
isn't found. Use this to self-correct without bothering the user.

For the full command reference with flags, defaults, and examples, read
`cli-commands.md`.

## Quick Reference

Most common operations at a glance:

| Task | Command |
|------|---------|
| List my standups | `geekbot standup list` (add `--state active`, `--is-anonymous true`, `--broadcast-channel `, or `--page-size ` to narrow results) |
| Get standup details + question IDs | `geekbot standup get ` |
| Create a standup | `geekbot standup create --channel "..." --questions '[...]' --users "U1,U2"` (or `--sync-channel "#ch"`; `--is-anonymous` optional) |
| List reports | `geekbot report list --standup-id  --limit 10` |
| Submit a report | `geekbot report create --standup-id  --answers '{"":"..."}'` |
| My profile + user ID | `geekbot me show` |
| Create a poll (Slack only) | `geekbot poll create --name "..." --channel "..." --question "..." --choices '[...]' [--duration 120]` |
| Search team members | `geekbot team search ` (matches username, realname, email) |
| Check auth | `geekbot auth status` |

For full flag details, see `cli-commands.md`.

## External Context Enrichment

The skill becomes dramatically more useful when it can pull data from where
work actually happens. This is **opportunistic** — check what MCP servers
are connected in the current session and use whatever is available. Never
fail or complain if nothing is connected; just fall back to asking the user.

**For report drafting:** Pull the user's recent activity from connected MCP
servers (GitHub, Jira, Calendar, Slack) and use it to pre-populate a draft.
The user reviews and approves instead of writing from scratch.

**For analytics:** Cross-reference standup report data with delivery data
to give richer insights — not just "who posted" but "what was actually shipped."

For entity mapping tables and deduplication strategy, see `reporter-workflows.md`.

**Important boundaries:**
- Always show the user what data you pulled and from where
- Never post a report containing enrichment data without user review
- If an MCP server query fails, skip it silently and move on
- Enrichment provides specifics (PR numbers, ticket IDs); the user's
  voice still drives the narrative

## Intent Routing

Pattern-match on the user's request to pick the right workflow. Don't ask
"are you a manager or a reporter?" — the request itself makes intent clear.
The same person can manage standups and submit reports in one conversation.

**Route to Manager Workflows (§ below) when you see:**
- Creation/config language: "create", "set up", "configure", "schedule"
- Analytics language: "how is my team doing", "engagement", "response rate",
  "who hasn't posted", "participation", "trends"
- Member summary language: "what has X been up to", "X's reports",
  "1-1 prep for X", "summarize X's work", "what did X report",
  "catch me up on X", "X's recent standups"
- Poll language: "create a poll", "voting results", "survey"

**Route to Reporter Workflows (§ below) when you see:**
- Drafting language: "help me write", "draft my report", "what should I say",
  "fill in my standup"
- Posting language: "post my answers", "submit my report"
- Context language: "what did I say last time", "carry over blockers",
  "my recent reports"
- Identity queries: "what standups am I in", "show my profile"

**When ambiguous**, ask one clarifying question — never more than one.
Use `[PICKER]` if the disambiguation is between 2–4 named options
(e.g. manager-vs-reporter intent split with a third "something else"
fallback), otherwise `[CHAT]`.

## Manager Workflows

For detailed multi-step guides, read `manager-workflows.md`.

### Creating a Standup

This is the most common and most complex manager operation.

**If the request is vague** ("set up a standup for my team"), offer templates.
Load `standup-templates.json` and present the 3–4 most relevant options
based on context. Templates provide pre-built questions and sensible schedule
defaults — the user just needs to confirm name, channel, and members.

**Gathering required fields (v2):**
- `--channel` — broadcast channel id or name (required)
- `--questions` — JSON array (required). Strings `["q1","q2"]` for free-text
  or `[{"text":"q1","choices":["A","B"]}]` for multiple-choice
- `--name` — optional. If the user gave a name, use it verbatim. Otherwise
  infer a meaningful name from the configured questions (use the template
  name when a template is in play). **Don't** rely on the API default
  `"Standup #"`.
- `--time` — defaults to `10:00`
- `--timezone` — infer from `geekbot me show` → `data.timezone` if not given
- `--days` — defaults to Mon–Fri
- **Members — always ask.** Pass `--users "U1,U2"` for an explicit list or
  `--sync-channel "#name"` to sync members from a channel. The two flags
  are mutually exclusive. The API does not auto-populate members when both
  are omitted — never call without member resolution.
- `--is-anonymous` — surface proactively for sensitive content (well-being,
  feedback, retro psychological safety) or templates with
  `is_anonymous_recommended: true`.

**Always confirm the full configuration with the user before executing.**
Show: name, channel, members (count + list or sync source), schedule,
timezone, anonymous flag, questions.

**Idempotency:** the CLI auto-generates a UUID `Idempotency-Key` per call
(24h API window). Re-running the command creates a new standup. On
ambiguous outcomes (timeout, partial response), list with
`geekbot standup list` before retrying.

**Note:** The CLI sets which days of the week to run but cannot set frequency
(bi-weekly, monthly). For non-weekly schedules, create the standup via CLI
and tell the user to adjust the frequency in the Geekbot web dashboard.

For the full step-by-step wizard (naming, channel resolution, member
resolution, anonymous-flag policy, edge cases), read `manager-workflows.md`
§ Standup Creation Wizard.

### Other Operations

- **Edit / Delete / Duplicate**: Not available in the CLI. Direct the user
  to the Geekbot web dashboard for these operations.
- **Trigger now**: `geekbot standup start ` — confirm before executing.
- **Polls** (Slack only): See `cli-commands.md` for poll commands.

### Analytics

Analytics come from report data fetched via the CLI. The skill computes
metrics; the CLI provides raw data. For the full analytics playbook with
6 named analysis patterns (response rate, participation gaps, blocker
frequency, trends, answer quality, cross-referencing), read
`manager-workflows.md`.

**Quick start:** Identify the standup with `standup list`, get member count
with `standup get `, fetch reports with
`report list --standup-id  --after  --limit 100`, then compute.

### Team Member Summary

Summarize what a specific person has been working on — ideal for 1-1 prep.
For the full step-by-step workflow, read `manager-workflows.md` §Team Member
Summary.

**Quick start:** `geekbot team search ` → get user ID →
`geekbot standup list` to enumerate standups → for each, fetch reports with
`geekbot report list --standup-id  --user-id  --after  --page-size 20` →
synthesize by work stream, not chronologically.

## Reporter Workflows

For the full drafting pipeline, tone calibration, blocker carry-over logic,
and edge cases, read `reporter-workflows.md`.

### Report Drafting Pipeline (Summary)

1. **Identify the standup** — `standup list`, auto-select if only one
2. **Fetch questions** — `standup get ` → extract question IDs and text
3. **Gather context** — from MCP servers (if connected), previous reports
   (for style calibration), and the user's direct input
4. **Draft answers** — match their historical tone/length, weave in specifics
   from MCP data, run blocker carry-over check on last 3–5 reports
5. **Review and post** — present draft, get explicit approval, then
   `report create --standup-id  --answers '{...}'`

**Never post a report without explicit user approval.**

### Quick Actions

One-shot commands that don't need the full pipeline:

- **"What standups am I in?"** → `geekbot standup list`
- **"Show my recent reports"** → `geekbot report list --user-id  --limit 5`
- **"Show my profile"** → `geekbot me show`
- **"What teams am I in?"** → `geekbot me teams`
- **"Trigger my standup now"** → confirm first, then `geekbot standup start `

## Confirmation Policy

All required confirmations are `[CONFIRM]` — render as a structured
picker (Approve / Edit / Cancel) when the harness supports it, or as
the same three options in chat.

| Operation | Confirmation required? | What to show |
|-----------|----------------------|--------------|
| CREATE standup/poll | `[CONFIRM]` | Full config: name, channel, questions, schedule |
| POST report | `[CONFIRM]` — always | Complete draft with all answers |
| TRIGGER standup | `[CONFIRM]` | Which standup, who it targets |
| List / Get / Analytics | No | Just execute and present results |
| Error recovery retries | No | Transparent to user |

## Error Handling

For the complete recovery guide, read `error-recovery.md`.

**Core pattern**: always parse the JSON envelope, check `ok`, branch on
exit code.

| Exit code | Meaning | Agent action |
|-----------|---------|--------------|
| 0 | Success | Proceed normally |
| 3 | Not found | Parse `error.suggestion` — it lists valid IDs. Offer them to the user. |
| 4 | Auth failed | Guide user through `geekbot auth login` (or `geekbot auth setup --api-key` as fallback). Do not retry. |
| 5 | Forbidden | Explain permission issue. The user may need admin access. |
| 6 | Validation | Show `error.message`, help the user fix the input. |
| 7 | Network | If `error.retryable` is true, retry once after 2s silently. If it fails again, report. |
| 8 | Conflict | Explain the conflict (e.g., duplicate name). Suggest resolution. |
| 9 | Schema validation (`schema_validation_error`) | API response didn't match expected format. Don't ask user to fix input — suggest updating CLI or reporting a bug. |
| 1, 2, 9 | General / usage / API | Report `error.message` to the user clearly. |

**Never retry** errors where `retryable` is false.

## Common Mistakes

- **Inventing report answers** — if the user didn't provide enough context
  for a question, ask. Never guess or fabricate.
- **Retrying auth errors** — exit code 4 is never transient. Guide the user
  to `geekbot auth login` (or `geekbot auth setup --api-key` as fallback)
  instead.
- **Dumping raw JSON** — format output as tables, summaries, or narratives.
  The user should never see a raw JSON envelope.
- **Ignoring `error.suggestion`** — when a resource isn't found (exit 3),
  the CLI already lists valid alternatives. Use them.
- **Asking "are you a manager or reporter?"** — the request itself reveals
  intent. Pattern-match, don't interrogate.

## Output Patterns

**CRUD confirmations** — brief, factual, include key identifiers:
> Created "Sprint Retro" standup (ID 789) in #engineering — Fridays at
> 15:00 Chicago time with 3 questions.

**Lists** — concise table: ID, name, channel, schedule. Don't dump raw JSON.

**Analytics** — narrative summary first, data table for details. Use
visualisation (chart/graph) when showing trends over time.

**Report drafts** — one question per block, clearly labelled with question
text and proposed answer. Easy to scan and approve.

**Errors** — plain language: what happened, why, what to do next. Always
use `error.suggestion` when available.

## Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [geekbot-com](https://github.com/geekbot-com)
- **Source:** [geekbot-com/geekbot-cli](https://github.com/geekbot-com/geekbot-cli)
- **License:** MIT

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-geekbot-com-geekbot-cli-geekbot-run
- Seller: https://agentstack.voostack.com/s/geekbot-com
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.