@elevasis/sdk 1.5.3 → 1.5.4

package/reference/claude-config/skills/project/SKILL.md

@@ -0,0 +1,918 @@
+---
+name: project
+description: "Portfolio- and project-level work management -- orientation, intent routing, active projects, milestones, tasks, notes, and resume context -- via the elevasis-sdk project:* CLI."
+argument-hint: "[create | list | work | add | update | status | note | milestone | task | delete] [args]"
+allowed-tools: Bash, Read, Write, Edit, Glob, Grep
+---
+
+# Project Management (Portfolio + Per-Project)
+
+`/project` is the primary work-tracking entrypoint for the template. It covers:
+
+- **Portfolio orientation** — bare `/project` invocation shows the landscape of active work and suggests next actions.
+- **Intent routing** — on an opening message that reads as "do work", decide new-vs-resume and route accordingly.
+- **New-work flow** — when the user starts multi-step work without a project, ask: create project, link existing, or standalone.
+- **CRUD surface** — projects, milestones, tasks, notes, checklists via `elevasis-sdk project:*`.
+
+> **Note:** the template no longer ships a separate `/work` skill. Project tasks are the unit of work; use `/project task:*` operations for task lifecycle. Resume context is canonical in `prj_tasks.resume_context` and written via `project:task:save` (never via task-doc frontmatter).
+
+**Usage:**
+
+- `/project` — **Portfolio orientation** (see "Orientation Mode" below). List active/blocked projects, surface most-recently-touched project's `resume_context`, suggest next actions.
+- `/project list` — Same as no-args orientation but just the project table, no suggestions.
+- `/project work <query>` — Fuzzy-match a project/task and print a resume brief (wraps `project:work`).
+- `/project status [<client>]` — Detailed status across all projects, or a single project.
+- `/project create` — Guided project creation (QnA walkthrough).
+- `/project add "Client Name" [--status active] [--value 5000]` — Quick create (flags only, no QnA).
+- `/project update <client> --status on_track` — Update project fields.
+- `/project milestone add <client> "Phase 1" [--due 2026-05-01]` — Add milestone.
+- `/project milestone update <client> "Phase 1" --status completed` — Update milestone.
+- `/project task add <client> "API docs" --milestone "Phase 1" [--type documentation]` — Add task.
+- `/project task update <client> "API docs" --status approved` — Update task.
+- `/project task save <task> --current-state "..."` — Persist `resume_context` (use this, never task-doc frontmatter).
+- `/project note <client> "Kickoff call went well" [--type call_note]` — Add note.
+- `/project notes <client>` — List notes for project.
+- `/project checklist <client> "<milestone>"` — View checklist for a milestone.
+- `/project delete <client>` — Delete project (cascades milestones, tasks, notes).
+
+---
+
+## Orientation Mode (bare `/project` invocation)
+
+When invoked without a subcommand, enter **project mode**: present the portfolio landscape and offer next actions. This is the hub — distinct from `project:work <id>`, which is single-task resume.
+
+### Flow
+
+1. **List active work** — run:
+
+   ```bash
+   pnpm -C operations exec elevasis-sdk project:list --status active,blocked --format brief
+   ```
+
+   Show a compact table: client, status, last-touched.
+
+2. **Surface most-recently-touched project's resume context** — identify the top row (most recent `updated_at`), then print its latest task's `resume_context` (via `project:task:list` → pick most recent in-progress task → `project:task:resume <id> --pretty`). Keep it short: current state + next steps, no files dump.
+
+3. **List available operations** — a one-liner reminder of what the user can do from here:
+
+   ```
+   Available: /project status <client> | /project work <query> | /project task add | /project note | /project create
+   ```
+
+4. **Offer next-action suggestions** — 1-3 concrete follow-ups driven by what's on screen. Examples:
+   - "3 active projects, 1 blocked (Acme — waiting on credentials). Resume Beta (most recent)?"
+   - "No active projects. Create one with `/project create`?"
+   - "Acme's Phase 2 has 2 overdue tasks. Open status?"
+
+### Presentation template
+
+```
+Project Portfolio (2 active, 1 blocked)
+=======================================
+| Client       | Status   | Last touched |
+|--------------|----------|--------------|
+| Beta LLC     | on_track | 2h ago       |
+| Acme Corp    | blocked  | 1d ago       |
+| Gamma Inc    | active   | 4d ago       |
+
+Most recent: Beta LLC — API integration
+  Current: Endpoint wired, tests passing locally.
+  Next:    Deploy to staging, verify webhook delivery.
+
+Next? Resume Beta | Status Acme (why blocked?) | Create new project
+```
+
+---
+
+## Intent Detection (opening-message routing)
+
+Apply this heuristic on the user's first substantive message of a session, before branching into any other operation. The goal: distinguish **resume existing work** from **start new work**, and confirm before committing.
+
+### Signals → classification
+
+| Signal in opening message                                                                       | Classify as                        |
+| ----------------------------------------------------------------------------------------------- | ---------------------------------- |
+| References a specific file path, PR, commit, or existing task/milestone/project by name         | **Resume**                         |
+| "Continue", "pick up", "finish", "the thing we were doing", "yesterday's work"                  | **Resume**                         |
+| "Let's build X", "new Y", "I want to add Z", "start a new project", "help me with a new client" | **New work**                       |
+| Single-file cosmetic ask: "fix typo in X", "rename Y", "update dep Z"                           | **Trivial** (skip new-work prompt) |
+| Ambiguous / discussion only                                                                     | Ask before routing                 |
+
+### Routing
+
+- **Resume** — run `project:work <query>` with the extracted entity (file path stem, project name, task keywords). If one clean match, print the brief and ask "Continue here?". If multiple matches, show top 3 and ask which. If zero matches, fall back to orientation mode with a note ("No match for 'acme webhook'; here's the landscape").
+- **New work** — enter the **New-Work Project Decision** flow (next section).
+- **Trivial** — proceed directly; do not prompt about projects. Small single-file edits don't need portfolio tracking.
+- **Ambiguous** — reply with orientation mode output and ask "Resume something, or start new?"
+
+**Always confirm before branching.** A misclassified "new" routed as "resume" burns trust faster than a one-line confirmation.
+
+---
+
+## New-Work Project Decision
+
+When intent detection classifies the opening ask as **new multi-step work** and the conversation has no established project context, ask this question before writing any code:
+
+```
+Scope this work under a project?
+  a) Create new project "<proposed-slug>"     (recommended for multi-step work)
+  b) Link to existing "<closest-match>"       (if fuzzy-search finds one)
+  c) Standalone — no project tracking         (one-off / trivial)
+```
+
+### Rules
+
+- **Default to (a)** when the ask is multi-step (multiple files, multiple sessions expected, client-facing deliverable).
+- **Offer (b)** only when `project:list` fuzzy-matches produce a plausible candidate (name similarity, shared entity references). If nothing matches, omit the option — do not invent one.
+- **Skip the prompt entirely** for trivial single-file edits — intent detection's "Trivial" branch handles this.
+- **Propose a slug** by extracting the core noun from the ask. "Build a lead scraper for Acme" → `acme-lead-scraper`. User can override.
+
+### After the decision
+
+- **(a) Create** — invoke the guided `/project create` QnA flow (see below), pre-filling the name/description from the ask.
+- **(b) Link** — run `project:resolve <query>` to confirm the match, then add a task to that project for the new work via `project:task:create`.
+- **(c) Standalone** — proceed without project tracking. Do not create orphan task docs; standalone work leaves no artifact.
+
+---
+
+## Connection
+
+### Environment
+
+```bash
+# .env (project root)
+ELEVASIS_PLATFORM_KEY=sk_...
+```
+
+`ELEVASIS_PLATFORM_KEY` is read from the environment automatically. The SDK CLI walks up
+directories to find `.env`, so it resolves correctly from both the project root and
+`operations/`. `ELEVASIS_API_URL` defaults to `https://api.elevasis.io` (production). Set
+`ELEVASIS_API_URL=http://localhost:5170` to target a local API instance, or set
+`NODE_ENV=development` if the SDK CLI respects that convention.
+
+No `--prod` flag is needed — the template targets production by default via `ELEVASIS_API_URL`.
+
+### CLI Invocation
+
+All project operations go through the `elevasis-sdk` CLI installed in `operations/`. Run every
+command from the template project root using `-C operations`:
+
+```bash
+pnpm -C operations exec elevasis-sdk project:<command> [args]
+```
+
+Organization scoping is handled server-side via `ELEVASIS_PLATFORM_KEY`. No org header or
+`--org` flag is required.
+
+---
+
+## Database Schema
+
+### Tables
+
+| Table            | Purpose                      | Key Columns                                                           |
+| ---------------- | ---------------------------- | --------------------------------------------------------------------- |
+| `prj_projects`   | Client projects/contracts    | name, kind, status, description, contract_value, start/end dates      |
+| `prj_milestones` | Phases within projects       | name, status, due_date, sequence, completed_at, checklist             |
+| `prj_tasks`      | Work items within milestones | name, status, type, due_date, milestone_id, resume_context, checklist |
+| `prj_notes`      | Meeting notes, updates       | type, content, summary, occurred_at, task_id, milestone_id            |
+
+### Project Kind
+
+| Kind                | Description                      |
+| ------------------- | -------------------------------- |
+| `client_engagement` | External client delivery project |
+| `internal`          | Internal project work            |
+| `research`          | Research and investigation       |
+| `other`             | Catch-all                        |
+
+Default filter for `/project` operations is `kind=client_engagement` unless the user's intent
+is clearly internal or `--kind` is specified explicitly.
+
+### Status Values
+
+| Entity    | Values                                                                                                                   |
+| --------- | ------------------------------------------------------------------------------------------------------------------------ |
+| Project   | `active`, `on_track`, `at_risk`, `blocked`, `completed`, `paused`                                                        |
+| Milestone | `upcoming`, `in_progress`, `completed`, `overdue`, `blocked`                                                             |
+| Task      | `planned`, `in_progress`, `blocked`, `completed`, `cancelled`, `submitted`, `approved`, `rejected`, `revision_requested` |
+| Note type | `call_note`, `status_update`, `issue`, `blocker`, `agent_learning`                                                       |
+| Task type | `documentation`, `code`, `report`, `design`, `refactor`, `feature`, `bug`, `research`, `other`                           |
+
+### Checklist Shape
+
+Both `prj_milestones.checklist` and `prj_tasks.checklist` store a JSONB array of objects with this shape:
+
+```json
+[
+  { "id": "uuid", "label": "Item label", "completed": false },
+  { "id": "uuid", "label": "Another item", "completed": true }
+]
+```
+
+The CLI `--checklist` flag on both `project:milestone:update` and `project:task:update` performs a **full replace** — the entire array is replaced with the JSON you supply. There are no item-level add/toggle/remove flags. To mutate a single item:
+
+1. Read the current checklist (via psql or `project:task:get` / `project:milestone:list`)
+2. Mutate the array in memory (append, flip `completed`, filter out)
+3. Write the entire array back via `--checklist '<json>'`
+
+To clear a checklist: `--checklist '[]'`.
+
+### Foreign Keys
+
+- `prj_milestones.project_id` → `prj_projects.id` (CASCADE)
+- `prj_tasks.project_id` → `prj_projects.id` (CASCADE)
+- `prj_tasks.milestone_id` → `prj_milestones.id` (SET NULL)
+- `prj_tasks.parent_task_id` → `prj_tasks.id` (SET NULL) — for subtasks
+- `prj_notes.project_id` → `prj_projects.id` (CASCADE)
+- `prj_notes.task_id` → `prj_tasks.id` (SET NULL)
+- `prj_notes.milestone_id` → `prj_milestones.id` (SET NULL)
+- `prj_projects.deal_id` → `acq_deals.id` (SET NULL)
+- `prj_projects.client_company_id` → `acq_companies.id` (SET NULL)
+
+---
+
+## Operations
+
+### `list` — Portfolio Table (no orientation extras)
+
+For a plain project table without resume context or next-action suggestions (use the bare `/project` orientation mode above when the user wants the full hub experience):
+
+```bash
+pnpm -C operations exec elevasis-sdk project:list --kind client_engagement --pretty
+```
+
+Present as:
+
+```
+Project Portfolio
+=================
+| Client             | Status   | Kind               | Value   |
+|--------------------|----------|--------------------|---------|
+| Acme Corp          | on_track | client_engagement  | $5,000  |
+| Beta LLC           | active   | client_engagement  | $3,500  |
+```
+
+For progress detail (milestones/tasks), follow up with `project:milestone:list` and
+`project:task:list` per project.
+
+### `work <query>` — Resume Brief
+
+Wraps `project:work` for fuzzy-matched resume. Used by intent-detection "resume" classification.
+
+```bash
+pnpm -C operations exec elevasis-sdk project:work <query> --pretty
+```
+
+Prints the matched project/task brief with current `resume_context`. If multiple matches, show top 3 and ask which.
+
+### `status [<client>]` — Detailed Status
+
+If client specified, show full detail for that project. If not, show all.
+
+**Resolve the project first** (see Client Inference below), then:
+
+```bash
+# Get project details
+pnpm -C operations exec elevasis-sdk project:get <project-id>
+
+# Milestones (ordered by sequence)
+pnpm -C operations exec elevasis-sdk project:milestone:list --project <project-id> --pretty
+
+# Tasks (grouped by milestone)
+pnpm -C operations exec elevasis-sdk project:task:list --project <project-id> --pretty
+
+# Recent notes
+pnpm -C operations exec elevasis-sdk project:note:list --project <project-id> --pretty
+```
+
+Present as:
+
+```
+Acme Corp — On Track
+=====================
+Description: Automation project for AI-powered workflows
+Contract: $5,000 | Started: 2026-04-01 | Target: 2026-06-01
+
+Milestones (2/4 complete)
+  [x] Phase 1: Discovery (completed)
+  [>] Phase 2: Implementation (in_progress, due 2026-05-01)
+  [ ] Phase 3: Testing (upcoming, due 2026-05-15)
+  [ ] Phase 4: Launch (upcoming, due 2026-06-01)
+
+Tasks (3/8 approved)
+  Phase 2: Implementation
+    [approved] Requirements doc (documentation)
+    [in_progress] API integration (code, due 2026-05-01)
+    [planned] User guide (documentation)
+
+Recent Notes
+  2026-04-05 [call_note] Weekly check-in — on track, API work started
+  2026-04-01 [call_note] Kickoff — confirmed scope and timeline
+```
+
+### `create` — Guided Project Creation (QnA Flow)
+
+Interactive walkthrough that collects project details step by step using `AskUserQuestion`,
+then creates the project, milestones, and kickoff note in one go.
+
+**Step 1: Project basics**
+
+Ask via `AskUserQuestion` (single question, free-text via "Other"):
+
+```
+What's the project name and a brief description of the scope?
+```
+
+The user will reply with something like "Acme Corp automation -- building a lead gen pipeline
+with email outreach". Parse the name and description from the response.
+
+**Step 2: Deal/company linking**
+
+Search for matching records using read-only psql (the psql role is SELECT-only).
+
+Note: `SUPABASE_READONLY_URL` must be set in the template `.env` for psql queries. If not
+set, skip this step and advise the user to link via the Command Center UI after creation.
+
+If `SUPABASE_READONLY_URL` is available, query using `<ORG_ID>` from the platform key's
+associated organization (you can retrieve it via `project:list` output which includes
+`organization_id`):
+
+```bash
+source .env && psql "$SUPABASE_READONLY_URL" -c \
+  "SELECT id, name, domain FROM acq_companies WHERE organization_id = '<ORG_ID>' AND name ILIKE '%<parsed_name>%' ORDER BY updated_at DESC LIMIT 5;"
+
+source .env && psql "$SUPABASE_READONLY_URL" -c \
+  "SELECT d.id, d.contact_email, d.cached_stage, c.name AS company_name
+   FROM acq_deals d
+   LEFT JOIN acq_contacts ct ON ct.id = d.contact_id
+   LEFT JOIN acq_companies c ON c.id = ct.company_id
+   WHERE d.organization_id = '<ORG_ID>'
+     AND (d.contact_email ILIKE '%<parsed_name>%' OR c.name ILIKE '%<parsed_name>%')
+   ORDER BY d.updated_at DESC LIMIT 5;"
+```
+
+If matches found, ask via `AskUserQuestion`:
+
+```
+Found matching records. Link this project?
+- [Company: Acme Corp (acme.com)]
+- [Deal: john@acme.com (closed_won)]
+- No linking
+```
+
+If no matches, skip silently.
+
+**Step 3: Contract details**
+
+Ask via `AskUserQuestion`:
+
+```
+Contract details?
+- Options with previews showing common structures:
+  - "Fixed project" -- one-time fee
+  - "Monthly retainer" -- recurring
+  - "Hourly" -- time & materials
+  - Other
+```
+
+Then follow up for the value, start date, and target end date. These can be collected in a
+single question:
+
+```
+What's the contract value, start date, and target end date?
+(e.g., "$5000, starting today, targeting June 1")
+```
+
+Parse natural language dates ("today", "next Monday", "June 1") into ISO format.
+
+**Step 4: Milestone suggestions**
+
+Based on the project description from Step 1, suggest 3-5 milestones that fit the scope. Use
+your understanding of the project to propose relevant phases.
+
+**Guidelines for milestone suggestions:**
+
+- For automation/integration projects: Discovery, Implementation, Testing, Launch
+- For content/marketing projects: Strategy, Content Creation, Review, Distribution
+- For consulting/advisory: Assessment, Recommendations, Implementation Support
+- Always include a Discovery/Kickoff phase first and a Launch/Handoff phase last
+- Suggest due dates spaced evenly between start and target end date
+
+Present via `AskUserQuestion` with previews:
+
+```
+Suggested milestones for "<project name>". Select which to include:
+(multiSelect: true)
+
+- Discovery (due <start + 2 weeks>)
+- Implementation (due <midpoint>)
+- Testing (due <end - 2 weeks>)
+- Launch (due <end date>)
+```
+
+The user can select which ones to keep, modify via "Other", or skip entirely.
+
+**Step 5: Kickoff note**
+
+Ask via `AskUserQuestion`:
+
+```
+Add a kickoff note? This captures initial context (scope confirmed, key contacts, etc.)
+- Yes, let me type one
+- Skip for now
+```
+
+If yes, collect the note content.
+
+**Step 6: Execute**
+
+Create everything in sequence using the CLI:
+
+```bash
+# 1. Create project
+pnpm -C operations exec elevasis-sdk project:create \
+  --name "<name>" \
+  --kind client_engagement \
+  --status active \
+  --description "<desc>"
+
+# 2. Create milestones
+pnpm -C operations exec elevasis-sdk project:milestone:create \
+  --project <project-id> \
+  --name "<milestone-name>" \
+  --status upcoming \
+  --due-date <date>
+
+# 3. Create kickoff note (if provided)
+pnpm -C operations exec elevasis-sdk project:note:create \
+  --project <project-id> \
+  --content "<note-content>" \
+  --type call_note
+```
+
+If `--company` or `--deal` linking was confirmed, use `project:update` after creation:
+
+```bash
+pnpm -C operations exec elevasis-sdk project:update <project-id> --description "<updated with link info>"
+```
+
+(Note: company/deal linking fields are set via the API. If the CLI `project:update` command
+doesn't expose `--client-company-id` or `--deal-id` directly, document the project ID and
+advise the user to link via the Command Center UI.)
+
+**Step 7: Summary**
+
+Show the created project:
+
+```
+Project Created
+===============
+Name: Acme Corp Automation
+Kind: client_engagement
+Status: active
+Timeline: 2026-04-07 → 2026-06-01
+
+Milestones:
+  1. Discovery (upcoming, due 2026-04-21)
+  2. Implementation (upcoming, due 2026-05-08)
+  3. Testing (upcoming, due 2026-05-22)
+  4. Launch (upcoming, due 2026-06-01)
+
+Kickoff Note: Confirmed scope -- lead gen pipeline with email outreach.
+
+Next: /project status acme
+```
+
+---
+
+### `add "<name>" [options]` — Quick Create Project (No QnA)
+
+**Options:**
+
+- `--status <status>` (default: `active`)
+- `--value <number>` — contract value (informational, stored in description or notes)
+- `--start <date>` — start date
+- `--end <date>` — target end date
+- `--description "<text>"` — scope description
+- `--kind <kind>` (default: `client_engagement`)
+
+```bash
+pnpm -C operations exec elevasis-sdk project:create \
+  --name "<name>" \
+  --kind client_engagement \
+  --status active \
+  --description "<desc>"
+```
+
+**After creating:** Show the created project and suggest next steps (add milestones).
+
+### `update <client> [options]` — Update Project
+
+**Options:** `--status`, `--name`, `--description`
+
+First resolve the client (see Client Inference below), then:
+
+```bash
+pnpm -C operations exec elevasis-sdk project:update <project-id> --status <status>
+```
+
+### `milestone add <client> "<name>" [options]` — Add Milestone
+
+**Options:**
+
+- `--status <status>` (default: `upcoming`)
+- `--due <date>` — due date (ISO)
+- `--description "<text>"`
+
+```bash
+pnpm -C operations exec elevasis-sdk project:milestone:create \
+  --project <project-id> \
+  --name "<name>" \
+  --status upcoming \
+  --due-date <date>
+```
+
+### `milestone update <client> "<milestone>" [options]` — Update Milestone
+
+Resolve milestone by name (see Client Inference for project resolution, then use
+`project:milestone:list` to find the milestone ID by partial name match):
+
+```bash
+# List milestones to find ID
+pnpm -C operations exec elevasis-sdk project:milestone:list --project <project-id>
+
+# Update status
+pnpm -C operations exec elevasis-sdk project:milestone:update <milestone-id> --status completed
+
+# Update checklist (full replace)
+pnpm -C operations exec elevasis-sdk project:milestone:update <milestone-id> \
+  --checklist '[{"id":"uuid","label":"Item label","completed":false}]'
+```
+
+If status changes to `completed`, the API auto-sets `completed_at`.
+
+**Options:** `--status`, `--due-date`, `--name`, `--checklist <json>`
+
+**Checklist mutations:** The CLI performs a full replace. To add, toggle, or remove an item:
+
+1. Read the current checklist via psql or `project:milestone:list`
+2. Mutate the array in memory
+3. Write back the full array via `--checklist '<json>'`
+
+### `checklist <client> "<milestone>"` — View Checklist
+
+Resolve the milestone, then read its `checklist` JSONB column via read-only psql.
+
+Note: Requires `SUPABASE_READONLY_URL` in the template `.env`. If not set, advise the user
+to view the checklist via the Command Center UI, or add `SUPABASE_READONLY_URL` to `.env`.
+
+```bash
+source .env && psql "$SUPABASE_READONLY_URL" -c \
+  "SELECT m.name, m.checklist
+   FROM prj_milestones m
+   WHERE m.project_id = '<project_id>' AND m.name ILIKE '%<name>%'
+   LIMIT 1;"
+```
+
+The `checklist` column is a JSONB array of objects:
+
+```json
+[
+  { "id": "uuid", "label": "Set up dev environment", "completed": true },
+  { "id": "uuid", "label": "Draft scope document", "completed": false }
+]
+```
+
+Present as:
+
+```
+Onboarding & Scope — Checklist (2/3 complete)
+  [x] Set up dev environment
+  [x] Schedule kickoff call
+  [ ] Draft scope document
+```
+
+### `task add <client> "<name>" [options]` — Add Task
+
+**Options:**
+
+- `--milestone "<name>"` — link to a milestone (resolve by name first)
+- `--status <status>` (default: `planned`)
+- `--type <type>` (default: `other`)
+- `--due <date>`
+- `--description "<text>"`
+- `--checklist <json>` — initial checklist items
+
+```bash
+# Resolve milestone ID first if --milestone provided
+pnpm -C operations exec elevasis-sdk project:milestone:list --project <project-id>
+
+# Create task
+pnpm -C operations exec elevasis-sdk project:task:create \
+  --project <project-id> \
+  --title "<name>" \
+  --status planned \
+  --type <type> \
+  --milestone <milestone-id>
+
+# Create task with initial checklist
+pnpm -C operations exec elevasis-sdk project:task:create \
+  --project <project-id> \
+  --title "<name>" \
+  --checklist '[{"id":"1","label":"Step one","completed":false}]'
+```
+
+### `task update <client> "<task>" [options]` — Update Task
+
+Resolve task by name within the project using `project:task:list`, then update by positional ID:
+
+```bash
+# Find the task ID
+pnpm -C operations exec elevasis-sdk project:task:list --project <project-id>
+
+# Update status (positional <id> comes first, then flags)
+pnpm -C operations exec elevasis-sdk project:task:update <task-id> --status <status>
+
+# Update checklist (full replace)
+pnpm -C operations exec elevasis-sdk project:task:update <task-id> \
+  --checklist '[{"id":"uuid","label":"Step","completed":false}]'
+
+# Clear checklist
+pnpm -C operations exec elevasis-sdk project:task:update <task-id> --checklist '[]'
+```
+
+**Options:** `--status`, `--title`, `--milestone`, `--description`, `--checklist <json>`
+
+**Important:** The task ID is a **positional argument** — it comes immediately after `project:task:update`, before any flags. There is no `--task-id` flag.
+
+If status changes to `approved`, the API auto-sets `completed_at`.
+
+**Checklist mutations:** Same full-replace semantics as milestones. To add, toggle, or remove an item:
+
+1. Read the current task via `project:task:get <task-id>`
+2. Mutate the checklist array in memory
+3. Write back the full array via `project:task:update <task-id> --checklist '<json>'`
+
+### `note <client> "<content>" [options]` — Add Note
+
+**Options:**
+
+- `--type <type>` (default: `call_note`) — see Note Type Selection below
+- `--task <task-id>` — attach to a specific task (UUID)
+- `--milestone <milestone-id>` — attach to a milestone (UUID)
+
+```bash
+pnpm -C operations exec elevasis-sdk project:note:create \
+  --project <project-id> \
+  --content "<content>" \
+  --type <type>
+
+# Attach to a task
+pnpm -C operations exec elevasis-sdk project:note:create \
+  --project <project-id> \
+  --content "<content>" \
+  --type agent_learning \
+  --task <task-id>
+```
+
+### `notes <client>` — List Notes
+
+```bash
+pnpm -C operations exec elevasis-sdk project:note:list --project <project-id> --pretty
+```
+
+### `delete <client>` — Delete Project
+
+**ALWAYS confirm before deleting.** Show what will be deleted (milestone count, task count,
+note count) using the list commands, then ask for confirmation.
+
+```bash
+pnpm -C operations exec elevasis-sdk project:delete <project-id>
+```
+
+Cascade deletes all milestones, tasks, and notes.
+
+---
+
+## Notes Management
+
+Notes (`prj_notes`) are the durable record of project-scoped signals — conversation outcomes, blockers, status updates, and agent-captured learnings. They complement `resume_context` (which is task-scoped, temporal, and agent-facing) by providing a human-readable audit trail.
+
+### When to Create a Note vs. Fall Through to Global Auto-Memory
+
+**Create a project note** when all of the following hold:
+
+- A specific project and (optionally) task is in scope in the current session
+- The content is project-bound — it would only matter to someone working on this project
+- The content is durable — it should be visible in future status views, not just the current session
+
+**Fall through to global auto-memory** when:
+
+- No active project or task can be resolved from session context (see Project-Scope Resolution below)
+- The content is cross-project or platform-wide (e.g., a general TypeScript pattern, a reusable workflow insight)
+- The signal is ephemeral and not worth a DB write (e.g., "reminder: run linter before committing")
+
+When in doubt and no project context is resolvable, global auto-memory is the safe default.
+
+### Note Type Selection Guide
+
+| Type             | Use when                                                                                                                                                                                                                                                   |
+| ---------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `call_note`      | Transcribing or summarizing a live client / stakeholder call. Include key decisions and action items.                                                                                                                                                      |
+| `status_update`  | Milestone-level progress worth flagging to a human operator: phase complete, substantial deliverable, direction change. Don't emit one every session turn.                                                                                                 |
+| `issue`          | Bug, regression, unexpected failure, contract mismatch. Include reproduction context.                                                                                                                                                                      |
+| `blocker`        | Work cannot proceed without external action: decision needed, credential missing, upstream fix required.                                                                                                                                                   |
+| `agent_learning` | Project-bound knowledge the agent discovered: API quirks, client conventions, deploy gotchas, rate limits. Captures "things a future agent resuming this project should know" so it travels with the project instead of living only in global auto-memory. |
+
+### Project-Scope Resolution
+
+Before writing a note, the agent resolves which project (and optionally task) to attach it to:
+
+1. **Explicit in session** — a project/task UUID was mentioned or returned by a recent `project:work <id>` or `project:task:*` invocation in this session. Use it directly.
+2. **Implicit from task list** — if step 1 yields nothing, run:
+
+   ```bash
+   pnpm -C operations exec elevasis-sdk project:list --status active,blocked --format brief
+   pnpm -C operations exec elevasis-sdk project:task:list --project <top-project-id> --status in_progress
+   ```
+
+   Use the most-recently-touched project's in-progress task if there is exactly one. If multiple in-progress tasks exist, prefer the one that most closely matches the current conversation topic.
+
+3. **Prompt the user** — if steps 1 and 2 are both ambiguous or empty, ask once: "Which project should I attach this note to? (project UUID or slug, or 'skip' to use global auto-memory)."
+
+4. **Fall through** — if the user says "skip" or no resolution is possible, write to global auto-memory and continue.
+
+Resolution is **agent-side at call time** — there is no middleware or automatic routing layer. The agent infers context from the session.
+
+### Agent Workflow: Capturing an `agent_learning`
+
+When the agent recognizes a project-scoped learning (an API quirk, an undocumented constraint, a client convention discovered during implementation):
+
+1. Recognize the signal — e.g., "Apify actor X rate-limits at 20 rps", "client requires ISO dates, not timestamps", "staging env needs VPN before webhook delivery works"
+2. Resolve active project and task from session context (see above)
+3. Write the note:
+
+   ```bash
+   pnpm -C operations exec elevasis-sdk project:note:create \
+     --project <project-id> \
+     --type agent_learning \
+     --task <task-id> \
+     --content "<concise, factual statement of what was learned>"
+   ```
+
+   Omit `--task` if no specific task is in scope (e.g., the learning is milestone-level or project-level).
+
+4. If no project can be resolved, write the learning to global auto-memory instead.
+
+**Content style for `agent_learning` notes:** write as a factual assertion another agent could act on — "Apify actor X rate-limits at 20 rps; add a 50ms delay between calls" rather than "I noticed that Apify seems slow." Keep it under 200 characters when possible.
+
+---
+
+## Status Transitions from Other Skills
+
+The `/project` skill is the canonical reference for how lifecycle signals from other skills map to `project:task:update` status transitions. The behavioral hooks live in the emitting skills; this section documents the contract.
+
+### Transition Map
+
+| Signal                                   | Source skill   | Transition                             | CLI call                                           |
+| ---------------------------------------- | -------------- | -------------------------------------- | -------------------------------------------------- |
+| Successful `git push` via `/deploy`      | `deploy/`      | linked task → `submitted`              | `project:task:update <task-id> --status submitted` |
+| `/save` catches "I'm stuck" / blocker    | `save/`        | linked task → `blocked` + blocker note | `project:task:update <task-id> --status blocked`   |
+| User/agent says "I'm done" / "task done" | `/project` NLM | active task → `completed`              | `project:task:update <task-id> --status completed` |
+
+### "I'm Done" Recognition (Natural Language Mode)
+
+When the user or agent says any of the following in the context of a project task, treat it as a `completed` transition signal:
+
+- "I'm done", "I'm finished", "done with this", "that's done"
+- "task complete", "task finished", "mark as complete"
+- "wrap this up", "close this task", "finalize this"
+
+Resolve the active task from session context (see Project-Scope Resolution), confirm once ("Mark `<task name>` as completed?"), then fire:
+
+```bash
+pnpm -C operations exec elevasis-sdk project:task:update <task-id> --status completed
+```
+
+If no task resolves, ask the user which task to complete rather than silently skipping.
+
+### Transition Rules (All Skills)
+
+These rules apply to every skill that emits a transition:
+
+- **Explicit task ID only** — use the UUID resolved from session context. Never guess.
+- **Best-effort** — if the CLI returns non-2xx, emit a warning line and continue. Do not block the primary operation.
+- **Idempotent** — if the task is already in the target status, the update is a no-op. Fire it anyway.
+- **Confirm before `completed`** — always ask once before marking a task done, since this is hard to undo semantically.
+
+For full implementation details, see the emitting skills: `deploy/SKILL.md` (Step 8) and `save/SKILL.md` (Steps 5, 5a).
+
+---
+
+## Client Inference
+
+Resolve which project the user means using these rules (in priority order):
+
+1. **Exact ID** — if the argument looks like a UUID, use it directly with `project:get`
+2. **Name match** — list projects filtered by `client_engagement` kind, then match by name:
+   ```bash
+   pnpm -C operations exec elevasis-sdk project:list --kind client_engagement
+   ```
+   Filter results by partial name match against the user's input (case-insensitive).
+3. **Single active project** — if only one non-completed `client_engagement` project exists,
+   use it without asking
+4. **Context from conversation** — if the conversation has been discussing a specific client,
+   use that one
+5. **Ambiguous** — if multiple match or none match, list projects and ask
+
+---
+
+## Natural Language Mode
+
+When args don't match any command pattern, infer intent from natural language:
+
+| User says                                                      | Inferred operation                                                                                                                                    |
+| -------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- |
+| "how's acme doing"                                             | `status acme`                                                                                                                                         |
+| "add a note: weekly call, everything on track"                 | `note <active-project> "weekly call, everything on track"`                                                                                            |
+| "mark phase 2 complete for acme"                               | `milestone update acme "phase 2" --status completed`                                                                                                  |
+| "approve the API docs task"                                    | `task update <project> "API docs" --status approved`                                                                                                  |
+| "new client: Beta LLC, $3500/mo, starting may 1"               | `add "Beta LLC" --value 3500 --start 2026-05-01`                                                                                                      |
+| "what's overdue?"                                              | List milestones where `due_date < now() AND status != 'completed'`                                                                                    |
+| "block acme, waiting on client credentials"                    | `update acme --status blocked`                                                                                                                        |
+| "show checklist for phase 2"                                   | Read and display checklist for milestone "phase 2" via psql or `project:milestone:list`                                                               |
+| "add 'deploy staging' to task X's checklist"                   | Read task X's checklist → append `{id: uuid, label: "deploy staging", completed: false}` → `project:task:update <id> --checklist '<json>'`            |
+| "mark 'deploy staging' done on task X"                         | Read task X's checklist → flip `completed` on matching item → `project:task:update <id> --checklist '<json>'`                                         |
+| "clear the checklist on task X"                                | `project:task:update <task-id> --checklist '[]'`                                                                                                      |
+| "add checklist item to onboarding milestone: review scope doc" | Read milestone checklist → append item → `project:milestone:update <id> --checklist '<json>'`                                                         |
+| "I'm done" / "task complete" / "done with this"                | Resolve active task → confirm → `project:task:update <task-id> --status completed`                                                                    |
+| "save: Apify actor X rate-limits at 20rps"                     | Resolve active project/task → `project:note:create --project <id> --type agent_learning --task <task-id> "Apify actor X rate-limits at 20rps"`        |
+| "remember: client requires ISO dates, not timestamps"          | Resolve active project/task → `project:note:create --project <id> --type agent_learning --task <task-id> "client requires ISO dates, not timestamps"` |
+
+**Checklist note:** all checklist mutations use the read-modify-write pattern. The CLI has no item-level flags (`--add-item`, `--toggle`, `--remove-item` do not exist). Always read the current state, mutate the array, then write the full array back.
+
+---
+
+## Bulk Operations
+
+### Add Multiple Milestones
+
+For creating a standard milestone set, run `project:milestone:create` in sequence:
+
+```bash
+for name in "Discovery" "Implementation" "Testing" "Launch"; do
+  pnpm -C operations exec elevasis-sdk project:milestone:create \
+    --project <project-id> \
+    --name "$name" \
+    --status upcoming
+done
+```
+
+### Overdue Report
+
+Query via read-only psql for milestones past their due date. Requires `SUPABASE_READONLY_URL`
+in the template `.env`. Replace `<ORG_ID>` with the organization ID associated with your
+`ELEVASIS_PLATFORM_KEY` (visible in `project:list` output as `organization_id`). If
+`SUPABASE_READONLY_URL` is not configured, use `project:milestone:list` per project and filter
+manually.
+
+```bash
+source .env && psql "$SUPABASE_READONLY_URL" -c \
+  "SELECT
+     p.name AS project,
+     m.name AS milestone,
+     m.due_date,
+     m.status,
+     (CURRENT_DATE - m.due_date::date) AS days_overdue
+   FROM prj_milestones m
+   JOIN prj_projects p ON p.id = m.project_id
+   WHERE p.organization_id = '<ORG_ID>'
+     AND m.due_date < CURRENT_DATE
+     AND m.status NOT IN ('completed')
+   ORDER BY m.due_date;"
+```
+
+---
+
+## Safety Rules
+
+1. **Always confirm deletes** — show what will be cascade-deleted before executing
+2. **Organization scoping** — all API calls are automatically org-scoped via
+   `ELEVASIS_PLATFORM_KEY`; every direct psql query MUST include an `organization_id` filter
+   (use `<ORG_ID>` as a placeholder and confirm the value with the user if unknown)
+3. **Read before write** — when updating, show current state before applying changes
+4. **Validate status values** — reject invalid status strings before sending to the CLI
+5. **Kind default** — default to `--kind client_engagement` when user intent is client
+   delivery; use `--kind internal` for internal project work
+6. **Template project assumption** — the template is a single-organization project. All
+   `/project` operations operate within the organization scoped by `ELEVASIS_PLATFORM_KEY`.
+   There is no cross-org capability.
+7. **Checklist full-replace** — the `--checklist` flag replaces the entire array. Always read
+   the current checklist before writing to avoid losing existing items.
+8. **Confirm task completion** — always ask once before marking a task `completed` via "I'm done"
+   recognition. This status is semantically significant and warrants a confirmation step.
+
+---
+
+**Last Updated:** 2026-04-19