@atollhq/skill-codex 0.1.8 → 0.1.10

package/README.md

@@ -8,6 +8,8 @@ Gives your Codex agent the ability to manage tasks, goals, KPIs, initiatives, mi
 
 ```bash
 npx @atollhq/skill-codex --key sk_atoll_... --org your-org-id
+# or
+ATOLL_API_KEY=sk_atoll_... ATOLL_ORG_ID=your-org-id npx @atollhq/skill-codex
 ```
 
 Get an API key from **Settings > Members > Add Agent** (or **Create API Key** for integrations) in the Atoll app.
@@ -29,6 +31,7 @@ Once installed, ask Codex anything task-related:
 "List my Atoll tasks"
 "Create an issue to fix the login bug, priority 1"
 "What goals are off pace?"
+"Check my Atoll heartbeat"
 "Move ATOLL-42 to in_progress"
 ```
 
@@ -40,7 +43,9 @@ For terminal-first work, see [`@atollhq/cli`](https://www.npmjs.com/package/@ato
 npm install -g @atollhq/cli
 atoll auth login --key sk_atoll_...
 atoll config set-org your-org-slug
-atoll issue list
+atoll heartbeat
+atoll issue list --json
+atoll agent-context
 ```
 
 For multiple agents or orgs, use CLI auth profiles:
@@ -51,6 +56,14 @@ atoll auth login --profile agent-b --key sk_atoll_... --org client
 atoll --profile agent-b issue list
 ```
 
+The companion CLI also supports safer issue removal and local/upstream feedback:
+
+```bash
+atoll issue archive ATOLL-42
+atoll issue delete ATOLL-42 --dry-run
+atoll feedback "The heartbeat output should include blocked issue details"
+```
+
 ## License
 
 MIT

package/bin/install.mjs

@@ -20,10 +20,11 @@ function parseArgs(argv) {
 function printUsage() {
   console.log(`
 Usage: npx @atollhq/skill-codex --key <api-key> --org <org-id>
+   or: ATOLL_API_KEY=<api-key> ATOLL_ORG_ID=<org-id> npx @atollhq/skill-codex
 
 Options:
-  --key   Atoll API key (sk_atoll_...)
-  --org   Organization ID
+  --key   Atoll API key (sk_atoll_...). Defaults to ATOLL_API_KEY.
+  --org   Organization ID. Defaults to ATOLL_ORG_ID.
   --help  Show this help message
 
 Installs the Atoll integration for Codex CLI:
@@ -34,11 +35,13 @@ Installs the Atoll integration for Codex CLI:
 }
 
 const args = parseArgs(process.argv)
+args.key ??= process.env.ATOLL_API_KEY
+args.org ??= process.env.ATOLL_ORG_ID
 
 if (args.help) { printUsage(); process.exit(0) }
 
 if (!args.key || !args.org) {
-  console.error('Error: --key and --org are required\n')
+  console.error('Error: provide --key and --org, or set ATOLL_API_KEY and ATOLL_ORG_ID\n')
   printUsage()
   process.exit(1)
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@atollhq/skill-codex",
-  "version": "0.1.8",
+  "version": "0.1.10",
   "description": "Install the Atoll project management integration for Codex CLI",
   "bin": {
     "skill-codex": "bin/install.mjs"

package/skill/SKILL.md

@@ -75,12 +75,20 @@ atoll --profile agent-b issue list
 Common commands:
 
 ```bash
+# Agent orientation
+atoll heartbeat
+atoll heartbeat --signals-only
+atoll heartbeat --severity critical
+atoll heartbeat --json
+atoll agent-context
+
 # List tasks
-atoll issue list
-atoll issue list --status todo --priority 1
+atoll issue list --json
+atoll issue list --status todo --priority 1 --limit 25
 
 # View a task
-atoll issue view ATOLL-42
+atoll issue get ATOLL-42
+atoll issue view ATOLL-42   # alias kept for humans
 
 # Create a task
 atoll issue create --title "Fix login bug" --status todo --priority 1
@@ -95,11 +103,29 @@ atoll issue assign ATOLL-42 --to self
 # Comments
 atoll comment add ATOLL-42 --body "Working on this now"
 
+# Safe removal
+atoll issue archive ATOLL-42
+atoll issue unarchive ATOLL-42
+atoll issue delete ATOLL-42 --dry-run
+atoll issue delete ATOLL-42 --force
+
+# Report friction to Atoll maintainers
+atoll feedback "The status error should list custom board statuses"
+
 # Projects & milestones
 atoll project list
 atoll milestone list --project <project-id>
 ```
 
+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.
+
+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.
+
 ## Quick Start — API (for advanced use)
 
 All CLI commands map to REST endpoints. Use the API directly when the CLI doesn't cover a specific operation.
@@ -119,7 +145,7 @@ atoll "/api/orgs/$ATOLL_ORG_ID/issues?status=todo"
 
 ## The Heartbeat Loop
 
-The primary pattern for autonomous agents. `GET /api/orgs/{id}/heartbeat` returns a computed briefing:
+The primary pattern for autonomous agents. Prefer `atoll heartbeat --json` when the CLI is available; it wraps `GET /api/orgs/{id}/heartbeat` and returns the same computed briefing:
 
 - **Goal status** with days remaining
 - **KPI pace**: `pace_needed` vs `pace_actual`, trend (`accelerating`/`decelerating`/`flat`), staleness
@@ -129,6 +155,15 @@ The primary pattern for autonomous agents. `GET /api/orgs/{id}/heartbeat` return
 
 Signal types: `kpi_off_pace`, `kpi_stale`, `issue_stale`, `issue_blocked`, `milestone_overdue`, `initiative_stalled`, `webhook_failing`. Severity: `info`, `warning`, `critical`.
 
+Useful CLI forms:
+
+```bash
+atoll heartbeat
+atoll heartbeat --signals-only
+atoll heartbeat --severity critical
+atoll heartbeat --json
+```
+
 **The agent loop:**
 1. Call heartbeat
 2. Read signals (highest severity first)
@@ -141,7 +176,8 @@ Signal types: `kpi_off_pace`, `kpi_stale`, `issue_stale`, `issue_blocked`, `mile
 ### Pick up and complete a task
 
 ```bash
-atoll issue list --status todo --assignee self        # find assigned work
+atoll heartbeat --signals-only                        # orient first
+atoll issue list --status todo --assignee self --json # find assigned work
 atoll issue update ATOLL-42 --status in_progress      # start work
 atoll comment add ATOLL-42 --body "Progress update…"  # report progress
 atoll issue update ATOLL-42 --status done              # complete
@@ -190,7 +226,7 @@ Full endpoint tables and field schemas:
 
 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).
+† `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`.
 
 ### Quick enum reference
 
@@ -226,6 +262,14 @@ curl -X POST https://atollhq.com/api/feedback \
 
 No authentication required. Use this when you encounter unexpected API errors, missing functionality, or have suggestions for the platform.
 
+The CLI can record the same feedback locally, and optionally submit upstream:
+
+```bash
+atoll feedback "The /issues endpoint returns 500 when filtering by milestoneId and status together"
+atoll feedback --send "heartbeat should emit issue_blocked signals directly"
+atoll feedback list --json
+```
+
 ## Notes
 
 - Request bodies accept camelCase; responses use snake_case

package/skill/references/api-endpoints.md

@@ -231,6 +231,14 @@ Returns computed briefing with goal status, KPI pace/trend, initiative progress,
 
 Signal types: `kpi_off_pace`, `kpi_stale`, `issue_stale`, `issue_blocked`, `milestone_overdue`, `initiative_stalled`, `webhook_failing`. Severity: `info`, `warning`, `critical`.
 
+CLI equivalent:
+
+```bash
+atoll heartbeat --json
+atoll heartbeat --signals-only
+atoll heartbeat --severity critical
+```
+
 ## Activity
 
 | Method | Endpoint | Description |
@@ -419,3 +427,11 @@ No authentication required. Sends feedback to the Atoll team's internal board.
 | Method | Endpoint | Description |
 |--------|----------|-------------|
 | POST | `/api/feedback` | Submit bug report or feature request (`{ type, description, userEmail?, userName?, url? }`)
+
+CLI equivalent:
+
+```bash
+atoll feedback "Describe the bug or feature request"
+atoll feedback --send "Submit upstream as well"
+atoll feedback list --json
+```