From ee8e24ac3fabe64be373cfef92192603ce86dd2e Mon Sep 17 00:00:00 2001 From: Jerry Date: Thu, 16 Jul 2026 18:00:24 -0400 Subject: [PATCH] Add setup skill and restructure README deploy docs - New .warp/skills/setup skill: clones the repo (or reuses an existing clone), checks prerequisites, installs deps in a venv, configures .env per-integration, handles GitHub/Google auth, replaces placeholders, and verifies the result - README: consolidate Requirements/Setup/Placeholders into a 'How to deploy' section with a copy-paste Warp prompt (Option A) and the manual steps kept as reference (Option B) - AGENTS.md: register setup as the 16th skill Co-Authored-By: Oz --- .warp/skills/setup/SKILL.md | 132 ++++++++++++++++++++++++++++++++++++ AGENTS.md | 3 +- README.md | 27 +++++--- 3 files changed, 150 insertions(+), 12 deletions(-) create mode 100644 .warp/skills/setup/SKILL.md diff --git a/.warp/skills/setup/SKILL.md b/.warp/skills/setup/SKILL.md new file mode 100644 index 0000000..8460d4d --- /dev/null +++ b/.warp/skills/setup/SKILL.md @@ -0,0 +1,132 @@ +--- +name: setup +description: Sets up the competitive-intelligence-agent from scratch — clones the repo (or works from an existing clone), installs dependencies, configures .env credentials, authenticates GitHub and Google, and replaces codebase placeholders with the user's real values. Use when asked to "set up this agent", "run the setup skill", "deploy this agent", "configure this repo", or when a user has just cloned the repo and wants it working. +--- + +# Setup Skill + +Use this skill to take a user from nothing (or a fresh clone) to a fully working PM / competitive-intelligence agent. Work through the phases in order, but skip anything that is already done — every step is idempotent. The user may only want a subset of integrations; ask early and only configure what they need, since each integration is independent. + +## Phase 0: Locate or clone the repo + +Check whether you are already inside the repo (look for `.warp/skills` and `AGENTS.md` in the current directory or a parent). If not: + +```bash +git clone https://github.com/warpdotdev/competitive-intelligence-agent-oss.git +cd competitive-intelligence-agent-oss +``` + +If a clone already exists somewhere the user points you at, `cd` into it instead of re-cloning. Run all later commands from the repo root. + +## Phase 1: Check prerequisites + +Verify and report; offer install instructions for anything missing: + +- **Python 3.11+** — `python3 --version` +- **GitHub CLI** — `gh --version` (needed for `analyze_customer_feedback` and report PRs) +- **Warp** — the user is presumably already running the agent in Warp + +## Phase 2: Ask which integrations the user wants + +Not every skill needs every credential. Ask the user which capabilities they care about, then only configure the corresponding integrations: + +- **Google Workspace** (Docs, Drive, Gmail, BigQuery) → `analyze_customer_feedback`, `read/write/summarize_google_docs`, `write_prd` +- **Metabase** → NPS/churn queries in `analyze_customer_feedback`, usage pulls in `answer_pricing` +- **Grain** → `votc_insights` +- **Notion** → `weekly_wynk`, `write_notion` +- **Slack** → `post_to_slack`, `weekly_wynk` +- **Warp Oz API key** → `fix_p0_issues` (spawning cloud coding agents) +- **Octolens MCP** → `weekly_sentiment_analysis` +- **GitHub** → issue fetching in `analyze_customer_feedback` + +Skills whose integrations are skipped will simply be unavailable until configured later — that's fine, say so. + +## Phase 3: Install Python dependencies + +Prefer a virtualenv — on modern macOS/Homebrew Python, bare `pip3 install` fails with an `externally-managed-environment` error: + +```bash +python3 -m venv .venv +source .venv/bin/activate +pip install -r requirements.txt +``` + +The other skills invoke scripts with `python3`, so the venv must be active in the session where skills run. Tell the user to activate it (or ask if they prefer a global/user install where their environment allows it). `.venv` should be gitignored — add it if missing. + +## Phase 4: Create and fill .env + +```bash +cp -n .env.example .env +``` + +`.env` is gitignored; never overwrite an existing one without asking. Walk the user through each variable relevant to their chosen integrations (see the comments in `.env.example` for what each is used for): + +- `GOOGLE_OAUTH_TOKEN` — filled in Phase 6 +- `METABASE_API_KEY` +- `GRAIN_TOKEN` +- `NOTION_API_KEY` +- `SLACK_WEBHOOK_URL` +- `WARP_API_KEY` +- `FEEDBACK_EMAIL` — the Gmail address feedback emails arrive at +- Pricing rate variables (`SEAT_PRICE`, `USAGE_UNIT_PRICE`, etc.) — only if they want `answer_pricing`; these can also be passed as CLI flags later + +**Handling secrets:** never ask the user to paste secret values into the chat, and never echo them. Ask the user to edit `.env` directly (offer to open it), then confirm which variables are set by checking for non-empty values without printing them: + +```bash +awk -F= '/^[A-Z_]+=/ {sub(/[ \t]*#.*$/,""); v=substr($0, index($0,"=")+1); gsub(/[ \t]/,"",v); print $1 "=" (v=="" ? "" : "")}' .env +``` + +Note: `SLACK_WEBHOOK_URL` and `FEEDBACK_EMAIL` ship with example values, so `` for those may still mean unconfigured — confirm the user replaced `YOUR/WEBHOOK/URL` and `your-company.com`. + +## Phase 5: Authenticate GitHub CLI + +```bash +gh auth status || gh auth login +``` + +## Phase 6: Google OAuth (only if Google integrations are wanted) + +1. Tell the user to do this in Google Cloud Console (you cannot do it for them): + - Create/select a project; enable the **Google Docs, Google Drive, Gmail, and BigQuery** APIs. + - Create an **OAuth 2.0 Client ID** of type **Desktop app**. + - Download the client JSON and save it as `credentials.json` in the repo root (it is gitignored). +2. Then generate the token (opens a browser, writes `token.json`): + +```bash +python3 generate_readonly_token.py +``` + +3. For local use, scripts read `token.json` via `GOOGLE_OAUTH_TOKEN`. Tell the user to set `GOOGLE_OAUTH_TOKEN` in `.env` to the contents of `token.json` (they can do this themselves; do not print the token). For remote/cloud runs, it goes in the environment's secrets instead. + +## Phase 7: Replace codebase placeholders + +The repo ships with obvious placeholders. Ask the user for the real values relevant to their chosen integrations, then find-and-replace across the codebase (`grep -rl '' .` to find affected files). **Do not replace inside `README.md` or this skill (`.warp/skills/setup/`)** — those mention the placeholders as documentation and must keep them: + +- `YOUR_ORG/YOUR_REPO` — their GitHub org/repo (GitHub feedback, P0 fixes, WYNK) +- `YOUR_PRODUCT_CHANGELOG_URL` — public changelog URL (`summarize_changelogs`) +- `YOUR_PRODUCT_DOCS_URL` — public docs URL (`feature_research`) +- `your-gcp-project-id` — Google Cloud project ID (Metabase clients, `set_oauth_token.sh`) +- `https://your-metabase-instance.metabaseapp.com` — Metabase URL (both `metabase_client.py` files) +- `METABASE_DATABASE_ID = 0` — Metabase database ID, an integer (both `metabase_client.py` files) +- `your_nps_survey_responses_table` — BigQuery NPS table (`fetch_nps_data.py`) +- `your_subscriptions_table` — subscriptions/churn table (`fetch_churn_data.py`) +- `your_usage_events_table` — usage table + its column names (`answer_pricing/scripts/fetch_usage.py`) +- `YOUR_WORKSPACE_SLUG`, `YOUR_NOTION_PARENT_PAGE_ID`, `YOUR_CONTINUOUS_PLANNING_PAGE_ID`, `YOUR_NOTION_DATA_SOURCE_ID` — Notion workspace details (`weekly_wynk/SKILL.md`) +- `YOUR_OZ_ENVIRONMENT_ID` — Warp Oz cloud environment ID (`fix_p0_issues/SKILL.md`) +- `your-app-client`, `your-app-server` — paths to their application repos (`fix_p0_issues`, `analyze_git_history`) + +Leave untouched: `YOUR_GOOGLE_DOC_ID` and `YOUR_GOOGLE_DRIVE_FOLDER_ID` — these are illustrative runtime arguments, not values to hardcode. Also leave placeholders for integrations the user skipped. + +If they want `answer_pricing`, also remind them to describe their pricing model in `knowledge/platform_credits.md`. + +## Phase 8: Verify + +Run lightweight checks for the configured integrations and report a checklist of what works and what's still pending: + +- Python imports: `python3 -c "import googleapiclient, google.cloud.bigquery, requests"` +- GitHub: `gh auth status` +- Google token exists: `test -f token.json` +- `.env` variables set (using the non-revealing awk check from Phase 4) +- Remaining placeholders: `grep -rn "YOUR_ORG/YOUR_REPO\|your-gcp-project-id\|your-metabase-instance" .warp --exclude-dir=setup` — expected to be empty for configured integrations + +Finish with a short summary: which skills are ready to use, which are unconfigured, and one or two example prompts to try (e.g. "Analyze customer feedback for the last 7 days"). diff --git a/AGENTS.md b/AGENTS.md index 4303dd6..5313036 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -18,8 +18,9 @@ You are a Product Manager agent. Your job is to help the team make clear product Sometimes users will ask you to perform certain tasks. There are instructions for these tasks inside of the .warp/skills folder in this repository. Inside of skills, there is a folder for each skill. When determining which skills to use, only pick ones that are directly relevant to the task at hand. The skills folders also can contain scripts that help you do your job. Don't use scripts or instructinos from irrelevant skills. Sometimes a skill may ask you to use another skill, that is fine and expected. -There are 15 skills currently: +There are 16 skills currently: +setup - use this skill to set up or deploy this agent from scratch: clone the repo (or reuse an existing clone), install dependencies, configure credentials, and replace placeholders. Use when asked to "run the setup skill" or "set up this agent." analyze_customer_feedback - use this skill to analyze and summarize customer feedback from GitHub issues, NPS surveys (BigQuery), and email feedback. Produces trend analysis, themes, and actionable insights. analyze_git_history - use this skill to analyze git history from a repository to summarize recent development activity, features in progress, and engineering priorities. feature_research - use this skill to perform competitive feature analysis on specific functionality, comparing competitor products to your product. diff --git a/README.md b/README.md index 5a20597..324913c 100644 --- a/README.md +++ b/README.md @@ -22,6 +22,7 @@ This agent gives a PM the skills to: | `fix_p0_issues` | Reads the weekly briefing, triages P0s, and spawns cloud coding agents | | `post_to_slack` | Posts messages to a Slack channel via incoming webhook | | `read_google_docs` | Reads content from a Google Doc by URL or document ID | +| `setup` | Guides a Warp agent through deploying this repo end-to-end (see [How to deploy](#how-to-deploy)) | | `summarize_changelogs` | Summarizes competitor changelogs | | `summarize_google_docs` | Reads and summarizes recently modified Google Docs | | `votc_insights` | Extracts pain points, feature demand, and competitive signals from customer call transcripts (Grain) | @@ -48,16 +49,21 @@ This agent gives a PM the skills to: --- -## Requirements +## How to deploy -- Python 3.11+ -- [Warp](https://www.warp.dev/) (for running skills as an agent) -- [GitHub CLI (`gh`)](https://cli.github.com/) — authenticated -- [Warp `oz` CLI](https://docs.warp.dev/) — for the `fix_p0_issues` skill +### Option A: Run the setup skill with Warp (recommended) ---- +Copy-paste this prompt into [Warp](https://www.warp.dev/): + +``` +Clone https://github.com/warpdotdev/competitive-intelligence-agent-oss.git if it isn't already cloned locally, cd into it, then run the setup skill at .warp/skills/setup/SKILL.md to set this agent up. +``` -## Setup +The agent will clone the repo (or reuse an existing clone), install dependencies, walk you through credentials for only the integrations you want, and replace the codebase placeholders with your values. + +### Option B: Manual setup (reference) + +Requirements: Python 3.11+, [Warp](https://www.warp.dev/), [GitHub CLI (`gh`)](https://cli.github.com/), and a Warp API key for the `fix_p0_issues` skill. ```bash # 1. Clone the repo @@ -90,11 +96,9 @@ python3 generate_readonly_token.py > It writes `token.json`; for remote/cloud runs, set `GOOGLE_OAUTH_TOKEN` to the > contents of that file. ---- - -## Placeholders to replace +### Placeholders to replace -Before using this, find and replace these placeholders in the codebase: +Find and replace these placeholders in the codebase (the setup skill handles this for you): | Placeholder | What to replace it with | Files affected | |-------------|------------------------|----------------| @@ -160,6 +164,7 @@ Warp will automatically select the appropriate skill and execute the workflow. │ ├── fix_p0_issues/ │ ├── post_to_slack/ │ ├── read_google_docs/ +│ ├── setup/ │ ├── summarize_changelogs/ │ ├── summarize_google_docs/ │ ├── votc_insights/