@vimhead.dev/norn-cli 0.1.0-tip.35611592848.1 → 0.1.0-tip.35614826665.1

package/assets/README.md

@@ -21,7 +21,7 @@ through the CLI from any harness. Agents run on the bundled
    const summarize = workflow({
      name: "summarize",
      entrypoint: {
-       instructions: "Summarize staged and unstaged tracked changes relative to HEAD in an absolute repositoryPath. Requires Git and an existing commit; untracked files are excluded. Saves workspace-relative summaryPath and retains the diff log. A nonempty diff is sent to the configured model; an empty diff needs no model call.",
+       instructions: "Use when you need a saved summary of staged and unstaged tracked changes in a Git repository before review or handoff. Compares against HEAD, excludes untracked files, and does not edit the repository. Requires an existing commit and model access for nonempty diffs.",
      },
      args: Type.Object({ repositoryPath: Type.String({ minLength: 1 }) }),
      async execute({ args, paths, commands, logs, agents, run }) {

package/assets/docs/workflows.md

@@ -29,7 +29,7 @@ import { Type } from "typebox";
 
 export const greet = workflow({
   name: "greet",
-  entrypoint: { instructions: "Return a greeting for the supplied name." },
+  entrypoint: { instructions: "Use when you need a personalized greeting returned as the run summary, without writing a file or calling a model." },
   args: Type.Object({ name: Type.String() }),
   execute({ args, run }) {
     return run.complete({ summary: `Hello, ${args.name}!` });
@@ -43,7 +43,13 @@ Supply `name`, `args`, `entrypoint`, and `execute` explicitly. Use `entrypoint:
 
 Workflow and scope names must be nonempty and cannot contain dots. A standalone workflow's ID is its name; a scoped workflow's ID is `<scope name>.<workflow name>`. Declarations expose the resolved `id`; CLI commands, references, and `run.next` use that exact ID, without implicit scope lookup.
 
-`entrypoint.instructions` describe selection, inputs, effects, and outputs. They are neither a Norn agent system prompt nor a gate decision. Declare args and config with [TypeBox schemas](schemas.md). Workflow inputs must be JSON data; `execute` receives the values after schema defaults and conversions. Public schemas must support `workflows inspect`.
+`entrypoint.instructions` is a short capability-selection description, like a skill's short description—not an execution plan, a Norn agent system prompt, or a gate decision.
+
+| Decision | GOOD | BAD |
+|---|---|---|
+| IF exposing an entrypoint, THEN lead with “Use when…” and the caller's need, followed by the useful result and only prerequisites, effects, or limits that affect selection. ELSE keep the step internal with `entrypoint: false`. | “Use when you need a source-grounded summary checked for unsupported claims. Saves a draft and an assessment; completion does not imply approval. Requires model access.” | “Call the draft agent, write JSON, then invoke the analysis workflow.” |
+
+Declare args and config with [TypeBox schemas](schemas.md) rather than listing their fields in the description. Workflow inputs must be JSON data; `execute` receives the values after schema defaults and conversions. Public schemas must support `workflows inspect`.
 
 Destructure the properties needed by the step from `execute(context)`. Gate descriptions receive the same inferred context:
 

package/assets/examples/agent-then-analysis/plugin.ts

@@ -24,7 +24,7 @@ const analysisSchema = Type.Object({
 const scope = workflowScope({ name: "sourceSummary" });
 export const draft = scope.workflow({
 	name: "draft",
-	entrypoint: { instructions: "Summarize a supplied source, save the draft, and independently assess its support and omissions. Returns workspace-relative draftPath and analysisPath plus an assessment; needs-revision is a completed assessment, not an approved summary." },
+	entrypoint: { instructions: "Use when you need a source-grounded summary checked for unsupported claims and omitted qualifications. Saves the draft and an independent assessment; a completed run may still report needs-revision. Requires model access." },
 	args: Type.Object({ source: Type.String({ minLength: 1 }) }),
 	async execute({ args, paths, agents }) {
 		const draft = await agents.prompt({

package/assets/examples/caller-owned-routing/assessment.ts

@@ -5,7 +5,7 @@ import { assessmentContributionSchema, headingsSchema, outlineContributionSchema
 export const assessOutline = workflow({
 	name: "assessOutline",
 	entrypoint: {
-		instructions: "Check an outline for exact, case-sensitive '## heading' lines from requiredHeadings. Pass outline, requiredHeadings, and missingHeadings to the caller-selected next workflow. Reports heading presence only, not content quality; no model or external service is used.",
+		instructions: "Use when you need to identify missing level-two headings in a Markdown outline before deciding whether to accept or revise it. Reports missing required headings to your continuation using exact, case-sensitive line matching; does not assess prose quality or decide acceptance.",
 	},
 	args: Type.Object({
 		...outlineContributionSchema.properties,

package/assets/examples/caller-owned-routing/revision.ts

@@ -5,7 +5,7 @@ import { headingSchema, outlineContributionSchema } from "./contracts.ts";
 export const appendHeading = workflow({
 	name: "appendHeading",
 	entrypoint: {
-		instructions: "Append one empty level-two Markdown section named heading to outline, then pass the revised outline to the caller-selected next workflow. Does not assess the outline or select further work; no model or external service is used.",
+		instructions: "Use when a Markdown outline needs one additional empty section before further processing. Appends the requested level-two heading and passes the revised outline to your continuation; does not write section content or assess the result.",
 	},
 	args: Type.Object({
 		...outlineContributionSchema.properties,

package/assets/examples/caller-selected-continuation/producer.ts

@@ -11,7 +11,7 @@ export const greetingContributionSchema = Type.Object({
 const scope = workflowScope({ name: "greetingProducer" });
 export const write = scope.workflow({
 	name: "write",
-	entrypoint: { instructions: "Write a greeting file for name, then invoke the caller-selected next workflow with workspace-relative resultPath and summary. The continuation owns completion; no model or external service is used." },
+	entrypoint: { instructions: "Use when a later workflow needs a personalized greeting file and should decide what happens next. Passes the workspace-relative file path and summary to your continuation instead of completing the run." },
 	args: Type.Object({
 		name: Type.String({ minLength: 1 }),
 		next: workflowRefSchema({ args: greetingContributionSchema }),

package/assets/examples/coordinating-multiple-agents/plugin.ts

@@ -13,7 +13,7 @@ const workerReportSchema = Type.Object({ status: Type.Enum(["acknowledged", "idl
 const scope = workflowScope({ name: "coordinatingAgents" });
 export const start = scope.workflow({
 	name: "start",
-	entrypoint: { instructions: "Summarize 2–12 supplied notes using two concurrent Norn agents and a shared leased work queue. Checkpoint completed rounds, verify every persisted result and exact source quotation, and return workspace-relative summariesPath for summaries.json. Requires configured Norn agent authentication; modifies only this run's logs and workspace." },
+	entrypoint: { instructions: "Use when you need separate summaries of 2–12 notes processed concurrently with saved progress for recovery. Saves each summary with a checked verbatim source quotation; this checks quotation fidelity, not summary quality. Requires model access." },
 	args: inputSchema,
 	async execute({ args, paths }) {
 		const queue = await openQueue({ workspace: paths.workspace, create: true });

package/assets/examples/getting-started/plugin.ts

@@ -5,7 +5,7 @@ import { Type } from "typebox";
 
 export const summarize = workflow({
 	name: "summarize",
-	entrypoint: { instructions: "Summarize staged and unstaged tracked changes relative to HEAD in an absolute repositoryPath. Requires Git and an existing commit; untracked files are excluded. Saves workspace-relative summaryPath and retains the diff log. A nonempty diff is sent to the configured model; an empty diff needs no model call." },
+	entrypoint: { instructions: "Use when you need a saved summary of staged and unstaged tracked changes in a Git repository before review or handoff. Compares against HEAD, excludes untracked files, and does not edit the repository. Requires an existing commit and model access for nonempty diffs." },
 	args: Type.Object({ repositoryPath: Type.String({ minLength: 1 }) }),
 	async execute({ args, paths, commands, logs, agents, run }) {
 		const diff = await commands.run({

package/assets/examples/minimal-workflow/plugin.ts

@@ -5,7 +5,7 @@ import { Type } from "typebox";
 
 export const write = workflow({
 	name: "greet",
-	entrypoint: { instructions: "Write a greeting file for the supplied name. Returns the greeting text and its workspace-relative greetingPath; no agent or external service is used." },
+	entrypoint: { instructions: "Use when you need a personalized greeting saved as a local file with no model or external service. Completes with the greeting text and workspace-relative file path." },
 	args: Type.Object({ name: Type.Decode(Type.String({ pattern: "\\S" }), value => value.trim()) }),
 	async execute({ args, paths, run }) {
 		const greeting = `Hello, ${args.name}!`;

package/assets/examples/shared-state/plugin.ts

@@ -11,7 +11,7 @@ const copyField = { id: "copiedText", schema: Type.String() };
 
 export const copy = copyScope.workflow({
 	name: "copy",
-	entrypoint: { instructions: "A Norn agent reads explicitly shared source and writes a copy, then a separate workflow verifies exact equality from a workspace SQLite database." },
+	entrypoint: { instructions: "Use when you need to exercise an agent's access to explicitly shared state by copying a short string exactly. Saves a verified copy or fails on mismatch. Requires model access; not intended as a replacement for ordinary file copying." },
 	args: Type.Object({ source: Type.String({ minLength: 1, maxLength: 500 }) }),
 	async execute({ args, paths, agents }) {
 		const state = await SharedState.open({ path: join(paths.workspace, "state.sqlite"), create: true });

package/assets/examples/worktree-development-loop/workflows/development-loop/execute.ts

@@ -6,7 +6,7 @@ import { materializeWorkspaceRepository } from "./repository.ts";
 
 export const developmentLoopWorkflow = developmentLoopScope.workflow({
 	name: "developmentLoop",
-	entrypoint: { instructions: "Plan once, then loop implementation and review in a workspace repository copy. Call this when a repository task should run through planning, implementation, and review." },
+	entrypoint: { instructions: "Use when you want a repository task planned, implemented, and reviewed in a separate clone with a caller approval gate. Starts from committed content and retains changes for inspection without automatically merging or pushing results back. Requires Git, Bash, and model access." },
 	args: developmentLoopArgsSchema,
 	async execute({ args, scope, paths, commands }): Promise<WorkflowResult> {
 		const repositoryPath = await materializeWorkspaceRepository({ commands, paths, repositoryRoot: scope.config.repositoryRoot, baseRef: args.baseRef });

package/assets/package.json

@@ -1 +1 @@
-{"version":"0.1.0-tip.35611592848.1"}
+{"version":"0.1.0-tip.35614826665.1"}

package/assets/packages/cli/src/generated-build-info.ts

@@ -2,8 +2,8 @@ import type { NornBuildInfo } from "./build-info.ts";
 
 export const NORN_GENERATED_BUILD_INFO = {
   "kind": "npm-registry",
-  "version": "0.1.0-tip.35611592848.1",
-  "commit": "ece526887ef7a821f5e08062d1553e8a5273bd86",
+  "version": "0.1.0-tip.35614826665.1",
+  "commit": "286e68533b1d26b5afbb0cba9d75f857fb85dc53",
   "packageSpec": "@vimhead.dev/norn-cli@tip",
   "upgrade": {
     "supported": false,

package/dist/generated-build-info.d.ts

@@ -1,7 +1,7 @@
 export declare const NORN_GENERATED_BUILD_INFO: {
     readonly kind: "npm-registry";
-    readonly version: "0.1.0-tip.35611592848.1";
-    readonly commit: "ece526887ef7a821f5e08062d1553e8a5273bd86";
+    readonly version: "0.1.0-tip.35614826665.1";
+    readonly commit: "286e68533b1d26b5afbb0cba9d75f857fb85dc53";
     readonly packageSpec: "@vimhead.dev/norn-cli@tip";
     readonly upgrade: {
         readonly supported: false;

package/dist/generated-build-info.js

@@ -1,8 +1,8 @@
 // src/generated-build-info.ts
 var NORN_GENERATED_BUILD_INFO = {
   "kind": "npm-registry",
-  "version": "0.1.0-tip.35611592848.1",
-  "commit": "ece526887ef7a821f5e08062d1553e8a5273bd86",
+  "version": "0.1.0-tip.35614826665.1",
+  "commit": "286e68533b1d26b5afbb0cba9d75f857fb85dc53",
   "packageSpec": "@vimhead.dev/norn-cli@tip",
   "upgrade": {
     "supported": false,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vimhead.dev/norn-cli",
-  "version": "0.1.0-tip.35611592848.1",
+  "version": "0.1.0-tip.35614826665.1",
   "description": "Harness-agnostic runtime for agent-driven and code-driven workflows, built primarily for agents.",
   "type": "module",
   "license": "MIT",
@@ -43,7 +43,7 @@
     "@earendil-works/pi-coding-agent": "0.85.1",
     "jiti": "^2.7.0",
     "typebox": "^1.3.34",
-    "@vimhead.dev/norn": "0.1.0-tip.35611592848.1"
+    "@vimhead.dev/norn": "0.1.0-tip.35614826665.1"
   },
   "scripts": {
     "build": "node ../../scripts/build-package.ts"