clickup-agent-cli 0.5.0 → 0.5.2

package/.claude-plugin/marketplace.json

@@ -11,7 +11,7 @@
       "name": "clickup",
       "source": "./",
       "description": "ClickUp CLI with 31 agent skills covering the full API -- token-efficient alternative to MCP with chat, time tracking, docs, and project management workflows",
-      "version": "0.5.0",
+      "version": "0.5.2",
       "homepage": "https://github.com/henryreith/clickup-cli",
       "keywords": ["clickup", "project-management", "tasks", "time-tracking"],
       "category": "productivity"

package/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "clickup",
   "description": "ClickUp CLI with 31 agent skills covering the full API -- token-efficient alternative to MCP with chat, time tracking, docs, and project management workflows",
-  "version": "0.5.0",
+  "version": "0.5.2",
   "author": {
     "name": "Henry Reith"
   },

package/AGENTS.md

@@ -0,0 +1,61 @@
+# ClickUp CLI: Agent Operating Manual
+
+You have (or can install) `clickup`, a command-line tool covering the full ClickUp API v2. This file is the fastest path from zero to productive for any agent on any platform. Everything here works headless.
+
+## Setup
+
+```bash
+npm install -g clickup-agent-cli
+
+# Authenticate: env var (preferred for agents), --token-file, or --token per call
+export CLICKUP_API_TOKEN=pk_your_token
+
+# Verify auth and workspace resolution
+clickup config validate
+
+# One-time workspace binding (auto-selects when the account has one workspace)
+clickup workspace setup
+```
+
+## Discover, never guess
+
+Do not guess command syntax. The CLI is self-describing:
+
+```bash
+clickup skill show clickup          # Root skill: index of all capabilities (~150 tokens)
+clickup skill list                  # All 31 skills (12 resource references, 18 workflows)
+clickup skill show <name>           # Full skill content (JSON with a "content" field when piped)
+clickup skill path <name>           # Skill directory: bundled references/, assets/, scripts/
+clickup schema <resource>           # Actions for a resource (task, list, doc, time, ...)
+clickup schema <resource>.<action>  # Required and optional flags for one action
+```
+
+Skills bundle supporting files per the Agent Skills standard: `assets/report-template.md` (copy the structure for report output), `scripts/*.mjs` (deterministic helpers; pipe JSON in via node), and `references/` (deep detail such as `clickup skill path clickup`/references/gotchas.md).
+
+## Conventions that matter
+
+- **Output**: JSON by default when piped; force with `--format json|table|csv|tsv|quiet|id|md`. `--format id` prints just the first result's ID for capture: `ID=$(clickup task create ... --format id)`.
+- **Exit codes**: 0 ok, 1 general, 2 bad arguments, 3 auth, 4 not found, 5 permission, 6 rate limited, 7 network. Branch on these.
+- **Destructive commands** (`* delete`, `field remove`, `time delete`) require `--confirm` when non-interactive. Pass it deliberately; never bypass a confirmation you were not asked to give.
+- **Dates**: Unix ms/seconds, ISO 8601 (`2026-07-10`), or relative (`today`, `tomorrow`, `3d`, `-1w`, `friday`). Filter flags ending `-gt`/`-lt` take Unix ms only.
+- **Rate limits**: ~100 requests/min; 429s retry automatically. Prefer `task bulk-update`/`task bulk-delete` for batches.
+- **Dry runs**: add `--dry-run` to print the exact request without sending it.
+- Errors and spinners go to stderr; stdout is data only. Safe to pipe.
+
+## Quick example
+
+```bash
+# Find the list, create a task, comment on it
+LIST_ID=$(clickup list list --space-id 123 --filter name="Sprint 12" --format id)
+TASK_ID=$(clickup task create --list-id "$LIST_ID" --name "Fix login redirect" \
+  --priority high --due-date friday --format id)
+clickup comment create --task-id "$TASK_ID" --text "Repro steps in thread"
+```
+
+## For Claude Code specifically
+
+Install as a plugin instead: `/plugin marketplace add henryreith/clickup-cli` then `/plugin install clickup@clickup-agent-cli`. Skills load natively (`/clickup:weekly-review`, etc.).
+
+## Developing this repo
+
+Build/test conventions live in [CLAUDE.md](./CLAUDE.md): `npm run typecheck && npm test && npm run build && npm run lint:skills` must pass. The full command reference is [COMMANDS.md](./COMMANDS.md); architecture is [SPEC.md](./SPEC.md).

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Henry Reith
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,5 +1,11 @@
 # ClickUp CLI
 
+[![npm](https://img.shields.io/npm/v/clickup-agent-cli)](https://www.npmjs.com/package/clickup-agent-cli)
+[![node](https://img.shields.io/node/v/clickup-agent-cli)](https://nodejs.org)
+[![CI](https://github.com/henryreith/clickup-cli/actions/workflows/ci.yml/badge.svg)](https://github.com/henryreith/clickup-cli/actions/workflows/ci.yml)
+[![License: MIT](https://img.shields.io/npm/l/clickup-agent-cli)](./LICENSE)
+[![Agent Skills](https://img.shields.io/badge/agent%20skills-31-blueviolet)](./skills)
+
 Zero-overhead CLI for the ClickUp API v2 -- for AI agents, scripts, and automation. Covers the entire API surface with all MCP capabilities and more.
 
 ## Why This Exists
@@ -187,7 +193,7 @@ This creates `/marketing-weekly` alongside the built-in `/clickup:*` skills.
 
 ### Bootstrap From Any Agent
 
-Any agent that can run shell commands can set up and use the CLI in five steps, no plugin system required:
+The repo and npm package ship an [AGENTS.md](./AGENTS.md) operating manual that agent platforms (Codex, Cursor, Gemini CLI, custom agents) pick up automatically. Any agent that can run shell commands can set up and use the CLI in five steps, no plugin system required:
 
 ```bash
 # 1. Install

package/dist/clickup.js

@@ -4629,7 +4629,7 @@ function registerChatCommands(program, getClient) {
 }
 
 // src/cli.ts
-var VERSION = "0.5.0";
+var VERSION = "0.5.2";
 function createProgram() {
   const program = new Command();
   program.name("clickup").description("ClickUp CLI - Manage ClickUp workspaces from the terminal").version(VERSION).option("--token <token>", "API token").option("--token-file <path>", "Read API token from this file path").option("--profile <name>", "Profile to use (key, workspace name, or nickname)").option("--workspace-id <id>", "Workspace ID").addOption(

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "clickup-agent-cli",
-  "version": "0.5.0",
-  "description": "CLI covering the entire ClickUp API v2 surface",
+  "version": "0.5.2",
+  "description": "Zero-overhead ClickUp CLI for AI agents, shell scripts, and automation. Full ClickUp API v2 coverage with 31 bundled agent skills.",
   "type": "module",
   "bin": {
     "clickup": "dist/clickup.js"
@@ -9,7 +9,8 @@
   "files": [
     "dist",
     "skills",
-    ".claude-plugin"
+    ".claude-plugin",
+    "AGENTS.md"
   ],
   "engines": {
     "node": ">=22.0.0"

package/skills/clickup/SKILL.md

@@ -37,6 +37,8 @@ clickup skill show <name>              # Print a skill's full contents (e.g. cli
 
 Known pitfalls (rate limits, error codes, exit codes, destructive-command rules) live in `references/gotchas.md` next to this file; read it before debugging a failing command (`clickup skill path clickup` prints this skill's directory).
 
+Skills bundle supporting files per the Agent Skills standard: `references/` (deep detail), `assets/` (output templates to copy), and `scripts/` (deterministic helpers to run with node). `clickup skill path <name>` prints any skill's directory so these files can be read or executed directly.
+
 ## Sub-Skills (load when needed)
 
 | Skill | What it covers |

package/skills/clickup-blocker-report/SKILL.md

@@ -6,7 +6,7 @@ disable-model-invocation: true
 context: fork
 agent: general-purpose
 argument-hint: "[workspace-id]"
-allowed-tools: Bash(clickup *)
+allowed-tools: Bash(clickup *), Read
 ---
 
 # Blocker Report
@@ -71,6 +71,8 @@ clickup task bulk-time-in-status --task-id <id1> --task-id <id2> --format json
 
 ### Step 6: Compile the report
 
+Copy the exact structure from `assets/report-template.md` in this skill's directory (`clickup skill path clickup-blocker-report` prints it). Fill every placeholder; drop sections with no content.
+
 - **Blocked tasks**: What, who, and what is blocking them
 - **Stale tasks**: In progress but not updated recently
 - **Overdue + unassigned**: Nobody owns these

package/skills/clickup-blocker-report/assets/report-template.md

@@ -0,0 +1,16 @@
+## Blocker Report: <scope> (<date>)
+
+### Blocked tasks
+- <task> - <assignee>, blocked <n> days, waiting on: <blocker>
+
+### Dependency chains
+- <task A> blocks <task B> blocks <task C> (chain head is <status>)
+
+### Stale (in progress, no updates)
+- <task> - <assignee>, last touched <date>
+
+### Overdue and unassigned (nobody owns these)
+- <task> - due <date> (<list>)
+
+### Escalations needed
+1. <task>: blocked <n> days - <suggested action>

package/skills/clickup-capacity-check/SKILL.md

@@ -6,7 +6,7 @@ disable-model-invocation: true
 context: fork
 agent: general-purpose
 argument-hint: "[workspace-id]"
-allowed-tools: Bash(clickup *)
+allowed-tools: Bash(clickup *), Read
 ---
 
 # Capacity Check
@@ -57,6 +57,8 @@ clickup task search --workspace-id <id> --assignee <user-id> \
 
 ### Step 5: Compile capacity report
 
+Copy the exact structure from `assets/report-template.md` in this skill's directory (`clickup skill path clickup-capacity-check` prints it). Fill every placeholder; drop sections with no content.
+
 For each team member:
 - **Active tasks**: Count and total estimated hours
 - **Time logged this week**: Hours

package/skills/clickup-capacity-check/assets/report-template.md

@@ -0,0 +1,14 @@
+## Capacity Check: <team/scope> (<date>)
+
+| Person | Active tasks | Est. hours | Logged this week | Overdue | Status |
+|--------|--------------|-----------|------------------|---------|--------|
+| <name> | <n> | <n>h | <n>h | <n> | Under / At / Over |
+
+### Overloaded
+- <name>: <what to move and to whom>
+
+### Available bandwidth
+- <name>: <n> open tasks, can take on more
+
+### Suggested rebalance
+1. Move "<task>" from <overloaded> to <available>

package/skills/clickup-goal-progress/SKILL.md

@@ -6,7 +6,7 @@ disable-model-invocation: true
 context: fork
 agent: general-purpose
 argument-hint: "[workspace-id]"
-allowed-tools: Bash(clickup *)
+allowed-tools: Bash(clickup *), Read
 ---
 
 # Goal Progress Report
@@ -56,6 +56,8 @@ clickup task list --list-id <linked-list-id> --include-closed --format json
 
 ### Step 5: Compile the report
 
+Copy the exact structure from `assets/report-template.md` in this skill's directory (`clickup skill path clickup-goal-progress` prints it). Fill every placeholder; drop sections with no content.
+
 For each goal:
 - **Goal name** and due date
 - **Key results**: Current vs. target, % complete

package/skills/clickup-goal-progress/assets/report-template.md

@@ -0,0 +1,13 @@
+## Goal Progress: <scope> (<date>)
+
+| Goal | Due | Progress | Expected | Status |
+|------|-----|----------|----------|--------|
+| <goal> | <date> | <current>/<target> (<x>%) | <y>% | On track / At risk / Behind |
+
+### <goal name>
+- <key result>: <current> of <target> (<x>%)
+- Latest: <most recent note or update>
+- <status rationale in one line>
+
+### Stale goals (no recent key result updates)
+- <goal> - last update <date>

package/skills/clickup-my-day/SKILL.md

@@ -6,7 +6,7 @@ disable-model-invocation: true
 context: fork
 agent: general-purpose
 argument-hint: "[optional: a different person, or 'this week' for a wider window]"
-allowed-tools: Bash(clickup *)
+allowed-tools: Bash(clickup *), Read
 ---
 
 # My Day
@@ -45,19 +45,7 @@ Priority (urgent=1 to low=4) breaks ties inside each bucket.
 
 ### Step 4: Present the agenda
 
-```
-## Your day - <date>
-
-Now: <running timer task, if any>
-
-1. [OVERDUE] <task> - was due <date> (<list>)
-2. [TODAY] <task> - <priority>
-3. ...
-
-Blocked (not actionable): <task> - waiting on <dependency>
-
-Suggestion: <one sentence - e.g. "Clear the two overdue items before starting new work.">
-```
+Copy the exact structure from `assets/report-template.md` in this skill's directory (`clickup skill path clickup-my-day` prints it). Fill every placeholder; drop sections with no content.
 
 Keep it under ~10 items; summarize the rest as "and N more in the backlog".
 

package/skills/clickup-my-day/assets/report-template.md

@@ -0,0 +1,12 @@
+## Your day - <date>
+
+Now: <running timer task, if any>
+
+1. [OVERDUE] <task> - was due <date> (<list>)
+2. [TODAY] <task> - <priority>
+3. [IN PROGRESS] <task> - untouched <n> days
+4. [UP NEXT] <task> - <priority>
+
+Blocked (not actionable): <task> - waiting on <dependency>
+
+Suggestion: <one sentence on what to tackle first>

package/skills/clickup-release-notes/SKILL.md

@@ -6,7 +6,7 @@ disable-model-invocation: true
 context: fork
 agent: general-purpose
 argument-hint: "[period and scope - e.g. 'last sprint for the mobile space', 'June, customer-facing']"
-allowed-tools: Bash(clickup *), Write
+allowed-tools: Bash(clickup *), Write, Read
 ---
 
 # Release Notes
@@ -39,18 +39,7 @@ Group by tags and task names into: **Features**, **Improvements**, **Fixes**, an
 
 Rewrite task names for the audience - "Fix login redirect on Safari" becomes "Fixed an issue where Safari users could be redirected to the wrong page after logging in." Never paste raw task IDs into customer-facing notes.
 
-```markdown
-# Release Notes - <period>
-
-## New
-- ...
-
-## Improved
-- ...
-
-## Fixed
-- ...
-```
+Copy the exact structure from `assets/report-template.md` in this skill's directory (`clickup skill path clickup-release-notes` prints it). Fill every placeholder; drop sections with no content.
 
 For internal notes append task IDs and assignees for traceability.
 

package/skills/clickup-release-notes/assets/report-template.md

@@ -0,0 +1,12 @@
+# Release Notes - <period>
+
+## New
+- <benefit-focused line for each shipped feature>
+
+## Improved
+- <what got better and for whom>
+
+## Fixed
+- <user-visible bug fixes, written as outcomes>
+
+<!-- Internal variant: append task IDs and assignees per line -->

package/skills/clickup-standup/SKILL.md

@@ -6,7 +6,7 @@ disable-model-invocation: true
 context: fork
 agent: general-purpose
 argument-hint: "[scope - e.g. 'my tasks', 'engineering team', user-id]"
-allowed-tools: Bash(clickup *)
+allowed-tools: Bash(clickup *), Read
 ---
 
 # Daily Standup
@@ -74,19 +74,7 @@ clickup time running --workspace-id <id> --assignee <user-id> --format json
 
 ### Step 6: Compile standup
 
-Format as:
-
-```
-**Yesterday:**
-- Completed: [list of finished tasks with names]
-
-**Today:**
-- Working on: [list of in-progress tasks]
-- Due today: [list of tasks due today]
-
-**Blockers:**
-- [list of blocked tasks, if any]
-```
+Copy the exact structure from `assets/report-template.md` in this skill's directory (`clickup skill path clickup-standup` prints it). Fill every placeholder; drop sections with no content.
 
 ## Tips
 

package/skills/clickup-standup/assets/report-template.md

@@ -0,0 +1,9 @@
+**Yesterday:**
+- Completed: <finished task names>
+
+**Today:**
+- Working on: <in-progress tasks>
+- Due today: <tasks due today>
+
+**Blockers:**
+- <blocked tasks, or "None">

package/skills/clickup-team-report/SKILL.md

@@ -6,7 +6,7 @@ disable-model-invocation: true
 context: fork
 agent: general-purpose
 argument-hint: "[team or department name, e.g. 'marketing', 'engineering', 'operations']"
-allowed-tools: Bash(clickup *)
+allowed-tools: Bash(clickup *), Read
 ---
 
 # Team / Department Report
@@ -102,6 +102,8 @@ Filter time entries to those related to the team's tasks.
 
 ### Step 7: Compile the report
 
+Copy the exact structure from `assets/report-template.md` in this skill's directory (`clickup skill path clickup-team-report` prints it). Fill every placeholder; drop sections with no content.
+
 Structure the report as:
 
 - **Team/Department**: Name and scope of what is covered

package/skills/clickup-team-report/assets/report-template.md

@@ -0,0 +1,24 @@
+# <Team> Status Report (<date>)
+
+**Scope:** <spaces/folders/lists covered>
+**Summary:** <2-3 sentences on where things stand>
+
+## By the numbers
+| To do | In progress | Done this week | Overdue |
+|-------|-------------|----------------|---------|
+| <n> | <n> | <n> | <n> |
+
+## Key accomplishments
+- <completed task worth naming> (<assignee>)
+
+## Currently working on
+- <task> - <assignee>, due <date>
+
+## Upcoming deadlines (next 7 days)
+- <task> - due <date>, <assignee>
+
+## Risks and blockers
+- <overdue or blocked item> - <what unblocks it>
+
+## Time invested
+<n> hours logged this period (<top contributors>)

package/skills/clickup-time-audit/SKILL.md

@@ -6,7 +6,7 @@ disable-model-invocation: true
 context: fork
 agent: general-purpose
 argument-hint: "[workspace-id] [start-date] [end-date]"
-allowed-tools: Bash(clickup *)
+allowed-tools: Bash(clickup *), Read
 ---
 
 # Time Audit
@@ -81,6 +81,10 @@ Look for:
 clickup time running --workspace-id <id> --format json
 ```
 
+### Compile the report
+
+Copy the exact structure from `assets/report-template.md` in this skill's directory (`clickup skill path clickup-time-audit` prints it). Fill every placeholder; drop sections with no content.
+
 ## Tips
 
 - Duration is in milliseconds. Divide by 3600000 for hours.

package/skills/clickup-time-audit/assets/report-template.md

@@ -0,0 +1,19 @@
+## Time Audit: <scope> (<period>)
+
+Total logged: <n>h (<m>h billable / <k>h non-billable)
+
+### By person
+| Person | Hours | Billable | Entries |
+|--------|-------|----------|---------|
+| <name> | <n>h | <n>h | <n> |
+
+### Estimate accuracy (actual / estimated)
+- <task>: <actual>h vs <estimated>h (<ratio>)
+
+### Anomalies
+- <entry over 8h - forgot to stop timer?>
+- <entries with no description>
+- <running timers active for days>
+
+### Missing time
+- <tasks that changed status with zero time logged>

package/skills/clickup-timesheet-export/SKILL.md

@@ -6,7 +6,7 @@ disable-model-invocation: true
 context: fork
 agent: general-purpose
 argument-hint: "[period and scope - e.g. 'last week', 'June for Sarah', 'this month billable only']"
-allowed-tools: Bash(clickup *), Write
+allowed-tools: Bash(clickup *), Bash(node *), Write, Read
 ---
 
 # Timesheet Export
@@ -29,38 +29,37 @@ clickup time list --workspace-id <id> \
 
 `--start`/`--end` accept ISO dates (`2026-06-01`), relative forms (`-30d`), or Unix timestamps. Entry durations are milliseconds.
 
-### Step 2: Aggregate
+### Step 2: Aggregate deterministically
 
-Compute from the JSON:
+Never sum hours yourself. Pipe the entries through the bundled script; the math comes out exact:
 
-- Hours per person per day (duration ms / 3,600,000, round to 2 decimals)
-- Hours per task (join `task.id` to task names from the entries)
-- Billable vs non-billable split (the `billable` field)
-- Grand totals
+```bash
+SKILL_DIR=$(clickup skill path clickup-timesheet-export)
+
+# JSON summary: totals, byPerson, byTask, flagged entries
+clickup time list --workspace-id <id> --start <start> --end <end> --format json \
+    | node "$SKILL_DIR/scripts/aggregate.mjs"
+
+# CSV rows for the export file
+clickup time list --workspace-id <id> --start <start> --end <end> --format json \
+    | node "$SKILL_DIR/scripts/aggregate.mjs" --csv
+```
+
+The summary's `flags` field lists running timers (excluded from totals), entries with no task, and entries over 12h.
 
 ### Step 3: Write the export
 
 CSV for spreadsheets (default when the user says export/invoice):
 
-```csv
-date,person,task,description,hours,billable
-2026-06-30,Sarah,Login bug fix,Safari redirect,2.50,true
-```
+Copy the exact structure from `assets/report-template.md` in this skill's directory (`clickup skill path clickup-timesheet-export` prints it). Fill every placeholder; drop sections with no content.
 
 Save with the Write tool as `timesheet-<start>-<end>.csv` and tell the user the path. For a chat answer, use a markdown table plus totals instead.
 
 ### Step 4: Summarize
 
-```
-Timesheet <start> to <end>
-- Total: N hours (M billable / K non-billable)
-- By person: Sarah 32.5h, Tom 28.0h, ...
-- Top tasks: <task> 12.5h, ...
-Flagged: entries with no task attached, running timers still open
-```
+Use the summary block from the same template.
 
 ## Tips
 
-- Entries with a null `end` are running timers; exclude them from totals and flag them.
 - Cross-check suspicious days (over 12h per person) rather than silently exporting them.
 - For a recurring client invoice, filter to the client's space via the task IDs' locations.

package/skills/clickup-timesheet-export/assets/report-template.md

@@ -0,0 +1,9 @@
+date,person,task,description,hours,billable
+2026-06-30,Sarah,Login bug fix,Safari redirect,2.50,true
+
+<!-- Summary block to accompany the CSV: -->
+Timesheet <start> to <end>
+- Total: <n> hours (<m> billable / <k> non-billable)
+- By person: <name> <n>h, ...
+- Top tasks: <task> <n>h, ...
+Flagged: <entries with no task, running timers still open>

package/skills/clickup-timesheet-export/scripts/aggregate.mjs

@@ -0,0 +1,73 @@
+#!/usr/bin/env node
+// Deterministic timesheet aggregation. Pipe `clickup time list ... --format json`
+// into this script; totals come out exact so no arithmetic is done by the agent.
+//
+//   clickup time list --workspace-id X --start -7d --end today --format json \
+//     | node scripts/aggregate.mjs [--csv]
+//
+// Default output: JSON summary (totals, byPerson, byTask, flags).
+// --csv: timesheet rows (date,person,task,description,hours,billable) on stdout.
+
+import { readFileSync } from 'node:fs'
+
+const wantCsv = process.argv.includes('--csv')
+const raw = readFileSync(0, 'utf-8')
+let entries = JSON.parse(raw)
+if (!Array.isArray(entries)) entries = entries.data ?? [entries]
+
+const MS_PER_HOUR = 3_600_000
+const hours = (ms) => Math.round((ms / MS_PER_HOUR) * 100) / 100
+const rows = []
+const flags = { runningTimers: [], noTask: [], over12h: [] }
+const byPerson = {}
+const byTask = {}
+let totalMs = 0
+let billableMs = 0
+
+for (const e of entries) {
+  const duration = Number(e.duration)
+  const person = e.user_name || e.user?.username || 'unknown'
+  const task = e.task?.name || e.task_id || e.task?.id || ''
+  const desc = e.description || ''
+  const billable = e.billable === true || e.billable === 'true'
+
+  if (!e.end || duration < 0) {
+    flags.runningTimers.push({ id: e.id, person, task })
+    continue
+  }
+  if (!task) flags.noTask.push({ id: e.id, person, hours: hours(duration) })
+  if (duration > 12 * MS_PER_HOUR) flags.over12h.push({ id: e.id, person, task, hours: hours(duration) })
+
+  totalMs += duration
+  if (billable) billableMs += duration
+  byPerson[person] = (byPerson[person] ?? 0) + duration
+  byTask[task || '(no task)'] = (byTask[task || '(no task)'] ?? 0) + duration
+
+  const date = new Date(Number(e.start)).toISOString().slice(0, 10)
+  rows.push({ date, person, task, desc, hours: hours(duration), billable })
+}
+
+if (wantCsv) {
+  const esc = (v) => (/[",\n]/.test(String(v)) ? `"${String(v).replace(/"/g, '""')}"` : String(v))
+  process.stdout.write('date,person,task,description,hours,billable\n')
+  for (const r of rows.sort((a, b) => a.date.localeCompare(b.date) || a.person.localeCompare(b.person))) {
+    process.stdout.write([r.date, r.person, r.task, r.desc, r.hours.toFixed(2), r.billable].map(esc).join(',') + '\n')
+  }
+} else {
+  const toHours = (o) => Object.fromEntries(Object.entries(o).sort((a, b) => b[1] - a[1]).map(([k, v]) => [k, hours(v)]))
+  process.stdout.write(
+    JSON.stringify(
+      {
+        entries: rows.length,
+        totalHours: hours(totalMs),
+        billableHours: hours(billableMs),
+        nonBillableHours: hours(totalMs - billableMs),
+        byPerson: toHours(byPerson),
+        byTask: toHours(byTask),
+        flags,
+      },
+      null,
+      2,
+    ) + '\n',
+  )
+}

package/skills/clickup-weekly-review/SKILL.md

@@ -6,7 +6,7 @@ disable-model-invocation: true
 context: fork
 agent: general-purpose
 argument-hint: "[scope - e.g. 'marketing team', space-id, or workspace-id]"
-allowed-tools: Bash(clickup *)
+allowed-tools: Bash(clickup *), Read
 ---
 
 # Weekly Review
@@ -82,6 +82,8 @@ clickup goal list --workspace-id <id> --format json
 
 ### Step 7: Compile the report
 
+Copy the exact structure from `assets/report-template.md` in this skill's directory (`clickup skill path clickup-weekly-review` prints it). Fill every placeholder; drop sections with no content.
+
 Summarize the data into a clear report with sections:
 - **Completed this week**: Count and highlights of finished tasks
 - **In progress**: Tasks actively being worked on

package/skills/clickup-weekly-review/assets/report-template.md

@@ -0,0 +1,26 @@
+# Weekly Review: <scope> (<week-start> to <week-end>)
+
+**Summary:** <2-3 sentences: overall trajectory, the one thing to know>
+
+## By the numbers
+| Metric | This week |
+|--------|-----------|
+| Completed | <n> |
+| In progress | <n> |
+| Overdue | <n> |
+| Hours logged | <n> |
+
+## Completed this week
+- <task name> (<assignee>)
+
+## In progress
+- <task name> - <assignee>, due <date>
+
+## Overdue / Blocked
+- <task name> - due <date>, <why it matters>
+
+## Goal progress
+- <goal>: <current>/<target> (<status>)
+
+## Next week
+- <what is due or planned>

package/skills/clickup-workspace-audit/SKILL.md

@@ -6,7 +6,7 @@ disable-model-invocation: true
 context: fork
 agent: general-purpose
 argument-hint: "[scope - workspace, space name, or list name; optionally 'and fix']"
-allowed-tools: Bash(clickup *)
+allowed-tools: Bash(clickup *), Bash(node *), Read
 ---
 
 # Workspace Audit
@@ -27,9 +27,17 @@ clickup task search --workspace-id <id> --format json
 
 Server-side filters cannot express "no assignee" or "no due date", so fetch active tasks and inspect the JSON client-side. For large workspaces sweep one space at a time (`--space-id`).
 
-### Step 2: Detect problems
+### Step 2: Classify deterministically
 
-Classify each task into any of:
+Pipe the tasks through the bundled script so every task is bucketed by rule, not judgment:
+
+```bash
+SKILL_DIR=$(clickup skill path clickup-workspace-audit)
+clickup task search --workspace-id <id> --format json \
+    | node "$SKILL_DIR/scripts/classify.mjs" [--stale-days 14]
+```
+
+The output contains `activeTasks`, `flaggedTasks`, per-bucket lists, and per-person `load`. The buckets:
 
 | Check | Condition |
 |-------|-----------|
@@ -45,23 +53,7 @@ Tasks with `blocked` or `waiting` status whose blockers are themselves overdue d
 
 ### Step 4: Report
 
-```
-## Workspace Audit: <scope> (<date>)
-
-Overall: N active tasks, M flagged (X%)
-
-### Overdue (worst first)
-- <task> - due <date>, assignee <name> (<id>)
-
-### Unassigned / No due date / Stale
-- ...
-
-### Load
-- <name>: N open tasks (team median: M)
-
-### Recommended fixes
-1. ...
-```
+Copy the exact structure from `assets/report-template.md` in this skill's directory (`clickup skill path clickup-workspace-audit` prints it). Fill every placeholder; drop sections with no content.
 
 ### Step 5: Apply fixes (only when asked)
 

package/skills/clickup-workspace-audit/assets/report-template.md

@@ -0,0 +1,21 @@
+## Workspace Audit: <scope> (<date>)
+
+Overall: <n> active tasks, <m> flagged (<x>%)
+
+### Overdue (worst first)
+- <task> - due <date>, assignee <name> (<id>)
+
+### Unassigned
+- <task> (<list>)
+
+### No due date
+- <task> (<list>)
+
+### Stale (in progress, untouched 14+ days)
+- <task> - last touched <date>
+
+### Load
+- <name>: <n> open tasks (team median: <m>)
+
+### Recommended fixes
+1. <specific action with the command to run>

package/skills/clickup-workspace-audit/scripts/classify.mjs

@@ -0,0 +1,72 @@
+#!/usr/bin/env node
+// Deterministic hygiene classification. Pipe `clickup task search ... --format json`
+// into this script; every task is bucketed by rule, not judgment.
+//
+//   clickup task search --workspace-id X --format json | node scripts/classify.mjs
+//
+// Output: JSON buckets (overdue, unassigned, noDueDate, stale, load) plus counts.
+// --stale-days <n> overrides the 14-day staleness window.
+
+import { readFileSync } from 'node:fs'
+
+const staleIdx = process.argv.indexOf('--stale-days')
+const STALE_DAYS = staleIdx !== -1 ? Number(process.argv[staleIdx + 1]) : 14
+const now = Date.now()
+const staleCutoff = now - STALE_DAYS * 24 * 3_600_000
+
+const raw = readFileSync(0, 'utf-8')
+let tasks = JSON.parse(raw)
+if (!Array.isArray(tasks)) tasks = tasks.tasks ?? [tasks]
+
+const summarize = (t) => ({
+  id: t.id,
+  name: t.name,
+  status: typeof t.status === 'object' ? t.status?.status : t.status,
+  assignees: (t.assignees ?? []).map((a) => a.username ?? a.id),
+  due_date: t.due_date ? new Date(Number(t.due_date)).toISOString().slice(0, 10) : null,
+  list: t.list?.name ?? null,
+})
+
+const buckets = { overdue: [], unassigned: [], noDueDate: [], stale: [] }
+const load = {}
+const isClosed = (t) => {
+  const type = typeof t.status === 'object' ? t.status?.type : undefined
+  const s = (typeof t.status === 'object' ? t.status?.status : t.status ?? '').toLowerCase()
+  return type === 'closed' || type === 'done' || ['closed', 'complete', 'done'].includes(s)
+}
+
+let active = 0
+for (const t of tasks) {
+  if (isClosed(t)) continue
+  active++
+  const s = summarize(t)
+  for (const a of s.assignees) load[a] = (load[a] ?? 0) + 1
+
+  if (s.assignees.length === 0) buckets.unassigned.push(s)
+  if (!t.due_date) buckets.noDueDate.push(s)
+  else if (Number(t.due_date) < now) buckets.overdue.push(s)
+
+  const statusType = typeof t.status === 'object' ? t.status?.type : undefined
+  const updated = Number(t.date_updated)
+  if (statusType === 'custom' || /progress|review|doing/.test((s.status ?? '').toLowerCase())) {
+    if (updated && updated < staleCutoff) buckets.stale.push({ ...s, last_updated: new Date(updated).toISOString().slice(0, 10) })
+  }
+}
+
+buckets.overdue.sort((a, b) => (a.due_date ?? '').localeCompare(b.due_date ?? ''))
+const flagged = new Set([...buckets.overdue, ...buckets.unassigned, ...buckets.noDueDate, ...buckets.stale].map((t) => t.id))
+
+process.stdout.write(
+  JSON.stringify(
+    {
+      activeTasks: active,
+      flaggedTasks: flagged.size,
+      staleDays: STALE_DAYS,
+      counts: Object.fromEntries(Object.entries(buckets).map(([k, v]) => [k, v.length])),
+      load: Object.fromEntries(Object.entries(load).sort((a, b) => b[1] - a[1])),
+      ...buckets,
+    },
+    null,
+    2,
+  ) + '\n',
+)