@compass-labs/api-sdk 2.2.16 → 2.2.17

package/CLAUDE.md

@@ -36,6 +36,188 @@ SDK generation is handled by:
 2. Regenerate `openapi.json` via `make update_openapi_json`
 3. CI will regenerate and publish the SDK
 
+## Claude Documentation Convention (MANDATORY)
+
+**This convention is COMPULSORY. You MUST follow it for every plan, feature, or system you document. No exceptions.**
+
+All documentation lives in `docs/` and follows a structured planning workflow with Linear ticket integration.
+
+### Directory Structure
+
+```
+docs/
+├── systems/                              # Living docs for shipped systems
+│   ├── <system-name>/
+│   │   ├── README.md                     # Compiled from plan.md + all task files
+│   │   └── diagram.excalidraw           # Architecture / data flow diagram
+│   └── ...
+├── plans/                                # Upcoming features and designs
+│   ├── YYYY-MM-DD-<feature-name>/
+│   │   ├── plan.md                       # Overall plan: overview, goals, architecture, scope
+│   │   ├── diagram.excalidraw           # Architecture diagram for the feature
+│   │   ├── blockers.excalidraw          # Dependency/blocker diagram between tasks
+│   │   ├── 01-<task-name>.md            # Task 1: detailed implementation spec
+│   │   ├── 02-<task-name>.md            # Task 2: detailed implementation spec
+│   │   ├── 03-<task-name>.md            # Task 3: detailed implementation spec
+│   │   └── ...                           # As many tasks as needed
+│   └── ...
+├── TRACKER.yaml                          # Tracks plans AND individual tasks
+```
+
+### Planning Workflow (MANDATORY — follow every step)
+
+#### Step 1: Create the Plan Folder
+
+Create `docs/plans/YYYY-MM-DD-<feature-name>/` with:
+
+1. **`plan.md`** — The overall plan document containing:
+   - Feature overview and goals
+   - Architecture decisions and rationale
+   - Scope and constraints
+   - List of tasks with brief descriptions
+
+2. **`diagram.excalidraw`** — Architecture diagram showing how the feature works:
+   - System components involved
+   - Data flows
+   - External dependencies
+   - Create via Excalidraw MCP tools, then write the `.excalidraw` JSON file
+
+3. **Individual task files** (`01-<task-name>.md`, `02-<task-name>.md`, etc.):
+   - Each file is a self-contained implementation spec for one step
+   - Numbered to indicate execution order
+   - Contains: what to build, acceptance criteria, files to modify, dependencies
+   - These are followed step-by-step during implementation
+
+4. **`blockers.excalidraw`** — Blocker/dependency diagram showing:
+   - Which tasks block which other tasks
+   - The execution order and parallelization opportunities
+   - Critical path through the plan
+   - Create via Excalidraw MCP tools
+
+#### Step 2: Create Linear Tickets
+
+**You MUST create Linear tickets for every plan. This is not optional.**
+
+**Before creating tickets, ASK the user for:**
+- **Team**: Which Linear team should own these tickets?
+- **Project**: Which Linear project should these tickets belong to?
+- **Initiative**: Which Linear initiative (if any) should the project be linked to?
+- **Priority**: What priority level? (1=Urgent, 2=High, 3=Normal, 4=Low)
+- **Status**: What initial status should the parent ticket have? (e.g., Backlog, Todo, In Progress)
+- **Assignee**: Who should be assigned? (or "me" for the current user)
+
+**Do NOT guess these values. Always ask the user explicitly.**
+
+1. **Parent ticket** — Create a Linear issue for the overall plan:
+   - Title: the feature name
+   - Description: contents of `plan.md` + the blockers diagram explanation
+   - Attach or reference the `blockers.excalidraw` diagram
+   - Link to the plan folder in the repo
+   - Set the team, project, initiative, priority, status, and assignee as specified by the user
+
+2. **Sub-tickets** — Create a Linear sub-issue for EACH individual task file:
+   - Title: matches the task file name (e.g., "01 - Set up database schema")
+   - Description: full contents of the corresponding task `.md` file
+   - Set as child of the parent ticket
+   - Set blocker relationships matching `blockers.excalidraw`
+   - Link to the specific task file in the repo
+   - Inherit team, project, and priority from the parent ticket
+   - Set status to the team's initial/backlog status (first tasks may be set to "Todo" if unblocked)
+
+#### Step 3: Update TRACKER.yaml
+
+Add the plan AND all individual tasks to `docs/TRACKER.yaml`:
+
+```yaml
+plans:
+  - name: feature-name
+    path: plans/YYYY-MM-DD-feature-name/
+    status: planned              # planned → in-progress → shipped
+    created: YYYY-MM-DD
+    started:
+    shipped:
+    linear_ticket: COM-XXX       # Parent Linear ticket ID
+    tasks:
+      - name: task-1-name
+        file: 01-task-name.md
+        status: pending          # pending → in-progress → done
+        linear_ticket: COM-XXX   # Sub-ticket Linear ID
+      - name: task-2-name
+        file: 02-task-name.md
+        status: pending
+        linear_ticket: COM-XXX
+```
+
+#### Step 4: Implementation (follow tasks in order, keep everything in sync)
+
+Work through task files in numbered order (unless blockers allow parallelization). **You MUST keep Linear ticket statuses and TRACKER.yaml in sync at every state change.** This is not just about creating tickets — you must actively maintain them throughout the plan lifecycle.
+
+**When starting a task:**
+- Update the sub-ticket status on Linear to the team's "In Progress" state
+- Update `docs/TRACKER.yaml` task status to `in-progress`
+- If this is the first task being started, also update the parent ticket and plan status to `in-progress`
+
+**When completing a task:**
+- Update the sub-ticket status on Linear to "Done" (or the team's completed state)
+- Update `docs/TRACKER.yaml` task status to `done`
+- Check if any previously blocked tasks are now unblocked and mention this
+
+**When a task is blocked or has issues:**
+- Add a comment on the Linear sub-ticket explaining the blocker
+- Do NOT silently skip — communicate the issue
+
+**At the start of every implementation session:**
+- Check `docs/TRACKER.yaml` and the Linear board to understand current progress
+- Resume from where the last session left off
+
+#### Step 5: Shipping (move to systems)
+
+When ALL tasks are complete:
+
+1. **Compile README.md** — Create `docs/systems/<system-name>/README.md` by combining:
+   - The overview and architecture from `plan.md`
+   - Key details from each individual task file
+   - Final architecture decisions and operational notes
+
+2. **Copy the architecture diagram** — Move `diagram.excalidraw` to `docs/systems/<system-name>/`
+
+3. **Move the folder** — Move from `plans/` to `systems/`
+
+4. **Update TRACKER.yaml** — Set plan status to `shipped` with `shipped:` date
+
+5. **Update Linear** — Close the parent ticket and all sub-tickets
+
+### Rules (ALL mandatory — do not skip any)
+
+- Every plan folder MUST have: `plan.md`, `diagram.excalidraw`, `blockers.excalidraw`, and at least one task file
+- Every plan MUST have a parent Linear ticket with sub-tickets for each task
+- Diagrams use Excalidraw — create via the Excalidraw MCP tool, then write the `.excalidraw` JSON file
+- When creating diagrams: use `create_element` for rectangles, text, arrows etc., then `query_elements` to get all elements, then write to `.excalidraw` file format
+- The `.excalidraw` file is viewable in VS Code with the Excalidraw extension, or at excalidraw.com
+- **NEVER create a plan without an architecture diagram AND a blockers diagram**
+- **NEVER create a plan without corresponding Linear tickets**
+- **ALWAYS update `docs/TRACKER.yaml` when creating, starting, completing tasks, or shipping a plan**
+- **ALWAYS keep Linear ticket statuses in sync with TRACKER.yaml — every state change must be reflected in BOTH places**
+- **NEVER change a task's status in TRACKER.yaml without also updating the corresponding Linear ticket (and vice versa)**
+- **At the start of each session, check TRACKER.yaml and Linear to understand current plan progress before doing work**
+
+### Plan Tracker (MANDATORY)
+
+`docs/TRACKER.yaml` and Linear are the **dual source of truth** for plan progress. They MUST always agree. **You MUST update BOTH whenever you:**
+
+| Event | TRACKER.yaml | Linear |
+|-------|-------------|--------|
+| Create plan | Add entry, `status: planned`, all tasks `pending` | Create parent + sub-tickets in Backlog |
+| Start a task | Task `status: in-progress`, plan `status: in-progress` | Move sub-ticket to In Progress, parent to In Progress |
+| Complete a task | Task `status: done` | Move sub-ticket to Done |
+| Block on a task | No change (stays `in-progress`) | Add comment explaining blocker |
+| Ship the plan | Plan `status: shipped`, `shipped:` date | Close parent + all sub-tickets |
+
+Plan statuses: `planned` → `in-progress` → `shipped`
+Task statuses: `pending` → `in-progress` → `done`
+
+**Failure to keep TRACKER.yaml and Linear in sync is a violation of this convention.**
+
 ## Diagram Maintenance
 
 When changing SDK generation configuration, update `widgets-sdk/diagram.excalidraw` and `docs/systems/widgets-sdk/diagram.excalidraw` if the changes affect how the TypeScript SDK is consumed by the widgets-sdk.

package/dist/commonjs/lib/config.d.ts

@@ -32,7 +32,7 @@ export declare const SDK_METADATA: {
     readonly language: "typescript";
     readonly openapiDocVersion: "0.0.1";
     readonly sdkVersion: "2.0.0";
-    readonly genVersion: "2.824.1";
-    readonly userAgent: "speakeasy-sdk/typescript 2.0.0 2.824.1 0.0.1 @compass-labs/api-sdk";
+    readonly genVersion: "2.832.2";
+    readonly userAgent: "speakeasy-sdk/typescript 2.0.0 2.832.2 0.0.1 @compass-labs/api-sdk";
 };
 //# sourceMappingURL=config.d.ts.map

package/dist/commonjs/lib/config.js

@@ -32,7 +32,7 @@ exports.SDK_METADATA = {
     language: "typescript",
     openapiDocVersion: "0.0.1",
     sdkVersion: "2.0.0",
-    genVersion: "2.824.1",
-    userAgent: "speakeasy-sdk/typescript 2.0.0 2.824.1 0.0.1 @compass-labs/api-sdk",
+    genVersion: "2.832.2",
+    userAgent: "speakeasy-sdk/typescript 2.0.0 2.832.2 0.0.1 @compass-labs/api-sdk",
 };
 //# sourceMappingURL=config.js.map

package/dist/esm/lib/config.d.ts

@@ -32,7 +32,7 @@ export declare const SDK_METADATA: {
     readonly language: "typescript";
     readonly openapiDocVersion: "0.0.1";
     readonly sdkVersion: "2.0.0";
-    readonly genVersion: "2.824.1";
-    readonly userAgent: "speakeasy-sdk/typescript 2.0.0 2.824.1 0.0.1 @compass-labs/api-sdk";
+    readonly genVersion: "2.832.2";
+    readonly userAgent: "speakeasy-sdk/typescript 2.0.0 2.832.2 0.0.1 @compass-labs/api-sdk";
 };
 //# sourceMappingURL=config.d.ts.map

package/dist/esm/lib/config.js

@@ -28,7 +28,7 @@ export const SDK_METADATA = {
     language: "typescript",
     openapiDocVersion: "0.0.1",
     sdkVersion: "2.0.0",
-    genVersion: "2.824.1",
-    userAgent: "speakeasy-sdk/typescript 2.0.0 2.824.1 0.0.1 @compass-labs/api-sdk",
+    genVersion: "2.832.2",
+    userAgent: "speakeasy-sdk/typescript 2.0.0 2.832.2 0.0.1 @compass-labs/api-sdk",
 };
 //# sourceMappingURL=config.js.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@compass-labs/api-sdk",
-  "version": "2.2.16",
+  "version": "2.2.17",
   "author": "royalnine",
   "type": "module",
   "tshy": {

package/src/lib/config.ts

@@ -62,7 +62,7 @@ export const SDK_METADATA = {
   language: "typescript",
   openapiDocVersion: "0.0.1",
   sdkVersion: "2.0.0",
-  genVersion: "2.824.1",
+  genVersion: "2.832.2",
   userAgent:
-    "speakeasy-sdk/typescript 2.0.0 2.824.1 0.0.1 @compass-labs/api-sdk",
+    "speakeasy-sdk/typescript 2.0.0 2.832.2 0.0.1 @compass-labs/api-sdk",
 } as const;