From 891e1ab36aa01358bcd86026450f5a645c4eae11 Mon Sep 17 00:00:00 2001 From: Craig Jennings Date: Wed, 10 Jun 2026 00:18:05 -0500 Subject: docs(create-workflow): document the supporting-document convention A workflow that outgrows its inline content stores the overflow in a sibling ..org, linked inline. This reuses the engine.plugin dot-glob, so the drift-check and discovery glob already treat the file as owned rather than an orphan. It also travels with the workflow on promotion. I extended the INDEX drift-check note to name supporting docs alongside source plugins. --- .ai/workflows/create-workflow.org | 8 ++++++++ 1 file changed, 8 insertions(+) (limited to '.ai/workflows/create-workflow.org') diff --git a/.ai/workflows/create-workflow.org b/.ai/workflows/create-workflow.org index e6587c8..6060df1 100644 --- a/.ai/workflows/create-workflow.org +++ b/.ai/workflows/create-workflow.org @@ -223,6 +223,14 @@ Write the workflow file at =.ai/workflows/[name].org= using this structure: - Include decision frameworks for common situations - Note that this is a living document +*** Supporting documents + +When a workflow needs more supporting content than fits inline (a condensed method that has a fuller reference version, an extracted procedure, a long reference table), store it in a sibling file named after the workflow with a descriptive suffix — =..org= — and link it inline as part of the sentence, not as a bare "see X" footnote. + +This reuses the dot-delimited =engine.plugin.org= convention: the startup =.ai/= rsync, the INDEX.org drift-check, and the workflow-discovery glob already recognize a dotted name =foo.bar.org= as belonging to =foo=, so a supporting doc is correctly *not* treated as an independently-triggerable workflow or an INDEX orphan. It also keeps the workflow promotion-safe — when a project-only workflow is promoted to a template, its supporting files travel with it under the same prefix, whereas a link into a project-specific =assets/= doc would break on promotion. + +Worked example: a meeting-prep workflow whose mid-flow phase carries a condensed version of a method, with the full method extracted to =meeting-prep.pre-wire.org= beside it and linked inline. + ** Phase 5: Update Project State Update =notes.org=: -- cgit v1.2.3