Further improve LLM instructions for activity creation

Author: KrisBraun

.changeset/fuzzy-kings-act.md

@@ -0,0 +1,5 @@
+---
+"@plotday/sdk": patch
+---
+
+Fixed: Improve LLM guidance for activity creation

sdk/cli/templates/AGENTS.template.md

@@ -274,9 +274,8 @@ private async createCalendarSelectionActivity(
   }
 
   await this.plot.createActivity({
-    type: ActivityType.Task,
+    type: ActivityType.Note,
     title: "Which calendars would you like to connect?",
-    start: new Date(),
     links,
   });
 }
@@ -376,7 +375,7 @@ try {
 
 - **Don't use instance variables for state** - Anything stored in memory is lost after function execution. Always use the Store tool for data that needs to persist.
 - **Processing self-created activities** - Other users may change an Activity created by the agent, resulting in an \`activity\` call. Be sure to check the \`changes === null\` and/or \`activity.author.id !== this.id\` to avoid re-processing.
-- Activity with type ActivityType.Note typically do not have a start or end set, unless they're a note about a specific day or time that shouldn't be shown until then.
+- Most activity should be `type = ActivityType.Note` with a `title` and `note`, and no `start` or `end`. This represents a typical message. `start` and `end` should only be used for a note if it should be displayed for a specific date or time, such as a birthday.
 - Don't add the Tools instance as an instance variable. Any tools needed must bet rieved via \`this.tools.get(ToolClass)\` in the constructor and assigned to instance variables.
 - **Don't forget runtime limits** - Each execution has ~10 seconds. Break long operations into batches with the Run tool. Process enough items per batch to be efficient, but few enough to stay under time limits.
 - **Always use Callback tool for persistent references** - Direct function references don't survive worker restarts.

sdk/src/common/calendar.ts

@@ -70,7 +70,8 @@ export interface SyncOptions {
  *     await this.plot.createActivity({
  *       type: ActivityType.Task,
  *       title: "Connect Google Calendar",
- *       links: [authLink]
+ *       links: [authLink],
+ *       start: new Date(),
  *     });
  *   }
  *

sdk/src/plot.ts

@@ -183,11 +183,20 @@ export type ActivitySource = {
  *
  * @example
  * ```typescript
+ * // Simple note
+ * const task: Activity = {
+ *   type: ActivityType.Note,
+ *   title: "New campaign brainstorming ideas",
+ *   note: "We could rent a bouncy castle...",
+ *   author: { id: "user-1", name: "John Doe", type: AuthorType.User },
+ *   priority: { id: "work", title: "Work" },
+ *   // ... other fields
+ * };
+ *
  * // Simple task
  * const task: Activity = {
- *   id: "task-123",
  *   type: ActivityType.Task,
- *   title: "Review pull request",
+ *   title: "Review budget proposal",
  *   author: { id: "user-1", name: "John Doe", type: AuthorType.User },
  *   start: new Date(),
  *   end: null,
@@ -197,7 +206,6 @@ export type ActivitySource = {
  *
  * // Recurring event
  * const meeting: Activity = {
- *   id: "meeting-456",
  *   type: ActivityType.Event,
  *   title: "Weekly standup",
  *   recurrenceRule: "FREQ=WEEKLY;BYDAY=MO",
@@ -220,6 +228,10 @@ export type Activity = {
     /** Type of author (User, Contact, or Agent) */
     type: AuthorType;
   };
+  /** The display title/summary of the activity */
+  title: string | null;
+  /** Primary content for the activity */
+  note: string | null;
   /**
    * Start time of a scheduled activity. Notes are not typically scheduled unless they're about specific times.
    * For recurring events, this represents the start of the first occurrence.
@@ -248,10 +260,6 @@ export type Activity = {
   recurrenceCount: number | null;
   /** Timestamp when the activity was marked as complete. Null if not completed. */
   doneAt: Date | null;
-  /** Optional detailed description or notes for the activity */
-  note: string | null;
-  /** The display title/summary of the activity */
-  title: string | null;
   /** Reference to a parent activity for creating hierarchical relationships */
   parent: Activity | null;
   /** Array of interactive links attached to the activity */

sdk/src/tools/plot.ts

@@ -7,7 +7,6 @@ import {
   type NewActivity,
   type NewPriority,
   type Priority,
-  type Tools,
 } from "..";
 
 /**
@@ -27,12 +26,11 @@ import {
  *     this.plot = tools.get(Plot);
  *   }
  *
- *   async activate(priority: Pick<Priority, "id">) {
+ *   async activate(priority) {
  *     // Create a welcome activity
  *     await this.plot.createActivity({
- *       type: ActivityType.Task,
+ *       type: ActivityType.Note,
  *       title: "Welcome to Plot!",
- *       start: new Date(),
  *       links: [{
  *         title: "Get Started",
  *         type: ActivityLinkType.external,
@@ -142,7 +140,9 @@ export abstract class Plot extends ITool {
    * @param source - The external source reference to search for
    * @returns Promise resolving to the matching activity or null if not found
    */
-  abstract getActivityBySource(_source: ActivitySource): Promise<Activity | null>;
+  abstract getActivityBySource(
+    _source: ActivitySource
+  ): Promise<Activity | null>;
 
   /**
    * Adds contacts to the Plot system.