@atollhq/skill-codex 0.1.3 → 0.1.5

package/README.md

@@ -0,0 +1,47 @@
+# @atollhq/skill-codex
+
+Install the [Atoll](https://atollhq.com) project management integration for [Codex CLI](https://github.com/openai/codex).
+
+Gives your Codex agent the ability to manage tasks, goals, KPIs, initiatives, milestones, comments, and webhooks on Atoll — the same API surface a human teammate uses.
+
+## Install
+
+```bash
+npx @atollhq/skill-codex --key sk_atoll_... --org your-org-slug
+```
+
+Get an API key from **Settings > Members > Add Agent** (or **Create API Key** for integrations) in the Atoll app.
+
+This does three things:
+
+1. Appends (or updates) an `# Atoll Integration` section in `~/.codex/AGENTS.md`
+2. Copies API reference files to `~/.codex/atoll-references/`
+3. Appends `ATOLL_API_KEY` and `ATOLL_ORG_SLUG` exports to your shell profile (`~/.zshrc` or `~/.bashrc`)
+
+Open a fresh shell (or `source` your profile) and Codex has the Atoll integration.
+
+## Using the integration
+
+Once installed, ask Codex anything task-related:
+
+```
+"List my Atoll tasks"
+"Create an issue to fix the login bug, priority 1"
+"What goals are off pace?"
+"Move ATOLL-42 to in_progress"
+```
+
+## Companion CLI
+
+For terminal-first work, see [`@atollhq/cli`](https://www.npmjs.com/package/@atollhq/cli):
+
+```bash
+npm install -g @atollhq/cli
+atoll auth login --key sk_atoll_...
+atoll config set-org your-org-slug
+atoll issue list
+```
+
+## License
+
+MIT

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@atollhq/skill-codex",
-  "version": "0.1.3",
+  "version": "0.1.5",
   "description": "Install the Atoll project management integration for Codex CLI",
   "bin": {
     "skill-codex": "./bin/install.mjs"

package/skill/SKILL.md

@@ -26,16 +26,31 @@ Agents are org members with the same API, same permissions, same ability to crea
 
 All requests require: `Authorization: Bearer sk_atoll_<key>`
 
-Verify with: `GET /api/auth/me`
+API keys are generated in **Settings > Members > Add Agent** (for agents) or **Settings > Members > Create API Key** (for integrations). Each key is scoped to one org. Store both values as env vars:
 
-API keys are generated in **Settings > Members > Add Agent** (for agents) or **Settings > Members > Create API Key** (for integrations). Store as `$ATOLL_API_KEY`.
+```bash
+export ATOLL_API_KEY="sk_atoll_..."
+export ATOLL_ORG_ID="..."          # UUID of the org the key belongs to
+```
+
+**Sanity check** — exercises the org-scoped issues endpoint, not just `/api/auth/me`:
+
+```bash
+: "${ATOLL_API_KEY:?missing}" "${ATOLL_ORG_ID:?missing}" && \
+  curl -sS -o /dev/null -w "HTTP:%{http_code}\n" \
+    "https://atollhq.com/api/orgs/$ATOLL_ORG_ID/issues?limit=1" \
+    -H "Authorization: Bearer $ATOLL_API_KEY"
+# Expect: HTTP:200
+```
+
+If `$ATOLL_ORG_ID` is empty, the URL collapses to `/api/orgs//issues` which 308-redirects to a non-existent route and returns `Unauthorized` — a misleading symptom that looks like an auth failure. `GET /api/auth/me` alone cannot catch this since it doesn't depend on `$ATOLL_ORG_ID`. Always guard both vars.
 
 ## Quick Start — CLI (recommended)
 
 Install globally or use via npx:
 
 ```bash
-npm install -g @atollhq/cli   # or: npx atoll ...
+npm install -g @atollhq/cli   # or: npx @atollhq/cli ...
 ```
 
 Configure once:
@@ -78,11 +93,16 @@ atoll milestone list --project <project-id>
 All CLI commands map to REST endpoints. Use the API directly when the CLI doesn't cover a specific operation.
 
 ```bash
-export ATOLL_API_KEY="sk_atoll_..."
-
-curl -s -H "Authorization: Bearer $ATOLL_API_KEY" \
-     -H "Content-Type: application/json" \
-     "https://atollhq.com/api/orgs/{orgId}/issues?status=todo"
+# Prereq: both env vars exported (see Authentication above)
+atoll() {
+  : "${ATOLL_API_KEY:?ATOLL_API_KEY not set}"
+  : "${ATOLL_ORG_ID:?ATOLL_ORG_ID not set}"
+  curl -s -H "Authorization: Bearer $ATOLL_API_KEY" \
+       -H "Content-Type: application/json" \
+       "https://atollhq.com$1" "${@:2}"
+}
+
+atoll "/api/orgs/$ATOLL_ORG_ID/issues?status=todo"
 ```
 
 ## The Heartbeat Loop
@@ -142,7 +162,7 @@ Full endpoint tables and field schemas:
 |----------|--------|------|--------|--------|
 | Orgs | POST `/api/orgs` | GET `/api/orgs` | PATCH `/api/orgs/{id}` | DELETE `/api/orgs/{id}` |
 | Projects | POST `.../projects` | GET `.../projects` | PATCH `.../projects/{id}` | DELETE `.../projects/{id}` |
-| Tasks | POST `.../issues` | GET `.../issues` | PATCH `.../issues/{id}` | DELETE `.../issues/{id}` |
+| Tasks | POST `.../issues` | GET `.../issues` | PATCH `.../issues/{id}` | DELETE `.../issues/{id}` † |
 | Goals | POST `.../goals` | GET `.../goals` | PATCH `.../goals/{id}` | DELETE `.../goals/{id}` |
 | KPIs | POST `.../kpis` | GET `.../kpis` | PATCH `.../kpis/{id}` | DELETE `.../kpis/{id}` |
 | Initiatives | POST `.../initiatives` | GET `.../initiatives` | PATCH `.../initiatives/{id}` | DELETE `.../initiatives/{id}` |
@@ -152,6 +172,8 @@ Full endpoint tables and field schemas:
 
 All endpoints are under `/api/orgs/{orgId}/...`.
 
+† `DELETE /issues/{id}` requires `owner` or `admin` role — any caller without that role (including member-role agents) gets `403`. If you just need to remove a task, use `POST /api/orgs/{orgId}/issues/{issueId}/archive` (soft delete, no role gate); reverse with `DELETE` on the same path (unarchive).
+
 ### Quick enum reference
 
 - **Task status**: `backlog`, `todo`, `in_progress`, `done`, `cancelled` (custom per project)