@atollhq/skill-gemini 0.3.1 → 0.4.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@atollhq/skill-gemini",
-  "version": "0.3.1",
+  "version": "0.4.1",
   "description": "Install the Atoll project management integration for Gemini CLI",
   "bin": {
     "skill-gemini": "bin/install.mjs"

package/skill/SKILL.md

@@ -33,6 +33,26 @@ export ATOLL_API_KEY="sk_atoll_..."
 export ATOLL_ORG_ID="..."          # UUID of the org the key belongs to
 ```
 
+For OpenClaw / ClawHub, prefer skill-scoped config in `~/.openclaw/openclaw.json` instead of global shell exports:
+
+```json5
+{
+  skills: {
+    entries: {
+      "atoll-api": {
+        enabled: true,
+        apiKey: "sk_atoll_...",
+        env: {
+          ATOLL_ORG_ID: "..."
+        }
+      }
+    }
+  }
+}
+```
+
+`apiKey` maps to `ATOLL_API_KEY`; optional defaults such as `ATOLL_PROJECT`, `ATOLL_TEAM`, and `ATOLL_BASE_URL` belong under `env`.
+
 **Sanity check** — exercises the org-scoped issues endpoint, not just `/api/auth/me`:
 
 ```bash
@@ -96,9 +116,13 @@ atoll issue view ATOLL-42   # alias kept for humans
 
 # Create a task
 atoll issue create --title "Fix login bug" --status todo --priority 1
+atoll issue upsert --match-title --project <project-id> --title "Fix login bug" --status todo
+atoll issue bulk-create --file ./issues.json --continue-on-error
 
 # Update a task
 atoll issue update ATOLL-42 --status in_progress
+atoll issue upsert ATOLL-42 --status in_progress
+atoll issue bulk-update --file ./updates.json --dry-run
 
 # Assign a task
 atoll issue assign ATOLL-42 --to <user-id>
@@ -107,6 +131,13 @@ atoll issue assign ATOLL-42 --to self
 # Comments
 atoll comment add ATOLL-42 --body "Working on this now"
 
+# Dependencies
+atoll dependency bulk-add --file ./dependencies.json --continue-on-error
+
+# Graph plans
+atoll plan validate --file ./plan.json
+atoll plan apply --file ./plan.json --dry-run
+
 # Safe removal
 atoll issue archive ATOLL-42
 atoll issue unarchive ATOLL-42
@@ -119,6 +150,7 @@ atoll feedback "The status error should list custom board statuses"
 # Projects & milestones
 atoll project list
 atoll milestone list --project <project-id>
+atoll milestone upsert --project <project-id> --name "v1.0" --date 2026-06-01
 ```
 
 Prefer the CLI for routine task operations, heartbeat checks, comments, and feedback. Use direct API calls when the CLI does not expose the needed endpoint yet.
@@ -129,6 +161,77 @@ CLI JSON conventions:
 - 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.
+- `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`.
+
+## AI-Assisted Setup
+
+When a user needs help setting up Atoll, lean into the AI workflow. Atoll is most useful when the user's AI assistant helps turn messy context into projects, issues, goals, KPIs, and agent instructions.
+
+If you are the AI assistant with CLI access, prefer doing the setup directly after confirming the intended org/profile and scope. Start with read-only orientation:
+
+```bash
+atoll auth profiles
+atoll heartbeat --json
+atoll issue list --json --limit 10
+```
+
+If the user is setting up Atoll in another AI tool, give them a copyable prompt. Keep secrets out of chat: tell the user to run auth commands locally and never ask them to paste `sk_atoll_...` keys into a model conversation unless they explicitly choose that risk.
+
+### Prompt: Create the First Board
+
+```text
+I am setting up Atoll for my team. Help me create the first project an AI agent could understand.
+Ask me 3-5 questions about the current push, then propose:
+- one project name
+- the outcome this project should drive
+- 3-5 initial issues with clear titles, context, priorities, and owners if known
+- which issue an agent should pick up first and why
+Keep the setup small. I want a useful first board, not a full migration.
+```
+
+### Prompt: Turn a Project Into Issues
+
+```text
+I have an Atoll project but need help turning it into actionable issues.
+Interview me about the project, then write 5 issues an AI agent could execute.
+For each issue include:
+- title
+- why it matters
+- acceptance criteria
+- suggested priority
+- any context the agent would need before starting
+Make the issues specific enough that I can paste them into Atoll with minimal editing.
+```
+
+### Prompt: Install and Authenticate the CLI
+
+```text
+Help me connect this workspace to Atoll.
+First, explain what the Atoll CLI will let you do and what credentials you need.
+Then walk me through installing @atollhq/cli, adding an agent in Atoll, authenticating with the API key, and running a safe read-only check like `atoll issue list`.
+Do not ask me to paste secrets into chat unless I explicitly choose to. Tell me where to run each command locally.
+```
+
+### Prompt: Run the First Heartbeat
+
+```text
+You are helping me set up Atoll for agentic project management.
+Use the Atoll CLI to orient before doing any work.
+Run `atoll heartbeat`, summarize what you can see, identify the highest-leverage next action, and tell me whether you have enough access to list issues and update your assigned work.
+If anything is missing, explain the exact setup step I need to complete in Atoll.
+```
+
+### Prompt: Draft the Strategy Chain
+
+```text
+Help me define the strategy chain for my Atoll workspace.
+Ask me what business outcome matters most this month, then propose:
+- one goal with a clear target date
+- 1-2 KPIs that show whether we are on pace
+- one initiative expected to move the KPI
+- 3 issues that belong under that initiative
+Keep it practical. I want the smallest strategy layer that would help an AI agent choose better work.
+```
 
 ## Quick Start — API (for advanced use)
 
@@ -228,6 +331,8 @@ Full endpoint tables and field schemas:
 | Comments | POST `.../comments` | GET `.../comments` | 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`.
+
 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). In the CLI, prefer `atoll issue archive <id>`. Permanent `atoll issue delete <id>` requires `--force` and supports `--dry-run`.
@@ -282,4 +387,4 @@ atoll feedback resend fb_123
 - All timestamps are ISO 8601 UTC
 - Board statuses are customizable per project -- query `/board-columns` for available values
 - API changes appear in real-time on the web board
-- List endpoints support `limit` (default 25, max 100) and `offset` pagination
+- 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

@@ -120,6 +120,7 @@ Plan limits are enforced when creating projects, human members, agents/integrati
 - `orderDir` -- `asc` or `desc` (default)
 - `limit` -- max results (default 25, max 100)
 - `offset` -- pagination offset
+- `shape=envelope` or `response_shape=cli` -- opt into CLI-compatible list responses: `{ resource, items, total, limit, offset, nextOffset, truncated, hint }`
 
 **GET task detail** returns enriched data: `milestone`, `assignee`, `assignees`, `sub_tasks`, `issue_labels`, and `isBlocked`.
 
@@ -207,6 +208,8 @@ Roles: `owner`, `admin`, `member`, `guest`.
 | POST | `/api/orgs/{id}/initiatives/{initiativeId}/projects` | Add project to initiative |
 | DELETE | `/api/orgs/{id}/initiatives/{initiativeId}/projects` | Remove project from initiative |
 
+Create accepts `title` or legacy `name`, plus camelCase aliases `goalId`, `ownerId`, and `targetDate`.
+
 ## Initiative Links
 
 | Method | Endpoint | Description |
@@ -328,8 +331,9 @@ Custom statuses per project. Each column defines a valid status value.
 | Method | Endpoint | Description |
 |--------|----------|-------------|
 | GET | `/api/orgs/{id}/issues/{issueId}/pr-links` | List linked pull requests |
+| POST | `/api/orgs/{id}/issues/{issueId}/pr-links` | Attach a GitHub PR URL (`{ url }`) |
 
-PR links are created automatically via the GitHub webhook integration.
+Attach PRs manually with a canonical GitHub pull request URL such as `https://github.com/owner/repo/pull/123`; malformed or non-PR URLs return `400`. PR links can also be created automatically via the GitHub webhook integration.
 
 ## Project Status Updates
 

package/skill/references/api-fields.md

@@ -137,7 +137,7 @@ For portfolio-style initiatives (grouping projects):
 }
 ```
 
-Use `title` for create/update requests; Atoll keeps the legacy `name` field in sync for compatibility.
+Use `title` for create/update requests; create also accepts legacy `name`. Atoll keeps the legacy `name` field in sync for compatibility. Create accepts `goalId`, `ownerId`, and `targetDate` aliases for `goal_id`, `owner_id`, and `target_date`.
 
 Add/remove projects with `{ "project_id": "uuid" }`.
 
@@ -256,7 +256,7 @@ URL must be HTTPS. Response includes `secret` for HMAC signature verification.
 
 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.
+REST list responses use resource-specific keys by default. Main list endpoints support `?shape=envelope` or `?response_shape=cli` to return `{ resource, items, total, limit, offset, nextOffset, truncated, hint }`.
 
 ## Notes