Files
pipelines/docs/authoring-session-review.md
T
alan c42a19f7d3 Improve workflow UI, retain stage diffs, and add portable pipeline transfers
Make OpenCode authoring responsive and expand the managed skill references. Add conflict-aware import/export, real-provider reference workflows, and tracked V2 generation for reliable budget accounting.
2026-10-10 20:55:42 +01:00

4.9 KiB

Authoring session review

Observed in the supplied October 10 export

  • The initial prompt contained a draft-context path and CLI prefix, but no edit request. Before asking for intent, the agent made eight tool calls: skill load, three file reads, and four CLI commands. It already recognized that a question was needed, but continued investigating.
  • Those CLI calls listed templates, called show without its required argument, fetched an entire template already represented by the draft, and listed unrelated retained drafts. None was needed to ask what should change.
  • The question presented a generic feature menu instead of a direct edit question.
  • After the user requested success/error notifications, the agent made twenty discovery calls before its first edit: two globs, two shell commands, nine reads and seven greps. It repeatedly debated adding model/native delivery stages. Its format reference pointed to project-local ntfy docs, causing a repository search and a long read of installation, networking and phone setup information unrelated to this edit.
  • The agent treated an optional native-publisher hint as a recommended design, overlooking a minimal combination of existing stage hooks.
  • It eventually chose the correct failure-only research hook and success/failure report hook, validated the draft, and published version 2 after the user's explicit approval. Those approval and immutable-version boundaries were respected.
  • It also added a report attachment and renamed the output field from report to markdown even though only a notification was requested. Its final summary overstated this as a guarantee of exactly one notification per run; stage hooks do not cover every cancellation/crash/limit failure or guarantee phone reception.

The export's creation/update times span 3m56s, including the user's reply. It has no per-message/tool timestamps; it cannot establish time to first interaction or separate inference, tool, network and user-wait latency.

Changes

  1. Launch prompts distinguish absent intent from an explicit request. With no request they instruct OpenCode to ask first, before reads or CLI calls. With a request they ask for a brief acknowledgement followed by targeted reading. Launch remains one direct OpenCode command; no extra discovery or inference.
  2. The skill puts intent before investigation and replaces generic questionnaires with one open-ended question. After the reply it reads context, draft and only relevant references. It preserves the authoritative CLI executable/URL prefix and discourages speculative help calls, bare show, catalog comparisons, unrelated draft listings and repeated unchanged reads.
  3. A packaged references/notifications.md gives a self-contained decision guide: hooks for ordinary alerts; native delivery only for explicitly routed delivery. It includes the research/report terminal-path recipe, attachment requirements, failure semantics and cancellation/crash/recovery-loop limitations. Attachments and output-contract changes are added only when requested. No checkout of Pipelines is needed during ordinary authoring.
  4. Native-delivery examples use the system connection rather than suggesting a second topic/token. Ordinary event alerts leave output contracts unchanged.
  5. Skill installation includes the new reference and upgrades old managed installations without overwriting modified files. Existing drafts, published versions, schedules, tool permissions and approval boundaries are unchanged.

Verification and limits

New-pipeline guidance also avoids asking for a name/stage count/model/tools before understanding the task. It suggests one minimal graph and retains model inheritance, loading optional notification/example references only when relevant. Regression tests execute both new and edit launch commands against a stub executable and check that each launches exactly once with ask-first guidance, without session, help or API discovery. A command-preparation benchmark measures only local launch preparation, not OpenCode startup or real-provider response latency.

go test ./internal/author ./internal/server -run 'TestPrompt|TestCommandLaunches|TestInstalledSkill|TestSkillUpgrade|TestResearchTerminalNotificationRecipe' -count=1 passed. These checks execute the captured launch command, inspect generated prompts, upgrade the installed skill in an isolated directory, and execute the research/report notification recipe against SQLite and a mock HTTP ntfy endpoint. The recipe covers success, early/final blocked outcomes, early/final execution errors and failed delivery without changing the run verdict or sending intermediate success events.

The prompt/skill changes guide model behavior; they do not enforce a model's first action. Real-provider time-to-first-question, compliance with the new instructions, and actual phone reception are not tested. No new model inference or phone message is needed to install these authoring changes.