diff --git a/.agents/skills/setup/SKILL.md b/.agents/skills/setup/SKILL.md new file mode 100644 index 0000000..9d19ff2 --- /dev/null +++ b/.agents/skills/setup/SKILL.md @@ -0,0 +1,166 @@ +--- +name: setup +description: | + Sets up poc-bot end to end: clone (or reuse an existing clone of) the repo, create + `.env` from `.env.example`, interactively collect HubSpot/Metabase/Slack credentials, + discover pipeline/dashboard/parameter IDs via each service's API, load the environment, + and run read-only verification checks against every service. Use this skill whenever the + user asks to "run the setup skill", set up, install, configure, bootstrap, or deploy + poc-bot (or this repo), and also when a pipeline skill fails because of missing or + invalid environment variables. +--- + +# poc-bot Setup Skill + +Goal: finish with a cloned repo, a filled-in `.env`, and verified read-only access to +HubSpot, Metabase, and Slack — so the `poc-analysis` and `poc-not-customer-usage` skills +work on the next run. + +**Security rules for this entire skill:** +- Never echo, print, or log token values. Reference them only as `$VAR` after they are in + the environment, and let the user paste secrets directly into `.env` themselves whenever + possible. +- Never commit `.env` (it is gitignored — keep it that way). + +## Step 0: Locate or clone the repo + +Check whether you are already inside a poc-agent-oss checkout (the directory containing +`.agents/skills/poc-analysis/SKILL.md` and `.env.example`). Search the current directory +and its parents. If found, `cd` to the repo root and continue. + +If not found, clone it and enter it: + +```bash +git clone https://github.com/warpdotdev/poc-agent-oss.git +cd poc-agent-oss +``` + +Also confirm `python3 --version` is 3.8+. There are no other dependencies — every script +uses the Python standard library only. + +## Step 1: Create .env + +```bash +[ -f .env ] || cp .env.example .env +``` + +An existing `.env` is never overwritten (and unlike `cp -n`, this exits 0 on all +platforms when the file already exists). If `.env` already exists, read it and only work +on the required values that are still blank or still hold `.env.example` placeholders +(e.g. `https://metabase.example.com`) — this makes the skill safe to re-run to finish a +partial setup. + +When writing values, quote anything containing spaces (`LABEL="two words"`) — unquoted +spaces break the `source .env` load step. + +## Step 2: Determine scope and collect values + +Ask the user which skill(s) they plan to run — this decides which variables are required: + +- **Both skills**: `HUBSPOT_ACCESS_TOKEN`, `METABASE_BASE_URL`, `METABASE_API_KEY`, + `METABASE_DASHBOARD_ID`, `METABASE_PARAM_DATE_RANGE_ID`, `METABASE_PARAM_TEAM_ID_ID`, + `POC_BOT_SLACK_TOKEN`, `SLACK_CHANNEL` +- **poc-analysis only**: add `HUBSPOT_POC_PIPELINE_ID`, `HUBSPOT_POC_STAGE_ID` +- **poc-not-customer-usage only**: add `METABASE_DB_ID`, + `METABASE_PRIMARY_METRIC_DASHCARD_ID`, `METABASE_PRIMARY_METRIC_CARD_ID` + +`.env.example` is fully annotated (required vs. optional, and which skill uses what) — +treat it as the source of truth for every variable and its default. + +Ask the user for the credentials first (HubSpot private app token, Metabase URL + API +key, Slack bot token with `chat:write`). Have them edit `.env` directly for the secrets. +The IDs can then be discovered for them in Step 3. + +## Step 3: Discover the IDs + +First load the credentials into the environment — run Step 4's `source` command now, and +again after any later `.env` edit. Then you can look up every ID the user doesn't know, +instead of making them hunt through UIs. Use read-only GET requests and never print the +tokens: + +**HubSpot pipeline + stage IDs** (`poc-analysis`): + +```bash +curl -s "https://api.hubapi.com/crm/v3/pipelines/deals" \ + -H "Authorization: Bearer $HUBSPOT_ACCESS_TOKEN" +``` + +Present the pipelines and their stages by label; let the user pick the POC pipeline and +the "Pilot Kicked Off" (or equivalent) stage. + +**Metabase dashboard parameter, dashcard, and card IDs** (both skills): + +```bash +curl -s "$METABASE_BASE_URL/api/dashboard/$METABASE_DASHBOARD_ID" \ + -H "x-api-key: $METABASE_API_KEY" +``` + +- `parameters[]` → the `id` of the date-range parameter (`METABASE_PARAM_DATE_RANGE_ID`) + and the team-id parameter (`METABASE_PARAM_TEAM_ID_ID`) +- `dashcards[]` → each tile's `id` (dashcard_id) and `card_id`; for + `poc-not-customer-usage`, ask which tile is the primary metric and set + `METABASE_PRIMARY_METRIC_DASHCARD_ID` / `METABASE_PRIMARY_METRIC_CARD_ID` + +**Metabase database ID** (`poc-not-customer-usage`): + +```bash +curl -s "$METABASE_BASE_URL/api/database" -H "x-api-key: $METABASE_API_KEY" +``` + +The dashboard ID itself is visible in the dashboard URL: +`https://metabase.example.com/dashboard/-...`. + +Write each confirmed ID into `.env` (IDs are not secrets, so editing them in is fine). + +## Step 4: Load the environment + +The scripts read from the process environment — there is **no dotenv auto-loader**: + +```bash +set -a && source .env && set +a +``` + +Re-run this after every `.env` edit. Remind the user they will need it in any new shell. + +## Step 5: Verify (read-only) + +Run these checks; none of them write or post anything: + +1. **HubSpot**: the pipelines request from Step 3 returns HTTP 200 and, for + `poc-analysis`, contains the chosen `HUBSPOT_POC_PIPELINE_ID` / `HUBSPOT_POC_STAGE_ID`. +2. **Metabase**: the dashboard request from Step 3 returns HTTP 200 and its `parameters` + array contains both configured parameter IDs. +3. **Slack**: + ```bash + curl -s https://slack.com/api/auth.test -H "Authorization: Bearer $POC_BOT_SLACK_TOKEN" + ``` + Expect `"ok": true`. Note that `auth.test` does not prove channel access — remind the + user to `/invite` the bot to `$SLACK_CHANNEL` (default `#poc-bot`) or posting will fail + with `not_in_channel`. + +If a check fails, show the error (never the token), help fix the value in `.env`, reload +(Step 4), and re-check. + +## Step 6: Deployment-specific configuration + +The repo ships with generic labels and placeholder card wiring. Point the user at what to +customize for their product (details in the README's "Adapting to your product" section): + +- `.agents/skills/poc-analysis/config/metabase_cards.json` — which dashboard cards to + query and their exact `parameter_mappings` targets (from the Step 3 dashboard response) +- `.agents/skills/poc-analysis/config/methodology.md` — primary metric definition, user + tier criteria, summary framing +- `.agents/skills/poc-analysis/references/metabase_config.md` — their dashboard's column + schemas +- `.agents/skills/poc-not-customer-usage/config/data_sources.json` — primary-metric + parameter targets plus warehouse table/column names +- Optional display vars in `.env`: `PRIMARY_METRIC_LABEL`, `PRIMARY_METRIC_EMOJI` + +This can be deferred — the environment verification above is the blocking part of setup. + +## Step 7: Report and hand off + +Summarize: repo location, which variables were set (names only, never values), which +verification checks passed, and anything deferred from Step 6. Then offer to run a +pipeline skill (`poc-analysis` or `poc-not-customer-usage`) as the first real end-to-end +test. diff --git a/.env.example b/.env.example index 392cc4b..2037974 100644 --- a/.env.example +++ b/.env.example @@ -10,6 +10,9 @@ # # Never commit your real .env — only this .env.example belongs in version control. # +# Quote any value containing spaces (e.g. LABEL="two words") — unquoted spaces +# break the `source .env` load step. +# # Legend: [required] must be set [optional] has a default / can be left blank # Skills: [poc-analysis] [poc-not-customer-usage] [both] # ------------------------------------------------------------------------------ @@ -63,14 +66,14 @@ DATA_SOURCES_CONFIG= # Primary metric display [poc-not-customer-usage] # ============================================================================== # Display label + emoji for your primary value metric (e.g. "API calls", "pipeline runs", "MAU"). -PRIMARY_METRIC_LABEL=primary metric +PRIMARY_METRIC_LABEL="primary metric" PRIMARY_METRIC_EMOJI=:bar_chart: # ============================================================================== # Cohort / filters [poc-not-customer-usage] # ============================================================================== # pipeline_label value that marks PoC deals in the deals table. -POC_PIPELINE_LABEL=poc pipeline +POC_PIPELINE_LABEL="poc pipeline" # Comma-separated internal demo/test team names to exclude (empty by default). INTERNAL_TEAM_NAMES= # Comma-separated internal domains whose admin emails are flagged as internal/test (empty by default). diff --git a/README.md b/README.md index 226c2e4..8518031 100644 --- a/README.md +++ b/README.md @@ -11,7 +11,7 @@ library only. - [How it works](#how-it-works) - [Skills](#skills) - [Requirements](#requirements) -- [Setup](#setup) +- [How to deploy](#how-to-deploy) - [Configuration](#configuration) - [Finding Metabase IDs](#finding-metabase-ids) - [Finding HubSpot IDs](#finding-hubspot-ids) @@ -42,10 +42,12 @@ skill's `SKILL.md`. ## Skills -This repo ships two independent skills under `.agents/skills/`: +This repo ships three skills under `.agents/skills/` — one for deployment and +two independent reporting pipelines: | Skill | What it does | |---|---| +| `setup` | Guided deployment — clones the repo if needed, builds `.env`, discovers IDs, verifies API access. | | `poc-analysis` | End-to-end POC health analysis — one detailed Slack message per company. | | `poc-not-customer-usage` | 30-day primary-metric usage for active-enterprise PoCs not yet closed-won — one ranked Slack summary. | @@ -55,14 +57,34 @@ This repo ships two independent skills under `.agents/skills/`: - No third-party packages - API credentials for HubSpot, Metabase, and Slack (see [Configuration](#configuration)) -## Setup +## How to deploy + +### With an agent (recommended) + +Paste this prompt into Warp (or any agent that supports `.agents/skills/`): + +``` +Set up poc-bot: clone https://github.com/warpdotdev/poc-agent-oss.git if it +isn't already cloned, then run the setup skill. +``` + +The [`setup` skill](.agents/skills/setup/SKILL.md) walks the agent through the +whole deployment: cloning (or reusing an existing clone), creating `.env`, +collecting credentials, discovering your HubSpot/Metabase IDs via their APIs, +loading the environment, and running read-only verification checks against +each service. It is safe to re-run to finish a partial setup. + +### Manually + +The same steps, by hand: 1. Clone the repo: ```bash git clone https://github.com/warpdotdev/poc-agent-oss.git cd poc-agent-oss ``` -2. Create your environment file from the example and fill in your values: +2. Create your environment file from the example and fill in your values + (see [Configuration](#configuration) for what goes where): ```bash cp .env.example .env # then edit .env @@ -202,6 +224,8 @@ JSON file in its `config/` directory: ├── README.md ├── SECURITY.md └── .agents/skills/ + ├── setup/ + │ └── SKILL.md # guided deployment (see How to deploy) ├── poc-analysis/ │ ├── SKILL.md │ ├── config/ # metabase_cards.json, methodology.md