@atollhq/skill-claude 0.1.4 → 0.1.6

package/README.md

@@ -0,0 +1,56 @@
+# @atollhq/skill-claude
+
+Install the [Atoll](https://atollhq.com) project management skill for [Claude Code](https://docs.anthropic.com/en/docs/claude-code).
+
+Gives your Claude Code 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-claude --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 two things:
+
+1. Copies the skill into `~/.claude/skills/atoll-api/`
+2. Writes `ATOLL_API_KEY` and `ATOLL_ORG_SLUG` into `~/.claude/settings.json` under `env`
+
+Restart Claude Code and the `atoll-api` skill is available.
+
+## Using the skill
+
+Once installed, ask Claude 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"
+```
+
+The skill also documents how to talk to the Atoll API directly via curl, in case your agent needs to.
+
+## 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
+```
+
+For multiple agents or orgs, use CLI auth profiles:
+
+```bash
+atoll auth login --profile agent-a --key sk_atoll_... --org acme
+atoll auth login --profile agent-b --key sk_atoll_... --org client
+atoll --profile agent-b issue list
+```
+
+## License
+
+MIT

package/bin/install.mjs

@@ -23,7 +23,7 @@ function parseArgs(argv) {
 
 function printUsage() {
   console.log(`
-Usage: npx @atoll/skill-claude --key <api-key> --org <org-slug>
+Usage: npx @atollhq/skill-claude --key <api-key> --org <org-slug>
 
 Options:
   --key   Atoll API key (sk_atoll_...)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@atollhq/skill-claude",
-  "version": "0.1.4",
+  "version": "0.1.6",
   "description": "Install the Atoll project management skill for Claude Code",
   "bin": {
     "skill-claude": "./bin/install.mjs"

package/skill/SKILL.md

@@ -50,7 +50,7 @@ If `$ATOLL_ORG_ID` is empty, the URL collapses to `/api/orgs//issues` which 308-
 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:
@@ -60,6 +60,18 @@ atoll auth login --key sk_atoll_...
 atoll config set-org my-org
 ```
 
+For machines or agents that need multiple credentials, use auth profiles:
+
+```bash
+atoll auth login --profile agent-a --key sk_atoll_... --org acme
+atoll auth login --profile agent-b --key sk_atoll_... --org client
+atoll auth profiles
+atoll auth use agent-a
+
+# Run one command as a specific profile
+atoll --profile agent-b issue list
+```
+
 Common commands:
 
 ```bash
@@ -150,6 +162,12 @@ Every KPI snapshot can be attributed to an initiative or issue, building a recor
 
 `POST /api/orgs/{id}/issues/bulk` with `{ "issues": [{...}, ...] }` (max 50).
 
+### Billing and plan limits
+
+Owners/admins can read billing state with `GET /api/orgs/{id}/billing` and start Stripe checkout with `POST /api/orgs/{id}/billing/checkout` using `{ "plan": "starter" }` or `{ "plan": "team" }`.
+
+Creation endpoints can return `402` with `code: "PLAN_LIMIT_REACHED"` when an org reaches limits for humans, agents/integrations, active projects, or active issues.
+
 ## API Reference
 
 Full endpoint tables and field schemas:

package/skill/references/api-endpoints.md

@@ -10,6 +10,7 @@ All endpoints require `Authorization: Bearer sk_atoll_...` header.
 - [Projects](#projects)
 - [Project Members](#project-members)
 - [Project Teams](#project-teams)
+- [Billing](#billing)
 - [Tasks (Issues)](#tasks-issues)
 - [Dependencies](#dependencies)
 - [Comments](#comments)
@@ -85,6 +86,18 @@ Access levels: `view`, `edit`, `admin` (default: `view`).
 | POST | `/api/orgs/{id}/projects/{projectId}/teams` | Add team (`{ teamId }`) |
 | DELETE | `/api/orgs/{id}/projects/{projectId}/teams?teamId=...` | Remove team |
 
+## Billing
+
+Org billing is managed through Stripe. Owners/admins can create checkout and billing portal sessions.
+
+| Method | Endpoint | Description |
+|--------|----------|-------------|
+| GET | `/api/orgs/{id}/billing` | Get plan, status, usage, limits, and subscription summary |
+| POST | `/api/orgs/{id}/billing/checkout` | Create Stripe Checkout Session (`{ plan: "starter" \| "team" }`) |
+| POST | `/api/orgs/{id}/billing/portal` | Create Stripe Billing Portal Session |
+
+Plan limits are enforced when creating projects, human members, agents/integrations, and active tasks. Limit errors return `402` with `code: "PLAN_LIMIT_REACHED"`.
+
 ## Tasks (Issues)
 
 | Method | Endpoint | Description |

package/skill/references/api-fields.md

@@ -12,6 +12,7 @@
 - [Webhook Fields](#webhook-fields)
 - [Heartbeat Response](#heartbeat-response)
 - [Analytics Response](#analytics-response)
+- [Plan Limit Errors](#plan-limit-errors)
 - [Enums](#enums)
 
 ---
@@ -53,6 +54,23 @@ All fields work on both POST (create) and PATCH (update).
 ```
 Returns `{ issues: [...], count: N }` (201). Max 50 per request.
 
+## Plan Limit Errors
+
+Creation endpoints may return `402` when an org reaches its billing plan limit:
+
+```json
+{
+  "error": "Plan limit reached",
+  "code": "PLAN_LIMIT_REACHED",
+  "resource": "activeProjects",
+  "plan": "free",
+  "limit": 2,
+  "usage": 2
+}
+```
+
+`resource` is one of `humans`, `agents`, `activeProjects`, or `activeIssues`.
+
 ## Goal Fields
 
 ```json
@@ -234,7 +252,7 @@ URL must be HTTPS. Response includes `secret` for HMAC signature verification.
 
 ## Response Format
 
-All endpoints return JSON. Successful: `200` or `201`. Errors: `{ "error": "message" }` with `400`, `401`, `403`, `404`, `409`, or `500`.
+All endpoints return JSON. Successful: `200` or `201`. Errors: `{ "error": "message" }` with `400`, `401`, `402`, `403`, `404`, `409`, or `500`.
 
 List responses include `total`, `limit`, `offset` for pagination.