Plans

Plans capture what the agent intends to do, outside its context window: human-reviewable intent before execution, a shared document that worker prompts can read, and traceable revisions to the objective or approach. They are freeform documents with title, content, metadata, timestamps, and a version that increments when title or content changes.

import { plan } from "@use-crux/core/plan";

const roadmap = await plan({
  title: "Roadmap analysis",
  content: "Compare customer feedback, usage data, and support volume.",
  metadata: { threadId: "thread-123" },
});

Handles

plan() returns a command handle, not a data snapshot.

roadmap.id;
await roadmap.get();
await roadmap.update({ content: "Updated objective and approach." });

Bind an existing plan without reading it first:

const roadmap = plan.ref(planId);
const current = await roadmap.get();

List plans by metadata:

const threadPlans = await plan.list({
  metadata: { threadId: "thread-123" },
  limit: 20,
});

Context

asContext() injects the latest plan content into a prompt at resolve time.

prompt({
  use: [roadmap.asContext()],
  system: "Follow the plan unless the user changes the objective.",
});

Use reference mode when the model only needs a compact pointer:

prompt({
  use: [roadmap.asContext({ mode: "reference", priority: 60 })],
});

Custom rendering is useful when your plan content has a stable house style:

roadmap.asContext({
  renderContext: (p) => `# ${p.title}\n\nVersion ${p.version}\n\n${p.content}`,
});

Tools

asTools() gives the model focused plan read/update tools bound to this plan.

const tools = roadmap.asTools();

prompt({
  tools: {
    getPlan: tools.getPlan,
    updatePlan: tools.updatePlan,
  },
});

Create plans from model output with plan.tool(). Use created() after execution to read the handle safely.

const makePlan = plan.tool({
  template: "## Goal\n\n## Constraints\n\n## Steps",
});

await generate(
  prompt({
    system: "Create a concise execution plan.",
    tools: { makePlan },
  }),
  { model, input: { request } },
);

const roadmap = makePlan.created();

Metadata

Plan metadata must be JSON-safe. Store IDs and small routing fields, not functions, class instances, or cyclic values.

await roadmap.update({
  metadata: {
    threadId: "thread-123",
    source: "support",
  },
});

Execution Lives Elsewhere

Plans record intent; they do not run anything. Use flow() or an external durable runner for execution guarantees such as queues, retries, schedules, and resume behavior.