@atollhq/skill-claude 0.4.4 → 0.4.5

package/package.json

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

package/skill/SKILL.md

@@ -156,6 +156,7 @@ atoll milestone upsert --project <project-id> --name "v1.0" --date 2026-06-01
 # Goals, KPIs, and initiatives
 atoll goal create --title "Reach 100 paying customers by Q2" --target-date 2026-06-30
 atoll kpi create --name paying_customers --goal "Reach 100 paying customers by Q2" --unit count --target 100 --current 34
+atoll kpi create --name mvp_tasks_done --goal "Launch MVP" --internal-task-completion
 atoll initiative create --title "Content pipeline" --goal "Reach 100 paying customers by Q2" --status active
 atoll initiative kpi link "Content pipeline" paying_customers --impact "+30 customers/mo"
 atoll kpi snapshot add paying_customers --value 42 --initiative "Content pipeline" --note "End-of-week Stripe check"
@@ -172,9 +173,32 @@ CLI JSON conventions:
 - Use `--json` for machine-readable output.
 - List commands return `{ resource, items, total, limit, offset, nextOffset, truncated, hint }`.
 - Diagnostics and errors go to stderr.
-- `atoll agent-context` returns a versioned command/flag manifest and available profile context.
+- Interactive CLI update notices also go to stderr and are suppressed for JSON/non-TTY/CI/completion flows.
+- `atoll agent-context` returns a versioned command/flag manifest, available profile context, and structured `cli.update_available` metadata.
+- `atoll heartbeat --json` includes the same structured `cli` update metadata for agents.
 - `atoll plan validate/apply` consumes `schemaVersion: "atoll.plan.v1"` files with `milestones`, `issues`, `dependencies`, `initiativeLinks`, and `milestoneLinks`; local `key` values can be referenced by `milestoneKey`, `issueKey`, `dependsOn`, `blockedBy`, or `blocks`.
 
+## KPI HTTP Sync Drafts
+
+When a human asks you to help automate a KPI from a third-party API, use this Atoll skill. If the current agent environment does not have the `atoll-api` skill installed, tell the user to install it before continuing or use the Atoll CLI/MCP tools directly if they are available.
+
+Agents may create draft syncs and validate proposed configs only after a human admin has allowlisted the exact destination host in Atoll. Human admins must review the draft in Atoll, enter secrets, dry-run, publish, disable, or run-now with snapshot writing.
+
+```bash
+atoll kpi sync validate <kpi-id> \
+  --name "PostHog visitors" \
+  --schedule daily \
+  --url https://us.posthog.com/api/projects/123/query/ \
+  --pointer /results/0/value \
+  --auth-secret-ref posthog_api_key
+
+atoll kpi sync draft <kpi-id> --file sync-draft.json
+```
+
+Draft configs must be `GET` only, `https` only, JSON only, no redirects, no request bodies, no inline query strings, no secret values, and an already-allowlisted exact destination host. Use secret reference names only for `Authorization: Bearer <secretRef>` or `X-API-Key: <secretRef>`.
+
+Never include API keys, bearer tokens, cookies, raw third-party response bodies, or secret values in prompts, draft files, comments, or issue descriptions. If a human pasted a secret into chat, stop and ask them to rotate it and enter the replacement directly in Atoll.
+
 ## Remote MCP Server
 
 Use `@atollhq/mcp-server` when an agent or ChatGPT-style client needs Atoll access but cannot run a local CLI command or read local auth profiles.
@@ -322,7 +346,7 @@ atoll issue update ATOLL-42 --status done              # complete
 ### Set up the strategy chain
 
 1. `POST /api/orgs/{id}/goals` -- create goal with `target_date`
-2. `POST /api/orgs/{id}/kpis` -- attach KPI with `goal_id`, `target_value`, `target_direction`
+2. `POST /api/orgs/{id}/kpis` -- attach KPI with `goal_id`, `target_value`, `target_direction`; for launch-style goals you can use `source_type: "formula"` with `source_config.formula: "goal_linked_issue_completion"` to calculate done directly linked and milestone-linked tasks over total linked tasks
 3. `POST /api/orgs/{id}/kpis/{kpiId}/snapshots` -- record measurement (auto-updates `current_value`)
 4. `POST /api/orgs/{id}/initiatives` -- create initiative linked to goal
 5. `POST /api/orgs/{id}/initiatives/{id}/kpi-impacts` -- declare expected KPI impact

package/skill/references/api-endpoints.md

@@ -201,6 +201,21 @@ Roles: `owner`, `admin`, `member`, `guest`.
 | DELETE | `/api/orgs/{id}/kpis/{kpiId}` | Delete KPI (admin/owner only) |
 | GET | `/api/orgs/{id}/kpis/{kpiId}/snapshots` | List snapshots (optional `?limit=50`) |
 | POST | `/api/orgs/{id}/kpis/{kpiId}/snapshots` | Record a snapshot |
+| GET | `/api/orgs/{id}/kpi-http-sync-policy` | List exact-host KPI HTTP sync allowlist policy |
+| POST | `/api/orgs/{id}/kpi-http-sync-policy` | Add an allowed exact host (human admin only) |
+| GET | `/api/orgs/{id}/kpis/{kpiId}/http-syncs` | List KPI HTTP syncs |
+| POST | `/api/orgs/{id}/kpis/{kpiId}/http-syncs` | Create a draft KPI HTTP sync |
+| PUT | `/api/orgs/{id}/kpis/{kpiId}/http-syncs` | Validate a proposed KPI HTTP sync config without storing or running it |
+| GET | `/api/orgs/{id}/kpis/{kpiId}/http-syncs/{syncId}` | Get a KPI HTTP sync |
+| PATCH | `/api/orgs/{id}/kpis/{kpiId}/http-syncs/{syncId}` | Update a KPI HTTP sync draft (human admin only) |
+| POST | `/api/orgs/{id}/kpis/{kpiId}/http-syncs/{syncId}/validate` | Validate a stored sync (human admin only) |
+| GET | `/api/orgs/{id}/kpis/{kpiId}/http-syncs/{syncId}/secrets` | List sanitized secret metadata (human admin only) |
+| PUT | `/api/orgs/{id}/kpis/{kpiId}/http-syncs/{syncId}/secrets` | Add or replace a sync secret value (human admin only) |
+| POST | `/api/orgs/{id}/kpis/{kpiId}/http-syncs/{syncId}/dry-run` | Execute a sanitized dry run without writing a snapshot (human admin only) |
+| POST | `/api/orgs/{id}/kpis/{kpiId}/http-syncs/{syncId}/publish` | Publish a validated, dry-run sync (human admin only) |
+| POST | `/api/orgs/{id}/kpis/{kpiId}/http-syncs/{syncId}/disable` | Disable a sync (human admin only) |
+| POST | `/api/orgs/{id}/kpis/{kpiId}/http-syncs/{syncId}/run-now` | Preview by default; write a snapshot only with explicit admin confirmation |
+| GET | `/api/orgs/{id}/kpis/{kpiId}/http-syncs/{syncId}/runs` | List sanitized sync run history (human admin only) |
 
 ## Initiatives
 

package/skill/references/api-fields.md

@@ -100,6 +100,22 @@ Creation endpoints may return `402` when an org reaches its billing plan limit:
 }
 ```
 
+Calculated task-completion KPIs use `source_type: "formula"` and are calculated from linked work instead of snapshots:
+
+```json
+{
+  "name": "mvp_tasks_done",
+  "goal_id": "goal-uuid",
+  "source_type": "formula",
+  "source_config": {
+    "formula": "goal_linked_issue_completion",
+    "done_statuses": ["done"]
+  }
+}
+```
+
+For `goal_linked_issue_completion`, `current_value` is the count of non-archived directly linked issues and milestone-linked issues in `done` status and `target_value` is the total non-archived directly linked issue and milestone-linked issue count under initiatives for the goal.
+
 ## KPI Snapshots
 
 ```json
@@ -114,6 +130,40 @@ Creation endpoints may return `402` when an org reaches its billing plan limit:
 
 Recording a snapshot auto-updates the KPI's `current_value`.
 
+Calculated KPIs do not accept manual snapshots.
+
+`api_poll` snapshots are written by published KPI HTTP Syncs and include provenance: `source_sync_id`, `source_sync_run_id`, `source_config_hash`, `source_recorded_for`, `observed_at`, and optional `provider_recorded_at`.
+
+## KPI HTTP Syncs
+
+```json
+{
+  "name": "PostHog visitors",
+  "schedule": "daily",
+  "request_config": {
+    "method": "GET",
+    "url": "https://us.posthog.com/api/projects/123/query/",
+    "headers": {
+      "Authorization": {
+        "secretRef": "posthog_api_key",
+        "format": "Bearer {value}"
+      }
+    }
+  },
+  "extraction_config": {
+    "contentType": "json",
+    "pointer": "/results/0/value",
+    "numeric": {
+      "mode": "number",
+      "percentageScale": null
+    }
+  },
+  "freshness_config": {}
+}
+```
+
+V1 syncs are `GET` only, `https` only, JSON only, exact-host allowlisted, no redirects, no request bodies, no inline query strings, and no secret values. Machine actors can create drafts and validate configs only after the host is allowlisted. Human admins manage allowlists, secrets, dry-runs, publishing, disabling, and snapshot-writing run-now actions in Atoll.
+
 ## Initiative Fields
 
 ```json
@@ -295,6 +345,9 @@ Each finding carries whichever entity ids apply: `goal_id`, `kpi_id`, `initiativ
 | KPI | `target_direction` | `increase`, `decrease`, `maintain` |
 | KPI | `source_type` | `manual`, `webhook`, `api_poll`, `formula` |
 | KPI snapshot | `source` | `manual`, `webhook`, `api_poll`, `formula`, `agent` |
+| KPI HTTP sync | `status` | `draft`, `published`, `disabled` |
+| KPI HTTP sync secret | `placement` | `authorization_bearer`, `x_api_key` |
+| KPI HTTP sync run | `status` | `queued`, `running`, `success`, `error` |
 | Initiative | `status` | `proposed`, `active`, `completed`, `paused`, `cancelled` |
 | Status update | `status` | `on_track`, `at_risk`, `off_track` |
 | Member | `role` | `owner`, `admin`, `member`, `guest` |