@trailstep/authoring 0.1.1 → 0.2.0

package/README.md

@@ -17,6 +17,7 @@ Use this package to author continuation workflows with:
 - `defineWorkflow({ start })` as the workflow boundary.
 - `step(...)` for focused units of agent or local work.
 - `.prompt(...).do(...)` for agent-backed steps with structured output.
+- `subPrompt(...)` for dispatching typed helper prompts from inside a running step.
 - `done(...)` and `fail(...)` for terminal continuations.
 - `shape(...)` or `jsonSchema(...)` for JSON-object validation.
 - prompt helpers such as `promptSections`, `section`, `loadFragments`, and `promptTemplate`.
@@ -25,19 +26,56 @@ Use this package to author continuation workflows with:
 
 Keep workflow entrypoints small and put step logic in separate files as workflows grow.
 
+```ts
+// workflows/feature-summary.schema.ts
+import { shape } from "@trailstep/authoring";
+
+export type FeatureSummaryInput = {
+  readonly request: string;
+};
+
+export type FeatureSummaryOutput = {
+  readonly summary: string;
+  readonly nextStep: string;
+};
+
+export const featureSummaryInput = shape<FeatureSummaryInput>({
+  request: "string",
+});
+
+export const featureSummaryOutput = shape<FeatureSummaryOutput>({
+  summary: "string",
+  nextStep: "string",
+});
+```
+
 ```ts
 // workflows/feature-summary.workflow.ts
-import { defineWorkflow, shape } from "@trailstep/authoring";
+import { defineWorkflow } from "@trailstep/authoring";
+import {
+  type FeatureSummaryInput,
+  type FeatureSummaryOutput,
+  featureSummaryInput,
+  featureSummaryOutput,
+} from "./feature-summary.schema.js";
 import { summarizeRequestStep } from "./steps/summarize-request.step.js";
 
-type FeatureSummaryInput = { request: string };
-type FeatureSummaryOutput = { summary: string; nextStep: string };
-
 export const featureSummary = defineWorkflow<FeatureSummaryInput, FeatureSummaryOutput>({
   id: "feature-summary",
   description: "Summarize a feature request and suggest one next step.",
-  inputShape: shape<FeatureSummaryInput>({ request: "string" }),
-  outputShape: shape<FeatureSummaryOutput>({ summary: "string", nextStep: "string" }),
+  skill: {
+    description: "Use when an agent needs to summarize a feature request.",
+    instructions: "Capture the user's request faithfully and recommend one concrete next step.",
+  },
+  inputShape: featureSummaryInput,
+  outputShape: featureSummaryOutput,
+  agents: {
+    summarizer: {
+      size: "medium",
+      thinking: "medium",
+      description: "Summarizes feature requests for planning.",
+    },
+  },
   start(input) {
     return summarizeRequestStep(input);
   },
@@ -46,22 +84,37 @@ export const featureSummary = defineWorkflow<FeatureSummaryInput, FeatureSummary
 
 ```ts
 // workflows/steps/summarize-request.step.ts
-import { done, shape, step } from "@trailstep/authoring";
-
-type FeatureSummaryInput = { request: string };
-type FeatureSummaryOutput = { summary: string; nextStep: string };
-
-export function summarizeRequestStep(input: FeatureSummaryInput) {
-  return step({ id: "summarize-request" })
-    .prompt<FeatureSummaryInput, FeatureSummaryOutput>(
-      ({ input: stepInput }) =>
-        `Summarize this feature request and recommend one next step:\n\n${stepInput.request}`,
-      { output: shape<FeatureSummaryOutput>({ summary: "string", nextStep: "string" }) },
-    )
-    .do((output) => done(output))(input);
+import { done, promptSections, section, step } from "@trailstep/authoring";
+import {
+  type FeatureSummaryInput,
+  type FeatureSummaryOutput,
+  featureSummaryOutput,
+} from "../feature-summary.schema.js";
+
+function summarizeRequestPrompt({
+  input,
+}: {
+  readonly input: FeatureSummaryInput;
+}): string {
+  return promptSections(
+    section("Feature request", input.request),
+    section(
+      "Task",
+      "Summarize the request in two or three sentences, then recommend exactly one next step.",
+    ),
+  );
 }
+
+export const summarizeRequestStep = step({ id: "summarize-request" })
+  .prompt<FeatureSummaryInput, FeatureSummaryOutput>(summarizeRequestPrompt, {
+    agent: "summarizer",
+    output: featureSummaryOutput,
+  })
+  .do((output) => done(output));
 ```
 
+The optional `skill` block customizes generated agent skill metadata. TrailStep still appends generated CLI usage, input-file, and schema instructions when creating the skill. Raw skill markdown that starts with YAML frontmatter keeps that frontmatter exactly; raw markdown without frontmatter is wrapped in generated `name`/`description` frontmatter before the custom body.
+
 Run direct refs while developing:
 
 ```bash

package/dist/index.d.ts

@@ -1,14 +1 @@
-import { PlainObject, Workflow } from '@trailstep/core';
-export { Document, FailNode, PromptOptions, PromptTemplateSource, RetryPolicy, RetryPolicyInput, Schema, ShapeInput, ShapeObject, ShapePrimitive, StepConfig, StepFactory, TimeoutPolicy, TimeoutPolicyInput, Workflow, document, done, fail, jsonSchema, list, loadFragments, promptSections, promptTemplate, section, shape, state, step } from '@trailstep/core';
-
-interface WorkflowBuilderOptions<TInput extends PlainObject = PlainObject, TOutput extends PlainObject = PlainObject> extends Workflow<TInput, TOutput> {
-    readonly description?: string;
-    readonly start: (input: TInput) => ReturnType<NonNullable<Workflow<TInput, TOutput>["start"]>>;
-}
-type DefinedWorkflow<TInput extends PlainObject = PlainObject, TOutput extends PlainObject = PlainObject> = Workflow<TInput, TOutput> & {
-    readonly description?: string;
-};
-
-declare function defineWorkflow<TInput extends PlainObject = PlainObject, TOutput extends PlainObject = PlainObject>(options: WorkflowBuilderOptions<TInput, TOutput>): DefinedWorkflow<TInput, TOutput>;
-
-export { type DefinedWorkflow, type WorkflowBuilderOptions, defineWorkflow };
+export { AbsoluteDoneNode, AbsoluteFailNode, CheckWaitCallback, CheckWaitContext, CheckWaitHelpers, ContinuationArray, ContinuationResult, DeepReadonly, DefinedWorkflow, DisplayPhase, DoPhase, Document, FailNode, NotifyApi, NotifyArtifact, ParallelNode, PostContinuation, PromptOptions, PromptPhase, PromptTemplateSource, RetryPolicy, RetryPolicyInput, RunnableContinuationNode, Schema, ShapeInput, ShapeObject, ShapePrimitive, StepConfig, StepContextContinuation, StepContinuationOutput, StepCwdCallback, StepCwdContext, StepCwdInput, StepDisplayCallback, StepDisplayContent, StepDisplayContext, StepDisplayLevel, StepDisplayObject, StepDisplayValue, StepFactory, StepPhase, StepWaitContext, SubPromptFactory, SubPromptOptions, TerminalMessageOptions, TimeoutPolicy, TimeoutPolicyInput, WaitCallback, WaitCheckResult, WaitDefinition, WaitDoneResult, WaitInput, WaitOptions, WaitPendingInput, WaitPendingResult, WaitPhase, Workflow, WorkflowBuilderOptions, WorkflowInputApi, WorkflowInvocationNode, WorkflowInvocationOptions, WorkflowSkillOptions, absoluteDone, absoluteFail, defineWorkflow, document, done, fail, globalState, isAbsoluteDoneNode, isAbsoluteFailNode, isParallelNode, isWorkflowInvocationNode, jsonSchema, list, loadFragments, notify, parallel, promptSections, promptTemplate, section, shape, state, step, subPrompt, workflow } from '@trailstep/core';

package/dist/index.js

@@ -1,51 +1,58 @@
 // src/index.ts
 import {
+  absoluteDone,
+  absoluteFail,
   Document,
   document,
   done,
   fail,
+  globalState,
+  isAbsoluteDoneNode,
+  isAbsoluteFailNode,
+  isParallelNode,
+  isWorkflowInvocationNode,
   jsonSchema,
   list,
   loadFragments,
+  notify,
+  parallel,
   promptSections,
   promptTemplate,
   section,
   shape,
   state,
-  step
+  step,
+  subPrompt,
+  workflow
 } from "@trailstep/core";
 
-// src/shared/assert-builder-object.ts
-function assertBuilderObject(value, builderName) {
-  if (typeof value !== "object" || value === null || Array.isArray(value)) {
-    throw new TypeError(`${builderName} requires a single object argument.`);
-  }
-  if (typeof value.id !== "string") {
-    throw new TypeError(`${builderName} requires an id string.`);
-  }
-}
-
 // src/workflow-builder/workflow-builder.ts
-function defineWorkflow(options) {
-  assertBuilderObject(options, "defineWorkflow");
-  if (typeof options.start !== "function")
-    throw new TypeError("defineWorkflow requires a start function.");
-  return options;
-}
+import { defineWorkflow } from "@trailstep/core";
 export {
   Document,
+  absoluteDone,
+  absoluteFail,
   defineWorkflow,
   document,
   done,
   fail,
+  globalState,
+  isAbsoluteDoneNode,
+  isAbsoluteFailNode,
+  isParallelNode,
+  isWorkflowInvocationNode,
   jsonSchema,
   list,
   loadFragments,
+  notify,
+  parallel,
   promptSections,
   promptTemplate,
   section,
   shape,
   state,
-  step
+  step,
+  subPrompt,
+  workflow
 };
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../src/index.ts","../src/shared/assert-builder-object.ts","../src/workflow-builder/workflow-builder.ts"],"sourcesContent":["export type {\n  FailNode,\n  PromptOptions,\n  PromptTemplateSource,\n  RetryPolicy,\n  RetryPolicyInput,\n  Schema,\n  ShapeInput,\n  ShapeObject,\n  ShapePrimitive,\n  StepConfig,\n  StepFactory,\n  TimeoutPolicy,\n  TimeoutPolicyInput,\n  Workflow,\n} from \"@trailstep/core\";\nexport {\n  Document,\n  document,\n  done,\n  fail,\n  jsonSchema,\n  list,\n  loadFragments,\n  promptSections,\n  promptTemplate,\n  section,\n  shape,\n  state,\n  step,\n} from \"@trailstep/core\";\nexport { defineWorkflow } from \"./workflow-builder/workflow-builder.js\";\nexport type {\n  DefinedWorkflow,\n  WorkflowBuilderOptions,\n} from \"./workflow-builder/workflow-builder.types.js\";\n","export function assertBuilderObject(\n  value: unknown,\n  builderName: string,\n): asserts value is { readonly id: string } {\n  if (typeof value !== \"object\" || value === null || Array.isArray(value)) {\n    throw new TypeError(`${builderName} requires a single object argument.`);\n  }\n  if (typeof (value as { readonly id?: unknown }).id !== \"string\") {\n    throw new TypeError(`${builderName} requires an id string.`);\n  }\n}\n","import type { PlainObject } from \"@trailstep/core\";\nimport { assertBuilderObject } from \"../shared/assert-builder-object.js\";\nimport type { DefinedWorkflow, WorkflowBuilderOptions } from \"./workflow-builder.types.js\";\n\nexport function defineWorkflow<\n  TInput extends PlainObject = PlainObject,\n  TOutput extends PlainObject = PlainObject,\n>(options: WorkflowBuilderOptions<TInput, TOutput>): DefinedWorkflow<TInput, TOutput> {\n  assertBuilderObject(options, \"defineWorkflow\");\n  if (typeof options.start !== \"function\")\n    throw new TypeError(\"defineWorkflow requires a start function.\");\n  return options;\n}\n"],"mappings":";AAgBA;AAAA,EACE;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,OACK;;;AC9BA,SAAS,oBACd,OACA,aAC0C;AAC1C,MAAI,OAAO,UAAU,YAAY,UAAU,QAAQ,MAAM,QAAQ,KAAK,GAAG;AACvE,UAAM,IAAI,UAAU,GAAG,WAAW,qCAAqC;AAAA,EACzE;AACA,MAAI,OAAQ,MAAoC,OAAO,UAAU;AAC/D,UAAM,IAAI,UAAU,GAAG,WAAW,yBAAyB;AAAA,EAC7D;AACF;;;ACNO,SAAS,eAGd,SAAoF;AACpF,sBAAoB,SAAS,gBAAgB;AAC7C,MAAI,OAAO,QAAQ,UAAU;AAC3B,UAAM,IAAI,UAAU,2CAA2C;AACjE,SAAO;AACT;","names":[]}
+{"version":3,"sources":["../src/index.ts","../src/workflow-builder/workflow-builder.ts"],"sourcesContent":["export type {\n  AbsoluteDoneNode,\n  AbsoluteFailNode,\n  CheckWaitCallback,\n  CheckWaitContext,\n  CheckWaitHelpers,\n  ContinuationArray,\n  ContinuationResult,\n  DeepReadonly,\n  DisplayPhase,\n  DoPhase,\n  FailNode,\n  NotifyApi,\n  NotifyArtifact,\n  ParallelNode,\n  PostContinuation,\n  PromptOptions,\n  PromptPhase,\n  PromptTemplateSource,\n  RetryPolicy,\n  RetryPolicyInput,\n  RunnableContinuationNode,\n  Schema,\n  ShapeInput,\n  ShapeObject,\n  ShapePrimitive,\n  StepConfig,\n  StepContextContinuation,\n  StepContinuationOutput,\n  StepCwdCallback,\n  StepCwdContext,\n  StepCwdInput,\n  StepDisplayCallback,\n  StepDisplayContent,\n  StepDisplayContext,\n  StepDisplayLevel,\n  StepDisplayObject,\n  StepDisplayValue,\n  StepFactory,\n  StepPhase,\n  StepWaitContext,\n  SubPromptFactory,\n  SubPromptOptions,\n  TerminalMessageOptions,\n  TimeoutPolicy,\n  TimeoutPolicyInput,\n  WaitCallback,\n  WaitCheckResult,\n  WaitDefinition,\n  WaitDoneResult,\n  WaitInput,\n  WaitOptions,\n  WaitPendingInput,\n  WaitPendingResult,\n  WaitPhase,\n  Workflow,\n  WorkflowInputApi,\n  WorkflowInvocationNode,\n  WorkflowInvocationOptions,\n  WorkflowSkillOptions,\n} from \"@trailstep/core\";\nexport {\n  absoluteDone,\n  absoluteFail,\n  Document,\n  document,\n  done,\n  fail,\n  globalState,\n  isAbsoluteDoneNode,\n  isAbsoluteFailNode,\n  isParallelNode,\n  isWorkflowInvocationNode,\n  jsonSchema,\n  list,\n  loadFragments,\n  notify,\n  parallel,\n  promptSections,\n  promptTemplate,\n  section,\n  shape,\n  state,\n  step,\n  subPrompt,\n  workflow,\n} from \"@trailstep/core\";\nexport { defineWorkflow } from \"./workflow-builder/workflow-builder.js\";\nexport type {\n  DefinedWorkflow,\n  WorkflowBuilderOptions,\n} from \"./workflow-builder/workflow-builder.types.js\";\n","export { defineWorkflow } from \"@trailstep/core\";\n"],"mappings":";AA6DA;AAAA,EACE;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,OACK;;;ACtFP,SAAS,sBAAsB;","names":[]}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@trailstep/authoring",
-  "version": "0.1.1",
+  "version": "0.2.0",
   "description": "TypeScript authoring helpers for TrailStep workflows.",
   "license": "Apache-2.0",
   "type": "module",
@@ -29,14 +29,14 @@
     "LICENSE"
   ],
   "dependencies": {
-    "@trailstep/core": "0.1.1"
+    "@trailstep/core": "0.2.0"
   },
   "peerDependencies": {
-    "@trailstep/core": "^0.1.1"
+    "@trailstep/core": "^0.2.0"
   },
   "devDependencies": {
-    "@biomejs/biome": "^2.1.1",
-    "@types/node": "^26.1.1",
+    "@biomejs/biome": "^2.5.8",
+    "@types/node": "^26.2.0",
     "tsup": "^8.5.0",
     "typescript": "^5.8.3",
     "vitest": "^3.2.4"