@atollhq/skill-claude 0.4.14 → 0.4.15

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@atollhq/skill-claude",
-  "version": "0.4.14",
+  "version": "0.4.15",
   "description": "Install the Atoll project management skill for Claude Code",
   "bin": {
     "skill-claude": "bin/install.mjs"
@@ -22,6 +22,9 @@
     "url": "git+https://github.com/atollhq/atoll.git",
     "directory": "packages/skill-claude"
   },
+  "publishConfig": {
+    "access": "public"
+  },
   "license": "MIT",
   "type": "module"
 }

package/skill/SKILL.md

@@ -138,6 +138,8 @@ atoll issue assign ATOLL-42 --to self
 atoll comment add ATOLL-42 --body "Working on this now"
 atoll comment add ATOLL-42 --body "tagging..." --mention-member <member-id>
 atoll comment add ATOLL-42 --body "tagging..." --mention "Raphael Ubales"
+atoll comment add ATOLL-42 --body "Agent update" --source-harness codex --source-thread-id <thread-id>
+atoll comment add ATOLL-42 --body "Continuing this" --reply-to-comment <comment-id>
 
 # --mention-member uses a stable Atoll org member ID; --mention exact-matches display names and fails on ambiguity.
 
@@ -238,7 +240,7 @@ PORT=8787 atoll-mcp
 
 Remote MCP clients call `POST /mcp` with Streamable HTTP and should send `Authorization: Bearer sk_atoll_...` per request. Single-tenant deployments can set `ATOLL_API_KEY` and `ATOLL_ORG_ID` as environment variables.
 
-The MCP server mirrors core CLI workflows with tools such as `atoll_get_heartbeat`, issue/project/goal/KPI/initiative/milestone tools, dependency tools, webhook tools, `atoll_send_feedback`, and `atoll_api_request` for advanced endpoints. `atoll_add_comment` accepts `mentions: [{ "member_id": "member-id" }]` for structured mention fanout; `atoll_update_issue` accepts `comment_body` for durable progress comments.
+The MCP server mirrors core CLI workflows with tools such as `atoll_get_heartbeat`, issue/project/goal/KPI/initiative/milestone tools, dependency tools, webhook tools, `atoll_send_feedback`, and `atoll_api_request` for advanced endpoints. `atoll_add_comment` accepts structured mentions, `reply_to_comment_id`, and explicit agent `source_metadata`; it does not infer harness thread IDs. `atoll_update_issue` accepts `comment_body` for durable progress comments.
 
 Keep Atoll skills separate from the MCP package. Skills are client-side agent guidance; the MCP server is runtime infrastructure for auth, transport, validation, and Atoll API calls.
 
@@ -471,7 +473,7 @@ Full endpoint tables and field schemas:
 | KPIs | POST `.../kpis` | GET `.../kpis` | PATCH `.../kpis/{id}` | DELETE `.../kpis/{id}` |
 | Initiatives | POST `.../initiatives` (`project_id`/`projectId` optional; required for guests) | GET `.../initiatives` (`project_id` optional; required for guests) | PATCH `.../initiatives/{id}` | DELETE `.../initiatives/{id}` |
 | Milestones | POST `.../milestones` | GET `.../milestones` | PATCH `.../milestones/{id}` | DELETE `.../milestones/{id}` |
-| Comments | POST `.../comments` with `{ body, mentions? }` | GET `.../comments` | PATCH `.../comments/{id}` | DELETE `.../comments/{id}` |
+| Comments | POST `.../comments` with `{ body, mentions?, reply_to_comment_id?, source_metadata? }` | GET `.../comments` or `.../comments/{id}` | PATCH `.../comments/{id}` | DELETE `.../comments/{id}` |
 | Subtasks | POST `.../subtasks` | GET `.../subtasks` | PATCH `.../subtasks/{id}` | DELETE `.../subtasks/{id}` |
 
 Initiative create accepts `title` or legacy `name`, plus camelCase aliases `goalId`, `ownerId`, and `targetDate`.
@@ -484,6 +486,10 @@ Comment bodies accept Markdown/plain text or existing rich-text HTML. Atoll stor
 
 Structured mentions are recommended for agents and integrations. Direct comment requests accept `mentions: [{ "member_id": "member-id" }]`; issue updates that create comments accept `comment_mentions: [{ "member_id": "member-id" }]`. `member_id` is the stable Atoll org member ID, not an auth user ID or display name. Markdown and HTML `atoll:member` links remain backward-compatible.
 
+Use `reply_to_comment_id` for a direct reply. List/read responses include the relationship plus `reply_to_comment.source_metadata`, allowing an orchestration agent to route a human reply back to the originating harness thread without a separate run resource.
+
+Agent-authored direct comments may include explicit `source_metadata` with `harness`, `thread_id` and/or `session_id`, and optional `host_id`. Unknown keys are rejected, humans cannot submit agent provenance, and harnesses must supply values explicitly. Never include credentials or secrets. Issue-update comments accept the same object as `comment_source_metadata`.
+
 Responses that create comments include `mentions: { requested, created, skipped }`. Each `skipped[]` entry includes `member_id` and `reason`; reasons are `invalid_member_id`, `not_found`, `self_mention`, `no_project_access`, `guest_unprojected_issue`, `unsupported_member_type`, and `mentions_muted`.
 
 † `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). In the CLI, prefer `atoll issue archive <id>`. Permanent `atoll issue delete <id>` requires `--force` and supports `--dry-run`.

package/skill/references/api-endpoints.md

@@ -145,8 +145,9 @@ Add with `{ "blockedByIssueId": "uuid" }` or `{ "blockingIssueId": "uuid" }`. Ci
 
 | Method | Endpoint | Description |
 |--------|----------|-------------|
-| GET | `/api/orgs/{id}/issues/{issueId}/comments` | List comments |
-| POST | `/api/orgs/{id}/issues/{issueId}/comments` | Add comment (`{ body, mentions? }`) |
+| GET | `/api/orgs/{id}/issues/{issueId}/comments` | List comments with reply and parent routing context |
+| POST | `/api/orgs/{id}/issues/{issueId}/comments` | Add comment (`{ body, mentions?, reply_to_comment_id?, source_metadata? }`) |
+| GET | `/api/orgs/{id}/issues/{issueId}/comments/{commentId}` | Read one comment with reply and parent routing context |
 | PATCH | `/api/orgs/{id}/issues/{issueId}/comments/{commentId}` | Edit comment |
 | DELETE | `/api/orgs/{id}/issues/{issueId}/comments/{commentId}` | Delete comment |
 
@@ -156,6 +157,8 @@ Comment bodies accept Markdown/plain text or existing rich-text HTML. Atoll stor
 
 Structured mentions are recommended for agents and integrations. Direct comment requests accept `mentions: [{ "member_id": "member-id" }]`; issue updates that create comments accept `comment_mentions: [{ "member_id": "member-id" }]`. `member_id` is the stable Atoll org member ID, not an auth user ID or display name. Markdown and HTML `atoll:member` links remain backward-compatible.
 
+Replies use `reply_to_comment_id`. List/read responses include a `reply_to_comment` object containing the parent comment's routing-safe `source_metadata`. Agent-authored comments may submit explicit `source_metadata` with `harness`, `thread_id` and/or `session_id`, and optional `host_id`; unknown keys and human-authored provenance are rejected. The issue-update comment path uses `comment_source_metadata`.
+
 Responses that create comments include `mentions: { requested, created, skipped }`. Each `skipped[]` entry includes `member_id` and `reason`; reasons are `invalid_member_id`, `not_found`, `self_mention`, `no_project_access`, `guest_unprojected_issue`, `unsupported_member_type`, and `mentions_muted`.
 
 ## Subtasks
@@ -346,7 +349,7 @@ Custom statuses per project. Each column defines a valid status value and may in
 
 | Method | Endpoint | Description |
 |--------|----------|-------------|
-| GET | `/api/orgs/{id}/projects/{projectId}/board-views` | List views |
+| GET | `/api/orgs/{id}/projects/{projectId}/board-views` | List board columns and views (`{ columns, views }`) |
 | POST | `/api/orgs/{id}/projects/{projectId}/board-views` | Create view (`{ name, columnIds: [...] }`) |
 | 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) |
@@ -452,11 +455,15 @@ URL must be an HTTPS DNS hostname. IP literals, `localhost`, and `.local` hosts
 | POST | `/api/orgs/{id}/notifications/{notificationId}/ack` | Acknowledge current-member notification |
 | GET | `/api/orgs/{id}/notifications/preferences` | Read current-member notification preferences, including default-on mention notifications |
 | POST | `/api/orgs/{id}/notifications/preferences` | Update current-member notification preferences, including mention opt-out and cleanup |
+| GET | `/api/orgs/{id}/integrations/google-chat` | Read Google Chat integration status (owner/admin) |
+| POST | `/api/orgs/{id}/integrations/google-chat/link-token` | Create a one-time Google Chat connect command for the current member |
+| POST | `/api/orgs/{id}/integrations/google-chat/test-message` | Send a Google Chat test message to the current admin (owner/admin) |
+| POST | `/api/integrations/google-chat/events` | Google Chat app event callback, verified with Google bearer token |
 | GET | `/api/notifications` | List notifications (last 50, unread first) |
 | POST | `/api/notifications/{id}/read` | Mark as read |
 | POST | `/api/notifications/read-all` | Mark all as read |
 
-Current-member notifications can include `mention.created`, `issue.assigned`, `comment.added`, and `issue.status_changed`. Comment writes can request structured mentions with `mentions[].member_id` or `comment_mentions[].member_id`; comment-create responses include mention fanout proof. Notification preferences currently support mention opt-out for `mention.created`. Disabling in-app `mention.created` delivery also attempts to acknowledge that member's currently unread mention notifications; when cleanup succeeds, muted mentions leave both the bell and heartbeat `attention_items`.
+Current-member notifications can include `mention.created`, `issue.assigned`, `comment.added`, and `issue.status_changed`. Comment writes can request structured mentions with `mentions[].member_id` or `comment_mentions[].member_id`; comment-create responses include mention fanout proof. Notification preferences support `in_app` and `google_chat` channels; `google_chat` is currently supported for `mention.created`. Disabling `google_chat` stops future Chat delivery without acknowledging in-app notifications. If `in_app` mentions are muted but `google_chat` mentions are enabled, Atoll can still create an acknowledged notification row for Chat delivery without surfacing it in the bell or heartbeat. Disabling in-app `mention.created` delivery also attempts to acknowledge that member's currently unread mention notifications; when cleanup succeeds, muted mentions leave both the bell and heartbeat `attention_items`. Google Chat user linking uses a one-time `connect <token>` command generated from Profile settings.
 
 ## Agents
 

package/skill/references/api-fields.md

@@ -430,9 +430,9 @@ Proposal JSON currently supports at most one item in each collection: `projects`
 
 Heartbeat is org-scoped, but project-bound goals, KPIs, initiatives, issue health, milestone signals, assigned work, and `project_context` are filtered by the caller's project access. Non-guest members can also see unprojected org-level strategy. Shared initiatives can appear with counts and signals based only on accessible work.
 
-Heartbeat also includes `attention_items` for direct current-member notifications such as mentions, assignments, assignee comments, and creator-visible status changes. Each attention item includes `id`, `source`, `event_type`, `severity`, `action_kind`, resource fields, `target_path`, `created_at`, and `ack_endpoint`; after handling the referenced item, call `ack_endpoint` so the notification is acknowledged and removed from later heartbeat attention results. `attention_summary` includes counts such as `mentions`, `assignments`, `blockers`, and `total_unread`.
+Heartbeat also includes `attention_items` for direct current-member notifications such as mentions, assignments, direct replies, assignee comments, and creator-visible status changes. Each attention item includes `id`, `source`, `event_type`, `severity`, `action_kind`, resource fields, `comment_id`, `reply_to_comment_id`, optional validated parent `routing`, `target_path`, `created_at`, and `ack_endpoint`; after handling the referenced item, call `ack_endpoint` so the notification is acknowledged and removed from later heartbeat attention results. `attention_summary` includes counts such as `mentions`, `assignments`, `blockers`, and `total_unread`.
 
-Current-member notifications can use `event_type` values such as `mention.created`, `issue.assigned`, `comment.added`, and `issue.status_changed`. Notification preferences use `event_type` (currently `mention.created`), `channel` (currently `in_app`), and `enabled` for current-member mention opt-out. Setting `enabled: false` for in-app `mention.created` also attempts to acknowledge that member's currently unread mention notifications; when cleanup succeeds, they no longer appear in notification lists or heartbeat `attention_items`.
+Current-member notifications can use `event_type` values such as `mention.created`, `issue.assigned`, `comment.added`, and `issue.status_changed`. Notification preferences use `event_type`, `channel` (`in_app` or `google_chat`), and `enabled` for current-member delivery preferences. The `google_chat` channel currently supports `mention.created`. Setting `enabled: false` for `google_chat` stops future Chat delivery without acknowledging in-app notifications. Setting `enabled: false` for in-app `mention.created` also attempts to acknowledge that member's currently unread mention notifications; when cleanup succeeds, they no longer appear in notification lists or heartbeat `attention_items`. Google Chat user linking uses a one-time `connect <token>` command generated from Profile settings.
 
 Agents should follow `recommended_action.usage_guidance`: prefer `suggested_write.operation` when it still matches the board, preserve KPI/initiative/initiative-target/why-now/expected-impact/first-step/success-criteria evidence in any write, and avoid copying deferred busywork or unrelated assigned tasks into issue or comment payloads. When `start_work` uses `suggested_write.operation: "issue.update"` with a body, apply the status update and preserve that body as an issue comment; `PATCH /issues/{issueId}` accepts `comment_body` for this same-request progress note.
 
@@ -488,6 +488,10 @@ Each finding carries whichever entity ids apply: `goal_id`, `kpi_id`, `initiativ
 | Task | `priority` | `0` (urgent), `1` (high), `2` (medium), `3` (low) |
 | Task update request | `comment_body` | Optional Markdown/plain text or rich-text HTML comment body created with the issue update; stored and returned as sanitized HTML |
 | Task update request | `comment_mentions[].member_id` | Stable Atoll org member ID to mention in the issue update comment created by `comment_body`; not an auth user ID or display name |
+| Task update request | `comment_source_metadata` | Optional explicit agent provenance using the same validated shape as direct comment `source_metadata` |
+| Comment create request | `reply_to_comment_id` | Optional comment ID that this flat, one-level reply addresses; target must be an active comment on the same task |
+| Comment create request | `source_metadata` | Agent-only explicit routing object: `harness`, `thread_id` and/or `session_id`, optional `host_id`; unknown keys and secrets are not allowed |
+| Comment response | `reply_to_comment` | Parent context including `id`, `body`, `author_type`, and routing-safe `source_metadata` |
 | Comment create request | `mentions[].member_id` | Stable Atoll org member ID to mention in a direct comment API request; recommended for agents and integrations |
 | Comment create response | `mentions.requested` | Count of structured mention targets requested for the created comment |
 | Comment create response | `mentions.created` | Count of mention notifications created or confirmed by the request |