@trailstep/authoring 0.1.0 → 0.1.1

package/README.md

@@ -1,19 +1,111 @@
 # @trailstep/authoring
 
-`@trailstep/authoring` provides TypeScript helpers for writing TrailStep workflows.
+`@trailstep/authoring` provides TypeScript helpers for writing TrailStep workflows. Most workflow authors should start here rather than using `@trailstep/core` directly.
 
 ## Install
 
 ```bash
-pnpm add @trailstep/authoring
+npm install @trailstep/authoring @trailstep/core
 ```
 
-## Public role
+Use the equivalent command for your package manager if you use `pnpm`, `yarn`, or `bun`.
 
-Use this package to author workflows with:
+## What this package is for
 
-- `defineWorkflow({ start })` as the workflow definition boundary.
-- `step(...)` for continuation steps.
-- `done(...)` for successful completion.
+Use this package to author continuation workflows with:
 
-Export workflows from a Node-readable module. Consumers can run direct refs such as `./workflows/sample.ts#sampleWorkflow`, register refs with `trailstep add`, or use bundle refs when a package exposes a TrailStep workflow manifest.
+- `defineWorkflow({ start })` as the workflow boundary.
+- `step(...)` for focused units of agent or local work.
+- `.prompt(...).do(...)` for agent-backed steps with structured output.
+- `done(...)` and `fail(...)` for terminal continuations.
+- `shape(...)` or `jsonSchema(...)` for JSON-object validation.
+- prompt helpers such as `promptSections`, `section`, `loadFragments`, and `promptTemplate`.
+
+## Basic pattern
+
+Keep workflow entrypoints small and put step logic in separate files as workflows grow.
+
+```ts
+// workflows/feature-summary.workflow.ts
+import { defineWorkflow, shape } from "@trailstep/authoring";
+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" }),
+  start(input) {
+    return summarizeRequestStep(input);
+  },
+});
+```
+
+```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);
+}
+```
+
+Run direct refs while developing:
+
+```bash
+trailstep ./workflows/feature-summary.workflow.ts#featureSummary --input '{"request":"Add CSV export."}'
+```
+
+Register stable refs when the workflow should be shared:
+
+```bash
+trailstep add ./workflows/feature-summary.workflow.ts#featureSummary --scope project --name feature-summary --project-skill
+trailstep project/feature-summary --input '{"request":"Add CSV export."}'
+```
+
+## Packaging prompt fragments
+
+If a published workflow imports markdown prompt fragments, prefer bundling them into the workflow entrypoint so the installed package has no runtime file-path assumptions. With `tsup`, use raw imports plus the text loader:
+
+```ts
+import methodology from "./methodology.md?raw";
+
+const promptFragment = methodology.trimEnd();
+```
+
+```json
+{
+  "scripts": {
+    "build": "tsup src/index.ts --format esm --dts --sourcemap --clean --loader .md=text"
+  }
+}
+```
+
+Add a declaration for TypeScript:
+
+```ts
+declare module "*.md?raw" {
+  const content: string;
+  export default content;
+}
+```
+
+`loadFragments(import.meta.dirname, ...)` is useful for local source workflows or packages that deliberately ship copied asset files, but publishable bundled workflow packages must either inline those fragments or include copied assets in `files` at the exact runtime paths used by the built bundle.
+
+## More docs
+
+- [Authoring workflows](../../docs/authoring-workflows.md)
+- [Generated skills](../../docs/generated-skills.md)
+- [CLI reference](../../docs/cli-reference.md)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@trailstep/authoring",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "description": "TypeScript authoring helpers for TrailStep workflows.",
   "license": "Apache-2.0",
   "type": "module",
@@ -29,10 +29,10 @@
     "LICENSE"
   ],
   "dependencies": {
-    "@trailstep/core": "0.1.0"
+    "@trailstep/core": "0.1.1"
   },
   "peerDependencies": {
-    "@trailstep/core": "^0.1.0"
+    "@trailstep/core": "^0.1.1"
   },
   "devDependencies": {
     "@biomejs/biome": "^2.1.1",