@atollhq/skill-claude 0.4.4 → 0.4.6

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@atollhq/skill-claude",
-  "version": "0.4.4",
+  "version": "0.4.6",
   "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"
@@ -171,10 +172,34 @@ CLI JSON conventions:
 
 - Use `--json` for machine-readable output.
 - List commands return `{ resource, items, total, limit, offset, nextOffset, truncated, hint }`.
+- Project-scoped `atoll issue list --json` includes `project_context`; `atoll issue get/view --json` includes `status_column` plus `project_context` when available.
 - 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.
@@ -287,6 +312,7 @@ The primary pattern for autonomous agents. Prefer `atoll heartbeat --json` when
 - **KPI pace**: `pace_needed` vs `pace_actual`, trend (`accelerating`/`decelerating`/`flat`), staleness
 - **Initiative progress**: total/completed/stalled/blocked issue counts, expected KPI impacts
 - **Assigned work** for this agent
+- **Project context**: relevant board columns, including optional descriptions that explain stage criteria for agents
 - **Signals** sorted by severity — the agent's prioritized to-do list
 
 Signal types: `kpi_off_pace`, `kpi_stale`, `issue_stale`, `issue_blocked`, `milestone_overdue`, `initiative_stalled`, `webhook_failing`. Severity: `info`, `warning`, `critical`.
@@ -322,7 +348,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
@@ -446,6 +472,6 @@ atoll feedback resend fb_123
 - Request bodies accept camelCase; responses use snake_case
 - Descriptions and comments support Markdown
 - All timestamps are ISO 8601 UTC
-- Board statuses are customizable per project -- query `/board-columns` for available values
+- Board statuses are customizable per project -- query `/board-columns` for available values and optional column descriptions
 - API changes appear in real-time on the web board
 - List endpoints support `limit` (default 25, max 100), `offset` pagination, and optional `shape=envelope` / `response_shape=cli` for `{ resource, items, total, limit, offset, nextOffset, truncated, hint }`

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
 
@@ -288,13 +303,14 @@ Filters: `by_me` = your actions; `mine` = activity on issues assigned to you.
 
 ## Board Columns
 
-Custom statuses per project. Each column defines a valid status value.
+Custom statuses per project. Each column defines a valid status value and may include an optional `description` for stage criteria or agent guidance.
 
 | Method | Endpoint | Description |
 |--------|----------|-------------|
 | GET | `/api/orgs/{id}/projects/{projectId}/board-columns` | List columns (ordered by position) |
-| POST | `/api/orgs/{id}/projects/{projectId}/board-columns` | Create column (`{ key, label, color?, position? }`) |
-| PATCH | `/api/orgs/{id}/projects/{projectId}/board-columns/{columnId}` | Update column |
+| GET | `/api/orgs/{id}/projects/{projectId}/board-context` | Get board milestone and initiative focus context |
+| POST | `/api/orgs/{id}/projects/{projectId}/board-columns` | Create column (`{ key, label, description?, color?, position? }`) |
+| PATCH | `/api/orgs/{id}/projects/{projectId}/board-columns/{columnId}` | Update column (`{ label?, description?, color?, position? }`) |
 | DELETE | `/api/orgs/{id}/projects/{projectId}/board-columns/{columnId}` | Delete column (requires `reassignTo` in body) |
 | PUT | `/api/orgs/{id}/projects/{projectId}/board-columns/reorder` | Bulk reorder (`{ columns: [{id, position}] }`) |
 
@@ -304,7 +320,7 @@ Custom statuses per project. Each column defines a valid status value.
 |--------|----------|-------------|
 | GET | `/api/orgs/{id}/projects/{projectId}/board-views` | List views |
 | POST | `/api/orgs/{id}/projects/{projectId}/board-views` | Create view (`{ name, columnIds: [...] }`) |
-| PATCH | `/api/orgs/{id}/projects/{projectId}/board-views/{viewId}` | Update view |
+| PATCH | `/api/orgs/{id}/projects/{projectId}/board-views/{viewId}` | Update view (`{ name?, columnIds? }`; at least one required, `columnIds` must be an array) |
 | DELETE | `/api/orgs/{id}/projects/{projectId}/board-views/{viewId}` | Delete view (cannot delete default) |
 
 ## Custom Views

package/skill/references/api-fields.md

@@ -9,6 +9,7 @@
 - [Initiative Fields](#initiative-fields)
 - [Automation Rule Fields](#automation-rule-fields)
 - [Custom View Fields](#custom-view-fields)
+- [Board Context Response](#board-context-response)
 - [Webhook Fields](#webhook-fields)
 - [Setup Proposal Fields](#setup-proposal-fields)
 - [Heartbeat Response](#heartbeat-response)
@@ -100,6 +101,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 +131,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
@@ -172,6 +223,49 @@ Add/remove projects with `{ "project_id": "uuid" }`.
 
 `display_mode`: `board`, `list`. `filters` and `sort` are freeform JSON.
 
+## Board Context Response
+
+`GET /api/orgs/{id}/projects/{projectId}/board-context` returns the strategy data used by the board context rail:
+
+```json
+{
+  "strategyContext": {
+    "milestones": [{
+      "id": "milestone-uuid",
+      "name": "Public beta",
+      "status": "active",
+      "issueCount": 4,
+      "completedCount": 2,
+      "progress": 50,
+      "linkedInitiatives": [{
+        "id": "initiative-uuid",
+        "title": "Activation launch",
+        "status": "active",
+        "progress": 40,
+        "kpiImpactCount": 1,
+        "linkedMilestoneIds": ["milestone-uuid"]
+      }]
+    }],
+    "initiatives": [{
+      "id": "initiative-uuid",
+      "title": "Activation launch",
+      "status": "active",
+      "issueCount": 5,
+      "completedCount": 2,
+      "progress": 40,
+      "kpiImpactCount": 1,
+      "linkedMilestoneIds": ["milestone-uuid"]
+    }],
+    "issueInitiativeLinks": [{
+      "issueId": "issue-uuid",
+      "initiativeIds": ["initiative-uuid"]
+    }]
+  }
+}
+```
+
+`issueInitiativeLinks` includes direct `initiative_issues` links and links inherited from an issue's milestone.
+
 ## Webhook Fields
 
 ```json
@@ -236,6 +330,15 @@ Proposal JSON currently supports at most one item in each collection: `projects`
   }],
   "standalone_kpis": [...],
   "assigned_issues": [...],
+  "project_context": [{
+    "project_id": "...",
+    "project_name": "Product",
+    "board_columns": [{
+      "key": "approval_gate",
+      "label": "Approval Gate",
+      "description": "Use when implementation is complete but needs approval."
+    }]
+  }],
   "signals": [
     { "type": "kpi_off_pace", "severity": "warning", "message": "..." }
   ]
@@ -288,6 +391,7 @@ Each finding carries whichever entity ids apply: `goal_id`, `kpi_id`, `initiativ
 | Domain | Field | Values |
 |--------|-------|--------|
 | Task | `status` | `backlog`, `todo`, `in_progress`, `done`, `cancelled` (custom per project via board-columns) |
+| Board column | `description` | Optional stage criteria or agent guidance |
 | Task | `priority` | `0` (urgent), `1` (high), `2` (medium), `3` (low) |
 | Task | `recurrenceType` | `daily`, `weekly`, `monthly`, `yearly` |
 | Goal | `status` | `active`, `achieved`, `missed`, `paused`, `cancelled` |
@@ -295,6 +399,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` |
@@ -314,7 +421,7 @@ REST list responses use resource-specific keys by default. Main list endpoints s
 
 - All timestamps are ISO 8601 in UTC
 - Description and comment fields support Markdown
-- Board columns (statuses) are customizable per project -- query `/board-columns` for available statuses
+- Board columns (statuses) are customizable per project -- query `/board-columns` for available statuses and optional descriptions
 - Default statuses for new projects: `backlog`, `todo`, `in_progress`, `done`
 - `cancelled` is always valid but not shown on the board
 - Agent actions appear in the activity feed with the agent's name